| Sensor API |
| ---------- |
| |
| The sensor API implements the sensor abstraction and the functions: |
| |
| - For a sensor device driver package to initialize a sensor object with |
| the device specific information. |
| |
| - For an application to read sensor data from a sensor and to configure |
| a sensor for polling. |
| |
| A sensor is represented by the ``struct sensor`` object. |
| |
| Sensor API Functions Used by a Sensor Device Driver Package |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| A sensor device driver package must use the sensor API to initialize |
| device specific information for a sensor object and to change sensor |
| configuration types. |
| |
| Initializing a Sensor Object |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| When the BSP or the sensor creator package creates an OS device for a |
| sensor named ``SENSORNAME``, it specifies the ``<sensorname>_init()`` |
| callback function, that the device driver exports, for the |
| ``os_dev_create()`` function to call to initialize the device. The |
| ``<sensorname>_init()`` function must use the following sensor API |
| functions to set the driver and interface information in the sensor |
| object: |
| |
| - The ``sensor_init()`` function to initialize the ``struct sensor`` |
| object for the device. |
| |
| - The ``sensor_set_driver()`` function to set the types that the sensor |
| device supports and the sensor driver functions to read the sensor |
| data from the device and to retrieve the value type for a given |
| sensor type. |
| |
| - The ``sensor_set_interface()`` function to set the interface to use |
| to communicate with the sensor device. |
| |
| **Notes**: |
| |
| - See the :doc:`Sensor Device |
| Driver <../os/modules/sensor_framework/sensor_driver>` page for |
| the functions and data structures that a sensor driver package |
| exports. |
| |
| - The ``<sensorname>_init()`` function must also call the |
| ``sensor_mgr_register()`` function to register the sensor with the |
| sensor manager. See the :doc:`Sensor Manager |
| API <../os/modules/sensor_framework/sensor_mgr_api>` for |
| details. |
| |
| Setting the Configured Sensor Types |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| |
| The BSP, or the sensor creator package, also calls the |
| ``<sensorname>_config()`` function to configure the sensor device with |
| default values. The ``<sensorname>_config()`` function is exported by |
| the sensor device driver and must call the sensor API |
| ``sensor_set_type_mask()`` function to set the configured sensor types |
| in the sensor object. The configured sensor types are a subset of the |
| sensor types that the device supports. The sensor framework must know |
| the sensor types that a sensor device is configured for because it only |
| reads sensor data for the configured sensor types. |
| |
| **Note:** An application may also call the ``<sensorname>_config()`` |
| function to configure the sensor device. |
| |
| Sensor API Functions Used By an Application |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| The sensor API provides the functions for an application to read sensor |
| data from a sensor and to configure a sensor for polling. |
| |
| Reading Sensor Data |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| An application calls the ``sensor_read()`` function to read sensor data |
| from a sensor device. You specify a bit mask of the configured sensor |
| types to read from a sensor device and a callback function to call when |
| the sensor data is read. The callback is called for each specified |
| configured type and the data read for that sensor type is passed to the |
| callback. |
| |
| Setting a Poll Rate for A Sensor |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The sensor manager implements a poller that reads sensor data from a |
| sensor at specified poll intervals. An application must call the |
| ``sensor_set_poll_rate_ms()`` function to set the poll rate for a sensor |
| in order for poller to poll the sensor. |
| |
| **Note:** An application needs to register a :doc:`sensor |
| listener <../os/modules/sensor_framework/sensor_listener_api>` to |
| receive the sensor data that the sensor manager poller reads from a |
| sensor. |
| |
| Data Structures |
| ~~~~~~~~~~~~~~~ |
| |
| We list the main data structures that the sensor API uses and mention |
| things to note. For more details, see the |
| `sensor.h <https://github.com/apache/mynewt-core/blob/master/hw/sensor/include/sensor/sensor.h>`__ |
| include file. |
| |
| Sensor Object |
| ^^^^^^^^^^^^^ |
| |
| The ``struct sensor`` data structure represents the sensor device. The |
| sensor API, the :doc:`sensor manager |
| API <../os/modules/sensor_framework/sensor_mgr_api>`, and the :doc:`sensor |
| listener API <../os/modules/sensor_framework/sensor_listener_api>` |
| all operate on the ``sensor`` object abstraction. A sensor is maintained |
| in the sensor manager global sensors list. |
| |
| .. code:: c |
| |
| struct sensor { |
| /* The OS device this sensor inherits from, this is typically a sensor |
| * specific driver. |
| */ |
| struct os_dev *s_dev; |
| |
| /* The lock for this sensor object */ |
| struct os_mutex s_lock; |
| |
| |
| /* A bit mask describing the types of sensor objects available from this |
| * sensor. If the bit corresponding to the sensor_type_t is set, then this |
| * sensor supports that variable. |
| */ |
| sensor_type_t s_types; |
| |
| /* Sensor mask of the configured sensor type s*/ |
| sensor_type_t s_mask; |
| /** |
| * Poll rate in MS for this sensor. |
| */ |
| uint32_t s_poll_rate; |
| |
| /* The next time at which we want to poll data from this sensor */ |
| os_time_t s_next_run; |
| |
| /* Sensor driver specific functions, created by the device registering the |
| * sensor. |
| */ |
| struct sensor_driver *s_funcs; |
| |
| /* Sensor last reading timestamp */ |
| struct sensor_timestamp s_sts; |
| |
| /* Sensor interface structure */ |
| struct sensor_itf s_itf; |
| |
| /* A list of listeners that are registered to receive data off of this |
| * sensor |
| */ |
| SLIST_HEAD(, sensor_listener) s_listener_list; |
| /* The next sensor in the global sensor list. */ |
| SLIST_ENTRY(sensor) s_next; |
| }; |
| |
| **Note:** There are two fields, ``s_types`` and ``s_mask``, of type |
| ``sensor_type_t``. The ``s_types`` field is a bit mask that specifies |
| the sensor types that the sensor device supports. The ``s_mask`` field |
| is a bit mask that specifies the sensor types that the sensor device is |
| configured for. Only sensor data for a configured sensor type can be |
| read. |
| |
| Sensor Types |
| ^^^^^^^^^^^^ |
| |
| |
| The ``sensor_type_t`` type is an enumeration of a bit mask of sensor |
| types, with each bit representing one sensor type. Here is an excerpt of |
| the enumeration values. See the |
| `sensor.h <https://github.com/apache/mynewt-core/blob/master/hw/sensor/include/sensor/sensor.h>`__ |
| for details: |
| |
| .. code:: c |
| |
| |
| typedef enum { |
| /* No sensor type, used for queries */ |
| SENSOR_TYPE_NONE = 0, |
| /* Accelerometer functionality supported */ |
| SENSOR_TYPE_ACCELEROMETER = (1 << 0), |
| /* Magnetic field supported */ |
| SENSOR_TYPE_MAGNETIC_FIELD = (1 << 1), |
| /* Gyroscope supported */ |
| SENSOR_TYPE_GYROSCOPE = (1 << 2), |
| /* Light supported */ |
| SENSOR_TYPE_LIGHT = (1 << 3), |
| /* Temperature supported */ |
| SENSOR_TYPE_TEMPERATURE = (1 << 4), |
| |
| .... |
| |
| SENSOR_TYPE_USER_DEFINED_6 = (1 << 31), |
| /* A selector, describes all sensors */ |
| SENSOR_TYPE_ALL = 0xFFFFFFFF |
| |
| } sensor_type_t; |
| |
| Sensor Interface |
| ^^^^^^^^^^^^^^^^ |
| |
| The ``struct sensor_itf`` data structure represents the interface the |
| sensor device driver uses to communicate with the sensor device. |
| |
| .. code:: c |
| |
| struct sensor_itf { |
| |
| /* Sensor interface type */ |
| uint8_t si_type; |
| |
| /* Sensor interface number */ |
| uint8_t si_num; |
| |
| /* Sensor CS pin */ |
| uint8_t si_cs_pin; |
| |
| /* Sensor address */ |
| uint16_t si_addr; |
| }; |
| |
| The ``si_cs_pin`` specifies the chip select pin and is optional. The |
| ``si_type`` field must be of the following types: |
| |
| .. code:: c |
| |
| |
| #define SENSOR_ITF_SPI (0) |
| #define SENSOR_ITF_I2C (1) |
| #define SENSOR_ITF_UART (2) |
| |
| Sensor Value Type |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| |
| The ``struct sensor_cfg`` data structure represents the configuration |
| sensor type: |
| |
| .. code:: c |
| |
| /** |
| * Configuration structure, describing a specific sensor type off of |
| * an existing sensor. |
| */ |
| struct sensor_cfg { |
| /* The value type for this sensor (e.g. SENSOR_VALUE_TYPE_INT32). |
| * Used to describe the result format for the value corresponding |
| * to a specific sensor type. |
| */ |
| uint8_t sc_valtype; |
| /* Reserved for future usage */ |
| uint8_t _reserved[3]; |
| }; |
| |
| Only the ``sc_valtype`` field is currently used and specifies the data |
| value type of the sensor data. The valid value types are: |
| |
| .. code:: c |
| |
| |
| /** |
| * Opaque 32-bit value, must understand underlying sensor type |
| * format in order to interpret. |
| */ |
| #define SENSOR_VALUE_TYPE_OPAQUE (0) |
| /** |
| * 32-bit signed integer |
| */ |
| #define SENSOR_VALUE_TYPE_INT32 (1) |
| /** |
| * 32-bit floating point |
| */ |
| #define SENSOR_VALUE_TYPE_FLOAT (2) |
| /** |
| * 32-bit integer triplet. |
| */ |
| #define SENSOR_VALUE_TYPE_INT32_TRIPLET (3) |
| /** |
| * 32-bit floating point number triplet. |
| */ |
| #define SENSOR_VALUE_TYPE_FLOAT_TRIPLET (4) |
| |
| Sensor Driver Functions |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| |
| The ``struct sensor_device`` data structure represents the device driver |
| functions. The sensor device driver must implement the functions and set |
| up the function pointers. |
| |
| :: |
| |
| struct sensor_driver { |
| sensor_read_func_t sd_read; |
| sensor_get_config_func_t sd_get_config; |
| }; |
| |
| API |
| ~~~ |
| |
| .. doxygengroup:: SensorAPI |
| :content-only: |
| :members: |