aliro_ble.h

// Aliro BLE-UWB reader transport: GATT service definition, advertised feature flags, and transport
// callbacks connecting the BLE peripheral role to the Aliro protocol handler in aliro_reader.
// Callers configure the transport via aliro_ble_prepare (which builds the READ characteristic
// payload without touching NimBLE), then register the GATT service returned by
// aliro_ble_service_def with the host's combined service table.
/*
 * Copyright (c) 2026 asxeem
 * SPDX-License-Identifier: ISC
 *
 * aliro_ble — Aliro BLE transport (NimBLE) for the ESP32-S3 port.
 * Advertises the Aliro GATT service, negotiates the BLE-UWB protocol version,
 * and carries the Aliro transaction over an L2CAP CoC. Independent
 * reimplementation; see SPEC.md for the wire protocol and provenance.
 */
#pragma once
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct aliro_ble_features {
        bool timesync_procedure_0;
        bool timesync_procedure_1;
        bool le_coded_phy;
};
 
struct aliro_ble_callbacks {
        void (*on_data)(uint16_t conn_handle, const uint8_t *data, uint16_t len);
        void (*on_connected)(uint16_t conn_handle);
        void (*on_disconnected)(uint16_t conn_handle);
        void (*on_rssi)(uint16_t conn_handle, int8_t rssi_dbm);
};
 
struct aliro_ble_config {
        const uint16_t *proto_versions;
        size_t proto_versions_count;
        struct aliro_ble_features features;
        struct aliro_ble_callbacks cb;
};
 
int aliro_ble_start(const struct aliro_ble_config *cfg);
 
uint16_t aliro_ble_spsm(void);
 
int aliro_ble_send(uint16_t conn_handle, const uint8_t *data, size_t len);
 
int aliro_ble_disconnect(uint16_t conn_handle);
 
/* Marshal a reader->phone status send onto the NimBLE host task (where every sc_ble
 * seal + L2CAP send already runs), so a caller on another task can send without racing
 * the BleSK counter. `cb` runs on the host task and is passed `unsecured`. */
void aliro_ble_post_reader_status(void (*cb)(bool unsecured), bool unsecured);
 
/* Marshal a presence-proof reset onto the NimBLE host task. The callback may
 * inspect the reader session table and terminate links without racing the
 * transaction callbacks that own it. Only one proof command is served at a
 * time by the console, so one queued callback slot is sufficient. */
void aliro_ble_post_presence_reset(void (*cb)(void));
 
/* ---- Attach mode: share a NimBLE host another stack already owns ---------- *
 * Instead of owning NimBLE (aliro_ble_start), the reader can attach to a host
 * brought up by e.g. esp-matter, so both coexist on one controller. Three
 * phases: prepare() captures the config; the owner registers our GATT service
 * (aliro_ble_service_def()) through its extra-services hook BEFORE it starts its
 * GATT server; start_attached() brings up the L2CAP CoC + advertising once the
 * host is synced and the owner has released the advertiser (post-commissioning). */
struct ble_gatt_svc_def; /* NimBLE type, opaque here */
 
int aliro_ble_prepare(const struct aliro_ble_config *cfg);
 
const struct ble_gatt_svc_def *aliro_ble_service_def(void);
 
int aliro_ble_start_attached(void);
 
void aliro_ble_set_adv_params(const uint8_t group_id8[8], const uint8_t sub_id2[2],
                              const uint8_t grk[16], int8_t tx_power);
 
void aliro_ble_readvertise(void);
 
void aliro_ble_time_updated(void);
 
#ifdef __cplusplus
}
#endif