Since version 0.9.0
On this page you can find a short tutorial with an example scripting scenario to let you get started with Shelly scripts. Follow the steps to create your first script about idle alerts. The resulting script Script will monitor the inputs of a Shelly and if there was no user interaction with the input(s), it will call an URL with a predefined message.
Create a script named my_idle_alert_script. You can do this in the web interface of your device:
- Open the web interface and choose the Scripts menu:
- Click Add script
- Type my_idle_alert_script and click Save
Alternatively, you can use the RPC method:
The result from this method will be some
id, let's say id=3.
To be able to easily receive results from the scripts we create and to debug them, we will enable debug logs (for example, over websocket) first.
Again, this could be done easily through the web interface:
Then we will return to the page of the script that we just created and we will receive logs there.
In this case, we will start receiving logs by executing the following command:
To start creating scripts, let's create some code that prints "Hello world!":
To upload this code to the script we just created, just paste the code in the script's page in the web interface and click Save.
Alternatively, we can create the code in a file, let's say
hello_world.txt and upload it in one step, using the script
put_script. This script takes three parameters:
- the IP of the device on which we will upload the script (already set as value of the env variable SHELLY)
- the id of the script object, where we will upload the code (in our case id=3)
- the name of the file containing the code itself
Again, you can also upload this code (chunk by chunk) to the script through the RCP request:
Note that in this case, when the code is long, it has to be uploaded chunk by chunk. In the example, it is uploaded line by line, but you may divide it differently across the invocations of
Another thing to note is that, as our first invocation of
Script.PutCode contained the parameter
"append":false, all of code uploaded previously in this Script object will be automatically removed and the content of the script will be replaced with the new code.
Finally, we have the code uploaded and we can run our first Shelly script (the one with id=3).
To do this, we can just click the Save and Run button from the web interface:
... or we can send the RPC request:
This must print 'Hello world!' in the debug log. That is how it looks like in the web interface:
Let's stop the script now. We can do this by using:
Note that we cannot start this script again without stopping it first! This is needed especially when we update the script - if it is already in execution, it will continue to execute the old version of the code until it is stopped and then started again. We will need that in the next steps of the tutorial, where we will upgrade our code step by step.
Now, we will start to create more sophisticated and useful scripts.
Firstly, let's create some variables: an object
CONFIG and an
alertTimer with value null:
Create a new script object as described in Step 1, or just change the code of the previous Script object as described in step 3. The resulting script (let's say, again with id=3) can be run as before, but it won't print anything to the terminal.
Let's create a function called "replace". It will take three strings:
substr is a substring of the
origin. The function will replace
Add the function to the code from the previous step and upload it. The resulting script (let's say, again with id=3) can be run as before, but we shouldn't forget to stop it first, in case it has been running when the code was updated. Again, nothing will be printed to the terminal. However, while the script is running, the function we just added can be easily evaluated by the RPC method:
This must result in the string "The second generation of Shelly devices rule the world!".
We will set a timer that fires repeatedly at every 12 hours, sending an http get request. If the response code from this request is 200, a message will be printed to notify about the success. The values used here are the ones we created in step 5.
Again, append this code to the already added one.
Let's add an event handler which will restart the timer when any event occurs. You will be notified about each reset timer by a message "TIMER WAS RESET" printed in the logs.
Append this code to the already created one. Finally, we have the whole script and you can upload it.
Now, stop the script (if it has been running when the code was updated) and then start it again as described in Step 4.
If you have followed the steps properly, you will be notified each time when there was no event occurred in the last 12 hours (it may indicate a problem at home, or just the fact that someone is on a vacation :) ).