060. The API
The API is a set of endpoints, most of which consume and/or return JSON payloads. These have a path that starts with 'api'
For now, three endpoints return an HTML page. It is planned that the master module could offer more than one version of the web app, in which case each version will be one HTML page.
The master endpoints are available on both its IPs: the one on your home wifi network (once configured), and the one on the wifi network it creates.
When the master module has never been initialized, or when it has just been flashed with a new version of the firmware for which the config version number is different from the previous one, the "/" path will return the initalization webpage (of course, only on the ip address on the default wifi network "iotinator", since the custom network is not set yet).
Typically, if you connect your computer or phone to the "iotinator" wifi network and type http://192.168.4.1 in your browser, you'll see the initialization webpage.
Once the master module is initialized, the same call will display the webApp instead.
This is the endpoint called by the init page to save the data from the form. It returns the "Init Done" html webpage, but you may not have the time to see it since the master module will switch to the custom wifi ssid you chose. The parameters are sent as form-data: apSsid: name of the wifi network the master will create apPwd: password to connect to the wifi network above. homeSsid: name of the home wifi network the master should connect to homePwd: password to connect to the home wifi network appHost: full hostname where the "app" directory holds the UI framework and agent files ntpHost: to use other ntp servers, if needed.
If you need to modify the master configuration, this endpoint will provide the init page again. It's the same as "/" when the module is not initialized.
It's conveninent for debuging for now, not sure it will stay, especially once the GSM card will be available.
This is the endpoint that each module will call when it connects to the wifi network opened by the master.
The master will respond with a payload providing the custom network name and password that the agent should connect to, the current date and time, and other information:
{
"version": "1.0",
"APInitialized": true,
"APSsid": "toto",
"APPwd": "tototutu",
"timestamp": 1526813694,
"homeWifiConnected": true,
"gsmEnabled": false,
"timeInitialized": true
}
- APInitialized: (Access Point Initialized): true means that the custom wifi has been configured (Reminder: as long as it has not, the default 'iotinator/iotinator' will be used).
- APSsid: the custom ssid you chose when initializing the master module on its initialization page.
- APPwd: the password for this ssid
- timestamp: the current date and time
- homeWifiConnected: true means the master is connected to the home network.
- gsmEnabled: true means the master is equipped with a GSM board and SIM Card
- timeInitialized: true means a NTP server has returned the current date and time.
This is the endpoint called by an agents that needs to register itself to the master module
{
"name": "Dimmer",
"ip": "192.168.4.9",
"MAC": "60:01:94:0c:31:14",
"uiClassName": "dimmerUIClass",
"heap": 39184,
"canSleep": false,
"custom": "{\"level\":50}"
}
This is the endpoint called by an agent that needs to refresh the data the master keeps in its agent list.
TODO
Although it's a GET, it will reset all the modules, master and registered agents: they will reinitialize the EEPROM saved configuration to the default values. Factory reset ! This needs to be changed to a POST, or DELETE may be.
This call returns an object with various master data (not yet exposed), and a json map in which each item is the data from one registered module. The key of this item in the map is the MAC address of the module on the custom wifi network.
For instance:
{
"agentList": {
"5c:cf:7f:24:7a:ef": {
"name": "Dimmer_1",
"ip": "192.168.4.2",
"canSleep": false,
"connected": 0,
"uiClassName": "dimmerUIClass",
"heap": 38664,
"pingPeriod": 0,
"custom": "{\"level\":23}"
},
"60:01:94:06:80:51": {
"name": "Fan",
"ip": "192.168.4.4",
"canSleep": false,
"connected": 0,
"uiClassName": "fanUIClass",
"heap": 39136,
"pingPeriod": 0,
"custom": "{\"speed\":0, \"osc\":\"off\"}"
},
"84:f3:eb:96:82:aa": {
"name": "Lampe Coin",
"ip": "192.168.4.3",
"canSleep": false,
"connected": 0,
"uiClassName": "switchUIClass",
"heap": 39736,
"pingPeriod": 0,
"custom": "{\"status\":\"off\"}"
}
}
}
agentList is a MAC indexed has, containing one entry per registered module. Each entry contains:
- name: name of the module.
- ip: ip of the module
- canSleep: means a module can use the sleep mode of the ESP8266, and should therefore not be pinged regularly by master
- pong: true means the module has answered to last ping from master
- uiClassName: name of the directory holding the js and css files for this module's UI
- heap: available memory on the heap, for monitoring purpose and memory leak detection
- pingPeriod: minimum interval in seconds between pings by master. 0 means no ping.
- custom: the module's custom data.
The important feature of this payload is that the "custom" field holds stringyfied JSON, which is the "customData" of the module. The structure of this JSON is opaque to the master module, and keeping it as a string makes keeping it in memory and allocating space for it much safer and easier. If is parsed by the module's UI js code to display what needs to be displayed for the module.
Returns the customData of the module, that will be saved by the master, as well as the heap size: memory available on the heap, for monitoring.
This is the data that will be fetched by the UI
TODO payload
Although it's a GET, it will reset the module: reinitialize the EEPROM saved configuration to the default values. Factory reset ! This should be changed to POST or DELETE
This is to rename the module. When an agent module registers itself to the master module, if it has the same name than an already other registered agent module, then it will be renamed. The new name is the original name to which an underscore and a sequential number is appended.
{"name":"Dimmer_1"}
The header Xiot-forward-to should provide the local IP of the module to update wirelessly, since his call is not working yet to update the master.
This will put the agent module in OTA mode, waiting for an new version of the software to be uploaded. It will display a blinking "WAITING OTA" message. If you change your mind, reset the module (power cycle or reset button).
Please chek the OTA page of this wiki for more information
This request will return the customData. Almost same as /api/ping, no heap size... Mostly for symetry with:
TODO: payload
When the UI needs to save some data, it will send a payload to the master module with a custom header containing the ip of the agent module to which this payload should be forwarded. The master module will then PUT the payload on this endpoint on the specified IP.
TODO: payload