ELIO IOT / Language API documentation

/*—----------—-------—------------------- ELIO LANGUAGE/API DOCUMENTATION V. 2.0  ------------------—-------------------*/// ELIO applications and API calls are defined by a JSON string with the following root elements:{   "setup": {      // with optional actions to do before running the code   },   "do": [      // with a list of methods to execute   ]}/*—-------- METHODS—--------*/// SETUP: optional actions to do before running the code (root method){   "setup": {      "reset": false, // reset actuators, vars, tasks (false by default)      "save": false, // save the app on the device (false by default)      "restart": false // restart the device (false by default)   }}// DO: execute a list of methods (root method){   "do": [      {         "on": {            "dark": [               {                  "light": {                     "id": 0, // all                     "color": 1 // white                  }               }            ],            "light": [               {                  "light": {                     "led": 0, // all                     "color": 0 // led off                  }               }            ]         }      }   ]}// ON: event manager that adds a listener for a list of events{   "on": {      // System events      "connected": [], // WIFI connecttion success event      "bootPressed": [], // BOOT switch button pressed      "upPressed": [], // UP switch button pressed      "downPressed": [], // DOWN switch button pressed      // Power events      "plugged": [], // USB plugged      "unplugged": [], // USB unplugged      "wirelessChargingStarted": [],      "wirelessChargingFinished": [],      "sunDetected": [],      "sunUndetected": [],      // Light sensor events        "bright": [],      "dark": [],      "lowIR": [],      "highIR": [],      // Proximity sensor events      "near": [],      "far": [],      // Accelerometer/Gyroscope events      "wakeUp": [],      "tap": [],      "freeFall": [],      "cubicPositionChanged": [],      // Temp & humidity sensor events      "hot": [],      "cold": [],      "humid": [],      "dry": [],      // Air quality sensor events            "clean": [],      "polluted": [],      // Events from ELIO PLAY interface      "touchCircle": [],      "touchSquare": [],      "touchTriangle": [],      "touchX": [],      "touchLeft": [],      "touchRight": [],      "touchPlus": [],      "touchMinus": []   }}// SYSTEM: system settings{   "system": {      "volume": 0-16, // system audio volume      "D1..D4": "INPUT/OUTPUT", // sets the mode of use for digital ports      "IO2": "INPUT/OUTPUT" // sets the mode of use for the analog port   }}// THRESHOLDS: method to define the thresholds of the events from sensors{   "thresholds": {      "bright": 5.0, // higher value raise the event      "dark": 10.0, // lower value raise the event      "lowIR": 10.0, // lower value raise the event      "highIR": 600.0, // higher value raise the event      "near": 10.0, // higher value raise the event      "far": 10.0, // lower value raise the event      "hot": 30.0, // higher value raise the event      "cold": 15.0, // lower value raise the event      "humid": 65.0, // higher value raise the event      "dry": 35.0, // lower value raise the event      "clean": 1500.0, // lower value raise the event      "polluted": 3000.0 // higher value raise the event   }}// OFFSET: method to calibrate the values from the sensors{   "offset": {      "light": 0,      "IRlight": 0,      "proximity": 0,      "tempC": 0,      "tempF": 0,      "humidity": 0,      "tvoc": 0,      "cubePosition": 0   }}// IF: conditional statement{   "if": {      "is": [         "a-z",         ">",         25.0,         "and/or",         "vbat",         ">",         25      ],      // [value1, operator, value2, and/or, value1, operator, value2, ...]      // Operators: "==", "!=", "<", ">", "<=", ">=". Max operands: 8       // Values can be numbers or string shortcuts. See the "Shortcuts" section      "then": [],      "else": []   }}// TIMER: method used to execute timed actions{   "timer": {      "id": 0, // identifier of the task (required)      "after": 0, // (default 0) initial delay in seconds      "every": 0, // (default 0) final delay in seconds of each execution (req. play != 1)       "play": 1, // (default 1) n>0: play n times, 0: stop, -1: infinite      "init": [],      "do": []   }}// SET: sets the value of a variable assigning to it a number, other var, a sensors value or math values{   "set": [      "a",      "=",      "light",      "+",      100   ]   // [destination var name, math function, value1, operator1, value2, operator2, value3, …]   // Available var names: from "a" to "z"   // Available math functions: =, +=, -=, *=, /=, floor, ceil, round (applied to the final result)   // Values can bee a number or string shortcut. See the "shortcut" section   // Available operators: +, -, *, /}// CONSOLE: object that interacts with the IDE console{   "console": {      "log": "The values are: & & &, xAxis yAxis zAxis"   }} // LIGHT: object that deals with leds control{   "light": {      "led": 0-15, // It identifies a single or a group of leds. 0: All; 1...3: leds on MINI board; 4..15: leds on EDU board	   "color": 0-12, // 0-12 color id or shortcut. 0: off, 1:white, ... 12: red       "brightness": 0-255, // 0-255 brightness or shortcut (255 by default)       "ms": 0, // Duration of the light on. 0: infinite (0 by default)      "play": 1 // if >0 plays n times (1 by default) , 0: stop, -1: infinite   }   // id, color and brightness can be numbers or string shortcuts. See the "Shortcuts" section}/*COLOR ID:0 000000 // black1 FFFFFF // white2 FF8800 // orange3 FFFF00 // yellow4 88FF00 // lime (yellow-green)5 00FF00 // green6 00FF88 // spring green (green-blue)7 00FFFF // light blue (aqua)8 0088FF // azure9 0000FF // blue10 8800FF // violet11 FF0088 // purple12 FF0000 // red*/// SOUND: object that deals with the buzzer. Methods: set, switch, refresh{   "sound": {      "frequency": 0-10000, // if is a string is a shortcut      "volume": 0-4, // default 2      "play": 1 // if >0 plays n times (1 by default) , 0: stop, -1: infinite   }}// INFRARED: object that deals with infrared leds{  "infrared": {	"command": "send/record", // ("send" by default) 	"recordTime": 5, // seconds (5 by default) only for IR record	"success": [],	"error": [],	"key": 0 // 0..15 (or var shortcut)   }}// WEBHOOK: HTTP-based callback function {   "webhook": {      "url": "", // endpoint of the call      "type": "get/post", // request type      "query": "q", // number or the shortcut of a variable      "result": "r", // the shortcut of a variable where to put the result of the       "values": true, // send the sensors and status values in JSON format      "success": [],      "error": []   }}// PORT: Object that deals with the 4 digital ports (of the embedded GPIO Expander){   "port": {	      "D1..D4": 0-1, // sets to 0 or 1 the digital ports D1-D5   }}// LOGGER: object that deals with logging on micro-sd drive{   "logger": { // write data to Micro-SD CSV file adding a row with TIMESTAMP,DATA LIST      "file": "data/filename.csv", // micro-sd file       "data": [  // array of sensors or variables (see shortcut section)         "light",         "temperature"      ]   }}// SAY: speech a text in the selected voice language{   "say": {      "text": "Hi! I'm ELIO", // The text to speech      "voice": "Salli", // Salli (English), Joey (English), Bianca (Italiano), Giorgio (Italiano), Lucia (Español), Enrique (Español) ,Léa (Français), Mathieu (Français), Vicki (Deutsch), Hans (Deutsch),  Ines (Português), Cristiano (Português), Mizuki（日本語), Takumi（日本語)      "url": "https://elioiot.wp1.host/app/php/string.php" // Endpoint with a textual output to speech   }}// RADIO: object that deals with MP3 streaming{   "radio": {      "url": "http://icestreaming.rai.it/1.mp3", // MP3 streaming URL      "play": 0-1, // 0: stop, 1:start,      "setChannel": 0-9, // Save the streaming URL to a channel      "channel": 0-9 // Stream the URL memorized in the channel   }}// CAMERA: object that deals with the camera{   "camera": {      "take": "photo/webcam",      "to": 1, // file destination. 0: app, 1: SD card      "resolution": 2, // resolution in pixel. 0: 160x120, 1: 320x240, 2: 640x480, 3: 800x600, 4: 1024x768 (default 2)       "name": 0, // file name. Default is the last incremental number; if string, it is a shortcut; the files are stored in the path /camera of the sd-card      "play": 0-1, // if take is "webcam" 0: stop, 1: play      "vflip": 0-1, // default 0 (experimental)      "hmirror": 0-1, // default 0 (experimental)   }}/*--------------------SHORTCUTS / VALUES--------------------*/// If an integer parameter is a string, it's a shortcut for the following methods// VARS"A-Z" -> var.get(A) // get the value of the N element of the variables array [ord("a..z")-60]  // MATH"math random": Math.random()// SENSORS"pressure" -> NUM // BARO.readPressure();"altitude" -> NUM // BARO.readAltitude();"barometerTempC" -> NUM // BARO.readTemperature();"light" -> // from 0 to 64000 lux, resolution 1 lux"IRlight""proximity""tempC" -> clima.get("tempC") // celsius temperature in decigrad (380 = 38.0°) BOARD TEMPERATURE"tempF" -> clima.get("tempF") // fahrenheit temperature in decigrad (380 = 38.0°) NOT AMBIENT"humidity" -> clima.get("humidity") OK // percentage 0-100%"tvoc" -> ags10.get("tvoc") // tvoc in ppb"cubePosition" -> 0-5 // 0 = top, 1 = upside down, …."dodecahedronPosition" -> 0-11 // 0 = top, 1 = upside down, ….// STATUS"connected" -> 0/1 // wifi connection status"plugged" -> 0/1 // usb plug status"wirelessCharging" -> 0/1 // charging status"batteryFull" -> 0/1 // battery full status  "batteryVoltage" -> … // get battery voltage (in V) "batteryLow" -> 0/1… // get battery low status// PORTS"D1..D5" -> 0/1 // status of the digital ports D1..D5// TIME"hour" -> 0-23 // system hour"minute" -> 0-59 // system minute"second" -> 0-59 // system second"year" -> 0-9999 // system year "month" -> 0-11 // system month"day" -> 0-31 // system day"weekday" -> 0-6 // system week day"epoch" -> 1670407057 // system timestamp: seconds since JAN 01 1970"time" -> "YYYY-MM-DD hh:mm:ss" // system time// LOCAL: local info obtained from the web on the first connection and saved locally"local ip": "5.94.163.62","local network": "5.94.163.0/24","local version": "IPv4","local city": "Campobasso","local region": "Molise","local region_code": "67","local city": "Campobasso","local country": "IT","local country_name": "Italy","local country_code": "IT","local country_code_iso3": "ITA","local country_capital": "Rome","local country_tld": ".it","local continent_code": "EU","local in_eu": true,"local postal": "86100","local city": "Campobasso","local country": "IT","local latitude": 41.5575,"local longitude": 14.6686,"local timezone": "Europe/Rome","local city": "Campobasso","local country": "IT","local latitude": 41.5575,"local longitude": 14.6686,"local utc_offset": "+0100","local country_calling_code": "+39","local currency": "EUR","local currency_name": "Euro","local languages": "en-US,en-GB,it-IT,es-ES,pt-PT,fr-FR,de-DE...","local country_area": 301230.0,"local country_population": 60431283,"local asn": "AS30722","local org": "Vodafone Italia S.p.A."

/*—----------—-------—------------------- ELIO LANGUAGE/API DOCUMENTATION V. 2.0  ------------------—-------------------*/// ELIO applications and API calls are defined by a JSON string with the following root elements:{   "setup": {      // with optional actions to do before running the code   },   "do": [      // with a list of methods to execute   ]}/*—-------- METHODS—--------*/// SETUP: optional actions to do before running the code (root method){   "setup": {      "reset": false, // reset actuators, vars, tasks (false by default)      "save": false, // save the app on the device (false by default)      "restart": false // restart the device (false by default)   }}// DO: execute a list of methods (root method){   "do": [      {         "on": {            "dark": [               {                  "light": {                     "id": 0, // all                     "color": 1 // white                  }               }            ],            "light": [               {                  "light": {                     "led": 0, // all                     "color": 0 // led off                  }               }            ]         }      }   ]}// ON: event manager that adds a listener for a list of events{   "on": {      // System events      "connected": [], // WIFI connecttion success event      "bootPressed": [], // BOOT switch button pressed      "upPressed": [], // UP switch button pressed      "downPressed": [], // DOWN switch button pressed      // Power events      "plugged": [], // USB plugged      "unplugged": [], // USB unplugged      "wirelessChargingStarted": [],      "wirelessChargingFinished": [],      "sunDetected": [],      "sunUndetected": [],      // Light sensor events        "bright": [],      "dark": [],      "lowIR": [],      "highIR": [],      // Proximity sensor events      "near": [],      "far": [],      // Accelerometer/Gyroscope events      "wakeUp": [],      "tap": [],      "freeFall": [],      "cubicPositionChanged": [],      // Temp & humidity sensor events      "hot": [],      "cold": [],      "humid": [],      "dry": [],      // Air quality sensor events            "clean": [],      "polluted": [],      // Events from ELIO PLAY interface      "touchCircle": [],      "touchSquare": [],      "touchTriangle": [],      "touchX": [],      "touchLeft": [],      "touchRight": [],      "touchPlus": [],      "touchMinus": []   }}// SYSTEM: system settings{   "system": {      "volume": 0-16, // system audio volume      "D1..D4": "INPUT/OUTPUT", // sets the mode of use for digital ports      "IO2": "INPUT/OUTPUT" // sets the mode of use for the analog port   }}// THRESHOLDS: method to define the thresholds of the events from sensors{   "thresholds": {      "bright": 5.0, // higher value raise the event      "dark": 10.0, // lower value raise the event      "lowIR": 10.0, // lower value raise the event      "highIR": 600.0, // higher value raise the event      "near": 10.0, // higher value raise the event      "far": 10.0, // lower value raise the event      "hot": 30.0, // higher value raise the event      "cold": 15.0, // lower value raise the event      "humid": 65.0, // higher value raise the event      "dry": 35.0, // lower value raise the event      "clean": 1500.0, // lower value raise the event      "polluted": 3000.0 // higher value raise the event   }}// OFFSET: method to calibrate the values from the sensors{   "offset": {      "light": 0,      "IRlight": 0,      "proximity": 0,      "tempC": 0,      "tempF": 0,      "humidity": 0,      "tvoc": 0,      "cubePosition": 0   }}// IF: conditional statement{   "if": {      "is": [         "a-z",         ">",         25.0,         "and/or",         "vbat",         ">",         25      ],      // [value1, operator, value2, and/or, value1, operator, value2, ...]      // Operators: "==", "!=", "<", ">", "<=", ">=". Max operands: 8       // Values can be numbers or string shortcuts. See the "Shortcuts" section      "then": [],      "else": []   }}// TIMER: method used to execute timed actions{   "timer": {      "id": 0, // identifier of the task (required)      "after": 0, // (default 0) initial delay in seconds      "every": 0, // (default 0) final delay in seconds of each execution (req. play != 1)       "play": 1, // (default 1) n>0: play n times, 0: stop, -1: infinite      "init": [],      "do": []   }}// SET: sets the value of a variable assigning to it a number, other var, a sensors value or math values{   "set": [      "a",      "=",      "light",      "+",      100   ]   // [destination var name, math function, value1, operator1, value2, operator2, value3, …]   // Available var names: from "a" to "z"   // Available math functions: =, +=, -=, *=, /=, floor, ceil, round (applied to the final result)   // Values can bee a number or string shortcut. See the "shortcut" section   // Available operators: +, -, *, /}// CONSOLE: object that interacts with the IDE console{   "console": {      "log": "The values are: & & &, xAxis yAxis zAxis"   }} // LIGHT: object that deals with leds control{   "light": {      "led": 0-15, // It identifies a single or a group of leds. 0: All; 1...3: leds on MINI board; 4..15: leds on EDU board	   "color": 0-12, // 0-12 color id or shortcut. 0: off, 1:white, ... 12: red       "brightness": 0-255, // 0-255 brightness or shortcut (255 by default)       "ms": 0, // Duration of the light on. 0: infinite (0 by default)      "play": 1 // if >0 plays n times (1 by default) , 0: stop, -1: infinite   }   // id, color and brightness can be numbers or string shortcuts. See the "Shortcuts" section}/*COLOR ID:0 000000 // black1 FFFFFF // white2 FF8800 // orange3 FFFF00 // yellow4 88FF00 // lime (yellow-green)5 00FF00 // green6 00FF88 // spring green (green-blue)7 00FFFF // light blue (aqua)8 0088FF // azure9 0000FF // blue10 8800FF // violet11 FF0088 // purple12 FF0000 // red*/// SOUND: object that deals with the buzzer. Methods: set, switch, refresh{   "sound": {      "frequency": 0-10000, // if is a string is a shortcut      "volume": 0-4, // default 2      "play": 1 // if >0 plays n times (1 by default) , 0: stop, -1: infinite   }}// INFRARED: object that deals with infrared leds{  "infrared": {	"command": "send/record", // ("send" by default) 	"recordTime": 5, // seconds (5 by default) only for IR record	"success": [],	"error": [],	"key": 0 // 0..15 (or var shortcut)   }}// WEBHOOK: HTTP-based callback function {   "webhook": {      "url": "", // endpoint of the call      "type": "get/post", // request type      "query": "q", // number or the shortcut of a variable      "result": "r", // the shortcut of a variable where to put the result of the       "values": true, // send the sensors and status values in JSON format      "success": [],      "error": []   }}// PORT: Object that deals with the 4 digital ports (of the embedded GPIO Expander){   "port": {	      "D1..D4": 0-1, // sets to 0 or 1 the digital ports D1-D5   }}// LOGGER: object that deals with logging on micro-sd drive{   "logger": { // write data to Micro-SD CSV file adding a row with TIMESTAMP,DATA LIST      "file": "data/filename.csv", // micro-sd file       "data": [  // array of sensors or variables (see shortcut section)         "light",         "temperature"      ]   }}// SAY: speech a text in the selected voice language{   "say": {      "text": "Hi! I'm ELIO", // The text to speech      "voice": "Salli", // Salli (English), Joey (English), Bianca (Italiano), Giorgio (Italiano), Lucia (Español), Enrique (Español) ,Léa (Français), Mathieu (Français), Vicki (Deutsch), Hans (Deutsch),  Ines (Português), Cristiano (Português), Mizuki（日本語), Takumi（日本語)      "url": "https://elioiot.wp1.host/app/php/string.php" // Endpoint with a textual output to speech   }}// RADIO: object that deals with MP3 streaming{   "radio": {      "url": "http://icestreaming.rai.it/1.mp3", // MP3 streaming URL      "play": 0-1, // 0: stop, 1:start,      "setChannel": 0-9, // Save the streaming URL to a channel      "channel": 0-9 // Stream the URL memorized in the channel   }}// CAMERA: object that deals with the camera{   "camera": {      "take": "photo/webcam",      "to": 1, // file destination. 0: app, 1: SD card      "resolution": 2, // resolution in pixel. 0: 160x120, 1: 320x240, 2: 640x480, 3: 800x600, 4: 1024x768 (default 2)       "name": 0, // file name. Default is the last incremental number; if string, it is a shortcut; the files are stored in the path /camera of the sd-card      "play": 0-1, // if take is "webcam" 0: stop, 1: play      "vflip": 0-1, // default 0 (experimental)      "hmirror": 0-1, // default 0 (experimental)   }}/*--------------------SHORTCUTS / VALUES--------------------*/// If an integer parameter is a string, it's a shortcut for the following methods// VARS"A-Z" -> var.get(A) // get the value of the N element of the variables array [ord("a..z")-60]  // MATH"math random": Math.random()// SENSORS"pressure" -> NUM // BARO.readPressure();"altitude" -> NUM // BARO.readAltitude();"barometerTempC" -> NUM // BARO.readTemperature();"light" -> // from 0 to 64000 lux, resolution 1 lux"IRlight""proximity""tempC" -> clima.get("tempC") // celsius temperature in decigrad (380 = 38.0°) BOARD TEMPERATURE"tempF" -> clima.get("tempF") // fahrenheit temperature in decigrad (380 = 38.0°) NOT AMBIENT"humidity" -> clima.get("humidity") OK // percentage 0-100%"tvoc" -> ags10.get("tvoc") // tvoc in ppb"cubePosition" -> 0-5 // 0 = top, 1 = upside down, …."dodecahedronPosition" -> 0-11 // 0 = top, 1 = upside down, ….// STATUS"connected" -> 0/1 // wifi connection status"plugged" -> 0/1 // usb plug status"wirelessCharging" -> 0/1 // charging status"batteryFull" -> 0/1 // battery full status  "batteryVoltage" -> … // get battery voltage (in V) "batteryLow" -> 0/1… // get battery low status// PORTS"D1..D5" -> 0/1 // status of the digital ports D1..D5// TIME"hour" -> 0-23 // system hour"minute" -> 0-59 // system minute"second" -> 0-59 // system second"year" -> 0-9999 // system year "month" -> 0-11 // system month"day" -> 0-31 // system day"weekday" -> 0-6 // system week day"epoch" -> 1670407057 // system timestamp: seconds since JAN 01 1970"time" -> "YYYY-MM-DD hh:mm:ss" // system time// LOCAL: local info obtained from the web on the first connection and saved locally"local ip": "5.94.163.62","local network": "5.94.163.0/24","local version": "IPv4","local city": "Campobasso","local region": "Molise","local region_code": "67","local city": "Campobasso","local country": "IT","local country_name": "Italy","local country_code": "IT","local country_code_iso3": "ITA","local country_capital": "Rome","local country_tld": ".it","local continent_code": "EU","local in_eu": true,"local postal": "86100","local city": "Campobasso","local country": "IT","local latitude": 41.5575,"local longitude": 14.6686,"local timezone": "Europe/Rome","local city": "Campobasso","local country": "IT","local latitude": 41.5575,"local longitude": 14.6686,"local utc_offset": "+0100","local country_calling_code": "+39","local currency": "EUR","local currency_name": "Euro","local languages": "en-US,en-GB,it-IT,es-ES,pt-PT,fr-FR,de-DE...","local country_area": 301230.0,"local country_population": 60431283,"local asn": "AS30722","local org": "Vodafone Italia S.p.A."