Shelly LoRa Add-On

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

• LoRa.SetConfig to update the component's configuration
• LoRa.GetConfig to obtain the component's configuration
• LoRa.GetStatus to obtain the component's status
• LoRa.SendBytes to send raw data over LoRa RF sendbytes
• LoRa.Send to send data over LoRa RF using Shelly Long-Range Protocol (SheLR) send

Methods

LoRa.SetConfig

This method updates the configuration of the LoRa component.

Parameters:

Property	Type	Description
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:

Property	Type	Description
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:

Property	Type	Description
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:

Property	Type	Description
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:

Property	Type	Description
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:

Property	Type	Description
id	number	ID of the LoRa component instance
band_plan	string	RF band plan, possible settings: EU868, US915, BR915-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
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:
shelr	object	SheLR settings (see info below)` Property Type Description 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: Value Description 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]
• 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]

Possible bandwidth values depend on RF band plan.

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

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

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:

Property	Type	Description
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 Property Type Description 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. 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

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

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"

  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

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

• method: "NotifyEvent"

  Property	Type	Description
  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

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":[]},"shelr":{"lr_addr":"000000BA","tx_key_id":2,"key1":null,"key2":"MTIzNDU2Nzg5MEFCQ0RFRg==","key3":"cRIzRJVmd4iZqrvM3e7/AA==","accept":["user"]}}

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":[]},"shelr":{"lr_addr":"000000BA","tx_key_id":2,"key1":null,"key2":"MTIzNDU2Nzg5MEFCQ0RFRg==","key3":"cRIzRJVmd4iZqrvM3e7/AA==","accept":["user"]}}}}' 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":[]},"shelr":{"lr_addr":"000000BA","tx_key_id":2,"key1":null,"key2":"MTIzNDU2Nzg5MEFCQ0RFRg==","key3":"cRIzRJVmd4iZqrvM3e7/AA==","accept":["user"]}}}'

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

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

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

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

LoRa.Send Example

LoRa.Send HTTP GET Request

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

LoRa.Send Curl Request

curl -X POST -d '{"id":1,"method":"LoRa.Send","params":{"id":100,"lr_addr":"00000063","tx_key":"MTIzNDU2Nzg5MEFCQ0RFRg==","data":"MTA="}}' http://${SHELLY}/rpc

LoRa.Send Mos Request

mos --port ${PORT} call LoRa.Send '{"id":100,"lr_addr":"00000063","tx_key":"MTIzNDU2Nzg5MEFCQ0RFRg==","data":"MTA="}'

Response

LoRa.Send HTTP GET Response

null

LoRa.Send Curl Response

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

LoRa.Send 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",
          "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
              }
        }
      ]
   }
}