Skip to main content

Script

Since version 0.9.0

The Script component handles management of scripts on the device.

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
}

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.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, "src":"user_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, "src":"user_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, "src":"user_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"
}
}