Skip to main content
Version: 1.0

Shelly Pro LoRa Add-On

Shelly Pro LoRa add-on provides two-way RF communication using LoRa radio protocol for Shelly Pro devices. It uses LoRa as RPC namespace and provides the methods:

Methods​

LoRa.SetConfig​

This method updates the configuration of the LoRa component.

Parameters:

PropertyTypeDescription

id

number

ID of the LoRa component instance

config

object

Configuration that the method takes

Find more about the config properties in config section

Response:

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

Example: LoRa.SetConfig Example​

LoRa.GetConfig​

This method retrieves the configuration of the LoRa component.

Parameters:

PropertyTypeDescription

id

number

ID of the LoRa component instance

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:

PropertyTypeDescription

id

number

ID of the LoRa component instance

Find more about the status properties in status section

Example: LoRa.GetStatus Example​

LoRa.SendBytes​

Sends raw data over LoRa RF.

Parameters:

PropertyTypeDescription

id

number

ID of the LoRa component instance

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

Example: LoRa.SendBytes Example​

LoRa.Send​

Sends data over LoRa RF using SheLR. For more details see info below.

Parameters:

PropertyTypeDescription

id

number

ID of the LoRa component instance

lr_addr

string

The address of recipient in LoRa network as hexadecimal string

tx_key

string

The encryption key, optional. See detailed info below

tx_key_id

number

The encryption key index, possible values: [1,3], optional. See detailed info below

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 RF using SheLR:

  • LoRa RF using SheLR gives more benefits of using LoRa: more advanced security based on AES-CCM cryptography, unicast, multicast, broadcast communication
  • Using LoRa RF over SheLR should be considered preferable way compared to LoRa.SendBytes
info

The encryption key:

  • The cryptography keys should be encoded in 'base64'
  • The size of the keys should be 16 bytes (128 bit key)
  • To generate keys and encode them to base64 the following command could be used:

openssl rand -base64 16 (it works on Linux, macOS and Windows)

  • If tx_key or tx_key_id are not provided when calling LoRa.Send, the one from LoRa.SetConfig will be used for encryption
  • If both tx_key and tx_key_id are provided an error will be returned as mutual exclusive
info

The address of recipient lr_addr:

  • The size of the address should be 8 symbols (4 bytes), represented as hexadecimal string
  • The address could be "FFFFFFFF" for broadcast sending to all devices in LoRa network

Example: LoRa.Send 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 component shows the current settings of the LoRa add-on and Shelly Long-Range Protocol (SheLR).

Parameters:

PropertyTypeDescription

id

number

ID of the LoRa component instance

band_plan

string

RF band plan, currently supported and the default is EU868, see info below

freq

number

Frequency in Hz, possible values:

ValueDescription

[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

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

shelr

object

SheLR settings (see info below)`

PropertyTypeDescription

lr_addr

string or null

Device LoRa address as hexadecimal string

tx_key_id

number

The encryption key index, possible values: [1,3] optional

key1

string or null

The cryptography key #1 optional

key2

string or null

The cryptography key #2 optional

key3

string or null

The cryptography key #3 optional

accept

array of strings or empty array or null

The list of supported payload types:

ValueDescription

user

user payload type

info

Band Plan policy:

  • If Band plan is set to EU868, the frequency possible values should be used, like listed in freq: [863000000,870000000]

Possible bandwidth values depend on RF band plan.

RF Band PlanEU868
Bandwidth125 and 250
info

SheLR settings:

The cryptography keys:

  • The cryptography keys should be encoded in 'base64'
  • The size of the keys should be 16 bytes (128 bit key)
  • To generate keys and encode them to base64 the following command could be used:

openssl rand -base64 16 (it works on Linux, macOS and Windows)

  • If tx_key_id is not provided during configuration, it should be provided when LoRa.Send method is being called, in order encryption to be done
  • Although, configuring cryptography keys are optional, at least 1 from the list of 3 should be provided, in order cryptography to be done
  • If null is provided for key1, key2 and key3, the current settings will be erased

Device LoRa address lr_addr:

  • The size of the address should be 8 symbols (4 bytes), represented as hexadecimal string
  • The address could not be "FFFFFFFF" (broadcast)
  • If null is provided the last 4 bytes of Wi-Fi MAC will be used as lr_addr

Payload type:

  • Currently in the list of payload types - accept, the supported one is: user

Status​

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

Parameters:

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

shelr

object

Provides information if encryption keys are set or not

PropertyTypeDescription

key1

boolean

true - key1 is set, false - not set (it is null)

key2

boolean

true - key2 is set, false - not set (it is null)

key3

boolean

true - key3 is set, false - not set (it is null)

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 below

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, applies for EU868

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:

ValueDescription

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

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

send_blocked flag depends on bandwidth

Bandwidth, kHz125250500
Back-off sending period, seconds201010
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.

  • 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

This notification is triggered when data is received over LoRa RF using SheLR, sent by LoRa.Send.

  • method: "NotifyEvent"
    PropertyTypeDescription

    data

    string

    Received data (remark: encoded in 'base64')

    sender

    string

    Sender address

    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: Notifications Example​

Examples​

Enable / Disable LoRa Add-on​

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={"band_plan":"EU868","freq":865000000,"bw":125,"dr":7,"cr":5,"plen":8,"txp":14,"rx_enable":true,"fh":{"enable":false,"freqs":[]},"shelr":{"lr_addr":"000000BA","tx_key_id":2,"key1":null,"key2":"MTIzNDU2Nzg5MEFCQ0RFRg==","key3":"cRIzRJVmd4iZqrvM3e7/AA==","accept":["user"]}}

Response

{
  "restart_required": false
}

LoRa.GetConfig Example​

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

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": []
  },
  "shelr": {
    "lr_addr": "000000BA",
    "tx_key_id": 2,
    "accept": [
      "user"
    ]
  }
}

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

LoRa.Send Example​

http://192.168.33.1/rpc/LoRa.Send?id=100&lr_addr="00000063"&tx_key="MTIzNDU2Nzg5MEFCQ0RFRg=="&data="MTA="

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

When data is received over LoRa RF using SheLR, sent by LoRa.Send:​

Notify data is received over LoRa RF using SheLR.
{
   "src": "shelly1pmg3-dcda0ce0d36c",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266595.43,
      "events": [
        {
          "component": "lora:100",
          "id": 100,
          "event": "user_rx",
          "ts": 1631266595.43,
          "info": {
                "data": "MTA=",
                "sender": 23,
                "rssi": -70,
                "snr": 8,
                "tsu": 16212139809
              }
        }
      ]
   }
}