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().

Definitions

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.

enumerator SD_BHI160_ACCELEROMETER

BHI160 Accelerometer

enumerator SD_BHI160_MAGNETOMETER

BHI160 Magnetometer

enumerator SD_BHI160_ORIENTATION

BHI160 Orientation Sensor

enumerator SD_BHI160_GYROSCOPE

BHI160 Gyroscope

enumerator SD_MAX30001_ECG

MAX30001 ECG

enumerator SD_MAX

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.

bool 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.

Parameters
Returns

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.

Parameters

  • 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.

Returns

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.