Skip to main content

​
Event API

The Event API implements an event-driven callback system that allows modules to communicate without direct coupling.

​
System configuration

Capacity:
  • Maximum callbacks: 192 (EVENT_MAX_CALLBACKS)

​
Data structures

​
Event_t

Defines an event callback registration.
​
type
uint8_t
Event type identifier
​
context
void *
Context pointer passed to callback
​
callback
void (*)(void *, unsigned char *)
Function pointer to invoke when event is triggered

​
Event types

Events are identified by numeric types. Common event types include: Bluetooth events:
  • BT_EVENT_BOOT - Bluetooth module boot complete
  • BT_EVENT_DEVICE_CONNECTED - Device connected
  • BT_EVENT_DEVICE_DISCONNECTED - Device disconnected
  • BT_EVENT_PLAYBACK_STATUS_CHANGE - Playback state changed
  • BT_EVENT_METADATA_UPDATE - Track metadata received
  • BT_EVENT_CALL_STATUS_UPDATE - Call status changed
I-Bus events:
  • IBUS_EVENT_MODULE_STATUS_RESP - Module status response
  • IBUS_EVENT_IGN_STATUS_UPDATE - Ignition status changed
  • IBUS_EVENT_FIRST_MESSAGE_RX - First I-Bus message received
UI events:
  • UI_EVENT_SETTING_CHANGE - Configuration setting changed
Event type constants are defined in the respective module header files (bt.h, ibus.h, etc.).

​
Functions

​
EventRegisterCallback

Registers a callback function for an event type. 
void EventRegisterCallback(
    uint8_t type,
    void *context,
    void *callback
);
​
type
uint8_t
Event type to listen for
​
context
void *
Context pointer to pass to callback
​
callback
void (*)(void *, unsigned char *)
Callback function with signature: void callback(void *context, unsigned char *data)
Example: 
void OnDeviceConnected(void *context, unsigned char *data) {
    IBus_t *ibus = (IBus_t *)context;
    LogInfo("Bluetooth device connected");
    IBusCommandCDCAnnounce(ibus);
}

EventRegisterCallback(
    BT_EVENT_DEVICE_CONNECTED,
    &ibus,
    &OnDeviceConnected
);
Multiple callbacks can be registered for the same event type. All registered callbacks will be invoked when the event is triggered.

​
EventUnregisterCallback

Removes a callback registration for an event type. 
uint8_t EventUnregisterCallback(
    uint8_t type,
    void *callback
);
​
type
uint8_t
Event type to unregister from
​
callback
void *
Callback function to remove
​
returns
uint8_t
1 if callback was found and removed, 0 otherwise
Example: 
EventUnregisterCallback(
    BT_EVENT_DEVICE_CONNECTED,
    &OnDeviceConnected
);

​
EventTriggerCallback

Triggers all callbacks registered for an event type. 
void EventTriggerCallback(
    uint8_t type,
    unsigned char *data
);
​
type
uint8_t
Event type to trigger
​
data
unsigned char *
Data pointer to pass to callbacks (can be NULL)
Example: 
// Trigger event with no data
EventTriggerCallback(BT_EVENT_BOOT, 0);

// Trigger event with data
unsigned char status = PLAYBACK_STATUS_PLAYING;
EventTriggerCallback(BT_EVENT_PLAYBACK_STATUS_CHANGE, &status);
Callbacks are invoked synchronously in the order they were registered. Long-running callbacks will block the event system.

​
Callback signature

All event callbacks must use this signature: 
void CallbackFunction(void *context, unsigned char *data);
Parameters:
  • context - The context pointer provided during registration
  • data - Event-specific data pointer (may be NULL)
Example callback: 
void HandleMetadataUpdate(void *context, unsigned char *data) {
    BMBT_t *bmbt = (BMBT_t *)context;
    BT_t *bt = (BT_t *)data;
    
    // Update display with new metadata
    BMBTHeaderWriteText(bmbt, bt->title);
}

​
Usage patterns

​
Module initialization

Modules typically register callbacks during initialization: 
void MyModuleInit(IBus_t *ibus, BT_t *bt) {
    // Register for Bluetooth events
    EventRegisterCallback(
        BT_EVENT_DEVICE_CONNECTED,
        ibus,
        &OnBTConnected
    );
    
    EventRegisterCallback(
        BT_EVENT_METADATA_UPDATE,
        &myContext,
        &OnMetadataUpdate
    );
}

​
Event triggering

Modules trigger events when state changes: 
void BTHandleConnection(BT_t *bt) {
    bt->connectedDevice = deviceId;
    
    // Notify all listeners
    EventTriggerCallback(BT_EVENT_DEVICE_CONNECTED, 0);
}

​
Data passing

Pass data through the event system: 
// Trigger with struct
BTMetadata_t metadata = {
    .title = "Song Title",
    .artist = "Artist Name",
    .album = "Album Name"
};
EventTriggerCallback(BT_EVENT_METADATA_UPDATE, (unsigned char *)&metadata);

// Receive in callback
void OnMetadata(void *context, unsigned char *data) {
    BTMetadata_t *metadata = (BTMetadata_t *)data;
    LogInfo("Now playing: %s", metadata->title);
}

​
Constants

#define EVENT_MAX_CALLBACKS 192  // Maximum number of registered callbacks

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us