Skip to main content
Version: 1.0

EM

EM (Energy Meter) component handles the data collection and processing from energy meter devices like the ShellyPro3EM.

Methods

EM.SetConfig

Properties:

PropertyTypeDescription

id

number

Id of the EM component instance

config

object

Configuration that the method takes

Find more about the config properties in config section

EM.GetConfig

Properties:

PropertyTypeDescription

id

number

Id of the EM component instance

Find the EM.GetConfig response properties in config section

EM.GetStatus

Properties:

PropertyTypeDescription

id

number

Id of the EM component instance

Find more about the status response properties in status section

EM.PhaseToPhaseCalib

Properties:

PropertyTypeDescription

id

number

Id of the EM component instance

from

string

Select the phase from witch the calibration data is taken

to

string

Select the phase to witch the calibration is due

Response:

restart_required:true on success; error if request can't be executed or failed

info

In order to be able to calibrate correctly the phase voltages need to be equal i.e. if we calibrate a CT from phase c to a CT on phase a, the voltage of phase c and phase a needs to be the same (phases are connected on the same voltage line). The minimum power allowed for the calibration to take place is 500W. The method takes around 5 seconds to complete, and the response is delayed with the request answer - restart_required: true in case of success or error message in case of fail. The reasons for the calibration to fail may be - deviation in measurement after calibration on the from and to phases that indicating incorrect input phases setup, incorrect CTs or other problem.

EM.PhaseToPhaseCalibReset

Properties:

PropertyTypeDescription

id

number

Id of the EM component instance

phase

string

Phase for which user calibration is going to be reset

Response:

restart_required:true on success; error if request can't be executed or failed

EM.GetCTTypes

Properties:

PropertyTypeDescription

id

number

Id of the EM component instance

Response:

PropertyTypeDescription

supported

array

Array of strings of all supported CT types

Configuration

The configuration of the Energy Meter component shows the energy metering device's name, blink mode selector, phase selector and phase sequence detection enabled. To Get/Set the configuration of the EM component its id must be specified. Name setting does not require restart however, setting blink_mode_selector, phase_selector and/or ct_type requires restart.

Properties:

PropertyTypeDescription

id

number

Id of the EM component instance

name

string or null

Name of the energy meter instance

blink_mode_selector

string

Select the electrical quantity that drives the LED. Range of values: active_energy, apparent_energy

phase_selector

string

Select witch phase controls the LED. Range of values: a, b, c, all

monitor_phase_sequence

boolean

Set this to show phase_sequence error in GetStatus if three-phase power system is used and the wires are not connected correctly to the device.

reverse

object

Reverse CT measurement direction

PropertyTypeDescription

a

boolean

When set to true reverse CT measurement direction of active power and energy for phase A. shown if true

b

boolean

When set to true reverse CT measurement direction of active power and energy for phase B. shown if true

c

boolean

When set to true reverse CT measurement direction of active power and energy for phase C. shown if true

setting the reverse option requires restart

ct_type

string

Select the type of Shelly current transformer attached to the device.

note

If ct_type is not set, an error ct_type_not_set is present in component status.

Supported ct_types can be obtained with EM.GetCTTypes.

Webhook events

EM componnent supports conditional webhooks.

Events related to the EM component that can trigger webhooks:

  • voltage_change - when voltage has changed with at least 1V and 5% from the last reported value.
    • voltage_change event supports attributes, that can be used to compose conditional webhooks:
      PropertyTypeDescription

      phase

      string

      Phase which generates the event, one of 'a', 'b' or 'c'.

      voltage

      number

      New phase voltage in Volts

  • current_change - when current has changed with at least 0.05A and 5% from the last reported value.
    • current_change event supports attributes, that can be used to compose conditional webhooks:
      PropertyTypeDescription

      phase

      string

      Phase which generates the event, one of 'a', 'b', 'c' or 'n'.

      current

      number

      New phase current in Amps

  • active_power_change - when active power has changed with at least 10W and 5% from the last reported value.
    • active_power_change event supports attributes, that can be used to compose conditional webhooks:
      PropertyTypeDescription

      phase

      string

      Phase which generates the event, one of 'a', 'b' or 'c'.

      act_power

      number

      New phase active power in Watts

  • total_current_change - when the total current has changed with at least 3A and 5% from the last reported value.
    • total_current_change event supports attributes, that can be used to compose conditional webhooks:
      PropertyTypeDescription

      total_current

      number

      New total current in Amps

  • total_active_power_change - when the total active power has changed with at least 100W and 5% from the last reported value.
    • total_active_power_change event supports attributes, that can be used to compose conditional webhooks:
      PropertyTypeDescription

      total_active_power

      number

      New total active power in Watts

  • total_apparent_power_change - when the total apparent power has changed with at least 100W and 5% from the last reported value.
    • total_apparent_power_change event supports attributes, that can be used to compose conditional webhooks:
      PropertyTypeDescription

      total_apparent_power

      number

      New total apparent power in VAs

Status

The status of the Energy Meter Component contains information from the current measurements, for all active phase(es) of the device. To obtain information for the components status its id must be specified. The information for a phase contains information for:

  • The momentary values of the current in A (Amps), voltage in V (Volts), active_power in W (Watts), apparent_power in VA (Volt-Ampere), pf - power factor is dimensionless, freq - network frequency in Hz.

  • neutral is the reporting for the neutral current measurements.

    PropertyTypeDescription

    id

    number

    Id of the EM component instance

    a_current

    number or null

    Phase A current measurement value, [A]

    a_voltage

    number or null

    Phase A voltage measurement value, [V]

    a_act_power

    number or null

    Phase A active power measurement value, [W]

    a_aprt_power

    number or null

    Phase A apparent power measurement value, [VA]

    a_pf

    number or null

    Phase A power factor measurement value

    a_freq

    number or null

    Phase A network frequency measurement value

    a_errors

    array of type string

    Phase A error conditions occurred. May contain out_of_range:active_power, out_of_range:apparent_power, out_of_range:voltage, out_of_range:current,(shown if at least one error is present)

    b_current

    number or null

    Phase B current measurement value, [A]

    b_voltage

    number or null

    Phase B voltage measurement value, [V]

    b_act_power

    number or null

    Phase B active power measurement value, [W]

    b_aprt_power

    number or null

    Phase B apparent power measurement value, [VA]

    b_pf

    number or null

    Phase B power factor measurement value

    b_freq

    number or null

    Phase B network frequency measurement value

    b_errors

    array of type string

    Phase B error conditions occurred. May contain out_of_range:active_power, out_of_range:apparent_power, out_of_range:voltage, out_of_range:current,(shown if at least one error is present)

    c_current

    number or null

    Phase C current measurement value, [A]

    c_voltage

    number or null

    Phase C voltage measurement value, [V]

    c_act_power

    number or null

    Phase C active power measurement value, [W]

    c_aprt_power

    number or null

    Phase C apparent power measurement value, [VA]

    c_pf

    number or null

    Phase C power factor measurement value

    c_freq

    number or null

    Phase C network frequency measurement value

    c_errors

    array of type string

    Phase C error conditions occurred. May contain out_of_range:active_power, out_of_range:apparent_power, out_of_range:voltage, out_of_range:current,(shown if at least one error is present)

    n_current

    number or null

    Neutral current measurement value, [A] (if supported)

    n_errors

    array of type string

    Neutral error conditions occurred. May contain out_of_range:current,(shown if error is present)

    total_current

    number or null

    Sum of the current on all phases(excluding neutral readings if available)

    total_act_power

    number or null

    Sum of the active power on all phases

    total_aprt_power

    number or null

    Sum of the apparent power on all phases

    user_calibrated_phase

    array of type string

    Indicates which phase was user calibrated

    errors

    array of type string

    EM component error conditions. May contain power_meter_failure, phase_sequence or ct_type_not_set. Present in status only if not empty.

info

* phase_sequence is an error indicating if the sequence of zero-crossing events is Phase A followed by Phase C followed by Phase B. The regular succession of these zero-crossing events is Phase A followed by Phase B followed by Phase C.

Notifications

StatusChange

Statuschange notification on a regular interval and an error condition change.

Modbus registers

AddressTypeDescription
31000uint32Timestamp of the last update
31002booleanPhase A meter error
31003booleanPhase B meter error
31004booleanPhase C meter error
31005booleanNeutral meter error
31006booleanPhase sequence error
31007floatNeutral current, A
31009booleanNeutral current mismatch
31010booleanNeutral overcurrent error
31011floatTotal current, A *
31013floatTotal active power, W *
31015floatTotal apparent power, VA *
310173 registers reserved
31020floatPhase A voltage, V
31022floatPhase A current, A
31024floatPhase A active power, W
31026floatPhase A apparent power, VA
31028floatPhase A power factor
31030booleanPhase A overpower error
31031booleanPhase A overvoltage error
31032booleanPhase A overcurrent error
310337 registers reserved
31040floatPhase B voltage, V
31042floatPhase B current, A
31044floatPhase B active power, W
31046floatPhase B apparent power, VA
31048floatPhase B power factor
31050booleanPhase B overpower error
31051booleanPhase B overvoltage error
31052booleanPhase B overcurrent error
310537 registers reserved
31060floatPhase C voltage, V
31062floatPhase C current, A
31064floatPhase C active power, W
31066floatPhase C apparent power, VA
31068floatPhase C power factor
31070booleanPhase C overpower error
31071booleanPhase C overvoltage error
31072booleanPhase C overcurrent error
310737 registers reserved

If there is a second EM component on the device, its corresponding registers addresses are calculated by adding 80 to the address in the table above.

* sum of all available phases

Examples

EM.SetConfig example

Example:

http://192.168.33.1/rpc/EM.SetConfig?id=0&config={"name":"abc","blink_mode_selector":"apparent_energy","phase_selector":"all","monitor_phase_sequence":true,"ct_type":"120A"}

Response

{
"restart_required": true
}

EM.GetConfig example

Example:

http://192.168.33.1/rpc/EM.GetConfig?id=0

Response

{
"id": 0,
"name": null,
"blink_mode_selector": "active_energy",
"phase_selector": "a",
"monitor_phase_sequence": true,
"reverse": {
"b": true
},
"ct_type": "120A"
}

EM.GetStatus example

http://192.168.33.1/rpc/EM.GetStatus?id=0

Response

{
"id": 0,
"a_current": 4.029,
"a_voltage": 236.1,
"a_act_power": 951.2,
"a_aprt_power": 951.9,
"a_pf": 1,
"a_freq": 50,
"b_current": 4.027,
"b_voltage": 236.201,
"b_act_power": -951.1,
"b_aprt_power": 951.8,
"b_pf": 1,
"b_freq": 50,
"c_current": 3.03,
"c_voltage": 236.402,
"c_active_power": 715.4,
"c_aprt_power": 716.2,
"c_pf": 1,
"c_freq": 50,
"n_current": 11.029,
"total_current": 11.083,
"total_act_power": 2484.782,
"total_aprt_power": 2486.7,
"user_calibrated_phase": [],
"errors": [
"phase_sequence"
]
}

EM.PhaseToPhaseCalib example

http://192.168.33.1/rpc/EM.PhaseToPhaseCalib?id=0&from="a"&to="n"

Response

{
"restart_required": true
}

EM.PhaseToPhaseCalibReset example

http://192.168.33.1/rpc/EM.PhaseToPhaseCalibReset?id=0&phase="a"

Response

{
"restart_required": true
}

EM.GetCTTypes example

Example:

http://192.168.33.1/rpc/EM.GetCTTypes?id=0

Response

{
"supported": [
"120A",
"400A"
]
}