blob: 9c68ca23fc5f3392c9c143d373743d2331024930 [file] [log] [blame]
Sensor Manager API
The sensor manager API manages the sensors that are enabled in an
application. The API allows a sensor device to register itself with the
sensor manager and an application to look up the sensors that are
enabled. The sensor manager maintains a list of sensors, each
represented by a ``struct sensor`` object defined in the the `Sensor
API </os/modules/sensor_framework/sensor_api.html>`__.
Registering Sensors
When the BSP or the sensor creator package creates a sensor device in
the kernel, via the ``os_dev_create()`` function, the sensor device init
function must initialize a ``struct sensor`` object and call the
``sensor_mgr_register()`` function to register itself with the sensor
Looking Up Sensors
An application uses the sensor manager API to look up the
``struct sensor`` object for a sensor. The `sensor
API </os/modules/sensor_framework/sensor_api.html>`__ and the `sensor
listener API </os/modules/sensor_framework/sensor_listener_api.html>`__
perform operations on a sensor object. The sensor manager API provides
the following sensor lookup functions:
- ``sensor_mgr_find_next_bytype()``: This function returns the next
sensor, on the sensors list, whose configured sensor types match one
of the specified sensor types to search for. The sensor types to
search are specified as a bit mask. You can use the function to
search for the first sensor that matches or to iterate through the
list and search for all sensors that match. If you are iterating
through the list to find the next match, you must call the
``sensor_mgr_lock()`` function to lock the sensors list before you
start the iteration and call the ``sensor_mgr_unlock()`` unlock the
list when you are done. You do not need to lock the sensor list if
you use the function to find the first match because the
``sensor_mgr_find_next_bytype()`` locks the sensors list before the
- ``sensor_mgr_find_next_bydevname()``: This function returns the
sensor that matches the specified device name.
**Note:** There should only be one sensor that matches a specified
device name even though the function name suggests that there can be
multiple sensors with the same device name.
Checking Configured Sensor Types
An application may configure a sensor device to only support a subset of
supported sensor types. The ``sensor_mgr_match_bytype()`` function
allows an application to check whether a sensor is configured for one of
the specified sensor types. The type to check is a bit mask and can
include multiple types. The function returns a match when there is a
match for one, not all, of the specified types in the bit mask.
Polling Sensors
The sensor manager implements a poller that reads sensor data from
sensors at specified poll rates. If an application configures a sensor
to be polled, using the ``sensor_set_poll_rate_ms()`` function defined
in the `sensor API </os/modules/sensor_framework/sensor_api.html>`__, the
sensor manager poller will poll and read the configured sensor data from
the sensor at the specified interval.
The sensor manager poller uses an OS callout to set up a timer event to
poll the sensors, and uses the default OS event queue and the OS main
task to process timer events. The ``SENSOR_MGR_WAKEUP_RATE`` syscfg
setting specifies the default wakeup rate the sensor manager poller
wakes up to poll sensors. The sensor manager poller uses the poll rate
for a sensor if the sensor is configured for a higher poll rate than the
``SENSOR_MGR_WAKEUP_RATE`` setting value.
**Note:** An application needs to register a `sensor
listener </os/modules/sensor_framework/sensor_listener_api.html>`__ to
receive the sensor data that the sensor manager poller reads from a
Data Structures
The sensor manager API uses the ``struct sensor`` and ``sensor_type_t``
.. doxygengroup:: SensorManagerAPI