Skip to content

Device Communication Protocol

Jump to bottom
Winfried Holzapfel edited this page Oct 27, 2019 · 2 revisions

General Communication Information

The communcation protocol for the devices is relatively simple, and operates entirely over HTTP.

Bee Update Cycle

The protocol can support any version of HTTP supported by the LibCURL library. There is one API endpoint of the device that is responsible for updating and collecting data from the devices.

http://app.beebithive.com/bee/update

Transfer Contents

Server to Bee

The server sends a packet back to the Bee when the devices push to the server. This contains configuration values and any messages that are required to indicate the new device state. This message is represented by *pipe character delimited values indicating the actions that must be taken out in the next detection cycle. This can include;

  1. Taking an image
  2. Updating the config values of the device to match the included configuration values
updateConfig=1|sendFrame=1|frequency=20|image_quality=25|...
Parameter Function
updateConfig Whether to update the config before the next device update.
sendFrame Whether a jpeg-encoded frame should be sent over the network with the next detection

NOTE: More information about the transmitted configuration values is available at the configuration parameters page.

Bee to Server

Depending on the response message from the server, the next message from the bee will be a response payload with a format similar to as below. In addition, each sent JSON value is documented in the table below.

{
  "uuid": "3573871BA65032C9A7AE104979D55DE9",
  "people": 1,
  "timestamp": 1572166354,
  "trackers": [
    {
      "id": 0,
      "x": 0.259375,
      "y": 0.654167
    },
    {
      "id": 1,
      "x": 0.453753,
      "y": 0.674256
    }
  ],
  "frame": "/9j/4AAQSk...",
  "status": "Good"
}
Response property Meaning
uuid The UUID of the current device. Set up with the install script in the IoT repository.
people Convenience value of the total count of trackers
timestamp Unix timestamp (seconds) the measurement finish time corresponds to
trackers Normalized coordinates of each tracker on the screen and a cross-frame ID
frame JPEG-Encoded base64 representation of the image frame at the current time
status Optional message indicating any errors or issues indicated in the current cycle

General Notes

Due to the overhead on the device of changing its configuration and sending a JPEG image over the network, these tasks are only performed when strictly necessary by the device. Internally, the behavior is added to a priority queue and performed after a higher-priority immediate detection. Due to the device logic being multi-threaded, thread synchronization also incurs a copying overhead that is avoided if images are not extensively sent over the network. It is therefore not recommended to use the device as an image capturing endpoint as this is not intended behavior.

Clone this wiki locally