aliro_uwb_msg.c
setup/notification message codec.
Overview
setup/notification message codec.
depends on woz_log.h aliro_uwb_msg.h aliro_uwb_msg_builder.h aliro_uwb_msg_parser.h aliro_uwb_msg_spec.h aliro_uwb_adapter.h aliro_round_config.h woz_alloc.h woz_util.h
flowchart TD aliro_uwb_msg_build_general_error --> aliro_uwb_msg_free
API
Fvoid aliro_uwb_msg_free(struct aliro_uwb_message *message)
Releases a message allocated by this layer's message builders.
aliro_uwb_msg_build_general_error, aliro_uwb_msg_build_m1, aliro_uwb_msg_build_m3, aliro_uwb_msg_build_suspend_response, aliro_uwb_msg_build_suspend_resume_requestFstruct aliro_uwb_message *aliro_uwb_msg_build_m1(struct aliro_uwb_session *session)
Builds the M1 ranging-session-setup message advertising configuration IDs, pulse-shape combos, channel bitmask, and session ID.
session- Session whose Aliro capabilities and session ID populate the message.
- returns
- Newly allocated M1 message, or NULL if builder init or attribute encoding fails.
aliro_uwb_msg_freeFstatic struct aliro_uwb_message *aliro_uwb_msg_build_m3(struct aliro_uwb_session *session)
Builds the M3 ranging-parameters message, deriving RAN multiplier and chaps-per-slot from the M2-negotiated durations and committing the reader's MAC mode.
session- Session whose negotiated M2 config and reader settings populate the M3 attributes.
- returns
- Newly allocated M3 message, or NULL if builder init or attribute encoding fails.
handle_m2 · calls aliro_uwb_msg_freeFaliro_uwb_msg_build_suspend_resume_request
Builds a suspend or resume request message carrying the session identifier.
session- Session whose session ID is encoded into the message.
suspend- True to build a suspend request, false to build a resume request.
- returns
- Newly allocated request message, or NULL if builder init or attribute encoding fails.
aliro_uwb_msg_freeFaliro_uwb_msg_build_suspend_response
Builds a suspend-response message carrying an accept or reject status.
session- Unused; reserved for a consistent builder signature.
status- Response status; must be ALIRO_UWB_RANGING_SERVICE_STATUS_ACCEPT or ALIRO_UWB_RANGING_SERVICE_STATUS_REJECT.
- returns
- Newly allocated suspend-response message, or NULL if status is invalid, or if builder init or attribute encoding fails.
handle_suspend_request · calls aliro_uwb_msg_freeFstruct aliro_uwb_message *aliro_uwb_msg_build_general_error(struct aliro_uwb_session *session, uint8_t error_code)
Builds an Aliro general-error notification message carrying the given error code.
session- Unused; reserved for a consistent builder signature.
error_code- Error code to encode in the general-error notification attribute.
- returns
- Newly allocated notification message, or NULL if builder init or attribute encoding fails.
aliro_uwb_msg_freeFuint8_t aliro_uwb_msg_protocol_header(const uint8_t *bytes)
Extracts the protocol type from byte 0 of an Aliro message header.
bytes- Pointer to the start of the raw message bytes.
- returns
- The protocol type byte.
Fuint8_t aliro_uwb_msg_message_id(const uint8_t *bytes)
Extracts the message type ID from byte 1 of an Aliro message header, used to dispatch M1-M4 setup and ranging messages during parsing.
bytes- Pointer to the start of the raw message bytes.
- returns
- The message ID byte.
aliro_uwb_msg_process_notification, aliro_uwb_msg_process_ranging, aliro_uwb_msg_process_supplementaryFuint16_t aliro_uwb_msg_payload_length(const uint8_t *bytes)
Extracts the payload length from bytes 2-3 of an Aliro message header as a 16-bit big-endian integer.
bytes- Pointer to the start of the raw message bytes.
- returns
- The payload length in bytes.
aliro_uwb_msg_process_supplementaryFstatic enum aliro_uwb_err parse_config_id(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the UWB configuration ID attribute from M2 and stores it in the session config.
session- Session whose config receives the parsed configuration ID.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_pulse_shape(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the pulse-shape-combo attribute from M2 and stores it in the session config.
session- Session whose config receives the parsed pulse shape.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_session_id(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the session-identifier attribute from M2 and verifies it matches the session's active session ID.
session- Session whose session ID is checked against the parsed value.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read, or ALIRO_UWB_ERR_INVALID_PARAMETER on a session ID mismatch.
parse_session_attributeFstatic enum aliro_uwb_err parse_channel(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the channel bitmask attribute from M2, mapping it to channel 5 or 9 in the session config.
session- Session whose config receives the resolved channel number.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read, or ALIRO_UWB_ERR_INVALID_PARAMETER for an unsupported bitmask.
parse_session_attributeFstatic enum aliro_uwb_err parse_ran_multiplier(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the RAN multiplier attribute from M3, selecting the larger of the peer's value and the reader's minimum, and computes the ranging duration in milliseconds.
session- Session whose config receives the computed ranging duration.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_slot_bitmask(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the slot bitmask attribute from M3, intersects it with the local capability bitmask, and maps the lowest common bit to a chaps-per-slot count to compute slot duration.
session- Session whose config receives the computed slot duration.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_sync_code_bitmask(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the sync code bitmask attribute from M2 and logs the peer's offered bitmask; the reader retains its own capability bitmask for M3 and does not update the session config.
session- Unused; reserved for a consistent parser signature.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_sync_code_index(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the sync code index attribute from M3 and stores it in the session config.
session- Session whose config receives the parsed sync code index.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALDORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_hopping_bitmask(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the hopping configuration bitmask attribute from M2, intersects peer capabilities with local CCC capabilities, and selects the first mutually supported preferred hopping config.
session- Session whose reader preferences are matched and whose config receives the selected hopping mode.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read or no common hopping config is found.
parse_session_attributeFstatic enum aliro_uwb_err parse_sts_index0(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the STS index 0 attribute from M2 and stores it in the session config.
session- Session whose config receives the parsed STS index.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_uwb_time0(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the UWB time 0 attribute from M2 and stores it as the session's initial UWB time.
session- Session whose config receives the parsed UWB time.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_hop_mode_key(struct aliro_uwb_session *session, struct aliro_uwb_msg_attribute *attr)
Parses the hop mode key attribute from M2 and stores the raw key bytes in the session config; unused downstream on this lock.
session- Session whose config receives the parsed hop mode key.
attr- Attribute to parse.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_session_attributeFstatic enum aliro_uwb_err parse_status(struct aliro_uwb_msg_attribute *attr, uint8_t *status)
Parses a status attribute from a ranging message into the given output parameter.
attr- Attribute to parse.
status- Output parameter receiving the parsed 8-bit status value.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_MSG_MALFORMED if the value cannot be read.
parse_rangingFstatic enum aliro_uwb_err parse_session_attribute(struct aliro_uwb_msg_attribute *attr, struct aliro_uwb_session *session)
Dispatches a ranging-service session attribute to its type-specific parser and applies it to the session; unknown attributes are logged and ignored.
attr- Attribute to parse and apply.
session- Session updated by the attribute-specific parser.
- returns
- ALIRO_UWB_ERR_NONE on success or for ignored/unknown attributes, otherwise the error from the specific parser.
parse_ranging · calls parse_channel, parse_config_id, parse_hop_mode_key, parse_hopping_bitmask, parse_pulse_shape, parse_ran_multiplier, parse_session_id, parse_slot_bitmaskFstatic enum aliro_uwb_err parse_ranging(struct aliro_uwb_session *session, struct aliro_uwb_message *message, uint32_t *attr_mask, uint8_t *status)
Parses all ranging-service attributes in a message, applying each to the session and recording which attributes were present.
session- Session updated by attribute-specific parsers.
message- Message whose attributes are parsed.
attr_mask- Output parameter receiving a bitmask of attribute IDs present in the message.
status- Output parameter receiving the parsed status, or ALIRO_UWB_RANGING_SERVICE_STATUS_UNKNOWN if no status attribute is present.
- returns
- ALIRO_UWB_ERR_NONE on success, or the first parsing error encountered.
handle_m2, handle_m4, handle_resume_response, handle_suspend_request, handle_suspend_response · calls parse_session_attribute, parse_statusFstatic void compute_initiation_time(struct aliro_uwb_session *session)
Sets the session's ranging initiation time from its time offset, using zero if unsynchronized or adding the offset to the existing UWB time otherwise.
session- Session whose config's uwb_time_us is updated in place.
handle_m4, handle_resume_responseFstatic enum aliro_uwb_err set_resume_params(struct aliro_uwb_session *session)
Sets the STS index and initiation time on the CCC session in preparation for re-arming ranging after a suspend.
session- Session whose CCC session and Aliro config supply the resume parameters.
- returns
- ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_INTERNAL if either CCC call fails.
handle_resume_responseFstatic enum aliro_uwb_err handle_m2(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Handles an inbound M2 message by validating its attributes and session state, then building and transmitting M3 and advancing to the M3_SENT state.
session- Session receiving the M2 message.
message- Inbound M2 message to process.
- returns
- ALIRO_UWB_ERR_NONE on success, or an error if parsing, attributes, state, or M3 construction fail.
aliro_uwb_msg_process_ranging · calls aliro_uwb_msg_build_m3, parse_rangingFstatic enum aliro_uwb_err handle_m4(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Handles an inbound M4 message by validating its attributes and session state, computing the ranging initiation time, initializing the session, and advancing to the RANGING state.
session- Session receiving the M4 message.
message- Inbound M4 message to process.
- returns
- ALIRO_UWB_ERR_NONE on success, or an error if parsing, attributes, state, or session initialization fail.
aliro_uwb_msg_process_ranging · calls compute_initiation_time, parse_rangingFstatic enum aliro_uwb_err handle_suspend_request(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Handles an inbound suspend request by validating session state, stopping the session, then building and transmitting a suspend response with acceptance or rejection status.
session- Session receiving the suspend request.
message- Inbound suspend-request message to process.
- returns
- ALIRO_UWB_ERR_NONE on success, or an error if parsing, attributes, state, or response construction fail.
aliro_uwb_msg_process_ranging · calls aliro_uwb_msg_build_suspend_response, parse_rangingFstatic enum aliro_uwb_err handle_suspend_response(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Handles an inbound suspend response by validating its attributes and session state, stopping the session if accepted or returning to the RANGING state if rejected.
session- Session receiving the suspend response.
message- Inbound suspend-response message to process.
- returns
- ALIRO_UWB_ERR_NONE on success, or an error if parsing, attributes, or state validation fail.
aliro_uwb_msg_process_ranging · calls parse_rangingFstatic enum aliro_uwb_err handle_resume_response(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Handle an inbound resume response, arm timing and CCC state, and start ranging.
session- Aliro UWB session expected to be in RESUME_REQ_SENT state.
message- Received resume response message to validate and parse.
- returns
- ALIRO_UWB_ERR_NONE on success; an error if attributes are missing, state is wrong, or resume setup/session start fails.
aliro_uwb_msg_process_ranging · calls compute_initiation_time, parse_ranging, set_resume_paramsFenum aliro_uwb_err aliro_uwb_msg_process_ranging(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Dispatch an inbound ranging-phase message to its handler based on message type.
session- Aliro UWB session to update.
message- Received ranging message to dispatch.
- returns
- Handler's result on success; ALIRO_UWB_ERR_INVALID_PARAMETER if session or message is NULL; ALIRO_UWB_ERR_MESSAGE_UNSUPPORTED for unknown message types.
aliro_uwb_msg_message_id, handle_m2, handle_m4, handle_resume_response, handle_suspend_request, handle_suspend_responseFstatic enum aliro_uwb_err handle_init_ranging_later(struct aliro_uwb_session *session)
Handle an "init ranging later" notification, returning the session to CREATED state.
session- Aliro UWB session expected to be in M1_SENT state.
- returns
- ALIRO_UWB_ERR_NONE on success; ALIRO_UWB_ERR_INVALID_STATE if the session is not in M1_SENT.
parse_ranging_notificationFstatic enum aliro_uwb_err handle_resume_later(struct aliro_uwb_session *session)
Handle a "resume later" notification, moving the session to SUSPENDED without re-arming ranging.
session- Aliro UWB session expected to be in RESUME_REQ_SENT state.
- returns
- ALIRO_UWB_ERR_NONE on success; ALIRO_UWB_ERR_INVALID_STATE if the session is not in RESUME_REQ_SENT.
parse_ranging_notificationFstatic enum aliro_uwb_err handle_ranging_suspended(struct aliro_uwb_session *session)
Handle a "ranging suspended" notification by stopping the session and moving it to SUSPENDED.
session- Aliro UWB session expected to be in RANGING state.
- returns
- ALIRO_UWB_ERR_NONE on success; ALIRO_UWB_ERR_INVALID_STATE if the session is not in RANGING; otherwise the result of stopping the session.
parse_ranging_notificationFstatic enum aliro_uwb_err parse_event_notification(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Parse an Aliro event notification message, logging busy, general-error, and reader-descriptor events.
session- Aliro UWB session (unused).
message- Received event notification message to parse.
- returns
- ALIRO_UWB_ERR_NONE on success; ALIRO_UWB_ERR_MSG_MALFORMED if a general-error attribute has the wrong length.
aliro_uwb_msg_process_notificationFstatic enum aliro_uwb_err parse_ranging_notification(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Parse a ranging-setup notification message and dispatch each attribute to its session state handler.
session- Aliro UWB session to update.
message- Received ranging notification message to parse.
- returns
- ALIRO_UWB_ERR_NONE on success; the first handler error encountered otherwise.
aliro_uwb_msg_process_notification · calls handle_init_ranging_later, handle_ranging_suspended, handle_resume_laterFenum aliro_uwb_err aliro_uwb_msg_process_notification(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Dispatch a received notification message to its parser by message ID. Reader-status notifications are informational and ignored; unknown IDs are logged and ignored.
session- Aliro UWB session to update with the parsed notification's effects.
message- Received notification message to dispatch.
- returns
- ALIRO_UWB_ERR_NONE for handled, informational and unknown notifications, otherwise the error from the event or ranging parser.
aliro_uwb_msg_message_id, parse_event_notification, parse_ranging_notificationFenum aliro_uwb_err aliro_uwb_msg_process_supplementary(struct aliro_uwb_session *session, struct aliro_uwb_message *message)
Log every attribute of a Supplementary Service message (protocol 0x03). The phone sends one of these at session establishment. Nothing is modelled yet and no response is emitted, so this only surfaces the payload: the semantics are unknown and are being characterised by diffing the attributes across conditions.
session- Aliro UWB session (unused; no state is driven from here yet).
message- Received supplementary-service message to log.
- returns
- ALIRO_UWB_ERR_NONE always.
aliro_uwb_msg_message_id, aliro_uwb_msg_payload_length