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.

tip

For a step-by-step setup walkthrough, see the Local Network Messaging (LNM) — Setup Guide.

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​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance. Required

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 that the method takes

Find more about the config properties in config section

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​

Parameters:

PropertyTypeDescription

id

number

Id of the component instance. Required

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.

LNM.Call​

Send a fire-and-forget RPC notification to the multicast group. All devices on the group with rpc_enable: true will execute the method locally.

note

rpc_enable must be true on the LNM instance. tx.enable is NOT required for LNM.Call.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the LNM component. Required

method

string

RPC method name to invoke on remote devices (e.g., "Switch.Set"). Required

params

object

Parameters for the method. Optional

Response​

PropertyTypeDescription

id

number

Id of the LNM component that sent the notification

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")

rpc_enable

boolean

Whether RPC command delivery over multicast is enabled

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",
  "rpc_enable": false,
  "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

{}

LNM.Call example​

http://192.168.33.1/rpc/LNM.Call?id=200&method="Switch.Set"&params={"id":0,"on":true}

Response

{
  "id": 200
}

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));
});

Webhook Events​

There are two events related to the LNM component that can trigger webhooks:

  • lnm.rx_status - produced when a status update is received from the multicast group
  • lnm.rx_event - produced for each event entry received from the multicast group (one webhook per event)

Both webhook events support attributes that can be used to compose conditional webhooks:

PropertyTypeDescription

device

string

Device ID of the sender

status

object

Received status map (for lnm.rx_status only)

event_data

object

Received event object (for lnm.rx_event only)

note

Webhook events require rx.enable: true on the LNM instance. The rpc_enable flag is independent and does not affect webhook delivery.