Sensor Streams

Sensor drivers can make their data available to core 1 in a stream-like format. This allows batch-reading many samples and shoud reduce pressure on the Epicardium API this way. Sensor streams are read on core 1 using epic_stream_read().

This page intends to document how to add this stream interface to a sensor driver. It also serves as a reference of existing streams. For that, take a look at the definitions in the stream_descriptor enum.

Adding a new Stream

The list of possible sensor streams must be known at compile time. Each stream gets a unique ID in the stream_descriptor enum. Please do not assign IDs manually but instead let the enum assign sequencial IDs. SD_MAX must always be the highest stream ID. Additionally, please document what this stream is for using a doc-comment so it shows up on this page.

When a sensor driver enables data collection, it should also register its respective stream. This is done using a stream_info object. Pass this object to stream_register() to make your stream available. Your driver must guarantee the stream_info.queue handle to be valid until deregistration using stream_deregister().


enum stream_descriptor

Stream Descriptors:

This enum defines all known stream descriptors. Internally, the stream module allocates an array slot for each ID defined here. For that to work, SD_MAX must be greater than the highest defined ID. Please keep IDs in sequential order.


BHI160 Accelerometer


BHI160 Magnetometer


BHI160 Orientation Sensor


BHI160 Gyroscope


MAX30001 ECG


Highest descriptor must always be SD_MAX.

struct stream_info

Stream Information Object.

This struct contains the information necessary for epic_stream_read() to read from a sensor’s stream. This consists of:

QueueHandle_t queue

A FreeRTOS queue handle.

Management of this queue is the sensor drivers responsibility.

size_t item_size

The size of one data packet (= queue element).

int (*)() poll_stream

An optional function to call before performing the read. Set to NULL if unused.

poll_stream() is intended for sensors who passively collect data. A sensor driver might for example retrieve the latest samples in this function instead of actively polling in a task loop.

The function registered here should never block for a longer time.

int was_full

Set to true if the last write to queue failed because the queue was full.

int stream_register(int sd, struct stream_info * stream)

Register a stream so it can be read from Epicardium API.


0 on success or a negative value on error. Possible errors:

  • -EINVAL: Out of range sensor descriptor.

  • -EACCES: Stream already registered.

  • -EBUSY: The descriptor lock could not be acquired.

int stream_deregister(int sd, struct stream_info * stream)

Deregister a stream.

  • sd (int) – Stream Descriptor.

  • stream (stream_info) – The stream which should be registered for the stream sd. If a different stream is registered, this function will return an error.


0 on success or a negative value on error. Possible errors:

  • -EINVAL: Out of range sensor descriptor.

  • -EACCES: Stream stream was not registered for sd.

  • -EBUSY: The descriptor lock could not be acquired.