Shelly LoRa Add-Ons

Shelly offers two LoRa add-on variants that share the same RPC API:

• Shelly LoRa Add-On — for Gen2/Gen3/Gen4 Plus devices
• Shelly Pro LoRa Add-On — for Shelly Pro devices

Both add-ons provide two-way RF communication using the LoRa radio protocol. This page documents the LoRa RPC namespace, which controls the radio layer (a singleton component with fixed id 100): radio configuration (band plan, frequency, bandwidth, etc.), radio-level status, and raw byte transmission. Differences between the two variants are called out inline in dedicated :::note Pro LoRa Add-On::: blocks.

For the secure, addressed, multi-instance protocol layered on top of the LoRa radio (AES-CCM authenticated encryption, unicast/multicast/broadcast, JSON-RPC over LoRa, replay protection), see the SheLr dynamic component documentation.

The LoRa namespace provides the methods:

• LoRa.SetConfig to update the LoRa component's configuration
• LoRa.GetConfig to obtain the LoRa component's configuration
• LoRa.GetStatus to obtain the LoRa component's status
• LoRa.SendBytes to send raw data over LoRa RF

Methods

LoRa.SetConfig

This method updates the configuration of the LoRa (radio) component.

Parameters:

Property	Type	Description
id	number	ID of the LoRa component instance (always 100)
config	object	Configuration that the method takes

Find more about the config properties in config section

Response:

Property	Type	Description
restart_required	boolean	true if the device must be restarted for the new configuration to take effect, false otherwise

An error is returned if the request can not be executed or failed.

info

LoRa.SetConfig only configures the radio layer (band plan, frequency, modulation, etc.). It does not accept SheLr settings (own address, encryption keys, accept mask). To configure SheLr use SheLr.SetConfig on a SheLr instance previously created with SheLr.Create.

Example: LoRa.SetConfig Example

LoRa.GetConfig

This method retrieves the configuration of the LoRa (radio) component.

Parameters:

Property	Type	Description
id	number	ID of the LoRa component instance (always 100)

Find more about the config properties in config section

Example: LoRa.GetConfig Example

LoRa.GetStatus

This method retrieves the status of the LoRa component.

Parameters:

Property	Type	Description
id	number	ID of the LoRa component instance (always 100)

Find more about the status properties in status section

Example: LoRa.GetStatus Example

LoRa.SendBytes

Sends raw data over LoRa RF.

Parameters:

Property	Type	Description
id	number	ID of the LoRa component instance (always 100)
data	string	Data to be sent (remark: data should be encoded in 'base64')

Response:

null on success; error if the request can not be executed or failed

info

LoRa.SendBytes transmits an unencrypted, unaddressed byte payload directly over LoRa RF. For secure, addressed communication use the SheLR protocol via SheLr.Send, SheLr.Call or SheLr.Notify.

Example: LoRa.SendBytes Example

Configuration

LoRa add-on can be enabled or disabled by setting device.addon_type parameter in Sys config. To enable Shelly LoRa Add-on, addon_type must be set to "LoRa". When add-on is enabled, device must be restarted and all related API will be accessible. To disable Shelly LoRa Add-on, parameter device.addon_type must be set to null, after disabling, the device must be restarted as well.

The configuration of the LoRa (radio) component shows the current settings of the LoRa add-on's radio layer. SheLr settings (own address, encryption keys, accept mask) live on each individual SheLr instance and are managed via SheLr.SetConfig / SheLr.GetConfig.

Parameters:

Property	Type	Description
id	number	ID of the LoRa component instance (always 100)
band_plan	string	RF band plan, possible settings: EU868, US915, BR915-928, AU915-928, the default is EU868, see info below
freq	number	Frequency in Hz, possible values: Value Description [863000000,865000000] EU868 band plan, Sub-band K [865000000,868000000] EU868 band plan, Sub-band L [868000000,868600000] EU868 band plan, Sub-band M [868700000,869200000] EU868 band plan, Sub-band N [869400000,869650000] EU868 band plan, Sub-band P [869700000,870000000] EU868 band plan, Sub-band Q [902000000,928000000] US915 band plan [915000000,928000000] BR915-928 band plan [915000000,926000000] AU915-928 band plan
bw	number	Bandwidth in kHz, for possible values see the table below
dr	number	Data rate (or spreading factor), possible values: [7, 12]
cr	number	Coding rate, possible values: [5, 8], corresponding to coding rates:["4:5", "4:8"]
plen	number	Preamble length, possible values: [6, 65535]
txp	number	Transmit power in dBm, possible values: [0, 14]
rx_enable	boolean	Enable/disable reception over RF optional, the default is enabled
fh	object	Frequency hopping settings (see info below)` Property Type Description enable boolean Enable/disable frequency hopping, the default is disabled (see info below) freqs array of numbers or empty array The list of hopping frequencies in Hz:

info

Band Plan policy:

• If Band plan is set to EU868, the frequency possible values should be used, like listed in freq: [863000000,870000000]
• If Band plan is set to US915, the frequency possible values should be used, like listed in freq: [902000000,928000000]
• If Band plan is set to BR915-928, the frequency possible values should be used, like listed in freq: [915000000,928000000]
• If Band plan is set to AU915-928, the frequency possible values should be used, like listed in freq: [915000000,926000000]

Pro LoRa Add-On

The Shelly Pro LoRa Add-On supports only the EU868 band plan. The US915, BR915-928 and AU915-928 band plans are not supported on Pro devices.

Possible bandwidth values depend on RF band plan.

RF Band Plan	EU868	US915	BR915-928	AU915-928
Bandwidth	125 and 250	125, 250 and 500	125, 250 and 500	125, 250 and 500

Pro LoRa Add-On

On the Shelly Pro LoRa Add-On only EU868 is supported, therefore only bandwidth 125 and 250 kHz are available.

info

Frequency hopping enable flag: enable:

• enable flag applies only to band plan US915, otherwise is discarded
• If band plan is set US915, enable flag should be set to true

info

Frequency hopping settings: fh, freqs

• fh settings apply only to band plan US915, otherwise are discarded
• The number of elements (frequencies) in the list (freqs) should be exactly 64
• If Band plan is set to US915, the frequency possible values in the list (freqs) should be in range: [902000000,928000000]
• Any next frequency in the list should be greater or less with 25000 kHz compared to previous one
• Frequencies in the list should be unique

Pro LoRa Add-On

The Shelly Pro LoRa Add-On does not support frequency hopping. The fh configuration object is not applicable since only EU868 is supported.

Status

The status of the LoRa add-on component contains the following properties:

Parameters:

Property	Type	Description
id	number	ID of the LoRa component instance (always 100)
bytes_sent	number	Number of bytes sent over LoRa RF channel
bytes_recd	number	Number of bytes received over LoRa RF channel
air_time_hr_ms	number	Time in milliseconds of the transmission time in the last 60 minutes
send_fails	number	Number of failed transmissions
max_payload_size	number	Maximum payload size in bytes for the current LoRa radio configuration. Sending data larger than this limit will result in an error
notx	object	Information in condition of limit_reached occurred and sending is not allowed (no object, if no such condition), applies for EU868 only Property Type Description started_at number Unix timestamp (in UTC) when condition of limit_reached occurred duration number Duration in seconds of sending not allowed period
fw_version	string	Firmware version
available_updates	object	Information about available updates(empty object, if no updates available). This information is automatically updated every 24 hours. Property Type Description stable object Shown only if stable update is available Property Type Description version string Version of the new firmware
update	object	Provides details of the active OTA update, if any. See the Note below Property Type Description progress number Progress of the update in percentages state string the update state Value Description started the update has started updating the update is in progress success the update has finished successfully error the update has finished with fail ts number Unix timestamp (in UTC) when progress and state were updated
flags	array of strings	Informational flags if any. Currently the following flag is supported: Value Description duty_cycle_limit It is listed when recommended transmission time has been reached in the last 60 minutes, applies for EU868 send_blocked Back-off sending period, sending is not allowed during this period, applies for US915 and BR915-928. For details see the table bellow lp_mode Low power mode is active. For more details see info below
errors	array of strings	Error if any. Currently the following errors are supported: Value Description limit_reached It is listed when 25% transmission time has been reached in the last 60 minutes, applies for EU868 addon_update_required Firmware has to be updated in order component to be operational ota_update_failed Firmware update has finished with fail addon_unavailable The LoRa add-on hardware is not currently attached / available

info

max_payload_size is the total LoRa radio payload capacity. When using the SheLr protocol, each frame includes a SheLr header (13 bytes), a payload type byte (1 byte), and an AES-CCM authentication tag (4 bytes) — 18 bytes of overhead in total. The effective user payload available for SheLr transmission functions is therefore max_payload_size - 18 bytes.

info

SheLr-related status (per-instance, replay counters, key-slot occupancy, etc.) is not part of LoRa.GetStatus. Use SheLr.GetStatus on the desired SheLr instance to query per-instance state.

Note: Object update is presented in the status only during active OTA update.

send_blocked flag depends on bandwidth

Bandwidth, kHz	125	250	500
Back-off sending period, seconds	20	10	10

Pro LoRa Add-On

The send_blocked flag applies only to US915 and BR915-928 band plans, which are not supported on the Pro variant. Therefore this flag will never appear on a Shelly Pro LoRa Add-On.

info

Low power mode: lp_mode

• Low power mode lp_mode can be activated when: band_plan is EU868, and freq is in range: [869700000,870000000] (sub channel Q), and txp is in range: [0, 7]
• Having low power mode active, transmission is unlimited, duty_cycle_limit and limit_reached will never be listed

Notifications

This notification is triggered when data is received over LoRa RF, sent by LoRa.SendBytes. It is emitted on the LoRa (radio) component (component: "lora:100").

• method: "NotifyEvent"
• event: "lora_received"

  Property	Type	Description
  data	string	Received data (remark: encoded in 'base64')
  rssi	number	RSSI of the received packet
  snr	number	SNR (signal / noise ratio) of the received packet
  tsu	number	LoRa add-on uptime in ms

For SheLR-level notifications (user_rx), see SheLr notifications.

Example: Notifications Example

Examples

Enable / Disable LoRa Add-on

Enable LoRa Add-on

Sys.SetConfig HTTP GET Request

http://192.168.33.1/rpc/Sys.SetConfig?config={"device":{"addon_type":"LoRa"}}

Sys.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"Sys.SetConfig","params":{"config":{"device":{"addon_type":"LoRa"}}}}' http://${SHELLY}/rpc

Sys.SetConfig Mos Request

mos --port ${PORT} call Sys.SetConfig '{"config":{"device":{"addon_type":"LoRa"}}}'

Response

Sys.SetConfig HTTP GET Response

{
  "restart_required": true
}

Sys.SetConfig Curl Response

{
  "id": 1,
  "src": "shelly1pmg3-dcda0ce0d36c",
  "params": {
    "restart_required": true
  }
}

Sys.SetConfig Mos Response

{
  "restart_required": true
}

Disable LoRa Add-on

Sys.SetConfig HTTP GET Request

http://192.168.33.1/rpc/Sys.SetConfig?config={"device":{"addon_type":null}}

Sys.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"Sys.SetConfig","params":{"config":{"device":{"addon_type":null}}}}' http://${SHELLY}/rpc

Sys.SetConfig Mos Request

mos --port ${PORT} call Sys.SetConfig '{"config":{"device":{"addon_type":null}}}'

Response

Sys.SetConfig HTTP GET Response

{
  "restart_required": true
}

Sys.SetConfig Curl Response

{
  "id": 1,
  "src": "shelly1pmg3-dcda0ce0d36c",
  "params": {
    "restart_required": true
  }
}

Sys.SetConfig Mos Response

{
  "restart_required": true
}

LoRa.SetConfig Example

LoRa.SetConfig HTTP GET Request

http://192.168.33.1/rpc/LoRa.SetConfig?id=100&config={"band_plan":"EU868","freq":865000000,"bw":125,"dr":7,"cr":5,"plen":8,"txp":14,"rx_enable":true,"fh":{"enable":false,"freqs":[]}}

LoRa.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"LoRa.SetConfig","params":{"id":100,"config":{"band_plan":"EU868","freq":865000000,"bw":125,"dr":7,"cr":5,"plen":8,"txp":14,"rx_enable":true,"fh":{"enable":false,"freqs":[]}}}}' http://${SHELLY}/rpc

LoRa.SetConfig Mos Request

mos --port ${PORT} call LoRa.SetConfig '{"id":100,"config":{"band_plan":"EU868","freq":865000000,"bw":125,"dr":7,"cr":5,"plen":8,"txp":14,"rx_enable":true,"fh":{"enable":false,"freqs":[]}}}'

Response

LoRa.SetConfig HTTP GET Response

{
  "restart_required": false
}

LoRa.SetConfig Curl Response

{
  "id": 1,
  "src": "shelly1pmg3-dcda0ce0d36c",
  "params": {
    "restart_required": false
  }
}

LoRa.SetConfig Mos Response

{
  "restart_required": false
}

LoRa.GetConfig Example

LoRa.GetConfig HTTP GET Request

http://192.168.33.1/rpc/LoRa.GetConfig?id=100

LoRa.GetConfig Curl Request

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

LoRa.GetConfig Mos Request

mos --port ${PORT} call LoRa.GetConfig '{"id":100}'

Response

LoRa.GetConfig HTTP GET Response

{
  "id": 100,
  "band_plan": "EU868",
  "freq": 865000000,
  "bw": 125,
  "dr": 7,
  "cr": 5,
  "plen": 8,
  "txp": 14,
  "rx_enable": true,
  "fh": {
    "enable": false,
    "freqs": []
  }
}

LoRa.GetConfig Curl Response

{
  "id": 1,
  "src": "shelly1pmg3-dcda0ce0d36c",
  "params": {
    "id": 100,
    "band_plan": "EU868",
    "freq": 865000000,
    "bw": 125,
    "dr": 7,
    "cr": 5,
    "plen": 8,
    "txp": 14,
    "rx_enable": true,
    "fh": {
      "enable": false,
      "freqs": []
    }
  }
}

LoRa.GetConfig Mos Response

{
  "id": 100,
  "band_plan": "EU868",
  "freq": 865000000,
  "bw": 125,
  "dr": 7,
  "cr": 5,
  "plen": 8,
  "txp": 14,
  "rx_enable": true,
  "fh": {
    "enable": false,
    "freqs": []
  }
}

LoRa.GetStatus Example

LoRa.GetStatus HTTP GET Request

http://192.168.33.1/rpc/LoRa.GetStatus?id=100

LoRa.GetStatus Curl Request

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

LoRa.GetStatus Mos Request

mos --port ${PORT} call LoRa.GetStatus '{"id":100}'

Response

LoRa.GetStatus HTTP GET Response

{
  "id": 100,
  "bytes_sent": 69280,
  "bytes_recd": 44,
  "air_time_hr_ms": 893342,
  "send_fails": 0,
  "max_payload_size": 51,
  "fw_version": "1.11.1",
  "available_updates": {
    "stable": {
      "version": "1.11.2"
    }
  },
  "update": {
    "progress": 95,
    "state": "updating",
    "ts": 1739763916.762901
  },
  "errors": [
    "addon_update_required"
  ]
}

LoRa.GetStatus Curl Response

{
  "id": 1,
  "src": "shelly1pmg3-dcda0ce0d36c",
  "params": {
    "id": 100,
    "bytes_sent": 69280,
    "bytes_recd": 44,
    "air_time_hr_ms": 893342,
    "send_fails": 0,
    "max_payload_size": 51,
    "fw_version": "1.11.1",
    "available_updates": {
      "stable": {
        "version": "1.11.2"
      }
    },
    "update": {
      "progress": 95,
      "state": "updating",
      "ts": 1739763916.762901
    },
    "errors": [
      "addon_update_required"
    ]
  }
}

LoRa.GetStatus Mos Response

{
  "id": 100,
  "bytes_sent": 69280,
  "bytes_recd": 44,
  "air_time_hr_ms": 893342,
  "send_fails": 0,
  "max_payload_size": 51,
  "fw_version": "1.11.1",
  "available_updates": {
    "stable": {
      "version": "1.11.2"
    }
  },
  "update": {
    "progress": 95,
    "state": "updating",
    "ts": 1739763916.762901
  },
  "errors": [
    "addon_update_required"
  ]
}

LoRa.SendBytes Example

LoRa.SendBytes HTTP GET Request

http://192.168.33.1/rpc/LoRa.SendBytes?id=100&data="MDEyMzQ1Njc4OQ=="

LoRa.SendBytes Curl Request

curl -X POST -d '{"id":1,"method":"LoRa.SendBytes","params":{"id":100,"data":"MDEyMzQ1Njc4OQ=="}}' http://${SHELLY}/rpc

LoRa.SendBytes Mos Request

mos --port ${PORT} call LoRa.SendBytes '{"id":100,"data":"MDEyMzQ1Njc4OQ=="}'

Response

LoRa.SendBytes HTTP GET Response

null

LoRa.SendBytes Curl Response

{
  "id": 1,
  "src": "shelly1pmg3-dcda0ce0d36c",
  "params": null
}

LoRa.SendBytes Mos Response

null

Notifications Example

When data is received over LoRa RF sent by LoRa.SendBytes:

Notify data is received over LoRa RF.

{
   "src": "shelly1pmg3-dcda0ce0d36c",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266595.43,
      "events": [
        {
          "component": "lora:100",
          "id": 100,
          "event": "lora_received",
          "ts": 1631266595.43,
          "info": {
                "data": "MDEyMzQ1Njc4OQ==",
                "rssi": -70,
                "snr": 8,
                "tsu": 16212139809
              }
        }
      ]
   }
}

For an example of the SheLR-level user_rx notification (triggered by SheLr.Send), see SheLr notifications example.