Register an IOT device to the Prometeo Platform for an event [hardware steel-thread]

[JSegrave-IBM]

"As a Firefighter, I need to register an IOT Device for an Event, so that it can keep the Command Center informed about potential hazards I may be exposed to during that event".

This story is about two things:

1. Registering the device to the Prometeo platform and giving the user very basic feedback that the registration was successful/failed. The aim is to identify any integration problems in the new device -> phone -> cloud architecture as early as possible.
2. Defining a stable API for registrations - to help the team manage dependencies. i.e. to agree a Registration API definition between hardware and software teams that enables the hardware team to incrementally add functionality without having to change API definitions. For example: the registration API would include things like 'last calibration date' that will be blank at the start, but should be able to be filled out later without any need for API-breaking changes. This will help the team work independently without task dependencies blocking future work.

User Experience:

• Firefighter powers on their IOT device and checks the ID number written on the device
• They open the Mobile App, where they see all available Prometeo devices in range (there may be several)
• They select the device that matches the ID number written on the device
• The app connects to the device selected

API contracts

General contract notes:

• 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

Key	Attribute Name	Data Type	Description
Y	DeviceID	STRING	Together, the {DeviceID, FirefighterID} form the unique ID of a sensor being registered to an event.
Y	DeviceType	STRING	"Prometeo Sensor" - could have different types in the future.
Y	FirefighterID	STRING	This is available from the phone app
	Mobile App Version	STRING	? From the mobile app - to enable us to tell what version of the mobile app apart? For admin, debugging, etc
	Firmware Revision	STRING	? From the device - to enable us to tell different models apart? For admin, debugging, etc

API: Server returns registration acknowledgement to Mobile App, including config info needed by the device :

Key	Attribute Name	Data Type	Description
Y	DeviceID	STRING	The {DeviceID, FirefighterID} unique ID that has been registered.
Y	FirefighterID	STRING	The {DeviceID, FirefighterID} unique ID that has been registered.
-	ServerTimeSync	ISO 8601 formatted STRING	Base datetime for the device to use when writing SensorRecords to the SD card and sending them to the server. Provides clock synchronisation across all devices in the event, so that SensorRecords can be synced after an outage. YYYY-MM-DDTHH:MM:SS. e.g. possibly by adding the the device's 'number of seconds since boot' to this server TimeStamp, so that same-time sensor readings can be correlated and analyzed across all deployed devices
	RegistrationStatus	STRING	Valid values are {"success", "fail"}. Whether or not the server has successfully registered the device and is ready to log data from it. If "fail", the device LED should show a connection error
	AlertThresholds	LIST(STRING, FLOAT or null)	name/value pairs for the Alert Thresholds for each sensor. Value should be null (not zero) if unavailable. Sensors Names in the list are {temperature, humidity, CO, NO2, acrolein, formaldehyde, benzene}. If the device becomes disconnected (an 'outage'), it should change the device status LED to red if any of the instantaneous sensor values exceed these thresholds.

To discuss :

• EventID / Event Name? - Think these won't always be available. Are they needed by the mobile app at any point?

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?

Questions

• Where should device get "Last Calibration Date" from for burn-test? (and is that date per device or per sensor?)
  Is Last Calibration Date per sensor or per device?)
• Battery levels are part of routine data send, not registration (Device Battery level, Phone battery level)?

See similar 'stable API contract' requirements in Story #92