Introduction

lib_ux_nbgl is the UX event-routing layer for touch-enabled Ledger devices (Stax, Flex, Apex). It sits between the SE Proxy HAL (SEPH) and the NBGL drawing engine, dispatching hardware events (finger touches, buttons, ticker, default) to the right internal handler and triggering screen redraws when the OS requests them.

Applications do not interact with NBGL or SEPH directly for event processing — they use the macros and functions exposed by this library inside their main event loop.

Architecture

 ┌─────────────────────────────────────────────────────────────┐
 │  Application main event loop                                │
 │                                                             │
 │  UX_INIT()           UX_WAKE_UP()                           │
 │  UX_FINGER_EVENT()   UX_BUTTON_PUSH_EVENT()                 │
 │  UX_TICKER_EVENT()   UX_DEFAULT_EVENT()                     │
 └────────────────────────────┬────────────────────────────────┘
                              │
                   ┌──────────▼──────────┐
                   │    lib_ux_nbgl      │
                   │  ux_process_*()     │
                   └────────┬────────────┘
               ┌────────────┼─────────────┐
               │            │             │
     ┌─────────▼──┐  ┌──────▼──────┐  ┌───▼─────────┐
     │  NBGL      │  │  OS (os_ux) │  │  SEPH       │
     │  (drawing) │  │  (BOLOS UX) │  │  (events)   │
     └────────────┘  └─────────────┘  └─────────────┘

Initialization

Call UX_INIT() once at application startup, before entering the event loop. It initializes the NBGL object system.

void app_main(void) {
    UX_INIT();
    io_seproxyhal_general_status();
    while (1) {
        io_event(CHANNEL_APDU);
    }
}

Event-routing macros

Macro	Trigger	Action
UX_INIT()	Application startup	Calls `nbgl_objInit()`
UX_WAKE_UP()	User activity	Sends `BOLOS_UX_WAKE_UP` to the OS to prevent screen lock
UX_FINGER_EVENT(pkt)	`SEPROXYHAL_TAG_FINGER_EVENT`	Routes touch coordinates to NBGL via `ux_process_finger_event()`
UX_BUTTON_PUSH_EVENT(pkt)	`SEPROXYHAL_TAG_BUTTON_PUSH_EVENT`	No-op on touch devices (physical buttons not present)
UX_TICKER_EVENT(pkt, cb)	100 ms system ticker	Calls `ux_process_ticker_event()`
UX_DEFAULT_EVENT()	Any other SEPH event	Calls `ux_process_default_event()`

Global state

The library exposes two global variables:

G_ux (ux_state_t): holds the application exit code, a flag for PIN validation requests from the Dashboard, and a shared 128-byte string buffer for transient display strings.
G_ux_params (bolos_ux_params_t): used internally to pass UX commands to the OS via os_ux().