hci.h File Reference

Bluetooth HCI Driver. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "FreeRTOS.h"
#include "semphr.h"
#include "powerblocks/core/system/system.h"
#include "powerblocks/core/ios/ios.h"

Go to the source code of this file.

Classes
struct	hci_discovered_device_info_t
struct	hci_buffer_sizes_t
struct	hci_acl_packet_t

Macros
#define	HCI_INQUIRY_MODE_GENERAL_ACCESS   0x9E8B33
#define	HCI_MAX_NAME_REQUEST_LENGTH   254
#define	HCI_MAX_ACL_DATA_LENGTH   512
#define	HCI_ACL_RECEIVE_IPC_BUFFER_SIZE   (32 + 32 + 32 + 32 + sizeof(ipc_message))

Typedefs
typedef void(*	hci_discovered_device_handler) (void *user_data, const hci_discovered_device_info_t *device)
	Callback for handling a discovered device during inquiry.
typedef void(*	hci_discovery_complete_handler) (void *user_data, uint8_t error)
	Callback invoked when device discovery completes.

Enumerations
enum	hci_acl_packet_boundary_flag_t { HCI_ACL_PACKET_BOUNDARY_FLAG_FIRST_NON_AUTOMATICALLY_FLUSHABLE_PACKET , HCI_ACL_PACKET_BOUNDARY_FLAG_CONTINUING_FRAGMENT , HCI_ACL_PACKET_BOUNDARY_FLAG_FIRST_AUTOMATICALLY_FLUSHABLE_PACKET }
enum	hci_acl_packet_broadcast_flag_t { HCI_ACL_PACKET_BROADCAST_FLAG_PTP , HCI_ACL_PACKET_BROADCAST_FLAG_ACTIVE_DEVICE , HCI_ACL_PACKET_BROADCAST_FLAG_PARKED_DEVICE }

Functions
int	hci_initialize (const char *device)
	Initializes the HCI interface.
void	hci_close ()
	Closes the HCI driver.
int	hci_reset ()
	Resets the HCI Interface.
int	hci_begin_discovery (uint32_t lap, uint8_t length, uint8_t responses, hci_discovered_device_handler on_discovered, hci_discovery_complete_handler on_complete, void *user_data)
	Begins looking for bluetooth devices.
int	hci_cancel_discovery ()
	Stops a discovery session.
int	hci_get_remote_name (const hci_discovered_device_info_t *device, uint8_t *name)
	Returns the remote name of a device.
int	hci_create_connection (const hci_discovered_device_info_t *device, uint16_t *handle)
	Creates a connection to a device for you to use.
hci_acl_packet_t hci_acl_packet_out	ALIGN (32) MEM2
int	hci_send_acl (uint16_t handle, hci_acl_packet_boundary_flag_t pb, hci_acl_packet_broadcast_flag_t bc, uint16_t length)
	Sends a ACL Packet.
int	hci_receive_acl_async (hci_acl_packet_t *acl_buffer, uint8_t *ipc_buffer, ipc_async_handler_t handler, void *params)
	Receives a ACL Packet Asynchronously.
void	hci_decode_received_acl (uint16_t *handle, hci_acl_packet_boundary_flag_t *pb, hci_acl_packet_broadcast_flag_t *bc, uint16_t *length, const hci_acl_packet_t *acl_buffer)
	Decodes a received ACL packet.

Variables
hci_buffer_sizes_t	hci_buffer_sizes
SemaphoreHandle_t	hcl_acl_packet_out_lock

Detailed Description

Bluetooth HCI Driver.

This driver talks to USB HCI devices. Those are "Host Controller Interfaces" for communicating with bluetooth devices over USB

This is done as Wiimotes are connected through the Wii's internal bluetooth dongle.

Author

Samuel Fitzsimons (rainbain)

Date

2025

Typedef Documentation

hci_discovered_device_handler

typedef void(* hci_discovered_device_handler) (void *user_data, const hci_discovered_device_info_t *device)

Callback for handling a discovered device during inquiry.

Parameters

user_data	User-defined context passed to the callback.
device	Pointer to the discovered device information.

hci_discovery_complete_handler

typedef void(* hci_discovery_complete_handler) (void *user_data, uint8_t error)

Callback invoked when device discovery completes.

Parameters

user_data	User-defined context passed to the callback.
error	Error code (0 on success, nonzero on failure).

Function Documentation

hci_begin_discovery()

int hci_begin_discovery ( uint32_t lap, uint8_t length, uint8_t responses, hci_discovered_device_handler on_discovered, hci_discovery_complete_handler on_complete, void * user_data )

extern

Begins looking for bluetooth devices.

Will begin looking for bluetooth devices.

On emulator, dolphin will report wiimote devices 1 at a time.

Only 1 thing can be running discovery at a time. Calling this while a discovery session is already running will return an error.

You generally need to wait for the inquiry to end before doing anything. ACL packets are fine though.

Handlers called from the HCI Task. Please do not call HCI function from the HCI task.

Parameters

lap	Access code for what devices to discover. Usually HCI_INQUIRY_MODE_GENERAL_ACCESS
length	Time to discover devices for. In units of 1.28 seconds. 0x01 – 0x30, Dolphin always completes instantly
responses	Max devices discovered. Or 0 for infinite up until timeout.
on_discovered	Called when a device is discovered. May be NOT be NULL
on_complete	Called when the discovery session ends. May be NULL
user_data	Pointer passed to handlers. May be NULL.

Returns

Negative if Error

hci_cancel_discovery()

int hci_cancel_discovery ( )

extern

Stops a discovery session.

Once returns a non error value, no more of the discovery handlers will be called.

Returns

Negative if Error

hci_close()

void hci_close ( )

extern

Closes the HCI driver.

Currently, if HCI gets stuck, this function will get stuck waiting for the resource to open up.

Returns

Negative if Error

hci_create_connection()

int hci_create_connection ( const hci_discovered_device_info_t * device, uint16_t * handle )

extern

Creates a connection to a device for you to use.

Parameters

device	Discovered device to connect to
handle	Device handle out. Not null

Returns

Negative if Error

hci_decode_received_acl()

void hci_decode_received_acl ( uint16_t * handle, hci_acl_packet_boundary_flag_t * pb, hci_acl_packet_broadcast_flag_t * bc, uint16_t * length, const hci_acl_packet_t * acl_buffer )

extern

Decodes a received ACL packet.

Like send, gets back the packet boundary, broadcast flags, and more.

Parameters

handle	Bluetooth Connection Handle In. Not NULL!
pb	Packet boundary Flag In. Not NULL!
bc	Broadcast boundary Flag In. Not NULL!
length	Length of data received. Not NULL!

Returns

Negative if Error

hci_get_remote_name()

int hci_get_remote_name ( const hci_discovered_device_info_t * device, uint8_t * name )

extern

Returns the remote name of a device.

Useful for for device detection and enumeration.

IMPORTANT: You can't call this during an inquiry, you must wait for it to end.

Parameters

device	Device information to poll.
name	Name output, must be HCI_MAX_NAME_REQUEST_LENGTH in size.

Returns

Negative if Error

hci_initialize()

int hci_initialize ( const char * device )

extern

Initializes the HCI interface.

Initializes the HCI driver opening the USB interface in IOS.

Parameters

device

Device path to the USB device. For the wii's built in its "/dev/usb/oh1/57e/305"

Returns

Negative if Error

hci_receive_acl_async()

int hci_receive_acl_async ( hci_acl_packet_t * acl_buffer, uint8_t * ipc_buffer, ipc_async_handler_t handler, void * params )

extern

Receives a ACL Packet Asynchronously.

Unlike send, this is done asynchronously, and returns early, so that you can double buffer and make sure to never miss an ACL packet. Multiplexing / Reassembly / Channels are handled by L2CAP that makes these

These parameters will be set into hci_acl_packet_in. Your data and length is available in there.

Also must be provided is a buffer size HCI_ACL_RECEIVE_IPC_BUFFER_SIZE for storing the IPC data. So that it can store the message in the mean time until the callback is called.

Parameters

buffer	ACL packet buffer to receive into.
ipc_buffer	Data buffer for the IPC data. Needs to be kept around until the callback is called. Needs to be 32 byte aligned.
handler	Called when data is received
params	Pointer passed to handler

Returns

Negative if Error

hci_reset()

int hci_reset ( )

extern

Resets the HCI Interface.

Its recommended to do this to get it into a known state.

Returns

Negative if Error

hci_send_acl()

int hci_send_acl ( uint16_t handle, hci_acl_packet_boundary_flag_t pb, hci_acl_packet_broadcast_flag_t bc, uint16_t length )

extern

Sends a ACL Packet.

These are the asynchronous data packets that are sent to devices. Multiplexing / Reassembly / Channels are handled by L2CAP that makes these

These parameters will be set into hci_acl_packet_out, you must fill in the data though.

Parameters

handle	Bluetooth Connection Handle From hci_create_connection
pb	Packet boundary flag.
bc	Broadcast boundary flag.
length	Length of data transmitted.

Returns

Negative if Error