Suripu Service

Endpoints

At the moment, Suripu service accepts two endpoints for data upload from a Morpheus device:

1. POST /in/morpheus/pb
2. POST /in/morpheus
3. POST /audio/{mac_address}

POST /in/morpheus/pb

This expects a periodic_data message with the following definition:

message periodic_data {
    optional int32 unix_time=1;
    optional int32 light=2;
    optional int32 temperature=3;
    optional int32 humidity=4;
    optional int32 dust=5;
    optional string name=6;
}

Note: to see the most recent version check out the committed file

Note: In the future the message might be renamed to PeriodicData to follow naming conventions

The server REQUIRES the content type to be set to: application/x-protobuf. If you receive a HTTP 415 response, it means you are not sending the proper content-type.

You can expect a HTTP 204 if everything goes well.

POST /in/morpheus

Expects a csv with the following format:

snprintf( datastr, sizeof(datastr),
"%d,%d,%d,%d,%d,%d,%s",
MSG_VER,
data->time,
data->light,
data->temp,
data->humid,
data->dust,
MORPH_NAME
);

You can expect a HTTP 204 if everything goes well.

POST /audio/{mac_address}

Anything in the body will be save in S3. The temporary naming scheme is "{mac_address}_{now()} ex: 123456789_2014-08-27T18:54:59.167Z

Verification Flow

Our physical device – Morpheus – is connected to wifi and will upload directly to our receive endpoint the data it has collected.

To verify that the data collected has been generated by our device we need to sign it. The setup is relatively simple:

1. At the factory or fulfillment center, a public-private key pair is generated. The private key is stored somewhat securely on the device and the public key is sent somewhat securely to our server and stored permanently in a database

2. When the data is ready to be uploaded to our servers, the firmware signs the payload with the private key and uploads it

3. The server extracts the device_id from the payload and fetches its associated public key. It then verifies the signature to validates the identity of the device and the veracity of the information uploaded.

4. That's it.

Failure cases

1. If the private key on the device is accessed, the data being sent may no longer have been generated by the device. This could impact our data collection processes and algorithms, especially for aggregates. The risk is low but still needs to be considered.

2. If the public key stored on the server is lost/corrupted, we will be unable to validate the data being sent. Regular backups are essential.