Skip to main content
Version: 1.0

Shelly LoRa Add-On

Shelly LoRa add-on provides two way RF communication using LoRa radio protocol.

Methods​

LoRa.SetConfig​

Find more about the config properties in config section

LoRa.GetConfig​

Find the response properties in config section

LoRa.GetStatus​

Find the response properties in status section

LoRa.SendBytes​

Find more about send data properties in sendbytes section

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 disable device must be restarted as well.

The configuration of the LoRa component shows the current settings of the LoRa add-on.

Properties:

PropertyTypeDescription

id

number

ID of the LoRa component instance

freq

number

Frequency in Hz, possible values:

ValueDescription

[863000000,865000000]

EU Region, Sub-band K

[865000000,868000000]

EU Region, Sub-band L

[868000000,868600000]

EU Region, Sub-band M

[868700000,869200000]

EU Region, Sub-band N

[869400000,869650000]

EU Region, Sub-band P

[869700000,870000000]

EU Region, Sub-band Q

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)

Possible bandwidth values depend on RF region.

RF RegionEU
Bandwidth125 and 250

SetConfig:​

LoRa.SetConfig Example

GetConfig:​

LoRa.GetConfig Example

Status​

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

Properties:

PropertyTypeDescription

id

number

ID of the LoRa component instance

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

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.

PropertyTypeDescription

stable

object

Shown only if stable update is available

PropertyTypeDescription

version

string

Version of the new firmware

update

object

Provides details of the active OTA update, if any. See the Note bellow

PropertyTypeDescription

progress

number

Progress of the update in percentages

state

string

the update state

ValueDescription

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:

ValueDescription

duty_cycle_limit

It is listed when recommended transmission time has been reached in the last 60 minutes

errors

array of strings

Error if any. Currently the following errors are supported:

ValueDescription

limit_reached

It is listed when 25% transmission time has been reached in the last 60 minutes

addon_update_required

Firmware has to be updated in order component to be operational

ota_update_failed

Firmware update has finished with fail

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

GetStatus: LoRa.GetStatus Example​

Send​

Sends data over LoRa RF.

Properties:

PropertyTypeDescription

id

number

ID of the LoRa component instance

data

string

Data to be sent. (remark: data should be encoded in 'base64')

Send: LoRa.SendBytes Example​

Notifications​

This notification is triggered when data is received over LoRa RF.

  • method: "NotifyEvent"
    PropertyTypeDescription

    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

Example Notification​

Example Notification

Examples​

Enable / Disable LoRa Add-on examples​

Enable LoRa Add-on​

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

Response

{
  "restart_required": true
}

Disable LoRa Add-on​

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

Response

{
  "restart_required": true
}

LoRa.SetConfig example​

http://192.168.33.1/rpc/LoRa.SetConfig?id=100&config={"txp":12}

Response

{
  "restart_required": false
}

LoRa.GetConfig example​

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

Response

{
  "id": 100,
  "freq": 865000000,
  "bw": 12,
  "dr": 5,
  "plen": 8,
  "txp": 14
}

LoRa.GetStatus example​

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

Response

{
  "id": 100,
  "bytes_sent": 69280,
  "bytes_recd": 44,
  "air_time_hr_ms": 893342,
  "send_fails": 0,
  "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​

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

Response

null

Notifications example​

When data is received over LoRa RF:​

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",
          "ts": 1631266595.43,
          "info": {
                "data": "MDEyMzQ1Njc4OQ==",
                "rssi": -70,
                "snr": 8,
                "tsu": 16212139809
              }
          ],
        }
      ]
   }
}