Reference

HAL API Reference

Every bh_* function available to community programs and custom nodes — grouped by hardware category.

Rule: Only call bh_* functions in your programs — never call Arduino APIs directly. This keeps programs portable across board variants.

Display Buttons Constants System WiFi BLE NVS Storage SD Card IR RF 433MHz OTA

Display

bh_display_clear()

Clear the screen buffer. Does not update the physical display until bh_display_show() is called.

bh_display_show()

Flush the buffer to the OLED. Call after all drawing commands.

bh_display_cls()

Clear and immediately show — equivalent to clear() + show() in one call.

bh_display_font(BHFont f)

Set the active font.

bh_display_font(BH_FONT_SMALL);  // BH_FONT_SMALL | BH_FONT_MEDIUM | BH_FONT_LARGE

bh_display_print(int x, int y, const char* text)

Draw text at pixel coordinates (x, y). Origin is top-left.

bh_display_print_center(int y, const char* text)

Draw text centered horizontally at row y.

bh_display_print_int(int x, int y, long value)

Draw an integer at (x, y).

bh_display_print_float(int x, int y, float value, int decimals)

Draw a float with specified decimal places.

bh_display_hline(int x, int y, int w)

Draw a horizontal line from (x,y) of width w pixels.

bh_display_vline(int x, int y, int h)

Draw a vertical line from (x,y) of height h pixels.

bh_display_rect(int x, int y, int w, int h)

Draw an unfilled rectangle.

bh_display_fill_rect(int x, int y, int w, int h)

Draw a filled rectangle.

bh_display_circle(int x, int y, int r)

Draw an unfilled circle at center (x,y) with radius r.

bh_display_pixel(int x, int y, bool on)

Set a single pixel on or off.

bh_display_progress(int x, int y, int w, int h, int pct)

Draw a progress bar. pct is 0–100.

bh_display_invert(bool invert)

Invert the current buffer colors.

bh_display_notify(const char* message, unsigned long timeout_ms)→ int — button pressed (if any) during notify

Show a popup overlay for timeout_ms milliseconds. Blocks until timeout.

bh_display_statusbar(const char* left, const char* right)

Draw a status bar at the top: left-aligned text on left, right-aligned on right.

bh_display_menu(const char* title, const char** items, int count, int selected)

Draw a standard scrollable menu list with title and selection highlight.

Buttons

bh_wait_button()→ int — one of BH_BTN_* constants

Block until any button is pressed. Returns which button.

bh_wait_button_timeout(unsigned long timeout_ms)→ int — BH_BTN_NONE if timed out

Block until a button is pressed or timeout expires.

bh_poll_button()→ int — BH_BTN_NONE or BH_BTN_*

Non-blocking. Returns BH_BTN_NONE if no button is currently pressed. Use in game loops.

bh_button_held(int btn)→ bool

Returns true if the specified button is currently held down.

bh_exit_requested()→ bool

Returns true when the user has held BACK for 1.5 seconds. Programs MUST check this in their main loop.

bh_program_exit()

Signal clean exit back to the device flow. MUST be called before returning from the program entry point.

Constants

BH_BTN_OK = 0

OK / centre button

BH_BTN_BACK = 1

Back button (short press)

BH_BTN_UP = 2

Up button

BH_BTN_DOWN = 3

Down button

BH_BTN_1 = 4

Side button 1

BH_BTN_2 = 5

Side button 2

BH_BTN_EXIT = 99

Long-press BACK (1.5s) — program must clean up and return

BH_BTN_NONE = -1

No button pressed (poll only)

BH_FONT_SMALL

Smallest font — fits most text on screen

BH_FONT_MEDIUM

Medium font — good for UI labels

BH_FONT_LARGE

Large font — titles and big numbers only

BH_OLED_W = 128

OLED width in pixels

BH_OLED_H = 64

OLED height in pixels

System

bh_millis()→ unsigned long

Returns milliseconds since boot — equivalent to Arduino millis().

bh_delay(unsigned long ms)

Block for ms milliseconds. Use instead of Arduino delay().

bh_beep(int freq_hz, int duration_ms)

Play a tone on the buzzer. freq_hz is frequency, duration_ms is length.

bh_click()

Play a short click sound — UI feedback.

bh_led(bool on)

Turn the onboard LED on or off.

bh_led_blink(int times, int on_ms, int off_ms)

Blink the LED a specified number of times.

bh_version()→ const char*

Returns the current firmware version string.

WiFi

bh_wifi_connect(const char* ssid, const char* password, unsigned long timeout_ms)→ bool — true if connected

Connect to a WiFi network. Blocks until connected or timeout.

bh_wifi_disconnect()

Disconnect from WiFi.

bh_wifi_ip()→ const char*

Returns the current IP address as a string.

bh_http_get(const char* url, char* out_buf, size_t buf_size)→ int — HTTP status code

Perform an HTTP GET request. Response body written to out_buf.

bh_http_post(const char* url, const char* body, const char* content_type, char* out_buf, size_t buf_size)→ int — HTTP status code

Perform an HTTP POST request.

bh_wifi_ap_start(const char* ssid, const char* password, uint8_t channel)→ const char* — IP of the AP gateway

Start a WiFi access point.

bh_wifi_ap_stop()

Stop the access point.

BLE

bh_ble_start(const char* device_name)→ bool — true if started

Start BLE advertising with the given device name.

bh_ble_stop()

Stop BLE and disconnect any clients.

bh_ble_connected()→ bool

Returns true if a BLE client is currently connected.

bh_ble_notify(const uint8_t* data, size_t len)→ bool — true if sent

Send a BLE notification to the connected client.

NVS Storage

bh_nvs_set_string(const char* key, const char* value)

Save a string to non-volatile storage. Survives reboot and OTA.

bh_nvs_get_string(const char* key, const char* default_val)→ const char*

Read a string from NVS. Returns default_val if key not found.

bh_nvs_set_int(const char* key, int32_t value)

Save an integer to NVS.

bh_nvs_get_int(const char* key, int32_t default_val)→ int32_t

Read an integer from NVS.

bh_nvs_set_float(const char* key, float value)

Save a float to NVS.

bh_nvs_get_float(const char* key, float default_val)→ float

Read a float from NVS.

bh_nvs_erase(const char* key)

Delete a key from NVS.

SD Card

bh_sd_available()→ bool

Returns true if an SD card is inserted and mounted.

bh_sd_write(const char* path, const char* data, bool append)→ bool — true on success

Write data to a file. Set append=true to append, false to overwrite.

bh_sd_read(const char* path, char* out_buf, size_t buf_size)→ int — bytes read, or -1 on error

Read file contents into out_buf.

bh_sd_exists(const char* path)→ bool

Returns true if file or directory exists.

bh_sd_remove(const char* path)→ bool — true on success

Delete a file from SD.

IR

bh_ir_send(const char* protocol, uint64_t code, int bits)

Send an IR signal. protocol is e.g. "NEC", "SONY". code is the raw value.

bh_ir_receive(char* protocol_out, uint64_t* code_out, unsigned long timeout_ms)→ bool — true if signal captured

Listen for an IR signal. Blocks until received or timeout.

RF 433MHz

bh_rf_send(unsigned long code, int bit_length, int protocol)

Transmit an RF code. bit_length is typically 24. protocol is 1–3.

bh_rf_receive(unsigned long* code_out, int* protocol_out, unsigned long timeout_ms)→ bool — true if signal captured

Listen for an RF signal. Blocks until received or timeout.

OTA

bh_ota_check(const char* update_url)→ bool — false if up to date or failed (success never returns — device reboots)

Check for a firmware update at update_url/version.json. If a newer version exists, downloads update_url/firmware.bin, flashes it, and reboots. Device restarts automatically on success.

← Back to docs Writing programs →

↑