The One Platform supports attaching script applications to each client running in the cloud to handle real-time data streams and automate processes. The scripting interface uses the Lua language. Some uses of these scripts:
- Advanced data analytics using math functions and multiple dataports
- Parse raw data packets and split into individual dataports
- Perform conversion of data as it comes in
- Send out dispatches (Email, SMS, XMPP, HTTP,Twitter)
- Send data to other systems
- Perform initialization functions
The scripts have the ability to wait on new data values, read and write to dataports, access all of the platform's RPC APIs, access manage APIs, call dispatch transport functions, and access other Lua modules.
Scripting API - One Platform Scripting Documentation
Developer Notes / Best Practices
Scripts are typically written with a 'while' loop so they continually run for the life of the client, although it is not required for those scripts that just need to run once.
Starting / Updating
Scripts begin running when a client has been added under an owner, if they are a part of the Client Model's Clone. When scripts are added to an existing client, they begin running right away. Anytime a script is updated, it'll start from the beginning of the script. Scripts can be updated at any point but state and local variables are not maintained. Also be aware that when a device is cloned, scripts may start running before all dataports are also finished being created. It is good practice to 'test' a dataport before using it in a script.
Any 'state' of the script or local variables that are necessary to save through a script restart should be saved in dataports or meta for the client. The One Platform can restart scripts during updates and hot fixes. Developers should keep this in mind.
Scripts have a function call called 'debug' to print out strings defined in the script, which is useful for debugging. The debug log is available through the RPC API. When using Portals to edit a script, the debug log is contained in a box with time-stamps. Debug messages from scripts are flushed to the database every 10s
Memory / System Execution
Each Script runs independent of any other scripts and has a finite amount of memory available. The Scripting Documentation outlines this and execution information further.
Limited Cycle Ticks
All scripts are scheduled to run in a given cycle. Each script is giving a number of virtual ticks before it is stopped and rescheduled to continue running in the next cycle. Platform API calls such as alias.value, alias[ts], now take several ticks each. Limit their use and make usage of local variables to store values as much as possible.
Expect scripts to restart, which can happen when updates are made to the One Platform. Store state variables into dataports or meta for dataports/clients. You may want to initialize the .last value at script start to make sure it starts processing where it last left off.
Other Developer Notes
- alias objects are not automatically garbage collected, ‘nil’ them out if you no longer use them
- ‘now’ invokes a 1P API call, use it sparingly, don’t call it more than once per loop iteration, put it in a local variable and reuse
- The dispatch functions are asynchronous, but a second dispatch call while one is already pending, is synchronous