Messages

The Qualcomm® sensing hub (QSH) framework uses a unified communication model based on protocol buffer-encoded messages, data streams, and sensor unique identifiers (SUIDs). This model is the shared contract used by both client applications on the application processor and sensor drivers and algorithms on the low-power processor.

​

Communication among sensors

Within the QSH framework, every sensor driver and algorithm is treated as a sensor. This means that inter-sensor communication, such as a step-counter algorithm consuming accelerometer data or a tilt-to-wake algorithm consuming gyroscope data, uses the same request and event message model as client applications on the application processor. All communication to, from, and among sensors is performed through request and event messages over data streams. Message payloads are encoded in the protocol buffer format using the nanopb generator, encoder, and decoder. The QSH framework manages the payload length, message ID, and timestamp metadata for every message. The following figure shows the communication between a data client and a data source over a data stream: As shown in the figure:

• Client to Sensor (request): The client sends request messages to enable, disable, or reconfigure a sensor. Every request targets a specific SUID. The client manager validates the request and routes it to the target sensor, which passes it to the appropriate sensor instance for handling.
• Sensor to Client (event): Sensor instances send event messages asynchronously back to their registered clients. Clients can be application-processor apps or other sensors and algorithms running on the low-power processor. Events are triggered by new sensor data, configuration changes, flush completions, or errors.

The following sequence diagram shows the full message lifecycle between a client application, the client manager, and a sensor or driver: The following sections describe the message types exchanged between the client application, the client manager, and the sensor.

​

Client messages

The client application interacts with the QSH framework through three message types:

1. Sends a sns_client_request_msg request message through the sendRequest() API. The payload field of this message carries a protocol buffer-encoded, sensor-specific request.
2. Receives a sns_client_resp_msg response message. The client manager sends this acknowledgment immediately after receiving the request. It confirms that the request was correctly encoded and that the destination SUID is reachable. Minimal processing is performed at this stage.
3. Receives one or more sns_client_event_msg event messages using the callback registered with setCallback(). Each event message belongs to a single SUID. If a client has active requests on multiple SUIDs, events for each SUID are delivered in separate messages. A single event message can carry one or more sensor samples.

​

Request message fields

All requests to the client manager use sns_client_request_msg as the outermost protocol buffer message. This message has the following fields:

• SUID: The destination address of the request. The client manager rejects any request sent to an invalid or unavailable SUID.
• msg_id: A numeric identifier that tells the destination sensor how to interpret the encoded payload. Message IDs are unique within a sensor, but two different sensors may use the same ID for different message types. For example:
  • SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_CONFIG: Standard streaming request from a client to a sensor.
  • SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_EVENT: Standard sensor event from a data source sensor.
• Request (sns_std_request): The information package sent to the sensor. The sns_std_request::payload field carries the sensor-specific configuration, encoded as a protocol buffer message corresponding to the msg_id. For details, see the sensor-specific .proto file.
• Resampler configuration (optional): Controls the rate at which the client receives sensor data. Use one of the following options:
  • SNS_RESAMPLER_RATE_FIXED: Deliver data at an exact rate. For example, if the client requests 200 Hz but the sensor runs at 240 Hz, samples are interpolated down to 200 Hz.
  • SNS_RESAMPLER_RATE_MINIMUM: Deliver data at no less than the requested rate. For example, if the client requests 200 Hz but the sensor runs at 240 Hz, samples are delivered at 240 Hz.
• Threshold configuration (optional): Filters events so the client only receives data when a condition is met. The following threshold types are supported:
  • SNS_THRESHOLD_TYPE_RELATIVE_VALUE: Triggers when the delta between the current value and the last reported value exceeds the configured threshold.
  • SNS_THRESHOLD_TYPE_RELATIVE_PERCENT: Triggers when the difference between the current and last reported value exceeds a percentage of the last reported value.
  • SNS_THRESHOLD_TYPE_ABSOLUTE: Triggers when the current value crosses a fixed threshold.
  • SNS_THRESHOLD_TYPE_ANGLE: Triggers when the angle between the current and last reported quaternion exceeds the configured threshold, in radians. Applies to quaternion sensors only.
• Suspend configuration (optional): Controls system behavior when the client processor suspends. It has the following sub-fields:
  • client_proc_type: Identifies the processor where the client runs. A flush request from any client on this processor causes all clients on that processor to receive a flush.
  • delivery_type: Specifies whether events are delivered while the processor is suspended:
    • SNS_STD_DELIVERY_WAKEUP: Delivers events as they become available, regardless of processor state. If the requested batch_period exceeds system capacity, data is sent when the buffer is full. The flush_period is effectively ignored with this option.
    • SNS_STD_DELIVERY_NO_WAKEUP: Holds events while the processor is suspended and delivers all pending events when the processor resumes.
  • nowakeup_msg_ids: A list of message IDs that must not wake the client processor. These messages are only delivered if other wake-up-capable events are already being sent.
  For the full field reference, see <workspace>/build-qcom-wayland/workspace/sources/sensinghub/sensing-hub/apis/proto/sns_client.proto, where <workspace> is your working directory.

​

Batching

Within sns_client_request_msg::sns_std_request, the client can control how and when data is delivered using the following batching fields:

• batching::batch_period: Maximum time in microseconds between data deliveries. All events generated since the last delivery are held until this timer fires. In concurrency scenarios, events may be delivered sooner. A flush request overrides this timer immediately. Batching is disabled by default (batch_period = 0).
• batching::flush_period: A hint to the client manager and physical sensor about how much historical data to retain, in microseconds. Data older than this value may be dropped. If not set, defaults to batch_period, meaning only one batch is retained. When set, flush_period must be greater than or equal to batch_period.
• batching::flush_only: If True, the client manager delivers events only when the client explicitly sends a flush request. Otherwise, batching continues until flush_period is reached, at which point the oldest data is dropped.
• batching::max_batch: If True, directs the sensor to use its maximum hardware batching capacity. If both flush_only and max_batch are True, flush_only takes precedence.

​

Event message fields

All events delivered to the client use sns_client_event_msg as the outermost protocol buffer message. This message is carried inside the payload field of sns_client_report_ind_msg, which is the transport-level indication wrapper. The sns_client_event_msg message has the following fields:

• SUID: Identifies the data source that generated the event. If a client has active requests on multiple SUIDs, each SUID’s events are delivered in a separate sns_client_event_msg message.
• events::msg_id: Identifies the type of event and uses the same numeric ID space as requests — it tells the client which proto message to use when decoding the payload.
• events::timestamp: The time the event occurred, in QTimer clock ticks. For sensor data events, this is the time the physical sample was captured in hardware. For framework-generated events (configuration updates, errors, flush completions), this is the time the event was created.
• events::payload: The encoded event data. Decode this field using the sensor-specific proto buffer corresponding to the msg_id.

Events are generated in the following situations:

• New sensor data is available at the configured sample rate or batch period.
• A sensor configuration change is processed (SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_PHYSICAL_CONFIG_EVENT).
• A flush request completes (SNS_STD_MSGID_SNS_STD_FLUSH_EVENT).
• An error occurs in the sensor, sensor instance, or framework (SNS_STD_MSGID_SNS_STD_ERROR_EVENT).

​

Message payloads

The sensor-specific content of a request or event is carried in the payload field of sns_std_request and sns_client_event, respectively. These fields contain a protocol buffer-encoded message whose structure is defined by the msg_id. The field may also be empty if the message type carries no additional data. Clients use the .proto file for the sensor they’re communicating with. Each sensor type has a corresponding .proto file. For example, sns_accel.proto describes how to enable an accelerometer stream. Every sensor publishes its list of .proto files as part of its attributes.

• Data types: Each sensor advertises a data type attribute. A data type maps to a unique set of .proto files that define the sensor-specific API. All sensors of the same type must support a minimum set of request and event messages, and may define additional optional messages specific to their implementation.
• Standardized messages: The following Qualcomm-defined messages can be sent to any sensor. They’re defined in the sns_std.proto file.
  • SNS_STD_MSGID_SNS_STD_ATTR_REQ: Queries a sensor for its published attributes. The sensor responds with an SNS_STD_MSGID_SNS_STD_ATTR_EVENT containing all attributes.
    • sns_std_attr_req::register_updates: If True, the client receives an sns_std_attr_event notification whenever the sensor’s attributes change.
    • sns_std_attr_event::attributes: The list of all attributes published by the sensor, returned in response to sns_std_attr_req or on an attribute change.
  • SNS_STD_MSGID_SNS_STD_FLUSH_REQ: Forces all batched data from this sensor to be immediately delivered to the client. This flushes both hardware buffers (for example, the physical FIFO on an accelerometer) and any data held by the client manager. For algorithm sensors such as game rotation vector (GRV), this also flushes the FIFOs of all underlying physical sensors (accelerometer, gyroscope).
  • SNS_CLIENT_MSGID_SNS_CLIENT_DISABLE_REQ: Cancels the active request for this sensor. For example, if the client previously sent SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_CONFIG to enable accelerometer streaming, sending DISABLE_REQ stops the stream for this client.
  • SNS_STD_MSGID_SNS_STD_FLUSH_EVENT: Sent by the sensor in response to a flush request. Indicates that all data corresponding to the flush has been delivered and no further flush events follow.
  • SNS_STD_MSGID_SNS_STD_ERROR_EVENT: An error event generated by a sensor, sensor instance, or the framework.
  For the full message reference, see <workspace>/build-qcom-wayland/workspace/sources/sensinghub/sensing-hub/apis/proto/sns_client.proto.
• Standardized sensor messages: In addition to the messages above, the following Qualcomm-recommended messages apply to standard sensors. These are optional; you can define your own request and event messages instead. They’re defined in sns_std_sensor.proto:
  • SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_CONFIG: Enables streaming for physical sensors (accelerometer, gyroscope, magnetometer) and some algorithm sensors (rotation vector, gravity, linear acceleration).
  • SNS_STD_SENSOR_MSGID_SNS_STD_ON_CHANGE_CONFIG: Enables streaming for on-change sensors such as proximity, ambient light, and step detect.
  • SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_PHYSICAL_CONFIG_EVENT: Sent by physical sensors after processing a client request. Indicates the actual operating parameters, such as the sample rate the sensor produces.
  • SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_EVENT: A data sample produced by the sensor in response to an active streaming request.
• SUID lookup: Before sending any request, a client must know the SUID of the target sensor. The SUID lookup sensor provides this. A client sends an sns_suid_req message specifying a data type string (for example, accel), and receives back all matching SUIDs. An empty data type string returns all SUIDs on the system. The SUID lookup sensor has a fixed, well-known SUID published in sns_suid.proto. If the client wants to be notified when new sensors of a given type become available, it sets the register_updates field to True. After receiving SUIDs, the client can send an sns_std_attr_req to each SUID to inspect attributes and select the most appropriate sensor. The sns_suid_req message has the following fields. For more information, see the sns_suid.proto file and example code.

Table : SUID request

Field	Mandatory or optional	Data type	Description
data_type	Mandatory	String	Data type of the sensor to query, for example accel or gyro.
register_updates	Optional	Boolean	If True, the client receives a new SUID event whenever a sensor advertising this data type becomes available or unavailable.
default_only	Optional	Boolean	If True and a default sensor is explicitly configured for the data type, only that sensor’s SUID is returned. If no default is configured, the SUID of the first matching sensor is returned. If False, all SUIDs matching the data type are returned as they become available.

​

Sensor attributes

Every sensor publishes a list of attributes identified by a numeric ID. Attributes describe the sensor’s capabilities, operating parameters, and the range of values it accepts. A client queries attributes using SNS_STD_MSGID_SNS_STD_ATTR_REQ and receives them in an SNS_STD_MSGID_SNS_STD_ATTR_EVENT response. The following table lists the standard sensor attributes: Table : Sensor attributes

Attribute ID	Attribute name	Required?	Data type	Description
0	SNS_STD_SENSOR_ATTRID_NAME	Yes	String	Human-readable sensor name.
1	SNS_STD_SENSOR_ATTRID_VENDOR	Yes	String	Human-readable vendor name.
2	SNS_STD_SENSOR_ATTRID_TYPE	Yes	String	The data type used by this sensor, as defined in the sensor proto file.
3	SNS_STD_SENSOR_ATTRID_AVAILABLE	Yes	Boolean	Indicates whether this sensor is currently available to clients.
4	SNS_STD_SENSOR_ATTRID_VERSION	Yes	Integer	64-bit integer representing the sensor driver version as major[31:16].minor[15:8].revision[7:0]. For example: major 0x0002, minor 0x00, revision 0x36 gives DRIVER_VERSION 0x00020036.
5	SNS_STD_SENSOR_ATTRID_API	Yes	String	List of .proto filenames used by this sensor. Additional proto dependencies are specified as imports within those files. Used primarily for test automation.
6	SNS_STD_SENSOR_ATTRID_RATES	No	Float	List of sample rates supported by the sensor, in Hz.
7	SNS_STD_SENSOR_ATTRID_RESOLUTIONS	No	Float	List of sample resolutions supported by the sensor.
8	SNS_STD_SENSOR_ATTRID_FIFO_SIZE	No	Integer	Supported FIFO depth, in number of samples.
9	SNS_STD_SENSOR_ATTRID_ACTIVE_CURRENT	No	Integer	Array of active current draw values, in µA.
10	SNS_STD_SENSOR_ATTRID_SLEEP_CURRENT	No	Integer	Inactive (sleep) current draw, in µA.
11	SNS_STD_SENSOR_ATTRID_RANGES	No	Float	Supported operating measurement ranges.
12	SNS_STD_SENSOR_ATTRID_OP_MODES	No	String	Operating modes supported by the sensor, for example [LPM, HIGH_PERF, NORMAL, OFF].
13	SNS_STD_SENSOR_ATTRID_DRI	No	Boolean	Interrupt type supported: True = data ready interrupt (DRI); False = in-band interrupt (IBI).
14	SNS_STD_SENSOR_ATTRID_STREAM_SYNC	No	Boolean	Indicates whether the sensor supports synchronized streaming.
15	SNS_STD_SENSOR_ATTRID_EVENT_SIZE	No	Integer	Size in bytes of the protocol-buffer-encoded data event produced by this sensor. Used by the HAL to determine maximum batching capacity.
16	SNS_STD_SENSOR_ATTRID_STREAM_TYPE	Yes	Integer	Streaming type: 0 = continuous periodic, 1 = on-change, 2 = one-shot.
17	SNS_STD_SENSOR_ATTRID_DYNAMIC	No	Boolean	True if the sensor can connect or disconnect at runtime.
18	SNS_STD_SENSOR_ATTRID_HW_ID	No	Integer	Hardware identifier used to distinguish multiple sensors of the same type.
19	SNS_STD_SENSOR_ATTRID_RIGID_BODY	No	Integer	Physical location of the sensor: 0 = display side, 1 = keyboard side, 2 = external device.
21	SNS_STD_SENSOR_ATTRID_PHYSICAL_SENSOR	No	Boolean	True if this is a physical sensor; False if it is a virtual (algorithm) sensor.
22	SNS_STD_SENSOR_ATTRID_PHYSICAL_SENSOR_TESTS	No	Integer	List of supported physical sensor self-tests, using enum values from sns_physical_sensor_test_type.
23	SNS_STD_SENSOR_ATTRID_SELECTED_RESOLUTION	No	Float	Active measurement resolution for each configured dynamic range value.
24	SNS_STD_SENSOR_ATTRID_SELECTED_RANGE	No	Float[2]	Active dynamic range. For the default value, see the sensor hardware requirement specification from the vendor.
25	SNS_STD_SENSOR_ATTRID_ADDITIONAL_LOW_LATENCY_RATES	No	Float	Additional sample rates available for low-latency dedicated clients, in Hz. These extend the rates in SNS_STD_SENSOR_ATTRID_RATES and may impact system performance if used by non-dedicated clients.
26	SNS_STD_SENSOR_ATTRID_PASSIVE_REQUEST	No	Boolean	True if the sensor supports passive requests. If False, all requests are treated as active.
29	SNS_STD_SENSOR_ATTRID_TRANSPORT_MTU_SIZE	No	Integer	Maximum transmission unit (MTU) size for a transport sensor, in bytes.
30	SNS_STD_SENSOR_ATTRID_HLOS_INCOMPATIBLE	No	Boolean	True if the sensor is not compatible with the HLOS specification for its data type.
31	SNS_STD_SENSOR_ATTRID_SERIAL_NUM	No	String	Sensor serial number.
32	SNS_STD_SENSOR_ATTRID_TECH_USED	No	Integer array	Technologies used by this sensor. For the list of values, see sns_tech in sns_std_type.proto.

For more information, see the sns_std_sensor.proto file and example code. Proto files are located in the /etc/sensors/proto/ directory on the device.

​

Protocol buffers

The QSH client request and event messages are opaque memory buffers containing protocol buffer-encoded payloads. Clients can generate these messages in any language supported by the nanopb library, encode them into a byte stream, and copy that stream into the sns_client_request_msg payload field. Similarly, clients extract the payload from sns_client_report_ind_msg and decode it using the appropriate .proto definition. For more information, see Protocol Buffers and nanopb.