Skip to main content
Version: 1.0

LNM Components

caution

Available as preview. The API is subject to change.

note

Available for Gen 2, Gen 3, Gen 4 devices.

LNM (Local Network Messaging) components are a subset of dynamic components for broadcasting and receiving component status updates via UDP multicast on the local network.

Each LNM instance operates independently with its own multicast address, TX components, and UDP socket. Multiple instances can coexist on the same or different multicast groups.

The management is accomplished through RPC methods within the LNM namespace:

Methods​

LNM.GetConfig​

Find more about the config response properties in configuration section

LNM.SetConfig​

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the LNM component Required

config

object

Configuration object with the properties to update. All properties are optional -- only provided properties will be updated.

PropertyTypeDescription

addr

string

Multicast group address in ip:port format. IP must be a valid multicast address (224.0.0.0/4). Changing this value requires a restart.

tx

object

Transmit settings

PropertyTypeDescription

enable

boolean

Enable broadcasting status updates to the multicast group

components

array of strings

List of component keys to broadcast (e.g., ["switch:0", "em1:0"]). Supported component types: switch, cover, input, light, pm1, em1, em.

rx

object

Receive settings

PropertyTypeDescription

enable

boolean

Enable listening to multicast messages

Response​

On success, the response contains restart_required indicating whether a device restart is needed to apply the changes. Changing the addr property requires a restart.

LNM.GetStatus​

Find more about the status response properties in status section

LNM.Create​

Request​

Parameters:

PropertyTypeDescription

config

object

Configuration to be used for the new component. Must contain addr (valid multicast address:port). Find the config properties in the configuration section.

id

number

Id for the new component. Accepted range: [200..299]. Optional. If omitted, the first free ID will be used. If the desired ID is not available, an error will be returned.

Response​

The result from calling this method is a JSON object with the id of the newly created component upon success, otherwise it will return an error.

Received attributes:

PropertyTypeDescription

id

number

Id of the newly created component

LNM.Delete​

Request​

Parameters:

PropertyTypeDescription

id

number

The id of existing LNM component Required

Response​

The result from calling this method is an empty object on success, otherwise it will return an error.

Configuration​

The LNM component configuration contains the multicast address, transmit settings, and receive settings.

Properties:

PropertyTypeDescription

id

number

Id of the component instance

addr

string

Multicast group address in ip:port format (e.g., "239.1.1.1:3333")

tx

object

Transmit settings

PropertyTypeDescription

enable

boolean

Whether broadcasting is enabled

components

array of strings

List of component keys to broadcast (e.g., ["switch:0", "em1:0"])

rx

object

Receive settings

PropertyTypeDescription

enable

boolean

Whether listening is enabled

Status​

The LNM component status provides message statistics.

Properties:

PropertyTypeDescription

id

number

Id of the component instance

stats

object

Messaging statistics

PropertyTypeDescription

tx_msgs

number

Number of messages sent since since

rx_msgs

number

Number of messages received since since

since

number

UNIX timestamp of when stats counting started

Wire Protocol​

caution

The binary wire protocol is not yet stable and may change in future firmware updates.

Each UDP datagram is prefixed with a 12-byte binary header (little-endian, packed):

OffsetSizeFieldDescription
02magic0x53 0x4C ("SL")
21versionProtocol version (currently 0)
31payload_typePayload type (1 = status/event)
42payload_lenPayload length in bytes
62meta_lenMeta block length (reserved, currently 0)
84reservedReserved for future use

The datagram layout is: [header (12 bytes)] [payload (payload_len bytes)] [meta (meta_len bytes)].

Example status/event payload​

For payload_type 1 (status/event), the payload is JSON. Below is an example with 3 component statuses and 2 events (header stripped):

{
  "device": "shellypro4pm-xxxxxxxxxxxx",
  "ts": 1774350200.41,
  "status": {
    "switch:0": {"id": 0, "output": true, "apower": 120.3},
    "switch:1": {"id": 1, "output": false, "apower": 0.0},
    "em1:0": {"id": 0, "voltage": 237.1, "current": 1.136, "act_power": 269.5}
  },
  "events": [
    {"component": "input:0", "id": 0, "event": "single_push", "ts": 1774350200.41},
    {"component": "input:1", "id": 1, "event": "double_push", "ts": 1774350200.41}
  ]
}
  • device - Device ID of the sender
  • ts - UNIX timestamp of the message
  • status - Component statuses that changed (full GetStatus output per component); omitted when empty
  • events - Stateless events (e.g. single_push, double_push, long_push); omitted when empty

Examples​

LNM.GetConfig example​

http://192.168.33.1/rpc/LNM.GetConfig?id=200

Response

{
  "id": 200,
  "addr": "239.1.1.1:3333",
  "tx": {
    "enable": true,
    "components": [
      "em1:0",
      "em1:1",
      "em1:2"
    ]
  },
  "rx": {
    "enable": false
  }
}

LNM.SetConfig example​

http://192.168.33.1/rpc/LNM.SetConfig?id=200&config={"tx":{"enable":true,"components":["switch:0"]},"rx":{"enable":true}}

Response

{
  "restart_required": false
}

LNM.GetStatus example​

http://192.168.33.1/rpc/LNM.GetStatus?id=200

Response

{
  "id": 200,
  "stats": {
    "tx_msgs": 42,
    "rx_msgs": 100,
    "since": 1774350141
  }
}

LNM.Create example​

http://192.168.33.1/rpc/LNM.Create?config={"addr":"239.1.1.1:3333"}

Response

{
  "id": 200
}

LNM.Delete example​

http://192.168.33.1/rpc/LNM.Delete?id=200

Response

{}

Events​

rx event​

When RX is enabled and a message is received, an rx event is fired. These events are delivered to scripts only.

{
  "component": "lnm:200",
  "name": "lnm",
  "id": 200,
  "now": 1774422514.39,
  "info": {
    "component": "lnm:200",
    "id": 200,
    "event": "rx",
    "device": "shellypro3em-xxxxxxxxxxxx",
    "status": {
      "em1:0": {
        "id": 0,
        "voltage": 224.6,
        "current": 0.03,
        "act_power": 0,
        "aprt_power": 6.7,
        "pf": 0,
        "freq": 50,
        "calibration": "factory"
      }
    }
  }
}

To handle these events in a script:

Shelly.addEventHandler(function(ev) {
  if (ev.name !== "lnm" || ev.info.event !== "rx") return;
  print("Received from: " + ev.info.device);
  print(JSON.stringify(ev.info.status));
});