Skip to main content
The Bluetooth API provides functions for managing Bluetooth connections, audio playback, and telephony features.

​
Data structures

​
BT_t

Main Bluetooth module context structure.
​
activeDevice
BTConnection_t
Currently connected device information
​
pairedDevices
BTPairedDevice_t[8]
List of paired devices (max 8)
​
status
uint8_t
Connection status: BT_STATUS_OFF, BT_STATUS_DISCONNECTED, BT_STATUS_CONNECTED, BT_STATUS_CONNECTING
​
type
uint8_t
Bluetooth module type: BT_BTM_TYPE_BC127 or BT_BTM_TYPE_BM83
​
playbackStatus
uint8_t
Playback status: BT_AVRCP_STATUS_PAUSED or BT_AVRCP_STATUS_PLAYING
​
callStatus
uint8_t
Call status: BT_CALL_INACTIVE, BT_CALL_ACTIVE, BT_CALL_INCOMING, BT_CALL_OUTGOING, etc.
​
title
char[128]
Currently playing track title
​
artist
char[128]
Currently playing track artist
​
album
char[128]
Currently playing track album
​
callerId
char[32]
Caller ID for incoming/active calls
​
pbap
BTPBAP_t
Phone book access protocol state and contacts

​
BTConnection_t

Represents an active Bluetooth connection.
​
status
uint8_t
Connection status flag
​
deviceId
uint8_t
Device ID (1-3)
​
deviceIndex
uint8_t
Index in paired device list
​
a2dpId
uint8_t
A2DP link ID
​
avrcpId
uint8_t
AVRCP link ID
​
hfpId
uint8_t
Hands-free profile link ID
​
pbapId
uint8_t
Phone book access profile link ID

​
BTPairedDevice_t

Represents a paired Bluetooth device.
​
macId
uint8_t[6]
MAC address of the device
​
deviceName
char[32]
Friendly name of the device
​
number
uint8_t
Device number in pairing list

​
BTPBAPContact_t

Represents a contact from the phone book.
​
name
char[32]
Contact name
​
numbers
BTPBAPContactTelephone_t[3]
Up to 3 phone numbers with types
​
numberCount
uint8_t
Number of phone numbers for this contact

​
Core functions

​
BTInit

BT_t BTInit();
Initializes the Bluetooth module and UART communication.
​
Returns
BT_t
Initialized Bluetooth context structure

​
BTProcess

void BTProcess(BT_t *bt);
Processes incoming Bluetooth messages and manages state. Should be called regularly in the main loop.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
Connection functions

​
BTCommandConnect

void BTCommandConnect(BT_t *bt, BTPairedDevice_t *device);
Initiates connection to a paired device.
​
bt
BT_t *
required
Pointer to Bluetooth context
​
device
BTPairedDevice_t *
required
Pointer to paired device to connect to

​
BTCommandDisconnect

void BTCommandDisconnect(BT_t *bt);
Disconnects from the currently connected device.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandSetConnectable

void BTCommandSetConnectable(BT_t *bt, unsigned char connectable);
Sets the connectable state of the Bluetooth module.
​
bt
BT_t *
required
Pointer to Bluetooth context
​
connectable
unsigned char
required
1 to enable connectable mode, 0 to disable

​
BTCommandSetDiscoverable

void BTCommandSetDiscoverable(BT_t *bt, unsigned char discoverable);
Sets the discoverable state of the Bluetooth module.
​
bt
BT_t *
required
Pointer to Bluetooth context
​
discoverable
unsigned char
required
1 to enable discoverable mode, 0 to disable

​
BTCommandList

void BTCommandList(BT_t *bt);
Requests the list of paired devices from the Bluetooth module.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
Playback functions

​
BTCommandPlay

void BTCommandPlay(BT_t *bt);
Sends play command to connected device.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPause

void BTCommandPause(BT_t *bt);
Sends pause command to connected device.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPlaybackToggle

void BTCommandPlaybackToggle(BT_t *bt);
Toggles play/pause state.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPlaybackTrackNext

void BTCommandPlaybackTrackNext(BT_t *bt);
Skips to next track.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPlaybackTrackPrevious

void BTCommandPlaybackTrackPrevious(BT_t *bt);
Skips to previous track.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPlaybackTrackFastforwardStart

void BTCommandPlaybackTrackFastforwardStart(BT_t *bt);
Starts fast forward through current track.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPlaybackTrackFastforwardStop

void BTCommandPlaybackTrackFastforwardStop(BT_t *bt);
Stops fast forward and resumes normal playback.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPlaybackTrackRewindStart

void BTCommandPlaybackTrackRewindStart(BT_t *bt);
Starts rewind through current track.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPlaybackTrackRewindStop

void BTCommandPlaybackTrackRewindStop(BT_t *bt);
Stops rewind and resumes normal playback.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandGetMetadata

void BTCommandGetMetadata(BT_t *bt);
Requests metadata (title, artist, album) for currently playing track.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
Telephony functions

​
BTCommandCallAccept

void BTCommandCallAccept(BT_t *bt);
Accepts an incoming call.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandCallEnd

void BTCommandCallEnd(BT_t *bt);
Ends the current call.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandDial

void BTCommandDial(BT_t *bt, const char *number, const char *name);
Dials a phone number.
​
bt
BT_t *
required
Pointer to Bluetooth context
​
number
const char *
required
Phone number to dial
​
name
const char *
Optional contact name

​
BTCommandRedial

void BTCommandRedial(BT_t *bt);
Redials the last dialed number.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandToggleVoiceRecognition

void BTCommandToggleVoiceRecognition(BT_t *bt);
Toggles voice recognition on/off.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
Phone book functions

​
BTCommandPBAPOpen

void BTCommandPBAPOpen(BT_t *bt);
Opens PBAP (phone book access protocol) session.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPBAPClose

void BTCommandPBAPClose(BT_t *bt);
Closes PBAP session.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTCommandPBAPGetPhonebook

void BTCommandPBAPGetPhonebook(
    BT_t *bt,
    uint8_t objectType,
    uint16_t startIndex,
    uint8_t count
);
Retrieves contacts from phone book.
​
bt
BT_t *
required
Pointer to Bluetooth context
​
objectType
uint8_t
required
Phonebook type: BT_PBAP_OBJ_PHONEBOOK, BT_PBAP_OBJ_INCOMING, BT_PBAP_OBJ_OUTGOING, BT_PBAP_OBJ_MISSED, etc.
​
startIndex
uint16_t
required
Starting index in phonebook
​
count
uint8_t
required
Number of contacts to retrieve (max 8)

​
BTCommandPBAPAbort

void BTCommandPBAPAbort(BT_t *bt);
Aborts current PBAP operation.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
Utility functions

​
BTClearMetadata

void BTClearMetadata(BT_t *bt);
Clears currently stored metadata (title, artist, album).
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTClearPairedDevices

void BTClearPairedDevices(BT_t *bt);
Clears the paired devices list from memory.
​
bt
BT_t *
required
Pointer to Bluetooth context

​
BTPairedDeviceFind

uint8_t BTPairedDeviceFind(BT_t *bt, uint8_t *macId);
Finds a paired device by MAC address.
​
bt
BT_t *
required
Pointer to Bluetooth context
​
macId
uint8_t *
required
6-byte MAC address
​
Returns
uint8_t
Index in paired devices array, or 0xFF if not found

Build docs developers (and LLMs) love

Get started for freeTalk to us