Web endpoints¶
Synth simulates not just device output, but also device input too. An external service can “prod” Synth to generate asynchronous events on devices, via its Web server, at scale. These events are synchronised via the simulation engine.
Some general URL queries allow the status of the Synth framework to be checked, and new simulations to be spawned. And a POST interface allows events to be sent to specific devices running in specific Synth instances.
A Flask web server handles incoming queries at HTTPS port 443 and sends them onto an internal ZeroMQ bus, from which they are consumed by a process spawner (to create new Synth instances) and, within each instance, an event listener to post events into its simulation engine.
- For this module to work, the following SSL certificate files must be placed in ../synth_accounts/:
- ssl.crt ssl.key
Flask occasionally just stops responding to web requests (like every day or so) - no idea why. So we rely on an external service (e.g. Pingdom or UptimeRobot) to ping us regularly and then, knowing that that is happening, if we don’t recive any messages then we know to restart the server.
GET /?<magickey>¶
Return a basic page listing all running Synth processes and free memory. For security this must be accompanied by a magic key matching the “web_check_key” property in the file ../synth_accounts/default.json
GET /spawn?devicepilot_key=XXX&devicepilot_api=staging¶
Spawn a new instance of Synth, with these two specific parameters set. The UserDemo scenario is run. The instance_name is set to be “devicepilot_key=XXX” since that is assumed to be unique.
GET /is_running?devicepilot_key=XXX&devicepilot_api=staging¶
Find whether a specific instance of Synth (identified by its key) is still running. Return a JSON struct with active=true/false.
GET /plots/<filename>¶
Return a plot generated by the Expect device function
POST /event¶
This causes an inbound device event to be asynchronously generated, to a specific device on a specific Synth instance. The header of the web request must contain the following:
Key : <web_key parameter>
Instancename : <instance_name parameter>
The body of the web request must contain a JSON set include the following elements:
"deviceId" : "theid"
"eventName" : "replace_battery" | "upgradeFirmware" | "factoryReset"
"arg" : "0.7" - optional argument only relevant for some eventNames
If defining a Webhook Action in DevicePilot to create a Synth event, the device ID will be automatically filled-out if you define it as {device.$id}, resulting in an action specification which looks something like this:
method: POST
url: https://synthservice. com/event
headers: { "Key":"mywebkey", "Instancename" : "OnProductionAccountUser" }
body: { "deviceId" : "{device.$id}", "eventName" : "upgadeFirmware", "arg":"0.7"}