ble_nus.h

Go to the documentation of this file.

/*******************************************************************************
 * File Name: ble_nus.h
 *
 * Description: Nordic UART Service (NUS) transport for BENTO Bento Desktop
 *              Buddy. Runs on CM33_NS over AIROC CYW55500 BLE host stack.
 *              Wire protocol: JSON messages framed by NUS RX/TX characteristics
 *              (see https://github.com/anthropics/claude-desktop-buddy REFERENCE.md
 *              for the original protocol source — Bento forked this protocol
 *              under its own branding; it is not Anthropic-compatible).
 *
 *              Exclusive with WiFi: CYW55500 has a single RF transceiver.
 *              When BLE is active, the WiFi stack must not be initialized.
 *
 *              NUS UUIDs (128-bit, Nordic-defined):
 *                Service:  6E400001-B5A3-F393-E0A9-E50E24DCCA9E
 *                RX char:  6E400002-...  (host -> device, WRITE/WRITE_NO_RSP)
 *                TX char:  6E400003-...  (device -> host, NOTIFY)
 *
 *******************************************************************************/
 
#ifndef BLE_NUS_H
#define BLE_NUS_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif

#define BLE_NUS_MAX_PAYLOAD 244

typedef enum {
    BLE_NUS_STATE_OFF = 0,       /* stack not initialized */
    BLE_NUS_STATE_ADVERTISING,   /* broadcasting, waiting for Bento Desktop Buddy */
    BLE_NUS_STATE_CONNECTED,     /* paired, NUS exchanging data */
    BLE_NUS_STATE_ERROR,
} ble_nus_state_t;

typedef void (*ble_nus_rx_cb_t)(const uint8_t *data, size_t len, void *user_ctx);

typedef void (*ble_nus_state_cb_t)(ble_nus_state_t state, void *user_ctx);
 
typedef struct {
    const char         *device_name;    /* Advertised name, e.g. "BENTO Buddy" */
    ble_nus_rx_cb_t     on_rx;
    ble_nus_state_cb_t  on_state;
    void               *user_ctx;
} ble_nus_config_t;

bool ble_nus_init(const ble_nus_config_t *cfg);

int ble_nus_send(const uint8_t *data, size_t len);

#ifndef BLE_NUS_ADV_INTERVAL_MS
#define BLE_NUS_ADV_INTERVAL_MS 100
#endif

#ifndef BLE_NUS_ADV_FAST_SECONDS
#define BLE_NUS_ADV_FAST_SECONDS 30
#endif

#define BLE_NUS_METER_PAYLOAD_MAX 24

void ble_nus_deinit(void);

void ble_nus_rearm_advertising(void);

ble_nus_state_t ble_nus_get_state(void);

const char *ble_nus_get_adv_name(void);

void ble_nus_passkey_cb(const char *passkey_6_digits);

typedef struct {
    uint32_t disconnect_count;                       /* disconnects seen */
    uint8_t  last_disconnect_reason;                 /* reason code of the latest disconnect */
    uint32_t advert_restart_attempts;                /* automatic re-advertising attempts */
    int      last_advert_restart_result;             /* result of the latest such attempt */
    uint8_t  deinit_in_progress_at_last_disconnect;  /* 1 if the link dropped while BLE was shutting down */
    uint32_t boot_advert_attempts;                   /* advertising starts when the stack came up */
    int      last_boot_advert_result;                /* result of the latest of those */
} ble_nus_diag_t;
 
void ble_nus_get_diagnostics(ble_nus_diag_t *out);
 
#ifdef __cplusplus
}
#endif
 
#endif /* BLE_NUS_H */