File espos_ble.h¶

FileList > espos_ble > include > espos_ble.h

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"

Classes¶

Type	Name
struct	espos_ble_status_t Runtime counters, mirrored into GET /api/v1/ble/status and the `ble` SSE event.

Public Functions¶

Type	Name
esp_err_t	espos_ble_get_status (espos_ble_status_t * out)
void	espos_ble_portal_hold (bool up) Take or release the setup portal's suspension, idempotently.
esp_err_t	espos_ble_register_api (void) Register GET /api/v1/ble/status and the `ble` SSE snapshot hook.
esp_err_t	espos_ble_reserve_controller (void) Reserve the radio controller's memory, before anything else takes it.
bool	espos_ble_scan_is_suspended (void) True while suspended by espos_ble_scan_suspend() .
esp_err_t	espos_ble_scan_resume (void) Release one suspension taken by espos_ble_scan_suspend() .
esp_err_t	espos_ble_scan_suspend (const char * reason) Suspend scanning, leaving the BLE stack up, so another component may own the radio for a while.
esp_err_t	espos_ble_start (void) Start the gateway: brings up the BLE stack (if espos_ble_reserve_controller() has not already), allocates the advertisement ring, starts scanning, and runs the POST + control-WS tasks.
esp_err_t	espos_ble_status_json (char ** out_json) Status document for docs/rest-api.md (malloc'ed JSON; caller frees).
esp_err_t	espos_ble_stop (void)

Public Functions Documentation¶

function espos_ble_get_status¶

esp_err_t espos_ble_get_status (
    espos_ble_status_t * out
)

function espos_ble_portal_hold¶

Take or release the setup portal's suspension, idempotently.

void espos_ble_portal_hold (
    bool up
)

The portal is announced twice by design ESPOS_EVENT_PORTAL_UP for later transitions, and a check from espos_start() at boot, because the portal is raised inside espos_wifi_start() before this component exists to hear the event. This makes the portal exactly ONE holder either way: taking two holds when only one PORTAL_DOWN will ever arrive would leave the scanner suspended for good.

function espos_ble_register_api¶

Register GET /api/v1/ble/status and the ble SSE snapshot hook.

esp_err_t espos_ble_register_api (
    void
)

Called by espos_ble_start(); exposed for tests.

function espos_ble_reserve_controller¶

Reserve the radio controller's memory, before anything else takes it.

esp_err_t espos_ble_reserve_controller (
    void
)

Optional: espos_ble_start() calls this itself if it has not run. It exists because WHEN the controller is initialised decides whether it can be at all. esp_bt_controller_init() needs ~24 KB in ONE contiguous block, and it takes it from the same internal heap the WiFi driver uses. Measured on an ESP32-C5 (199 KB internal, single core, espOS #127): with the station up first there are 33 KB free but the largest block is 16 KB, so the controller cannot start however much total memory is spare and no amount of freeing total heap fixes it, which is why capping WiFi buffers (~40 KB) and trimming Bluedroid (64 KB of image) both failed to.

Call it before starting a WiFi station on a part where internal RAM is tight. On parts with room, or where the controller is a co-processor (ESP32-P4), the order does not matter and this is a no-op beyond bringing the stack up sooner.

Deliberately does NOT allocate the advertisement ring or start scanning. The ring sizes itself from the largest free block, and run this early it measures a heap nothing has taken yet and reserves far too much: 224 entries (28 KB) on the C5, after which esp_wifi_init() got 1 of the 10 rx buffers it wanted and the device reboot-looped. The ring belongs with the rest of the gateway, after the network.

Opt-in: espos_start() does not call it. Reserving first is not free the memory comes out of whatever starts next, and on a part with no headroom that is a different subsystem failing instead. Only a caller that knows its own budget can make that trade, so it makes it explicitly. See docs/ble.md for the measurements behind this.

function espos_ble_scan_is_suspended¶

True while suspended by espos_ble_scan_suspend() .

bool espos_ble_scan_is_suspended (
    void
)

Mirrored into GET /api/v1/ble/status as scan_suspended, because "scanning: false" on a device whose setup portal is up is expected, not a fault.

function espos_ble_scan_resume¶

Release one suspension taken by espos_ble_scan_suspend() .

esp_err_t espos_ble_scan_resume (
    void
)

Scanning restarts, and the GAP callback is reclaimed if something else took it, only when the count reaches zero. A no-op if nothing is suspended.

function espos_ble_scan_suspend¶

Suspend scanning, leaving the BLE stack up, so another component may own the radio for a while.

esp_err_t espos_ble_scan_suspend (
    const char * reason
)

The setup portal is the reason this exists.

This is NOT espos_ble_stop(): the stack stays initialised, the tasks keep running, and the counters keep their values. Only the scan stops.

It is also not merely a courtesy. Bluedroid keeps exactly ONE GAP callback and registering is a setter, so a component like protocomm's simple_ble silently takes ours when it starts after which scan results stop arriving with no error reported anywhere. Suspending makes that explicit instead of leaving a scanner that appears to run and receives nothing.

Suspensions are COUNTED, so callers must pair them: scanning restarts only when the last holder resumes. A firmware that adds a second holder BLE provisioning is the obvious one overlaps the portal exactly on an unconfigured device, and a plain flag there let one hand the radio back while the other still needed it.

Safe to call when the gateway was never started.

function espos_ble_start¶

Start the gateway: brings up the BLE stack (if espos_ble_reserve_controller() has not already), allocates the advertisement ring, starts scanning, and runs the POST + control-WS tasks.

esp_err_t espos_ble_start (
    void
)

Reads its settings from the ble config namespace. Idempotent.

function espos_ble_status_json¶

Status document for docs/rest-api.md (malloc'ed JSON; caller frees).

esp_err_t espos_ble_status_json (
    char ** out_json
)

function espos_ble_stop¶

esp_err_t espos_ble_stop (
    void
)

The documentation for this class was generated from the following file espos_ble/include/espos_ble.h