aliro_uwb_session.h File Reference

— per-session public interface. More...

#include <cherry/cherry.h>
#include <cherry/cherry_ccc.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for aliro_uwb_session.h:

Go to the source code of this file.

Data Structures
struct	aliro_uwb_message
	Framed Aliro BLE message with 4-byte header followed by TLV payload. More...
struct	aliro_uwb_session_event
	Session event handed to the client, carrying status, error, or distance reports. More...

Typedefs
typedef void(*	aliro_uwb_session_cb_t) (struct aliro_uwb_session_event *event, void *user_data)
	Session notification callback type.
typedef void(*	aliro_uwb_adapter_transmit_message_t) (struct aliro_uwb_message *message, struct aliro_uwb_session *session, void *user_data, bool timeout)
	BLE transmit callback: sends an adapter-built message to the peer.

Enumerations
enum	aliro_uwb_session_event_type
	Session event kinds (aliased to the CCC event types).

Functions
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)
	Create a session in the CREATED state.
void	aliro_uwb_session_destroy (struct aliro_uwb_session *session)
	Stop if needed and release a session.
void	aliro_uwb_session_message_free (struct aliro_uwb_message *message)
	Free a message produced by the adapter's transmit callback.
void	aliro_uwb_session_event_free (struct aliro_uwb_session_event *event)
	Free an event delivered to the session callback.
enum aliro_uwb_err	aliro_uwb_session_set_ursk (struct aliro_uwb_session *session, const uint8_t *ursk)
	Provide the 32-byte URSK for the session.
enum aliro_uwb_err	aliro_uwb_session_set_protocol_version (struct aliro_uwb_session *session, uint16_t selected_protocol_version)
	Record the selected BLE/UWB protocol version.
enum aliro_uwb_err	aliro_uwb_session_init_setup (struct aliro_uwb_session *session)
	Begin setup: build M1 and transmit it to the user device.
enum aliro_uwb_err	aliro_uwb_session_set_time_offset (struct aliro_uwb_session *session, int64_t time_offset)
	Set the time offset (microseconds) added to the negotiated UWB_Time0.
enum aliro_uwb_err	aliro_uwb_session_message_handle (struct aliro_uwb_session *session, struct aliro_uwb_message *message)
	Handle an incoming BLE message (M2/M4, suspend/resume, notifications).
enum aliro_uwb_err	aliro_uwb_session_suspend (struct aliro_uwb_session *session)
	Request a graceful suspend (builds and sends a suspend request).
enum aliro_uwb_err	aliro_uwb_session_forced_suspend (struct aliro_uwb_session *session)
	Suspend ranging immediately without waiting for a peer response.
enum aliro_uwb_err	aliro_uwb_session_resume (struct aliro_uwb_session *session)
	Build and send a resume request for a suspended Aliro UWB ranging session.

Detailed Description

— per-session public interface.

Function Documentation

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
	)

Create a session in the CREATED state.

No CCC session is started here.

Parameters

aliro_ctx	Adapter supplying the Cherry context and reader configuration.
session_id	Session identifier carried in the ranging-service messages.
callback	Session event callback; must not be NULL.
transmit	Message transmit callback; must not be NULL.
user_data	Opaque pointer passed back to the callbacks.

Returns

New session, or NULL on bad parameters or allocation failure.

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

)

Stop if needed and release a 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 an event delivered to the session callback.

Parameters

event

Event to free.

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

)

Suspend ranging immediately without waiting for a peer response.

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_setup()

enum aliro_uwb_err aliro_uwb_session_init_setup

(

struct aliro_uwb_session *

session

)

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

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 message produced by the adapter's transmit callback.

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
	)

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

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

)

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

Parameters

session

Aliro UWB session to resume.

Returns

Aliro UWB error code indicating success or failure of the 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
	)

Record the selected BLE/UWB protocol version.

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
	)

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

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
	)

Provide the 32-byte URSK for the session.

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_suspend()

enum aliro_uwb_err aliro_uwb_session_suspend

(

struct aliro_uwb_session *

session

)

Request a graceful suspend (builds and sends 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.