See a 'live' (simulated) sensor reading changing in real-time on the CC dashboard [software 'steel-thread']

[JSegrave-IBM]

"As a Command Center (CC) leader, I need to see the live Temp value for each firefighter in the current event, so that I can determine when it's appropriate to remove them."

This story is about getting a sensor data stream from the API onto a bare-bones CC web app - in order to identify any integration problems in the new software architecture as early as possible.

• Show a bare-bones CC web app with sensor data coming from the API (simulated for this story)
• Persist the firefighter data in the app database
• Define Stable APIs (help the team manage dependencies). Agree an API definition between hardware and software teams so that in subsequent stories, the hardware team can send data from new sensors to the API (and have it persisted on the DB) without the need for any API changes.

Current Design Draft [may change]

API contracts

General contract notes:

• The CC app database is the 'system of record' (one version of the truth) for recording sensor data for the current and previous events. Once the CC app database has stored a SensorRecord and acknowledged receipt back to the mobile app, the IOT device is no longer responsible for storing that SensorRecord. The device is only responsible for storing sensor data that has not yet been acknowledged as recorded in the CC app database (e.g. during a connectivity outage).
• Some of this API data - e.g. battery levels, LED status - will initially be null placeholders, and that's OK. The point is to publish a stable API during the steel-thread phase, so that we can fill in these placeholders as we go, without having to make API-breaking changes (as these are disruptive and hard to manage).

API : Mobile App sends data to the IOT platform

The API expects a LIST of SensorRecords from the Mobile App, in JSON format. Usually, the list will contain one SensorRecord, but it may contain more than one (e.g. when reconnecting after a period of disconnection).

Key	Attribute Name	Data Type	Description
Y	DeviceID	STRING	Together, the {DeviceID, TimeStamp, FirefighterID} form the unique key/ID/clau of a sensor record, enabling records to be synced with the server after an outage.
Y	TimeStamp	ISO 8601 formatted STRING	ISO 8601 format is YYYY-MM-DDTHH:MM:SS. The mobile app is expected to ensure this is in sync with the TimeStamp provided by the server during registration (story #100) - e.g. possibly by adding the the device's 'number of seconds since boot' to the server TimeStamp, so that same-time sensor readings can be correlated and analyzed across all deployed devices.
Y	FirefighterID	STRING	This is available from the phone app
	SensorData	LIST(STRING, FLOAT or null)	Sensor name/value pairs for each sensor. Value should be null (not zero) if unavailable. Sensors Names in the list are {temperature, humidity, CO, NO2, acrolein, formaldehyde, benzene}
	DeviceBatteryLevel	FLOAT or null	Battery Level expressed as a percentage in the range(0.0, 1.0)
	PhoneBatteryLevel	FLOAT or null	Battery Level expressed as a percentage in the range(0.0, 1.0). This is available from the phone app
	LastStatusShown	STRING or null	Valid values are {"g", "y", "r"}. A record of the exact LED status colour most-recently displayed to the Firefighter - so that when they look at their history, it matches what they remember seeing in the field. Usually, this will be the status colour most-recently returned from a previous call to the server (ML model). However, in a disconnected scenario, it will a colour determined by the device, using on-board thresholds.
	Offline	BOOLEAN	(suggested replacement for LastStatusShown above). false by default. Only set to true when this SensorRecord failed to be sent within it's normal timeframe and was stored by the device or phone to be uploaded later. Armed with this, the server can tell what LED status colour the firefighter was shown during this period (as the server knows both the sensor value and the G/Y/R thresholds) and ensure that it is logged in the firefighter's history. It would also provide more data about outages for later analysis.

API: Server returns acknowledgement and predicted status to Mobile App :

As with the previous API, this API expects a LIST of responses from the Server, in JSON format. Usually, the list will contain one SensorRecord response, but it may contain more than one (e.g. when reconnecting after a period of disconnection).

Key	Attribute Name	Data Type	Description
Y	DeviceID	STRING	The SensorRecord key {DeviceID, TimeStamp, FirefighterID} to which this message is responding
Y	TimeStamp	ISO 8601 formatted STRING	Part of the key, as above
Y	FirefighterID	STRING	Part of the key, as above
	RecordStatus	STRING	Valid values are {"success", "fail"}. Whether or not the server has safely stored the data previously sent with the {DeviceID, TimeStamp, FirefighterID} key. A failure should result in re-trying. Success should result in the device marking that record as 'received' (i.e. that the record (a) should not be sent again and (b) is safe to delete)
	ResponseStatus	STRING or null	Valid values are {"g", "y", "r", null}. This is the overall status colour to be displayed in the mobile app and on the device LED. null indicates that the machine learning component is down and the device should generate a status color itself
	ResponseStatusPerSensor	STRING or null	Sensor Names in the list are defined in the previous API above. Valid values are {"g", "y", "r", null}. This is so that the mobile app can display the right color for each sensor. null indicates that the machine learning component is down for that gas, and the mobile app should generate a status color for that gas itself

API: Mobile App returns acknowledgement and predicted status to IOT Device :

This is just a pass-though - exactly the same information as the Mobile App got from the server, minus the ResponseStatusPerSensor list (because the device has no use for it).

Outstanding Questions:_

• How often to send data? We said 'once per minute', but...
  • One consequence of that is that in order to detect an outage, we have to wait around 2 mins. Is that OK / too long? If it's too long, we may want to increase the frequency, e.g. sending every 30s.
  • The machine learning may be sensitive to the number of data points available (e.g. N minute delay between booting-up and being able to make the first prediction). It may also just be technically sensitive to the frequency of data points (there's no real-world example here, it's just a potential technical issue). So we don't yet know if the ML will play a role in determining how frequently to take sensor readings.