Skip to main content

Script

Since version 0.9.0

The Script component handles management of scripts on the device. It uses Script as RPC namespace and provides the methods:

A script on the device is a container or a slot consisting of meta data and a file - the actual executable code. The Script component offers RPC endpoints for creation, modification, configuration and execution of scripts.

A script in a slot can be running or not and can be configured to run on boot. More information about the scripting language and the opportunities it gives can be found on the Language Features page. You can also check out the short tutorial.

Status

The status of the Script component shows whether the script is currently running.

Properties:

  • id: number, id of the script
  • running: boolean, true if the script is currently running, false otherwise
Example status object
{
"id": 1,
"running": false
}

Script.GetStatus example

curl http://192.168.1.100/rpc/Script.GetStatus?id=1

Configuration

The configuration of the Script component shows the identifiers of the script, as well as whether it is run on boot.

Properties:

  • id: number, id of the script
  • name : string, name of the script
  • enable: boolean, true if the script runs by default on boot, false otherwise
Example configuration object
{
"id": 1,
"name": "my_script",
"enable": false
}

Script.GetConfig example

curl http://192.168.1.100/rpc/Script.GetConfig?id=1

Script.SetConfig example

curl -X POST -d '{"id":1, "method":"Script.SetConfig", "params": {"id": 1, "config": {"enable": true}}}' http://${SHELLY}/rpc

Script.List

This method lists all scripts.

Request

This method takes no parameters.

http://192.168.33.1/rpc/Script.List

Response

Attributes in the result:

  • scripts: array of JSON objects, list of all created scripts
    • id: number, id of the script
    • name: string, name of the script
    • enable: boolean, true if the script runs by default on boot, false otherwise
    • running: boolean, true if currently running, false otherwise
{
"scripts": [
{
"id": 1,
"name": "my_script",
"enable": false,
"running": true
},
{
"id": 2,
"name": "my_script2",
"enable": false,
"running": false
}
]
}

Script.Create

This method creates a new script.

Request

Parameters:

  • name: string, name of the script. If it is missed, a default name script_<id> will be assigned (e.g. script_0). Optional
Create a script named my_script
curl -X POST -d '{"id":1, "method":"Script.Create", "params":{"name":"my_script"}}'\
http://${SHELLY}/rpc

Response

Attributes in the result:

  • id: number, id of the created script
{
"id" : 1,
"src" : "shellyplus1pm-a8032abe3ed0",
"dst" : "user_1",
"result" : {
"id" : 1
}
}

Script.Delete

This method removes specified script.

Request

Parameters:

  • id : number, id of the script. Required
Delete a script with id=1
http://192.168.33.1/rpc/Script.Delete?id=1

Response

The result from this method is null.

null

Script.Start

This method runs a script.

Up to 3 scripts can be running at any given time.

If there is no code put in the script the method will return an error.

Request

Parameters:

  • id : number, id of the script. Required
Executes the script with id=1
http://192.168.33.1/rpc/Script.Start?id=1

Response

Attributes in the result:

  • was_running: boolean, true if the script was running in the previous state, false otherwise
{
"was_running": false
}

Script.Stop

This method stops the execution of a script.

Request

Parameters:

  • id : number, id of the script. Required
Stops the execution of script with id=1
http://192.168.33.1/rpc/Script.Stop?id=1

Response

Attributes in the result:

  • was_running: boolean, true if the script was running in the previous state, false otherwise
{
"was_running": true
}

Script.PutCode

This method allows uploading code to an existing script.

note

Uploading of code might need to happen in chunks. If the size of the file to be uploaded is large, and there is a need to upload files in chunks use the append parameter to add the next part of the content. We have a Python tool in our GitHub repo that is uploading scripts in chunks of 1024 bytes.

Request

Parameters:

  • id : number, id of the script. Required
  • code: string, the code which will be included in the script (the length must be greater than 0). Required
  • append: boolean, true to append the code, false otherwise. If set to false, the existing code will be overwritten. Default value: false. Optional
Overwrites script with id=1 with console.log(5+6)
curl -X POST -d '{"id":1, "method":"Script.PutCode", "params":{"id":1,"code":"console.log(5+6)"}}'\
http://${SHELLY}/rpc

Response

Attributes in the result:

  • len: number, the total code length in bytes
{
"id" : 1,
"src" : "shellyplus1pm-a8032abe3ed0",
"dst" : "user_1",
"result" : {
"len" : 16
}
}

Script.GetCode

This method downloads code from an existing script.

Request

Parameters:

  • id: number, id of the script. Required
  • offset: number, byte offset from the beginning. Default value: 0. Optional
  • len: number, bytes to read. Default value: maximum possible number of bytes till the end is reached. Optional
Download the code from script with id=1
http://192.168.33.1/rpc/Script.GetCode?id=1

Response

Attributes in the result:

  • data: string, the requested data chunk
  • left: number, number of bytes remaining till the end of the code
{
"data": "console.log(5+6)",
"left": 0
}

Script.Eval

This method evaluates or executes some code inside of a specified script.

The specified script must be running.

Request

Parameters:

  • id : number, id of the script. Required
  • code: string, argument to evaluate (the length must be greater than 0). Required
Script with id=1
let a = 5+5
Execute a+5 in script with id=1
curl -X POST -d '{"id":1, "method":"Script.Eval", "params":{"id":1, "code":"a+5"}}'\
http://${SHELLY}/rpc

Response

Attributes in the result:

  • result: string, the result of the evaluation
{
"id" : 1,
"src" : "shellyplus1pm-a8032abe49fc",
"dst" : "user_1",
"result" : {
"result" : "15"
}
}