Sensor Subsystem
Relevant source files
The following files were used as context for generating this wiki page:
The Sensor Subsystem (also referred to as the Sensing Subsystem) is a high-level sensor framework located within the Zephyr RTOS user space service layer. It is designed to manage complex sensor tasks such as sensor fusion, client arbitration, data sampling, timing, and power management. By providing a decoupled architecture, it supports various up-layer frameworks and applications regardless of the specific sensor exposure or transfer protocols used, such as CHRE or MQTT.
The subsystem distinguishes between physical sensors, which interact directly with hardware drivers, and virtual sensors, which process data from other sensor objects. This modularity allows the underlying device drivers to remain simple and focused on hardware abstraction while the sensing subsystem handles sophisticated data processing and scheduling in user space.
Sources: doc/services/sensing/index.rst:1-40, doc/introduction/index.rst:1-20
Architecture and Key Concepts
The Sensing Subsystem is built on a data-driven model that separates the concerns of data collection and data fusion. It utilizes a single-thread main loop for scheduling the sampling and processing of all registered sensor objects.
Sensor Types
The framework categorizes sensors into two primary types:
- Physical Sensors: These objects interact directly with the existing Zephyr sensor device drivers. Their primary responsibility is data collection from hardware.
- Virtual Sensors: These objects rely on other physical or virtual sensors as inputs. They are primarily used for sensor fusion and algorithm implementation.
Sources: doc/services/sensing/index.rst:13-25, doc/services/sensing/index.rst:80-90
System Integration
The following diagram illustrates the position of the Sensing Subsystem within the Zephyr architecture, sitting between low-level drivers and high-level applications.
This diagram shows the hierarchical relationship where applications interact with the subsystem, which in turn manages both virtual and physical sensor instances.
Sources: doc/services/sensing/index.rst:45-75
Functional Components
Scheduling and Arbitration
The subsystem manages a scheduling framework that governs sensor object relationships. It handles both polling mode (periodical sampling) and interrupt mode (data-ready or threshold interrupts). Client arbitration ensures that multiple applications or sensors requesting data from the same source are managed efficiently.
Sources: doc/services/sensing/index.rst:80-100
Data Structure and Timing
Sensor sample values consist of a common header and a reading array. Timing is managed with microsecond precision.
| Component | Description |
|---|---|
| Header | Contains base_timestamp in microseconds. |
| Readings | Array of data points containing timestamp_delta. |
| Data Format | Supports Q Format (e.g., q31) for DSP library integration. |
The timestamp_delta is relative to the previous reading or the base timestamp. If consecutive readings differ by more than the maximum uint32_t value (approximately 4295 seconds), the runtime splits the data into multiple events.
Sources: doc/services/sensing/index.rst:155-200
Sensor Instances and API Access
Applications can open sensor instances using two distinct methods depending on whether they need dynamic discovery or direct access.
Access Methods
- Enumeration: Applications use
sensing_get_sensors()to retrieve an array ofsensing_sensor_infostructures. This is common for frameworks like CHRE or HID that must discover platform capabilities at runtime. - Devicetree: Applications can open a specific sensor directly using
sensing_open_sensor_by_dt()with a devicetree node identifier.
Reporting Topology
The reporting relationship between sensors is automatically generated based on Devicetree definitions. While applications must explicitly call sensing_open_sensor(), the relationships between client sensors and reporter sensors are handled internally by the subsystem.
The sequence shows how the application initializes contact while the subsystem manages the underlying reporting dependencies.
Sources: doc/services/sensing/index.rst:120-150
Security and Safety Considerations
The Sensor Subsystem follows the broader Zephyr Project standards for security and quality.
- Execution Protection: Sensor threads benefit from Zephyr's thread separation and stack protection mechanisms, which detect and trap stack overruns.
- Quality Assurance: Code within the sensing subsystem is subject to mandatory code reviews and static analysis to ensure stability and verify user input validation.
- Safety Requirements: For safety-critical sensor applications, the project follows IEC 61508 standards, requiring 100% structural test coverage for entry points, statements, and branches within the safety scope.
Sources: doc/security/security-overview.rst:50-100, doc/safety/safety_overview.rst:150-180, doc/introduction/index.rst:110-120
Summary
The Sensor Subsystem provides a robust, modular framework for handling complex sensor data in Zephyr. By abstracting hardware into physical and virtual sensor objects, it enables sophisticated sensor fusion and multi-client support while maintaining a clean separation from low-level drivers. Its reliance on Devicetree for configuration and its integration with Zephyr's security and safety features make it suitable for both simple IoT devices and complex, safety-certified systems.
Sources: doc/services/sensing/index.rst:5-30, samples/sample_definition_and_criteria.rst:5-15