PM1

The PM1 component handles electrical power metering capabilities. It uses PM1 as the RPC namespace and provides the methods:

• PM1.SetConfig to update the component's configuration
• PM1.GetConfig to obtain the component's configuration
• PM1.GetStatus to obtain the component's status
• PM1.ResetCounters to reset component's energy counters

PM1 components are identified with PM1:<id> in objects containing multiple component payloads.

Methods

PM1.SetConfig

Parameters:

Property	Type	Description
id	number	Id of the PM1 component instance
config	object	Configuration that the method takes

Find more about the config properties in config section

PM1.GetConfig

Parameters:

Property	Type	Description
id	number	Id of the PM1 component instance

Find the PM1.GetConfig response properties in config section

PM1.GetStatus

Parameters:

Property	Type	Description
id	number	Id of the PM1 component instance

Find more about the status response properties in status section

PM1.ResetCounters

This method resets associated counters.

Request

Parameters:

Property	Type	Description
id	number	Id of the PM1 component instance. Required
type	array of strings	Array of strings, selects which counter to reset Optional

note

If no 'type' is provided, the method will reset all available counters.

Response

Attributes in the result:

Property	Type	Description
aenergy	object	Information about the active energy counter prior to reset Property Type Description total number Last counter value of the total energy consumed in Watt-hours
ret_aenergy	object	Information about the returned active energy counter prior to reset Property Type Description total number Last counter value of the total returned energy consumed in Watt-hours

Configuration

The configuration of the PM1 component contains information about the id and name of the component.

Property	Type	Description
id	number	Id of the PM1 component instance
name	string or null	Name of the PM1 instance
reverse	bool	Reverse measurement direction of active power and energy for the PM1 component. setting the reverse option requires restart
alarms	object	Settings for the alarm thresholds Property Type Description voltage array of numbers or null ['under','over'] thresholds current array of numbers or null ['under','over'] thresholds power array of numbers or null ['under','over'] thresholds 'null' disables a threshold, setting the alarms option to 'null' disables all alarms

Status

The status of the PM1 component contains information about the measured variables. To obtain the status of the PM1 component its id must be specified.

Property	Type	Description
id	number	Id of the PM1 component instance
voltage	number	Last measured voltage in Volts
current	number	Last measured current in Amperes
apower	number	Last measured instantaneous active power (in Watts) delivered to the attached load
aprtpower	number	Last measured instantaneous apparent power (in Volt-Amperes) delivered to the attached load (shown if applicable)
pf	number	Last measured power factor (shown if applicable)
freq	number	Last measured network frequency (shown if applicable)
aenergy	object	Information about the active energy counter Property Type Description total number Total energy consumed in Watt-hours by_minute array of type number Energy consumption in Milliwatt-hours for the last three complete minutes. The 0-th element indicates the counts accumulated during the minute preceding minute_ts. Present only if the device clock is synced. minute_ts number Unix timestamp marking the start of the current minute (in UTC).
ret_aenergy	object	Information about the returned active energy counter * Property Type Description total number Total returned energy consumed in Watt-hours by_minute array of type number Returned energy consumption by minute (in Milliwatt-hours) for the last three minutes (the lower the index of the element in the array, the closer to the current moment the minute) minute_ts number Unix timestamp marking the start of the current minute (in UTC).
errors	array of type string	Error conditions occurred. May contain power_meter_failure, out_of_range:voltage, out_of_range:current, out_of_range:aprtpower, out_of_range:apower(shown if at least one error is present)
flags	array of type string	Communicates present conditions, shown if at least one flag is set. May contain: undervoltage, overvoltage, undercurrent, overcurrent, underpower, overpower

note

• ret_aenergy - the active energy added to this container is also added to aenergy container. All the consumed energy is collected in aenergy regardless of the direction(consumed or returned) of the active energy.

Webhook Events

PM1 component supports conditional webhooks.

Events related to the PM1 component that can trigger webhooks:

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

    Property	Type	Description
    voltage	number	New voltage in Volts

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

    Property	Type	Description
    current	number	New current in Amps

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

    Property	Type	Description
    apower	number	New active power in Watts

• alarm_undervoltage - when the voltage drops below an under threshold.
  • alarm_undervoltage event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    voltage	number	Voltage below the under threshold in Volts

• alarm_undervoltage_clear - when the voltage rises above an under threshold.
  • alarm_undervoltage_clear event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    voltage	number	Voltage above the under threshold in Volts

• alarm_overvoltage - when the voltage rises above an over threshold.
  • alarm_overvoltage event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    voltage	number	Voltage above the over threshold in Volts

• alarm_overvoltage_clear - when the voltage drops below an over threshold.
  • alarm_overvoltage_clear event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    voltage	number	Voltage below the over threshold in Volts

• alarm_undercurrent - when the current drops below an under threshold.
  • alarm_undercurrent event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    current	number	Current below the under threshold in Amps

• alarm_undercurrent_clear - when the current rises above an under threshold.
  • alarm_undercurrent_clear event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    current	number	Current above the under threshold in Amps

• alarm_overcurrent - when the current rises above an over threshold.
  • alarm_overcurrent event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    current	number	Current above the over threshold in Amps

• alarm_overcurrent_clear - when the current drops below an over threshold.
  • alarm_overcurrent_clear event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    current	number	Current below the over threshold in Amps

• alarm_underpower - when the power drops below an under threshold.
  • alarm_underpower event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    power	number	Power below the under threshold in Watts

• alarm_underpower_clear - when the power rises above an under threshold.
  • alarm_underpower_clear event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    power	number	Power above the under threshold in Watts

• alarm_overpower - when the power rises above an over threshold.
  • alarm_overpower event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    power	number	Power above the over threshold in Watts

• alarm_overpower_clear - when the power drops below an over threshold.
  • alarm_overpower_clear event supports attributes, that can be used to compose conditional webhooks:

    Property	Type	Description
    power	number	Power below the over threshold in Watts

Alarms

Alarms provide a way to trigger custom behavior when a monitored variable reaches a certain threshold, without raising an error or activating defensive mechanisms.

There are six types of alarms across three variables, resulting in twelve available webhooks.

The monitored variables are voltage, current, and power. Each variable supports two thresholds:

• an under threshold
• an over threshold

For example, the voltage variable can trigger an undervoltage alarm when the measured value falls below the configured “under” threshold, or an overvoltage alarm when it exceeds the “over” threshold.

Each threshold can be configured with a numeric value, or disabled by setting it to null.

A triggered alarm will set a flag in the status, indicating the condition that triggered the alarm. The flag is cleared when the alarm condition is cleared.

A triggered

Examples

PM1.SetConfig example

PM1.SetConfig HTTP GET Request

http://192.168.33.1/rpc/PM1.SetConfig?id=0&config={"name":"Meter","reverse":true}

PM1.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"PM1.SetConfig","params":{"id":0,"config":{"name":"Meter","reverse":true}}}' http://${SHELLY}/rpc

PM1.SetConfig Mos Request

mos --port ${PORT} call PM1.SetConfig '{"id":0,"config":{"name":"Meter","reverse":true}}'

Response

PM1.SetConfig HTTP GET Response

{
  "restart_required": true
}

PM1.SetConfig Curl Response

{
  "id": 1,
  "params": {
    "restart_required": true
  }
}

PM1.SetConfig Mos Response

{
  "restart_required": true
}

PM1.SetConfig HTTP GET Request

http://192.168.33.1/rpc/PM1.SetConfig?id=0&config={"alarms":{"voltage":[190,245.9],"current":[4.9,11],"power":[100,1200]}}

PM1.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"PM1.SetConfig","params":{"id":0,"config":{"alarms":{"voltage":[190,245.9],"current":[4.9,11],"power":[100,1200]}}}}' http://${SHELLY}/rpc

PM1.SetConfig Mos Request

mos --port ${PORT} call PM1.SetConfig '{"id":0,"config":{"alarms":{"voltage":[190,245.9],"current":[4.9,11],"power":[100,1200]}}}'

Response

PM1.SetConfig HTTP GET Response

{
  "restart_required": false
}

PM1.SetConfig Curl Response

{
  "id": 1,
  "params": {
    "restart_required": false
  }
}

PM1.SetConfig Mos Response

{
  "restart_required": false
}

PM1.GetConfig example

PM1.GetConfig HTTP GET Request

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

PM1.GetConfig Curl Request

curl -X POST -d '{"id":1,"method":"PM1.GetConfig","params":{"id":0}}' http://${SHELLY}/rpc

PM1.GetConfig Mos Request

mos --port ${PORT} call PM1.GetConfig '{"id":0}'

Response

PM1.GetConfig HTTP GET Response

{
  "id": 0,
  "name": "PM1device",
  "reverse": false,
  "alarms": {
    "voltage": [
      200,
      250
    ],
    "current": [
      0.2,
      12
    ],
    "power": [
      20,
      1200
    ]
  }
}

PM1.GetConfig Curl Response

{
  "id": 1,
  "params": {
    "id": 0,
    "name": "PM1device",
    "reverse": false,
    "alarms": {
      "voltage": [
        200,
        250
      ],
      "current": [
        0.2,
        12
      ],
      "power": [
        20,
        1200
      ]
    }
  }
}

PM1.GetConfig Mos Response

{
  "id": 0,
  "name": "PM1device",
  "reverse": false,
  "alarms": {
    "voltage": [
      200,
      250
    ],
    "current": [
      0.2,
      12
    ],
    "power": [
      20,
      1200
    ]
  }
}

PM1.GetStatus example

PM1.GetStatus HTTP GET Request

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

PM1.GetStatus Curl Request

curl -X POST -d '{"id":1,"method":"PM1.GetStatus","params":{"id":0}}' http://${SHELLY}/rpc

PM1.GetStatus Mos Request

mos --port ${PORT} call PM1.GetStatus '{"id":0}'

Response

PM1.GetStatus HTTP GET Response

{
  "id": 0,
  "voltage": 225.9,
  "current": 0,
  "apower": 0,
  "freq": 50,
  "aenergy": {
    "total": 11.679,
    "by_minute": [
      0,
      0,
      0
    ],
    "minute_ts": 1654511972
  },
  "ret_aenergy": {
    "total": 4.126,
    "by_minute": [
      0,
      0,
      0
    ],
    "minute_ts": 1654511318
  },
  "errors": [
    "power_meter_failure",
    "out_of_range:voltage",
    "out_of_range:current",
    "out_of_range:apower",
    "out_of_range:aprtpower"
  ]
}

PM1.GetStatus Curl Response

{
  "id": 1,
  "src": "shellyplus1pm-441793ce3f08",
  "params": {
    "id": 0,
    "voltage": 225.9,
    "current": 0,
    "apower": 0,
    "freq": 50,
    "aenergy": {
      "total": 11.679,
      "by_minute": [
        0,
        0,
        0
      ],
      "minute_ts": 1654511972
    },
    "ret_aenergy": {
      "total": 4.126,
      "by_minute": [
        0,
        0,
        0
      ],
      "minute_ts": 1654511318
    },
    "errors": [
      "power_meter_failure",
      "out_of_range:voltage",
      "out_of_range:current",
      "out_of_range:apower",
      "out_of_range:aprtpower"
    ]
  }
}

PM1.GetStatus Mos Response

{
  "id": 0,
  "voltage": 225.9,
  "current": 0,
  "apower": 0,
  "freq": 50,
  "aenergy": {
    "total": 11.679,
    "by_minute": [
      0,
      0,
      0
    ],
    "minute_ts": 1654511972
  },
  "ret_aenergy": {
    "total": 4.126,
    "by_minute": [
      0,
      0,
      0
    ],
    "minute_ts": 1654511318
  },
  "errors": [
    "power_meter_failure",
    "out_of_range:voltage",
    "out_of_range:current",
    "out_of_range:apower",
    "out_of_range:aprtpower"
  ]
}

PM1.ResetCounters example

PM1.ResetCounters HTTP GET Request

http://192.168.33.1/rpc/PM1.ResetCounters?id=0&type=["aenergy","ret_aenergy"]

PM1.ResetCounters Curl Request

curl -X POST -d '{"id":1,"method":"PM1.ResetCounters","params":{"id":0,"type":["aenergy","ret_aenergy"]}}' http://${SHELLY}/rpc

PM1.ResetCounters Mos Request

mos --port ${PORT} call PM1.ResetCounters '{"id":0,"type":["aenergy","ret_aenergy"]}'

Response

PM1.ResetCounters HTTP GET Response

{
  "aenergy": {
    "total": 11.679
  },
  "ret_aenergy": {
    "total": 5.817
  }
}

PM1.ResetCounters Curl Response

{
  "id": 1,
  "src": "shellypluspmmini-44179bf90f08",
  "params": {
    "aenergy": {
      "total": 11.679
    },
    "ret_aenergy": {
      "total": 5.817
    }
  }
}

PM1.ResetCounters Mos Response

{
  "aenergy": {
    "total": 11.679
  },
  "ret_aenergy": {
    "total": 5.817
  }
}