When Purple Robot is in data acquisition mode, it uses built-in sensors to collect information about the user’s environment and periodically transmits the collected data to an external server for storage and analysis. This document describes how this process works and how to construct a compatible server.

To enable and configure the data upload, visit the “HTTP Upload Settings” in the Purple Robot settings. Among the options for storing data and encryption options, you can specify the upload server using the “HTTP Upload Endpoint”. Purple Robot will POST sensor data payloads to this endpoint.

The payload that Purple Robot sends looks like this:

{
  "Checksum": "9da09d64b4f8a778ef39454f2afff81a",
  "Operation": "SubmitProbes",
  "UserHash": "7916ea0044fb781a22f0582cf1104ad7",
  "Payload": (PAYLOAD_STRING),
  "ContentLength": 8700
}

The content of the Payload key is a an escaped string representing a JSON array containing the sensor data. Unescaped, this array looks like:

[
  {
    "TRANSMIT":  true,
    "NOISE_VALUE":  0.2112429141998291,
    "PROBE":  "edu.northwestern.cbits.purple_robot_manager.probes.builtin.RandomNoiseProbe",
    "GUID":  "1b7684b7-ce4e-4a3a-b3e0-b54813f42af0",
    "TIMESTAMP":  1.371186923592E9
  },
  {
    "TRANSMIT":  true,
    "NOISE_VALUE":  0.7886762022972107,
    "PROBE":  "edu.northwestern.cbits.purple_robot_manager.probes.builtin.RandomNoiseProbe",
    "GUID":  "2c7e69aa-d98b-4650-a4bb-49fb30507e98",
    "TIMESTAMP":  1.371186924043E9
  },
  {
    "TRANSMIT":  true,
    "NOISE_VALUE":  0.6586723923683167,
    "PROBE":  "edu.northwestern.cbits.purple_robot_manager.probes.builtin.RandomNoiseProbe",
    "GUID":  "ff8e1924-ca90-4857-af9d-29672af891aa",
    "TIMESTAMP":  1.371186924091E9
  },
  {
    "TIMESTAMP":  1371186924,
    "CALL_STATE":  "Idle",
    "PROBE":  "edu.northwestern.cbits.purple_robot_manager.probes.builtin.CallStateProbe",
    "GUID":  "82779b16-b2e6-400a-b3d5-59a95f6bedf9"
  },
  {
    "TRANSMIT":  true,
    "NOISE_VALUE":  0.6118898391723633,
    "PROBE":  "edu.northwestern.cbits.purple_robot_manager.probes.builtin.RandomNoiseProbe",
    "GUID":  "8682e4a9-eb22-4275-aa53-191501df35d0",
    "TIMESTAMP":  1.371186924229E9
  },
  {
    "TRANSMIT":  true,
    "NOISE_VALUE":  0.2691836953163147,
    "PROBE":  "edu.northwestern.cbits.purple_robot_manager.probes.builtin.RandomNoiseProbe",
    "GUID":  "e7c6f48c-a425-46a4-b62c-9030ec847df3",
    "TIMESTAMP":  1.371186924341E9
  }
]

The PROBE key is the name of the probe, the TIMESTAMP key contains the Unix timestamp when the data was collected and additional keys will be provided for different sensors. Inspect this array to learn more about how each probe structures its data.

Returning to the parent JSON object:

{
  "Checksum": "9da09d64b4f8a778ef39454f2afff81a",
  "Operation": "SubmitProbes",
  "UserHash": "7916ea0044fb781a22f0582cf1104ad7",
  "Payload": (PAYLOAD_STRING),
  "ContentLength": 8700
}

The Checksum key contains an MD5 hash of the concatenation of the UserHash, Operation, and Payload key. The POST endpoint should calculate this hash independently to verify the data received. The Operation key is always SubmitProbes, and the UserHash key is an MD5 hash of the user identifier set in the app’s settings. (This defaults to your Google account if not set explicitly.)

If the payload is complete and valid, the POST endpoint is responsible for unpacking the Payload key and processing and storing the data as needed. When this process is complete, the server returns a JSON response structured like

{
  "Status": "success", 
  "Checksum": "b64133ed68937736d488cd1f0b753034", 
  "Payload": "{}"
}

The Status key is success on a successful upload, and should be error if there was an issue processing the uploaded data. If an error status is returned, the device running Purple Robot will retain the data and attempt to upload it at a later time. The Payload key may contain additional information to be used by the application, but this is currently ignored by Purple Robot. The Checksum key is an MD5 hash of concatenation of the Status and Payload keys. Purple Robot will verify this checksum to assess validity of the response.

To assist new Purple Robot users with creating their own endpoint, we’ve built a small starter server written in Cherry.py that implements this protocol and saves the JSON payloads to files on a local server. To get started, install Python and Cherry.py on your local system. When you have the system up and running, point your instance of Purple Robot to the server and start collecting data!

  • ahiruyo

    How can we set up and run server.py? When I did >python server.py, I got an error

    File “server.py”, line 57, in
    cherrypy.quickstart(RobotPost(), config=CONFIG)
    AttributeError: ‘module’ object has no attribute ‘quickstart’

    • Chris Karr

      Apologies for the tardy reply (just saw this response). Did you ever figure out what the issue was? If you need further assistance, please feel free to contact me at c-karr@northwestern.edu. I have no idea how I missed your response.