aliro_uwb_session.c File Reference

— per-session lifecycle and state machine. More...

#include "aliro_uwb_internal.h"
#include "aliro_uwb_msg.h"
#include "aliro_uwb_msg_spec.h"
#include <aliro_uwb_adapter/aliro_uwb_session.h>
#include <cherry/cherry_ccc.h>
#include "woz_alloc.h"
#include <string.h>
#include "woz_log.h"

Include dependency graph for aliro_uwb_session.c:

Functions
static enum aliro_uwb_err	notify_error (struct aliro_uwb_session *session)
	Send a general-error notification to the peer.
static void	aliro_ccc_cb (struct cherry_ccc_event *event, void *user_data)
	CCC seam callback: wrap the CCC event and forward it to the client.
static void	session_close (struct aliro_uwb_session *session)
	Tear down: destroy the CCC session, or free directly if there is none.
enum aliro_uwb_err	aliro_uwb_session_init (struct aliro_uwb_session *session)
	Initialize a session by creating and configuring a CCC Aliro responder, setting URSK, protocol version, antennas, and diagnostics, then starting the session.
enum aliro_uwb_err	aliro_uwb_session_start (struct aliro_uwb_session *session)
	Start an active CCC session.
enum aliro_uwb_err	aliro_uwb_session_stop (struct aliro_uwb_session *session)
	Stop an active CCC session, transitioning to SUSPENDED state.
struct aliro_uwb_session *	aliro_uwb_session_create (struct aliro_uwb_adapter *aliro_ctx, uint32_t session_id, aliro_uwb_session_cb_t callback, aliro_uwb_adapter_transmit_message_t transmit, void *user_data)
	Allocate an Aliro UWB session in the CREATED state, bound to an adapter and to the caller's transmit and event callbacks.
void	aliro_uwb_session_destroy (struct aliro_uwb_session *session)
	Destroy an Aliro UWB session, freeing the URSK and tearing down the underlying CCC session.
void	aliro_uwb_session_message_free (struct aliro_uwb_message *message)
	Free a session message, delegating to the message-specific free function.
void	aliro_uwb_session_event_free (struct aliro_uwb_session_event *event)
	Free a session event, releasing its wrapped CCC event if present.
enum aliro_uwb_err	aliro_uwb_session_set_ursk (struct aliro_uwb_session *session, const uint8_t *ursk)
	Store a copy of the URSK (Unique Ranging Session Key) for later use during session initialization.
enum aliro_uwb_err	aliro_uwb_session_set_protocol_version (struct aliro_uwb_session *session, uint16_t selected_protocol_version)
	Store the protocol version selected by the reader for later use during session initialization.
enum aliro_uwb_err	aliro_uwb_session_init_setup (struct aliro_uwb_session *session)
	Begin session setup by building and transmitting M1, transitioning from CREATED to M1_SENT state.
enum aliro_uwb_err	aliro_uwb_session_set_time_offset (struct aliro_uwb_session *session, int64_t time_offset)
	Store the time offset used to synchronize clocks between reader and device.
enum aliro_uwb_err	aliro_uwb_session_message_handle (struct aliro_uwb_session *session, struct aliro_uwb_message *message)
	Validate and dispatch an incoming Aliro UWB message to the appropriate protocol handler.
enum aliro_uwb_err	aliro_uwb_session_suspend (struct aliro_uwb_session *session)
	Suspend an active ranging session by sending a suspend request.
enum aliro_uwb_err	aliro_uwb_session_forced_suspend (struct aliro_uwb_session *session)
	Forcibly stop the active CCC session, transitioning it to SUSPENDED without a request/response exchange.
enum aliro_uwb_err	aliro_uwb_session_resume (struct aliro_uwb_session *session)
	Resume a suspended ranging session by building and transmitting a resume request.

Detailed Description

— per-session lifecycle and state machine.

Function Documentation

aliro_ccc_cb()

static void aliro_ccc_cb ( struct cherry_ccc_event *  event, void *  user_data  )

static

CCC seam callback: wrap the CCC event and forward it to the client.

Parameters

event	CCC event to wrap and forward.
user_data	Aliro UWB session that owns the callback and client data.

aliro_uwb_session_create()

struct aliro_uwb_session * aliro_uwb_session_create	(	struct aliro_uwb_adapter *	aliro_ctx,
		uint32_t	session_id,
		aliro_uwb_session_cb_t	callback,
		aliro_uwb_adapter_transmit_message_t	transmit,
		void *	user_data
	)

Allocate an Aliro UWB session in the CREATED state, bound to an adapter and to the caller's transmit and event callbacks.

Create a session in the CREATED state.

No CCC session is started here.

aliro_uwb_session_destroy()

void aliro_uwb_session_destroy

(

struct aliro_uwb_session *

session

)

Destroy an Aliro UWB session, freeing the URSK and tearing down the underlying CCC session.

Stop if needed and release a session.

Parameters

session

Session to destroy; no-op if NULL.

aliro_uwb_session_event_free()

void aliro_uwb_session_event_free

(

struct aliro_uwb_session_event *

event

)

Free a session event, releasing its wrapped CCC event if present.

Free an event delivered to the session callback.

aliro_uwb_session_forced_suspend()

enum aliro_uwb_err aliro_uwb_session_forced_suspend

(

struct aliro_uwb_session *

session

)

Forcibly stop the active CCC session, transitioning it to SUSPENDED without a request/response exchange.

Suspend ranging immediately without waiting for a peer response.

Parameters

session

Session to force-suspend.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL, ALIRO_UWB_ERR_INVALID_STATE if no CCC session is active, otherwise the error translated from cherry_ccc_session_stop.

aliro_uwb_session_init()

enum aliro_uwb_err aliro_uwb_session_init

(

struct aliro_uwb_session *

session

)

Initialize a session by creating and configuring a CCC Aliro responder, setting URSK, protocol version, antennas, and diagnostics, then starting the session.

On any error, tears down the session and returns the mapped error code.

Parameters

session

Session to initialize.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL, or the mapped CCC error on failure.

aliro_uwb_session_init_setup()

enum aliro_uwb_err aliro_uwb_session_init_setup

(

struct aliro_uwb_session *

session

)

Begin session setup by building and transmitting M1, transitioning from CREATED to M1_SENT state.

Begin setup: build M1 and transmit it to the user device.

Returns ALIRO_UWB_ERR_INVALID_STATE if not in CREATED state.

Parameters

session

Session to begin setup on.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL, ALIRO_UWB_ERR_INVALID_STATE if not in CREATED state, or ALIRO_UWB_ERR_INTERNAL if M1 could not be built.

aliro_uwb_session_message_free()

void aliro_uwb_session_message_free

(

struct aliro_uwb_message *

message

)

Free a session message, delegating to the message-specific free function.

Free a message produced by the adapter's transmit callback.

Parameters

message

Message to free.

aliro_uwb_session_message_handle()

enum aliro_uwb_err aliro_uwb_session_message_handle	(	struct aliro_uwb_session *	session,
		struct aliro_uwb_message *	message
	)

Validate and dispatch an incoming Aliro UWB message to the appropriate protocol handler.

Handle an incoming BLE message (M2/M4, suspend/resume, notifications).

Parameters

session	Session that received the message.
message	Message to validate and process.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session or message is NULL, ALIRO_UWB_ERR_MSG_MALFORMED if the message is shorter than the header or the payload length does not match, ALIRO_UWB_ERR_MESSAGE_UNSUPPORTED for an unrecognized protocol.

aliro_uwb_session_resume()

enum aliro_uwb_err aliro_uwb_session_resume

(

struct aliro_uwb_session *

session

)

Resume a suspended ranging session by building and transmitting a resume request.

Build and send a resume request for a suspended Aliro UWB ranging session.

ALIRO_UWB_ERR_INVALID_STATE if there is no active CCC session or the session is not in the SUSPENDED state, ALIRO_UWB_ERR_INTERNAL if the resume request could not be built.

aliro_uwb_session_set_protocol_version()

enum aliro_uwb_err aliro_uwb_session_set_protocol_version	(	struct aliro_uwb_session *	session,
		uint16_t	selected_protocol_version
	)

Store the protocol version selected by the reader for later use during session initialization.

Record the selected BLE/UWB protocol version.

Parameters

session	Session that receives the selected protocol version.
selected_protocol_version	Protocol version chosen by the reader.

Returns

ALIRO_UWB_ERR_NONE on success, or ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL.

aliro_uwb_session_set_time_offset()

enum aliro_uwb_err aliro_uwb_session_set_time_offset	(	struct aliro_uwb_session *	session,
		int64_t	time_offset
	)

Store the time offset used to synchronize clocks between reader and device.

Set the time offset (microseconds) added to the negotiated UWB_Time0.

Parameters

session	Session to update.
time_offset	Time offset in microseconds.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL.

aliro_uwb_session_set_ursk()

enum aliro_uwb_err aliro_uwb_session_set_ursk	(	struct aliro_uwb_session *	session,
		const uint8_t *	ursk
	)

Store a copy of the URSK (Unique Ranging Session Key) for later use during session initialization.

Provide the 32-byte URSK for the session.

Allocates a 16-byte buffer and returns ALIRO_UWB_ERR_INTERNAL on allocation failure.

Parameters

session	Session that receives the copied URSK.
ursk	Source URSK bytes to copy.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session or ursk is NULL, or ALIRO_UWB_ERR_INTERNAL on allocation failure.

aliro_uwb_session_start()

enum aliro_uwb_err aliro_uwb_session_start

(

struct aliro_uwb_session *

session

)

Start an active CCC session.

Start ranging for a per-approach session.

On error, tears down the session and returns the mapped error code. the mapped CCC error on failure.

aliro_uwb_session_stop()

enum aliro_uwb_err aliro_uwb_session_stop

(

struct aliro_uwb_session *

session

)

Stop an active CCC session, transitioning to SUSPENDED state.

On error, tears down the session and returns the mapped error code.

Parameters

session

Session to stop.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL, or the mapped CCC error on failure.

aliro_uwb_session_suspend()

enum aliro_uwb_err aliro_uwb_session_suspend

(

struct aliro_uwb_session *

session

)

Suspend an active ranging session by sending a suspend request.

Request a graceful suspend (builds and sends a suspend request).

Parameters

session

Session to suspend.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL, ALIRO_UWB_ERR_INVALID_STATE if there is no active CCC session or the session is not in the RANGING state, ALIRO_UWB_ERR_INTERNAL if the suspend request could not be built.

notify_error()

static enum aliro_uwb_err notify_error ( struct aliro_uwb_session *  session )

static

Send a general-error notification to the peer.

Parameters

session

Session on which to build and transmit the error message.

Returns

ALIRO_UWB_ERR_NONE on success, ALIRO_UWB_ERR_INVALID_PARAMETER if session is NULL, or ALIRO_UWB_ERR_INTERNAL if the message could not be built.

session_close()

static void session_close ( struct aliro_uwb_session *  session )

static

Tear down: destroy the CCC session, or free directly if there is none.

Parameters

session

Session to close.