BLE HCI transport seam (host-side). More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_ble.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_ble_config_t
	Configuration passed to ra8_ble_open. More...

Typedefs
typedef void(*	ra8_ble_event_fn_t) (void ctx, uint8_t evt_code, const uint8_t params, uint8_t params_len)
	Fired when an HCI event packet has been received.
typedef void(*	ra8_ble_acl_fn_t) (void ctx, uint16_t handle, const uint8_t payload, uint16_t len)
	Fired when an HCI ACL data packet has been received.

Enumerations
enum	ra8_ble_limits_t : uint16_t { k_ra8_ble_max_cmd_params = 255U , k_ra8_ble_max_evt_params = 255U , k_ra8_ble_max_acl_payload = 251U , k_ra8_ble_addr_bytes = 6U , k_ra8_ble_adv_data_max = 31U }
	Driver-side packet bounds. More...
enum	ra8_ble_hci_pkt_t : uint8_t { k_ra8_ble_pkt_cmd = 0x01U , k_ra8_ble_pkt_acl_data = 0x02U , k_ra8_ble_pkt_event = 0x04U }
	H4 HCI packet-type indicator bytes (Bluetooth Core 5.3 Vol 4 Part A 2). More...

Functions
ra8_err_t	ra8_ble_open (const ra8_ble_config_t *cfg)
	Power up the BLE controller and open the HCI mailbox.
ra8_err_t	ra8_ble_close (void)
	Close the HCI mailbox and put the controller back in reset.
ra8_err_t	ra8_ble_hci_send_command (uint16_t opcode, const uint8_t *params, uint8_t params_len)
	Emit an HCI command packet.
ra8_err_t	ra8_ble_hci_send_acl_data (uint16_t handle, const uint8_t *payload, uint16_t len)
	Emit an HCI ACL data packet.
ra8_err_t	ra8_ble_attach_event_handler (ra8_ble_event_fn_t fn, void *ctx)
	Register a handler for inbound HCI events.
ra8_err_t	ra8_ble_attach_acl_handler (ra8_ble_acl_fn_t fn, void *ctx)
	Register a handler for inbound HCI ACL data.
ra8_err_t	ra8_ble_dispatch (void)
	Pump the HCI receive path – call from ISR or main loop.
ra8_err_t	ra8_ble_set_random_address (const uint8_t addr[k_ra8_ble_addr_bytes])
	Send LE_Set_Random_Address (opcode 0x2005).
ra8_err_t	ra8_ble_set_advertising_data (const uint8_t *data, uint8_t len)
	Send LE_Set_Advertising_Data (opcode 0x2008).
ra8_err_t	ra8_ble_set_advertising_enable (uint8_t enable)
	Send LE_Set_Advertising_Enable (opcode 0x200A).
ra8_err_t	ra8_ble_scan_start (uint8_t active, uint16_t interval, uint16_t window)
	Send LE_Set_Scan_Parameters then LE_Set_Scan_Enable.

Detailed Description

BLE HCI transport seam (host-side).

The host-side HCI transport the NimBLE host stack (via port/nimble) sits on. It is deliberately the controller-agnostic seam:

Open / close the HCI transport.
Send raw HCI command and HCI ACL data packets.
Deliver HCI events and incoming ACL data to user-supplied callbacks.
Convenience wrappers for a small set of GAP advertising and scanning HCI commands so a smoke test can verify packet framing without pulling in a full Bluetooth host stack (L2CAP / ATT / GATT / GAP / SM are the host's job, not this seam's).

The packet framing matches Bluetooth Core 5.3 Volume 4 Part A 2 ("HCI Transport Layer") with the H4-style packet-indicator byte:

| type | opcode (LE16) | param-len | params... |   command (0x01)
| type | event-code | param-len | params... |       event   (0x04)
| type | handle (LE16) | data-len (LE16) | payload | ACL  (0x02)

Note: The RA8D2 has no on-chip Bluetooth radio, so there is no on-chip controller backend. The current implementation (ra8_ble.c) is an in-memory loopback used by the host-stack unit tests. The production backend is an ESP32-C6 companion IC: the C6 runs the BLE controller (below HCI) and this seam carries HCI over the companion link, with the host stack above unchanged.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_ble.h.

Typedef Documentation

◆ ra8_ble_acl_fn_t

typedef void(* ra8_ble_acl_fn_t) (void *ctx, uint16_t handle, const uint8_t *payload, uint16_t len)

Fired when an HCI ACL data packet has been received.

Parameters

[in]	ctx	User context registered alongside the callback.
[in]	handle	ACL connection handle (12-bit, low bits of the LE16).
[in]	payload	Pointer into a driver-owned scratch buffer; valid only for the duration of the callback.
[in]	len	Number of payload bytes.

Definition at line 122 of file ra8_ble.h.

◆ ra8_ble_event_fn_t

typedef void(* ra8_ble_event_fn_t) (void *ctx, uint8_t evt_code, const uint8_t *params, uint8_t params_len)

Fired when an HCI event packet has been received.

Parameters

[in]	ctx	User context registered alongside the callback.
[in]	evt_code	HCI event code (Bluetooth Core 5.3 Vol 4 Part E 7.7).
[in]	params	Pointer into a driver-owned scratch buffer; valid only for the duration of the callback.
[in]	params_len	Number of bytes pointed to by params.

Definition at line 107 of file ra8_ble.h.

Enumeration Type Documentation

◆ ra8_ble_hci_pkt_t

enum ra8_ble_hci_pkt_t : uint8_t

H4 HCI packet-type indicator bytes (Bluetooth Core 5.3 Vol 4 Part A 2).

HCI protocol constants – not hardware registers. Public on the HCI seam so both the transport and its tests frame H4 packets with them.

Enumerator
k_ra8_ble_pkt_cmd	HCI command packet indicator.
k_ra8_ble_pkt_acl_data	HCI ACL data packet indicator.
k_ra8_ble_pkt_event	HCI event packet indicator.

Definition at line 72 of file ra8_ble.h.

◆ ra8_ble_limits_t

enum ra8_ble_limits_t : uint16_t

Driver-side packet bounds.

Picked to match HCI maximum sizes in Bluetooth Core 5.3 Vol 4 Part E 5.4 "Exchange of HCI-specific information".

Enumerator
k_ra8_ble_max_cmd_params	HCI command max parameter byte count.
k_ra8_ble_max_evt_params	HCI event max parameter byte count.
k_ra8_ble_max_acl_payload	LE Data Length Extension default cap.
k_ra8_ble_addr_bytes	48-bit BD_ADDR length.
k_ra8_ble_adv_data_max	Legacy advertising-data byte cap.

Definition at line 58 of file ra8_ble.h.

Function Documentation

◆ ra8_ble_attach_acl_handler()

ra8_err_t ra8_ble_attach_acl_handler	(	ra8_ble_acl_fn_t	fn,
		void *	ctx )

nodiscard

Register a handler for inbound HCI ACL data.

Parameters

[in]	fn	Callback. Pass NULL to detach.
[in]	ctx	Opaque user context, passed back on each ACL packet.

Returns: k_ra8_ok always.

Since: 0.1.0

Definition at line 281 of file ra8_ble.c.

References k_ra8_ok, and s_state.

Referenced by ble_hci_ra8_ble_deinit(), and ble_hci_ra8_ble_init().

◆ ra8_ble_attach_event_handler()

ra8_err_t ra8_ble_attach_event_handler	(	ra8_ble_event_fn_t	fn,
		void *	ctx )

nodiscard

Register a handler for inbound HCI events.

Parameters

[in]	fn	Callback. Pass NULL to detach.
[in]	ctx	Opaque user context, passed back on each event.

Returns: k_ra8_ok always.

Since: 0.1.0

Definition at line 274 of file ra8_ble.c.

References k_ra8_ok, and s_state.

Referenced by ble_hci_ra8_ble_deinit(), and ble_hci_ra8_ble_init().

◆ ra8_ble_close()

ra8_err_t ra8_ble_close ( void )

nodiscard

Close the HCI mailbox and put the controller back in reset.

Returns: k_ra8_err_invalid_arg if controller is not open.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 211 of file ra8_ble.c.

References k_ra8_err_invalid_arg, k_ra8_ok, ra8_log_info, s_state, and s_tag.

◆ ra8_ble_dispatch()

ra8_err_t ra8_ble_dispatch ( void )

nodiscard

Pump the HCI receive path – call from ISR or main loop.

Drains both the event FIFO and the ACL RX FIFO, dispatching each frame through the registered callbacks. Bounded by a static loop cap so it never blocks indefinitely.

Returns: k_ra8_err_not_initialized if controller is not open.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 362 of file ra8_ble.c.

References internal_dispatch_acl(), internal_dispatch_event(), internal_rx_byte(), k_ra8_ble_dispatch_budget, k_ra8_ble_pkt_acl_data, k_ra8_ble_pkt_event, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, and s_state.

Referenced by internal_demo_thread_entry().

◆ ra8_ble_hci_send_acl_data()

ra8_err_t ra8_ble_hci_send_acl_data	(	uint16_t	handle,
		const uint8_t *	payload,
		uint16_t	len )

nodiscard

Emit an HCI ACL data packet.

Frames [0x02][handle_lo][handle_hi][len_lo][len_hi][payload] and pushes it into the HCI ACL TX FIFO. The handle field carries the 12-bit connection handle plus PB/BC flags as one LE16 word; callers are expected to merge those fields beforehand.

Parameters

[in]	handle	Connection handle + PB/BC flags (LE16, 16 bits).
[in]	payload	Payload bytes. May be NULL iff len == 0.
[in]	len	Payload byte count (0..k_ra8_ble_max_acl_payload).

Returns: k_ra8_err_not_initialized if controller is not open.; k_ra8_err_null_ptr if payload == NULL && len > 0.; k_ra8_err_invalid_arg if len > k_ra8_ble_max_acl_payload.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 246 of file ra8_ble.c.

References internal_tx_byte(), k_ra8_ble_byte_mask, k_ra8_ble_byte_shift, k_ra8_ble_max_acl_payload, k_ra8_ble_pkt_acl_data, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and s_state.

Referenced by ble_transport_to_ll_acl_impl().

◆ ra8_ble_hci_send_command()

ra8_err_t ra8_ble_hci_send_command	(	uint16_t	opcode,
		const uint8_t *	params,
		uint8_t	params_len )

nodiscard

Emit an HCI command packet.

Frames [0x01][opcode_lo][opcode_hi][params_len][params...] and pushes it into the HCI command FIFO. Returns immediately; the matching Command Complete or Command Status event arrives via the event callback.

Parameters

[in]	opcode	16-bit HCI opcode (Bluetooth Core 5.3 Vol 4 Part E 5.4.1).
[in]	params	Parameter bytes. May be NULL iff params_len == 0.
[in]	params_len	Parameter byte count (0..255).

Returns: k_ra8_err_not_initialized if controller is not open.; k_ra8_err_null_ptr if params == NULL && params_len > 0.; k_ra8_err_invalid_arg if params_len > k_ra8_ble_max_cmd_params.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 226 of file ra8_ble.c.

References internal_tx_byte(), k_ra8_ble_byte_mask, k_ra8_ble_byte_shift, k_ra8_ble_pkt_cmd, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and s_state.

Referenced by ble_transport_to_ll_cmd_impl(), ra8_ble_scan_start(), ra8_ble_set_advertising_data(), ra8_ble_set_advertising_enable(), and ra8_ble_set_random_address().

◆ ra8_ble_open()

ra8_err_t ra8_ble_open ( const ra8_ble_config_t * cfg )

nodiscard

Power up the BLE controller and open the HCI mailbox.

Steps (mirrors FSP r_ble open + the production patch-load helper):

Drop the controller out of reset (CTRL.reset = 1, then 0).
Programme OSCCTL per cfg->use_external_osc.
Stub the patch-load loop (PATCHADDR/PATCHDATA writes).
Set CTRL.enable | CTRL.hci_enable.
Spin-wait for STATUS.ready.

Parameters

[in] cfg Driver configuration. Must not be NULL.

Returns: k_ra8_err_null_ptr if cfg == NULL.; k_ra8_err_invalid_arg if controller is already open.; k_ra8_ok on success.

Precondition: Caller has clocked the BLE block (MSTPCRC bit, HUM Ch 11).; No other thread holds the HCI mailbox.

Postcondition: STATUS.ready reads back as 1.; Subsequent ra8_ble_hci_send_command calls are accepted.

Note: Not thread-safe.

Warning: Real silicon needs the Renesas-supplied BLE firmware patch image; the patch-load loop is currently stubbed.

Since: 0.1.0

Definition at line 197 of file ra8_ble.c.

References k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_info, s_state, and s_tag.

Referenced by internal_demo_ble_or_halt().

◆ ra8_ble_scan_start()

ra8_err_t ra8_ble_scan_start	(	uint8_t	active,
		uint16_t	interval,
		uint16_t	window )

nodiscard

Send LE_Set_Scan_Parameters then LE_Set_Scan_Enable.

Bluetooth Core 5.3 Vol 4 Part E 7.8.10 / 7.8.11. Two HCI commands fly back-to-back; the controller answers with two Command Complete events, both delivered through the registered event handler.

Parameters

[in]	active	1 = active scanning (with SCAN_REQ), 0 = passive.
[in]	interval	Scan interval in 0.625 ms units (0x0004..0x4000).
[in]	window	Scan window in 0.625 ms units (0x0004..0x4000), <= interval.

Returns: k_ra8_err_invalid_arg if window > interval or values out of range.; k_ra8_err_not_initialized if controller is not open.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 426 of file ra8_ble.c.

References k_ra8_ble_byte_mask, k_ra8_ble_byte_shift, k_ra8_ble_op_le_set_scan_enable, k_ra8_ble_op_le_set_scan_params, k_ra8_ble_scan_enable_bytes, k_ra8_ble_scan_filt_basic, k_ra8_ble_scan_max, k_ra8_ble_scan_min, k_ra8_ble_scan_off_filter, k_ra8_ble_scan_off_interval_hi, k_ra8_ble_scan_off_interval_lo, k_ra8_ble_scan_off_own_addr, k_ra8_ble_scan_off_type, k_ra8_ble_scan_off_window_hi, k_ra8_ble_scan_off_window_lo, k_ra8_ble_scan_own_pub, k_ra8_ble_scan_param_bytes, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, ra8_ble_hci_send_command(), and s_state.

◆ ra8_ble_set_advertising_data()

ra8_err_t ra8_ble_set_advertising_data	(	const uint8_t *	data,
		uint8_t	len )

nodiscard

Send LE_Set_Advertising_Data (opcode 0x2008).

Parameters

[in]	data	Advertising-data bytes.
[in]	len	Byte count (0..k_ra8_ble_adv_data_max).

Returns: k_ra8_err_invalid_arg if len > k_ra8_ble_adv_data_max.; k_ra8_err_null_ptr if data == NULL && len > 0.; k_ra8_err_not_initialized if controller is not open.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 400 of file ra8_ble.c.

References internal_byte_copy(), k_ra8_ble_adv_data_max, k_ra8_ble_op_le_set_adv_data, k_ra8_err_invalid_arg, k_ra8_err_null_ptr, and ra8_ble_hci_send_command().

◆ ra8_ble_set_advertising_enable()

ra8_err_t ra8_ble_set_advertising_enable ( uint8_t enable )

nodiscard

Send LE_Set_Advertising_Enable (opcode 0x200A).

Parameters

[in] enable 0 = disable advertising, 1 = enable.

Returns: k_ra8_err_not_initialized if controller is not open.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 420 of file ra8_ble.c.

References k_ra8_ble_op_le_set_adv_enable, and ra8_ble_hci_send_command().

◆ ra8_ble_set_random_address()

ra8_err_t ra8_ble_set_random_address ( const uint8_t addr[k_ra8_ble_addr_bytes] )

nodiscard

Send LE_Set_Random_Address (opcode 0x2005).

Parameters

[in] addr 6-byte random Bluetooth address (LSB first per spec).

Returns: k_ra8_err_null_ptr if addr == NULL.; k_ra8_err_not_initialized if controller is not open.; k_ra8_ok on success.

Since: 0.1.0

Definition at line 394 of file ra8_ble.c.

References k_ra8_ble_addr_bytes, k_ra8_ble_op_le_set_random_address, ra8_ble_hci_send_command(), RA8_CHECK_NULL_PTR, and s_tag.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_ble_acl_fn_t

◆ ra8_ble_event_fn_t

Enumeration Type Documentation

◆ ra8_ble_hci_pkt_t

◆ ra8_ble_limits_t

Function Documentation

◆ ra8_ble_attach_acl_handler()

◆ ra8_ble_attach_event_handler()

◆ ra8_ble_close()

◆ ra8_ble_dispatch()

◆ ra8_ble_hci_send_acl_data()

◆ ra8_ble_hci_send_command()

◆ ra8_ble_open()

◆ ra8_ble_scan_start()

◆ ra8_ble_set_advertising_data()

◆ ra8_ble_set_advertising_enable()

◆ ra8_ble_set_random_address()