• Sensors can have limited buffers and cannot store a lot of data in case of server downtime, some of them can store no data at all.
• Some sensors can be misconfigured or compromised and could pose risk of incidental or intentional DDoS.
• Sensor ability to transfer data securely and/or solve security challenges can be limited.
• Sensor location is a sensitive information.

Our final design should address all of the above.

• Carbon Monoxide - Concentration, unit: mg/m³
• Lead - Concentration, unit: µg/m³
• Nitrogen Dioxide - Concentration, unit: µg/m³
• Ozone - Concentration, unit: µg/m³
• Particulate Matter (PM10) - Concentration, unit: µg/m³
• Particulate Matter (PM2.5) - Concentration, unit: µg/m³
• Sulfur Dioxide - Concentration, unit: µg/m³

• MQTT (ISO/IEC PRF 20922)
• REST HTTP(S)

This identifier is generated by the manufacturer.

Length: Exactly 128 bits.

Based on Universally Unique IDentifier (rfc4122) URN Namespace for SUID.

Example SUID: 123e4567-e89b-12d3-a456-426655440000

(TBD)

This variant is to be used in DIY devices, prototypes and sensor with poor accuracy. No authentication is used, using SUID for the first time will register the device.

POST /rogue/v1/sensors/[SUID]/readings

Payload (application/json):

See JSON Reading Payload section.

Response:

Status 200, empty response

This protocol is to be used by certified devices and readings should be considered accurate therefore sensor identity must be validated.

SSL/TLS Secure transport is required.

Sensor will receive SECRET during registration. For secure identification of the device HMAC will be used to send hash with every payload. The SECRET length is 256 bytes.

Registration is automatic and will be performed during first request (or next if failed).

Desired scenario:

• Sensor is powered and connected to the internet.
• Device should use DHCP and start data acquisition.
• User goes to sensor.opensmog.org
• Enters the SUID (printed on package as well as on the device sticker).
• User enters the street address (or lat/lon) of sensor location.
• Device is ready.

PUT /v1/sensors/[SUID]

Payload (application/json):

Example:

{
	"manufacturer": "ACME INC",
	"model": "X9000",
	"location" : {
		"latitude": 1.0,
		"longitude": 1.0,
		"elevation": 8000.0
	}
}

location (object) - this parameter is optional.

latitude, longitude (float) - a geographical coordinates using the WGS 84 reference frame.

elevation (float) - in meters. Positive values indicate altitudes above sea level. Negative values indicate altitudes below sea level.

This section may contain more meta-data about the sensor. TBD.

Response (text/plain):

256-bit SECRET.

Status 200

F9954C7A7A668E16A6572B4C49DA4

POST /v1/sensors/[SUID]/readings

Headers:

Authorization: OpenSmogHash [HASH]

If no such header is sent and the SUID is not registered via SECURE API, the server should assume ROGUE API variant. If no such header is sent and the SUID is registered via SECURE API, the server should respond with 403 Forbidden. If the header is sent and the SUID is not registered via SECURE API, the server should ignore the header. If HASH is not correct, the server should respond with 401 Unauthorized.

WARNING: If device memory is erased and lost the Secret it should register again and will be treated as a new device.

Payload (application/json):

See JSON Reading Payload section.

Response:

Status 200, empty response

Example:

[
	{
		"timestamp": 1485778030,
		"readings": {
			"PM2_5": 201.1,
			"PM10": 102.0,
			"TEMP": 12.7
		}
	},
	{
		"timestamp": 1485778031,
		"readings": {
			"PM2_5": 202.1,
			"PM10": 101.0
		}
	}
]

Payload shall be an array of at least one observation. Clients may choose to send one observation per request or to send them in bulk. Each observation shall be independent of others.

observation - Object containing a timestamp and readings

timestamp - Unix Epoch Time GMT+0000

readings - Object containing at least one association between Reading type and its value at timestamp.

• CO – Carbon Monoxide (unit: mg/m³)
• PB – Lead (unit: µg/m³)
• NO2 – Nitrogen Dioxide (unit: µg/m³)
• O3 – Ozone (unit: µg/m³)
• PM10 – PM10 (unit: µg/m³)
• PM2_5 – PM2.5 (unit: µg/m³)
• SO2 – Sulfur Dioxide (unit: µg/m³)
• TEMP – Temperature (unit: Celsius)
• HUM – Humidity (unit: %)
• PRES - Atmospheric Pressure (unit: hPa)

All float values.

Entire payload hashed (SHA256) with concatenated SECRET at the end.

Pseudocode:

SHA256(CONCAT(PAYLOAD,SECRET))