Shelly Script Language Features

Shelly Scripts run on a modified version of Espruino. While the previous JS interpreter running on Shelly supported a subset of JavaScript, Espruino interpreter is closer to the JavaScript standard.

The interpreter is feature compatible with one it's replacing. There should be no visible problem with scripts written and working before v 1.0.

More information about the API for managing Scripts on a Shelly device can be found here.

Supported

• global scope variables, let, var
• function binding
• String object
• Number object
• Function
• Array object
• Math object
• Date object
• new, delete operators
• Object.keys
• Exceptions

Not supported

• Hoisting
• Classes as in ES6, function prototypes are supported
• Promises and async functions
• ArrayBuffer

Specifics

• arguments.length will return number of arguments passed if more than defined, or number of defined, if the number of arguments passed to function are less than defined
• delete operator works without brackets only
• Function supports an additional method replaceWith

For detailed information on which methods are supported you can consult Espruino documentation. Please consider that we are only using the language interpreter and many of the system and hardware specific Espruino functions are not and will never be implemented in Shelly.

Strings

info

TL;DR

Strings support encoding bytes in the form \xHH escape sequence. Strings don't support encoding using \u escape sequence. UTF-8 works.

String encoding

String literals and objects in regular JS implementations use 16-bit words for character storage and are treated as UTF16-encoded text. In contrast, Shelly Scripts use byte arrays for string storage. This difference is not noticeable if strings are used to hold plain ASCII-encoded text but becomes important when strings are used to store characters outside of the ASCII set or arbitrary binary data.

The philosophy implemented in Shelly Scripts is to allow arbitrary binary data to be stored in strings and use UTF8 whenever encoding to byte streams or decoding input is involved. We thus optimize for memory usage, provide backward compatibility and Unicode support (in the form of UTF8 encoding) at the cost of some differences with standard JavaScript.

String literals

Script source code must be UTF8-encoded. String literals can thus contain Unicode text encoded in the UTF8 source. It is possible to encode arbitrary bytes in string literals using the \xHH escape sequence, where HH is the hexadecimal representation of a byte. Note, that this differs from regular JS implementations where the value is interpreted as a Unicode codepoint between 0 and 255.

String literals do not support the \uHHHH and \u{HHHHHH} escapes. Placing Unicode text in literals should be done by just using it's UTF8 representation in the source code.

Examples:

// a 4-byte long binary blob
let some_bytes = "\x00\x0a\xa0\xaa";
// UTF8-encoded Cyrillic string
let some_name = "Шели";

// UTF8 sequences as raw bytes
let an_emoji = "\xF0\x9F\x98\xB9"

// the following is not supported
let no_emoji = "\u{1F4A9}";
let a_letter = "\u0448";

Strings in JSON

JSON documents are UTF8-encoded, as defined in RFC 8259. Shelly Scripts follow the standard rules for parsing and serializing json.

• JSON.parse()
  • expects UTF8-encoded input and will raise an exception when users attempt to parse an invalid UTF8 string or strings containing invalid \uHHHH\uHHHH surrogate pairs
  • \uHHHH escapes and surrogate pairs encoded as \uHHHH\uHHHH are transcoded to their UTF8 representation in the corresponding string variable.
• JSON.stringify()
  • encodes control characters as required by RFC 8259
  • will raise an exception if it is asked to stringify a string with invalid UTF-8 contents
  • will return a valid UTF-8 encoded string

To transfer binary data with JSON, use atob() and btoa() to encode the binary blobs to base-64 and back.

Shelly APIs

Shelly.call()

To interact with the local device, JS code can invoke RPC methods using a "local" RPC channel:

Shelly.call(method, params[, callback[, userdata]]) -> undefined

Property	Type	Description
method	string	Name of the method to invoke
params	object or string	Parameters
callback	function or null or undefined	If it is a function, will be invoked when the call completes Property Type Description result object or null or undefined Result from the callback (null if the method does not return any data, undefined if the call resulted in an error) error_code number 0 if there was no error or non-zero if an error occurred error_message string More information on the error if one occurred userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• This method doesn't return a value. If invoked with invalid arguments the script is aborted.

Shelly.addEventHandler() and Shelly.addStatusHandler()

These methods allow JS code to react to internal events. These are identical to the events reported through RPC notifications as NotifyStatus and NotifyEvent. The signatures are identical:

Shelly.addEventHandler(callback[, userdata]) -> subscription_handle

Shelly.addStatusHandler(callback[, userdata]) -> subscription_handle

Property	Type	Description
callback	function	Will be invoked when the respective event occurs Property Type Description event_data object Identical in contents to what NotifyStatus and NotifyEvent emit. userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• Return value: On success, returns a handle which can be used to remove the listener with Shelly.removeEventHandler(subscription_handle) or Shelly.removeStatusHandler(subscription_handle) respectively. If invoked with invalid arguments the script is aborted.

Shelly.removeEventHandler() and Shelly.removeStatusHandler()

Shelly.removeEventHandler(subscription_handle) -> boolean

Shelly.removeStatusHandler(subscription_handle) -> boolean

Property	Type	Description
subscription_handle	number	The handle returned by previously called corresponding addEventHandler or addStatusHandler

• Return value: Returns true if the handle is found and the listener is removed, false if handle is not found or undefined if the handle is invalid.

Shelly.emitEvent()

This method creates an event which is broadcasted to all persistent RPC channels.

Shelly.emitEvent(name, data) -> undefined

Property	Type	Description
name	string	Name of the event
data	scalar or object or array	payload of the event. Any valid JSON value is allowed. undefined and function objects are not supported.

• This method doesn't return a value. If invoked with invalid arguments the script is aborted.

Shelly.emitEvent() example

Shelly.emitEvent("this_happened", {"what":"when", "why": 42});

The above code will trigger a notification to be emitted:

{
    "component": "script:1",
    "id": 1,
    "event": "this_happened",
    "data": {
        "why": 42,
        "what": "when"
    },
    "ts": 1657878122.44
}

Shelly.getComponentConfig()

Shelly.getComponentConfig(type_or_key, id) -> object or null

Property	Type	Description
type_or_key	string	Component type or key "component:id"). Component type must be in lowercase.
id	number	Numeric id of multi instance components if only type is specified or absent for single instance components

• Return value: an object with the current configuration of the component, null if component was not found. If invoked with invalid arguments the script is aborted.

Shelly.getComponentConfig() example

let time_server = Shelly.getComponentConfig("sys").sntp.server;
print("My time comes from", time_server);

Shelly.getComponentStatus()

Shelly.getComponentStatus(type_or_key, id) -> object or null

Property	Type	Description
type_or_key	string	Component type or key("component:id"). Component type must be in lowercase.
id	number	Numeric id of multi instance components if only type is specified or absent for single instance components

• Return value: an object with the current status of the component, null if component was not found. If invoked with invalid arguments the script is aborted.

Shelly.emitEven() example

let uptime = Shelly.getComponentStatus("sys").uptime;
print("I was awake", uptime, "seconds");

Shelly.getDeviceInfo()

• Return value: the DeviceInfo object.

Shelly.getCurrentScriptId()

• Return value: number - the id of the current script.

Utilities

Timer

Timer global object can be used for one-shot delayed code execution, or to run some code periodically.

Timer.set()

To arm a timer, use:

Timer.set(period, repeat, callback[, userdata]) -> timer_handle

Property	Type	Description
period	number	In milliseconds
repeat	boolean	If true, the timer will fire periodically, otherwise the callback will be invoked only once
callback	function	To be invoked when the timer fires Property Type Description userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• Return value: On success, returns a handle which can be used to stop the timer with Timer.clear(timer_handle). If invoked with invalid arguments the script is aborted.

Timer.clear()

To stop the execution of a timer, use:

Timer.clear(timer_handle) -> boolean or undefined

Property	Type	Description
timer_handle	handle	handle previously returned by Timer.set()

• Return value: true if the timer was armed and destroyed, false if no such timer existed orundefined if the given timer_handle was not valid.

btoh()

To convert a string to hexadecimal representation, use:

btoh(data) -> string

Property	Type	Description
data	string	The string to convert

• Return value: A string that represents every byte of data as 2 heaxadecimal digits.

MQTT support

MQTT

MQTT global object provides MQTT functionality. JS code can monitor connection status, subscribe and publish to miltiple topics.

MQTT.isConnected()

• Return value: true if device is connected to a MQTT broker or false otherwise.

MQTT.subscribe()

Subscribes to a topic on the MQTT broker.

MQTT.subscribe(topic, callback[, userdata]) -> undefined

Property	Type	Description
topic	string	The topic filter to subscribe to
callback	function	Function to be called when a message is published on the topic Property Type Description topic string The topic that we subscribed to message string Message received on the topic userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• This method doesn't return a value. It will throw an exception if:
  • Parameters topic and callback are missing or not of the correct type
  • MQTT is disabled
  • The limit for number of subscriptions has been reached
  • topic is not a valid topic filter

If a subscription with the same topic filter already exists, its callback and user data will be replaced by the ones given.

If an incoming message matches multiple subscriptions, we invoke the callback of the first match only. Subscriptions are ordered in the sequence they are added by the script.

MQTT.unsubscribe()

Unsubscribes from a topic previously subscribed, can be called only for topics subscribed in the same script.

MQTT.unsubscribe(topic) -> boolean

Property	Type	Description
topic	string	The topic to unsubscribe from

• Return value: true if unsubscribed or false if subscription to the topic does not exist. The script is aborted if the argument is not valid.

MQTT.publish()

Publishes a message to a topic.

MQTT.publish(topic, message[, qos[, retain]]) -> boolean

Property	Type	Description
topic	string	The topic to publish
message	string	Тhe message to publish
qos	integer	Can be 0 - at most once, 1 - at least once or 2 exactly once. Default is 0
retain	boolean	If true the message is retained by the broker and delivered when subscribers are activated. Default is false

• Return value: true if the message was enqueued for publishing, false if MQTT is currently disconnected. In the latter case, the message is dropped.

MQTT.setConnectHandler()

Registers a handler for the MQTT connection established event.

MQTT.setConnectHandler(callback[, userdata])

Property	Type	Description
callback	function	Function to be called when event is received Property Type Description userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• This method doesn't return a value. If invoked with invalid arguments the script is aborted.

MQTT.setDisconnectHandler()

Registers a handler for the MQTT connection closed event.

MQTT.setDisconnectHandler(callback[, userdata])

Property	Type	Description
callback	function	Function to be called when event is received Property Type Description userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• This method doesn't return a value. If invoked with invalid arguments the script is aborted.

Bluetooth support

Since version 0.12.0

caution

Bluetooth support in scripting is experimental. The API is subject to change.

A global BLE object provides a namespace for for various different layers of the bluetooth protocol stack. Shelly devices currently support the scanner role.

BLE.Scanner

The Scanner object provides access to functionality related to the discovery of bluetooth devices. It allows the script to start a scan and listen for scan events. It defines the following constants:

• Scan events passed to subscribers:

  • BLE.Scanner.SCAN_START = 0;
  • BLE.Scanner.SCAN_STOP = 1;
  • BLE.Scanner.SCAN_RESULT = 2;

• duration_ms value for perpetual scanning:

  • BLE.Scanner.INFINITE_SCAN = -1;

note

Processing advertisement packets can be very resource intensive, especially in environments with many broadcasters and advertisers. It is recommended that scripts filter advertisement data for specific devices or device types to prevent memory and bandwidth starvation.

note

Since version 1.0.0 the scanner will silence identical scan results for a 3-second window. Scripts which have subscribed for scan events will receive the first result, but any results from the same MAC, ADV packet payload and SCAN_RESP packet payload will be ignored and will not invoke the event handler for the next 3 seconds. This is done to mitigate the risk of resource starvation which a high rate of scan results may cause.

BLE.Scanner.Subscribe()

Subscribes for scan events and register a listener. A script must subscribe in order to receive events, can subscribe at any time, regardless of the status of the scan or previous subscription. Only one subscription can be active in a script and previous subscriptions are replaced by a new one.

BLE.Scanner.Subscribe(callback[, userdata]) -> undefined

Property	Type	Description
callback	function or null	Function invoked for each scan event. Specify null to unsubscribe. Property Type Description event number the scan event, can be one of BLE.Scanner.SCAN_START, BLE.Scanner.SCAN_STOP or BLE.Scanner.SCAN_RESULT result object or null scan result object for BLE.Scanner.SCAN_RESULT, null for BLE.Scanner.SCAN_START and BLE.Scanner.SCAN_STOP Property Type Description addr string address of the advertising device addr_type number type of the device address, can be one of BLE.GAP_ADDRESS_TYPE_* advData string advertisement data scanRsp string scan response for active scans; empty string for passive scans or when missing rssi number received signal strength indicator flags number or undefined the flags entry of the advertising data, if present local_name string or undefined long or short name of the device, if present in the advertising data manufacturer_data object or undefined the manufacturer data entry of the advertising data, if present. Key is the assigned number of the manufacturer and value is the associated data service_uuids array or undefined list of service UUIDs advertised by the device, if present service_data object or undefined keys are service UUIDs and values contain the associated service data, if present tx_power_level number or undefined transmitted power level of the packet, if present userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• This method doesn't return a value. If invoked with invalid arguments the script is aborted.

BLE.Scanner.Start()

Starts a scan and optionally subscribe for scan events.

Scan options allow tuning for scan timings, but some restrictions apply:

• scan window cannot be longer than 1/3 of scan interval
• the maximum scan window is 50 ms, but 30 ms seems to be optimal
• duration must be at least 3 scan intervals long

If these conditions are not met scanning will not start. In the future, some of these options may not be tunable or the device may choose to modify them for performance and compatibility with other firmware features. It is best to use defaults.

To run a perpetual scan, invoke with a single option: {duration_ms: BLE.Scanner.INFINITE_SCAN}.

BLE.Scanner.Start(options[, callback[, userdata]]) -> object or null

Property	Type	Description
options	object	object with scan options. All options are optional and may be omitted, substituting with defaults. Property Type Description duration_ms number duration of the scan in ms, BLE.Scanner.INFINITE_SCAN for perpetual (continuous) scan active boolean start an active scan if true, or passive if false interval_ms number scan interval in ms window_ms number scan window in ms
callback	function	Function invoked for each scan event. If specified the call will also subscribe for scan events. Property Type Description event number the scan event, can be one of BLE.Scanner.SCAN_START, BLE.Scanner.SCAN_STOP or BLE.Scanner.SCAN_RESULT result object or null scan result object for BLE.Scanner.SCAN_RESULT, null for BLE.Scanner.SCAN_START and BLE.Scanner.SCAN_STOP Property Type Description addr string address of the advertising device addr_type number type of the device address, can be one of BLE.GAP_ADDRESS_TYPE_* advData string advertisement data scanRsp string scan response for active scans; a zero-length string for passive scans or when missing rssi number received signal strength indicator flags number the flags entry of the advertising data, if present local_name string long or short name of the device, if present in the advertising data manufacturer_data object the manufacturer data entry of the advertising data, if present. Key is the assigned number of the manufacturer and value is the associated data service_uuids array list of service UUIDs advertised by the device, if present service_data object keys are service UUIDs and values contain the associated service data, if present tx_power_level number transmitted power level of the packet, if present userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• Return value: object with the options of the started scan or null if start failed. Start will fail also if there is a scan in progress. If invoked with invalid arguments the script is aborted.

BLE.Scanner.Stop()

Stops a running scan. Only the script that started the scan can stop it.

• Return value: true if scan is successfully stopped or false if there is an error.

BLE.Scanner.isRunning()

• Return value: true if currently there is a running scan or false otherwise.

BLE.Scanner.GetScanOptions()

• Return value: object with the options of the running scan if there is one or the default options otherwise.

BLE.GAP

The GAP object is responsible for the GAP layer of the bluetooth protocol. It provides helper functions for parsing advertisement data. It defines the following constants:

• BLE.GAP.ADDRESS_TYPE_PUBLIC = 0x1;
• BLE.GAP.ADDRESS_TYPE_RANDOM_STATIC = 0x2;
• BLE.GAP.ADDRESS_TYPE_RANDOM_NON_RESOLVABLE = 0x3;
• BLE.GAP.ADDRESS_TYPE_RANDOM_RESOLVABLE = 0x4;
• BLE.GAP.EIR_FLAGS = 0x1;
• BLE.GAP.EIR_SERVICE_16_INCOMPLETE = 0x2;
• BLE.GAP.EIR_SERVICE_16 = 0x3;
• BLE.GAP.EIR_SERVICE_32_INCOMPLETE = 0x4;
• BLE.GAP.EIR_SERVICE_32 = 0x5;
• BLE.GAP.EIR_SERVICE_128_INCOMPLETE = 0x6;
• BLE.GAP.EIR_SERVICE_128 = 0x7;
• BLE.GAP.EIR_SHORT_NAME = 0x8;
• BLE.GAP.EIR_FULL_NAME = 0x9;
• BLE.GAP.EIR_TX_POWER_LEVEL = 0xA;
• BLE.GAP.EIR_DEVICE_ID = 0x10;
• BLE.GAP.EIR_SERVICE_DATA_16 = 0x16;
• BLE.GAP.EIR_SERVICE_DATA_32 = 0x20;
• BLE.GAP.EIR_SERVICE_DATA_128 = 0x21;
• BLE.GAP.EIR_URL = 0x24;
• BLE.GAP.EIR_MANUFACTURER_SPECIFIC_DATA = 0xff;

BLE.GAP.parseName()

Parses device name from advertisement data or scan response.

BLE.GAP.parseName(data) -> string

Property	Type	Description
data	string	data to parse, should be either advertisment data or scan response.

• Return value: extracted name, may be empty string if data is not available. If invoked with invalid arguments the script is aborted.

BLE.GAP.parseManufacturerData()

Parses manufacturer data from advertisement data or scan response.

BLE.GAP.parseManufacturerData(data) -> string

Property	Type	Description
data	string	data to parse, should be either advertisment data or scan response.

• Return value: extracted data, may be empty string if data is not available. If invoked with invalid arguments the script is aborted.

BLE.GAP.ParseDataByEIRType()

Parses data for specified EIR type (Extended Inquiry Response) from advertisement data or scan response.

BLE.GAP.ParseDataByEIRType(data, type) -> string

Property	Type	Description
data	string	data to parse, should be either advertisment data or scan response.
type	number	EIR type, should be one of the defined constants.

• Return value: extracted data, may be empty string if data is not available. If invoked with invalid arguments the script is aborted.

BLE.GAP.HasService()

Searches for specified service UUID in the advertisement data or scan response.

BLE.GAP.HasService(data, uuid) -> boolean

Property	Type	Description
data	string	data to parse, should be either advertisment data or scan response.
uuid	string	service UUID to check.

• Return value: true if advertisement data or scan response lists the specified service uuid or false otherwise. If invoked with invalid arguments the script is aborted.

BLE.GAP.ParseServiceData()

Parses service data string for the specified service UUID if present in the advertisement data or scan response.

BLE.GAP.ParseServiceData(data, uuid) -> string

Property	Type	Description
data	string	data to parse, should be either advertisment data or scan response.
uuid	string	service UUID to check.

• Return value: extracted data, may be empty string if data is not available. If invoked with invalid arguments the script is aborted.

note

UUIDs can be 16, 32 or 128 bits. They are represented by hexadecimal strings of the correponding length with lowercase hexadecimal digits. 128-bit UUIDS are represented in format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.

HTTP handlers

HTTPServer

HTTPServer is a global object which allows a script to register handlers to incoming HTTP requests on specific to the script endpoints. The URL of the endpoint follows the format http://<SHELLY_IP>/script/<script_id>/<endpoint_name>.

HTTPServer.registerEndpoint()

Registers an endpoint with a corresponding handler

HTTPServer.registerEndpoint(endpoint_name, callback[, userdata]) -> string

Property	Type	Description
endpoint_name	string	The name of the endpoint to register
callback	function	Function to be called when a request comes on the registered endpoint Property Type Description request object request object created by the API containing parameters of the request Property Type Description method string The HTTP method of the request (see note) query string Query string of the request Optional, the part of the request URL following the ? if present headers array Array of two element arrays each containing the header name at index 0 and header value at index 1, corresponding to the request headers body string The body of the request Optional (see note) response object response object created by the API containing parameters of the response to be sent to the client which should be set by the script Property Type Description code number The HTTP response code to be sent to the client Optional body string The response body to be sent to the client Optional headers array Array of two element arrays each containing the header name at index 0 and header value at index 1, corresponding to the response headers to be sent to the client Optional (see note) send function method supplied by the API which should be called to send the repsonse. Returns true if successful or false otherwise (see note) userdata any type The passed userdata
userdata	any type	Can be used to pass data to the callback

• Return value: the part of the endpoint URL following the SHELLY_IP. The script is aborted if the arguments are not valid.

note

Handling of POST and PUT requests with payload of type multipart/* are not supported. Response to such requests is HTTP status code 415 (Unsupported Media Type).

note

The HTTP server cannot process requests of total size greater than 3072 bytes. This includes the HTTP request line, headers and body. In this case connection is reset and no response is sent.

note

Content-Length and Connection: close headers are automatically set in the response and and override any such headers set by the script. Content-Type header defaults to text/plain if not set by the script.

note

HTTP transaction (request and response) times out after 10 seconds if repsonse is not sent. If timeout is reached response of HTTP status code 504 (Gateway Timeout) is automatically sent and transaction is cancelled (send method will return false). No more than 5 concurrent transactions are allowed. If this limit reached further requests are not processed and response of HTTP status code 503 (Service Unavailable) is sent to the client.

note

HTTP endpoints exposed through scripts will require authentication if enabled on the device

Resource Limits

There are some limitations of the resources used in a script. At the moment, these are as follows:

• No more than 5 timers used in a script;
• No more than 5 subscriptions for events used in a script;
• No more than 5 subscriptions for status changes used in a script;
• No more than 5 RPC calls used in a script.
• No more than 10 MQTT topic subscriptions used in a script.
• No more than 5 HTTP registered endpoints used in a script.

Error Handling

When the script contains errors (either a javascript error or parameters error) its execution is aborted. An error message is printed on the console and a status change event is issued with information of the type of error. This information is also avalibale in the Script.GetStatus RPC call. When the error affects the behavior of script API this is reflected in the documentation.

A special case of error is when a script causes a device crash. The script causing the crash is detected during the reboot after the crash and is disabled. The error is reported in a status change event and also in the Script.GetStatus RPC call.

Known Issues

Non-blocking execution

Shelly scripts are executed in an environment which shares CPU time with the rest of the firmware. Code in the scripts runs on the main system task and is not allowed to block for long. This is why any APIs which can potentially take a long while are callback-based. Still, it is possible to write code which will hoard the CPU for longer then acceptable. Such code may cause issues with other firmware features, communication or even cause the device to crash. One obvious example is an infinite (or near infinite) loop:

Loop for too long

let n = 0;
while (n < 500000) {
    n = n + 1;
}

If a script manages to crash the device the system will detect this and disable the script at the next boot.

Limited levels of nested anonymous functions

A limitation of the javascript engine that it cannot parse too many levels of nested anonymous functions. With more than 2 or 3 levels the device crashes when attempting to execute the code. To avoid this problem it is recommended that asynchronous callback functions are defined at the top level and passed as a named reference. Also, where possible prefer synchronous calls like Shelly.getComponentStatus and Shelly.getComponentConfig to avoid the need for async callbacks altogether.

For example, instead of using an anonymous function for a callback:

Shelly.call(
  "HTTP.GET",
  {url: "http://example.com/"},
  function(result, error_code, error_message) {
    if (error_code != 0) {
      // process error
    } else {
      // process result
    }
  });

Prefer a named function:

function processHttpResponse(result, error_code, error) {
  if (error_code != 0) {
    // process error
  } else {
    // process result
  }
}

Shelly.call("HTTP.GET", {url: "http://example.com/"}, processHttpResponse);