— cherry_ccc_* seam (Aliro responder) implemented over the lock-native FiRa MAC; maps each call onto woz_uwb_facade. More...

#include <cherry/cherry.h>
#include <cherry/cherry_ccc.h>
#include <cherry/cherry_session.h>
#include "woz_alloc.h"
#include <string.h>
#include "woz_log.h"
#include "woz_util.h"
#include "woz_uwb_facade.h"
#include "aliro_round_config.h"

Include dependency graph for cherry_ccc_shim.c:

Data Structures
struct	cherry
	Opaque Cherry context holder. More...

struct	cherry_session
	Base session object; first member of cherry_ccc_session for up-casting. More...

struct	cherry_ccc_session
	CCC ranging session bound to FiRa MAC. More...

Macros
#define	SHIM_URSK_LEN 32u
	URSK length (bytes) the Aliro provisioned-STS path expects.

Functions
static struct cherry_ccc_session *	to_ccc (struct cherry_session *base)
	Up-cast a base session pointer (base is the first member).

static void	emit_status (struct cherry_ccc_session *s, enum cherry_ccc_session_state st)
	Allocate and dispatch a SESSION_STATUS event to the CCC callback.

static void	emit_error (struct cherry_ccc_session *s, enum cherry_err err)
	Allocate + dispatch a SESSION_ERROR event to the CCC callback.

struct cherry *	cherry_create (const char device, cherry_core_cb_t core_cb, void user_data)
	Allocate and initialize a Cherry context with the given core callback and user data.

void	cherry_destroy_sync (struct cherry *ctx)
	Deallocate a Cherry context; null input is safely ignored.

struct cherry_ccc_session *	cherry_ccc_session_create_aliro_responder (struct cherry ctx, cherry_ccc_cb_t callback, void user_data, struct cherry_ccc_aliro_session_config *config)
	Allocate and initialize an Aliro responder CCC session.

struct cherry_session *	cherry_ccc_session_to_base (struct cherry_ccc_session *session)
	Cast a CCC session pointer to its embedded base session structure.

void *	cherry_session_get_user_data (struct cherry_session *session)
	Retrieve the user data pointer stored in the base session.

void	cherry_session_destroy (struct cherry_session *session)
	Stop the UWB radio, emit a DEINIT status event, and deallocate the session.

enum cherry_err	cherry_session_start (struct cherry_session *session)
	Start an Aliro UWB session by building a RangingConfiguration byte array from session config, calling woz_uwb_start_aliro, and emitting IDLE then ACTIVE status events.

enum cherry_err	cherry_session_stop (struct cherry_session *session)
	Stop the UWB radio and emit an IDLE status event.

enum cherry_err	cherry_ccc_session_set_ursk (struct cherry_ccc_session session, const uint8_t ursk)
	Copy the URSK into the session and mark it as present.

enum cherry_err	cherry_ccc_session_set_protocol_version (struct cherry_ccc_session *session, uint16_t selected_protocol_version)
	Validate that the session exists; selected protocol version is accepted but ignored.

enum cherry_err	cherry_ccc_session_set_sts_index (struct cherry_ccc_session *session, uint32_t sts_index)
	Store the STS index on the session config.

enum cherry_err	cherry_ccc_session_set_initiation_time (struct cherry_ccc_session *session, uint64_t initiation_time_us)
	Store the UWB initiation timestamp in microseconds on the session config.

enum cherry_err	cherry_ccc_session_set_round2_antennas (struct cherry_ccc_session *session, uint8_t tx_antenna_set, uint8_t rx_antenna_set)
	Validate that the session exists; TX and RX antenna set parameters are accepted but ignored.

enum cherry_err	cherry_session_set_antennas (struct cherry_session *session, uint8_t tx_antenna_set, uint8_t rx_antenna_set)
	Validate that the session exists; TX and RX antenna set parameters are accepted but ignored.

enum cherry_err	cherry_session_set_diagnostics (struct cherry_session *session, struct cherry_common_diag_cfg config, bool controlee_only)
	Validate that the session exists; the diagnostics settings are accepted but ignored.

void	cherry_ccc_event_free (struct cherry_ccc_event *event)
	Free a CCC event and its payload; null input is safely ignored.

Detailed Description

— cherry_ccc_* seam (Aliro responder) implemented over the lock-native FiRa MAC; maps each call onto woz_uwb_facade.

Function Documentation

◆ cherry_ccc_event_free()

void cherry_ccc_event_free ( struct cherry_ccc_event * event )

Free a CCC event and its payload; null input is safely ignored.

Release a CCC event and any heap payload it owns.

◆ cherry_ccc_session_create_aliro_responder()

struct cherry_ccc_session * cherry_ccc_session_create_aliro_responder	(	struct cherry *	ctx,
		cherry_ccc_cb_t	callback,
		void *	user_data,
		struct cherry_ccc_aliro_session_config *	config
	)

Allocate and initialize an Aliro responder CCC session.

Create an Aliro responder session bound to config (NULL on error).

Parameters

ctx	Cherry context (unused).
callback	CCC notification callback.
user_data	User context to pass to callback.
config	Session configuration (channel, session ID, STS index, timing, slot geometry).

Returns: Session pointer, or null if callback is null, config is null, or allocation fails.

◆ cherry_ccc_session_set_initiation_time()

enum cherry_err cherry_ccc_session_set_initiation_time	(	struct cherry_ccc_session *	session,
		uint64_t	initiation_time_us
	)

Store the UWB initiation timestamp in microseconds on the session config.

Set the ranging initiation time on the UWBS time base (resume path).

Parameters

session	CCC session.
initiation_time_us	Initiation timestamp in microseconds.

Returns: CHERRY_ERR_INVALID_PARAMETER if session or its config is null, otherwise CHERRY_ERR_NONE.

◆ cherry_ccc_session_set_protocol_version()

enum cherry_err cherry_ccc_session_set_protocol_version	(	struct cherry_ccc_session *	session,
		uint16_t	selected_protocol_version
	)

Validate that the session exists; selected protocol version is accepted but ignored.

Record the selected BLE/UWB protocol version.

Parameters

session	CCC session.
selected_protocol_version	Protocol version (ignored).

Returns: CHERRY_ERR_INVALID_PARAMETER if session is null, otherwise CHERRY_ERR_NONE.

◆ cherry_ccc_session_set_round2_antennas()

enum cherry_err cherry_ccc_session_set_round2_antennas	(	struct cherry_ccc_session *	session,
		uint8_t	tx_antenna_set,
		uint8_t	rx_antenna_set
	)

Validate that the session exists; TX and RX antenna set parameters are accepted but ignored.

Select antennas for the Aliro second ranging round.

Parameters

session	CCC session.
tx_antenna_set	TX antenna set (ignored).
rx_antenna_set	RX antenna set (ignored).

Returns: CHERRY_ERR_INVALID_PARAMETER if session is null, otherwise CHERRY_ERR_NONE.

◆ cherry_ccc_session_set_sts_index()

enum cherry_err cherry_ccc_session_set_sts_index	(	struct cherry_ccc_session *	session,
		uint32_t	sts_index
	)

Store the STS index on the session config.

Set the starting STS index (resume path).

Parameters

session	CCC session.
sts_index	STS index value.

Returns: CHERRY_ERR_INVALID_PARAMETER if session or its config is null, otherwise CHERRY_ERR_NONE.

◆ cherry_ccc_session_set_ursk()

enum cherry_err cherry_ccc_session_set_ursk	(	struct cherry_ccc_session *	session,
		const uint8_t *	ursk
	)

Copy the URSK into the session and mark it as present.

Provide the 32-byte URSK (host-provided STS root key).

Parameters

session	CCC session.
ursk	16-byte Unique Responder Session Key.

Returns: CHERRY_ERR_INVALID_PARAMETER if session or ursk is null, otherwise CHERRY_ERR_NONE.

◆ cherry_ccc_session_to_base()

struct cherry_session * cherry_ccc_session_to_base ( struct cherry_ccc_session * session )

Cast a CCC session pointer to its embedded base session structure.

Return the base session for a CCC session (the base is the first member).

Parameters

session CCC session.

Returns: Base session pointer, or null if session is null.

◆ cherry_create()

struct cherry * cherry_create	(	const char *	device,
		cherry_core_cb_t	core_cb,
		void *	user_data
	)

Allocate and initialize a Cherry context with the given core callback and user data.

Allocate a Cherry context (NULL on allocation failure).

Parameters

device	Device parameter (unused).
core_cb	Core callback (never invoked).
user_data	User data to store in the context.

Returns: Cherry context pointer, or null if allocation fails.

◆ cherry_destroy_sync()

void cherry_destroy_sync ( struct cherry * ctx )

Deallocate a Cherry context; null input is safely ignored.

Synchronously release a Cherry context and its resources.

◆ cherry_session_destroy()

void cherry_session_destroy ( struct cherry_session * session )

Stop the UWB radio, emit a DEINIT status event, and deallocate the session.

Stop if needed, tear down, and release the session.

Parameters

session Base session; null or invalid input is safely ignored.

◆ cherry_session_get_user_data()

void * cherry_session_get_user_data ( struct cherry_session * session )

Retrieve the user data pointer stored in the base session.

Return the opaque client pointer stored at session creation.

Parameters

session Base session.

Returns: User data pointer, or null if session is null.

◆ cherry_session_set_antennas()

enum cherry_err cherry_session_set_antennas	(	struct cherry_session *	session,
		uint8_t	tx_antenna_set,
		uint8_t	rx_antenna_set
	)

Validate that the session exists; TX and RX antenna set parameters are accepted but ignored.

Select the Tx/Rx antenna sets for the first ranging round.

Parameters

session	Base session.
tx_antenna_set	TX antenna set (ignored).
rx_antenna_set	RX antenna set (ignored).

Returns: CHERRY_ERR_INVALID_PARAMETER if session is null, otherwise CHERRY_ERR_NONE.

◆ cherry_session_set_diagnostics()

enum cherry_err cherry_session_set_diagnostics	(	struct cherry_session *	session,
		struct cherry_common_diag_cfg	config,
		bool	controlee_only
	)

Validate that the session exists; the diagnostics settings are accepted but ignored.

Enable/disable per-session diagnostics (config passed by value).

Returns: CHERRY_ERR_INVALID_PARAMETER if session is null, otherwise CHERRY_ERR_NONE.

◆ cherry_session_start()

enum cherry_err cherry_session_start ( struct cherry_session * session )

Start an Aliro UWB session by building a RangingConfiguration byte array from session config, calling woz_uwb_start_aliro, and emitting IDLE then ACTIVE status events.

Request the session to start ranging.

Parameters

session Base session.

Returns: CHERRY_ERR_INVALID_PARAMETER if session or config is null; CHERRY_ERR_SESSION_CONFIG if URSK is not set; CHERRY_ERR_SESSION_INIT if UWB start fails; otherwise CHERRY_ERR_NONE.

◆ cherry_session_stop()

enum cherry_err cherry_session_stop ( struct cherry_session * session )

Stop the UWB radio and emit an IDLE status event.

Request the session to stop ranging.

Parameters

session Base session.

Returns: CHERRY_ERR_INVALID_PARAMETER if session is null or invalid, otherwise CHERRY_ERR_NONE.

◆ emit_status()

static void emit_status	(	struct cherry_ccc_session *	s,
		enum cherry_ccc_session_state	st
	)

static

Allocate and dispatch a SESSION_STATUS event to the CCC callback.

Parameters

s	CCC session.
st	State to report (INIT, IDLE, ACTIVE, or DEINIT).

Data Structures

Macros

Functions

Detailed Description

Function Documentation

◆ cherry_ccc_event_free()

◆ cherry_ccc_session_create_aliro_responder()

◆ cherry_ccc_session_set_initiation_time()

◆ cherry_ccc_session_set_protocol_version()

◆ cherry_ccc_session_set_round2_antennas()

◆ cherry_ccc_session_set_sts_index()

◆ cherry_ccc_session_set_ursk()

◆ cherry_ccc_session_to_base()

◆ cherry_create()

◆ cherry_destroy_sync()

◆ cherry_session_destroy()

◆ cherry_session_get_user_data()

◆ cherry_session_set_antennas()

◆ cherry_session_set_diagnostics()

◆ cherry_session_start()

◆ cherry_session_stop()

◆ emit_status()