Verified Commit 8fec99bb authored by Rahix's avatar Rahix
Browse files

docs: Document sensor streams


Signed-off-by: Rahix's avatarRahix <rahix@rahix.de>
parent 5459eead
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
:c:func:`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 :c:type:`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 :c:type:`stream_descriptor` enum. Please do not assign
IDs manually but instead let the enum assign sequencial IDs. :c:macro:`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 :c:type:`stream_info` object. Pass
this object to :c:func:`stream_register` to make your stream available. Your
driver must guarantee the :c:member:`stream_info.queue` handle to be valid until
deregistration using :c:func:`stream_deregister`.
Definitions
-----------
.. c:autodoc:: epicardium/modules/stream.h
......@@ -35,6 +35,7 @@ Last but not least, if you want to start hacking the lower-level firmware, the
debugger
pycardium-guide
memorymap
epicardium/sensor-streams
.. toctree::
:maxdepth: 1
......@@ -43,5 +44,3 @@ Last but not least, if you want to start hacking the lower-level firmware, the
epicardium/overview
epicardium/api
epicardium-guide
......@@ -10,18 +10,37 @@
/**
* **Stream Descriptors**:
*
* All supported streams have to have a unique ID in this list. ``SD_MAX``
* must be greater than or equal to the highest defined ID. Please keep IDs
* in sequential order.
* All supported streams have to have a unique ID in this list. :c:macro:`SD_MAX`
* must be greater than or equal to the highest defined ID. Please keep IDs in
* sequential order.
*/
enum stream_descriptor {
/** Highest descriptor must always be ``SD_MAX``. */
SD_MAX,
};
/**
* Stream Information Object.
*
* This struct contains the information necessary for :c:func:`epic_stream_read`
* to read from a sensor's stream. This consists of:
*/
struct stream_info {
/**
* A FreeRTOS queue handle.
*
* Management of this queue is the sensor drivers responsibility.
*/
QueueHandle_t queue;
/** The size of one data packet (= queue element). */
size_t item_size;
/**
* An optional function to call before performing the read.
*
* ``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.
*/
int (*poll_stream)();
};
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment