Lua API ESP32

This page documents ESP32 peripheral simulation and the overlapping APIs used by Local Sim on the phone. Mobile Central and Observer Lua are documented separately in Mobile Lua API.

Peripheral Lua in device packs may run on the ESP32 simulator / firmware or on the phone via Local → Sim. Functions such as ble_notify, gfx_*, and adv_* described here apply to both, with these Local Sim gaps:

• The phone cannot emit exact adv_data_hex PDUs; only OS-supported AD types are advertised. iOS is limited to local name + service UUIDs.
• ble_disconnect works on Android (cancelConnection); iOS cannot kick a central.
• get_adv_bd_addr is often nil when the OS hides the address.
• gpio_set / gpio_get are firmware/board pins only — Local Sim returns ok [, err] / nil [, err], not a Lua error.
• Local Sim runs only in the foreground (no iOS bluetooth-peripheral background mode, no Android foreground service in this version).
• Firmware and Local Sim both install the shared bits / hex / mac tables and lowercase bin_to_hex (same API as Mobile Lua). They do not install adv / uuid.

Runtime and standard library

ESP32 peripheral scripts run with a restricted standard library, in order to save the memory footprint:

• _G
• string
• math
• table

Do not assume Luaj JSE libraries such as io or os are available here.

Scripts are loaded by lua_init_persistent_minimal() in the firmware Lua VM.

Globals

Common helpers

These helpers are available in the ESP32 peripheral Lua VM.

bin_to_hex, bits.tohex, and hex.* packers emit lowercase hex. Decoders still accept mixed case. BLE write/notify hex is case-insensitive.

hex table

Pack integer arguments wrap to the field width, then emit lowercase hex. Non-numbers raise.

bits table

Bitwise ops error on non-number. Unpackers take (hex, offset) where offset is a 1-based byte index into the hex string as given (not hex.norm’d). Mixed case is OK; short, odd, or invalid slices return 0.

• band, bor, bxor, bnot, rshift, lshift, arshift
• byte_at(hex, index)
• tohex(n [, width]) — lowercase
• fromhex(hex)
• le16 / be16 / le32 / be32

mac table

Invalid / not exactly 6 octets → "". Colons, dashes, and spaces are ignored when collecting octets.

Firmware and Local Sim have no adv / uuid tables.

When to use bin_to_hex / hex_to_bin vs hex.* / bits.*

Central ATT values (ble_write, ble_read, on_notify) are hex text. Peripheral on_write(input) and crypto helpers are binary. Stay in hex unless you need a binary Lua string.

Do not use bits.tohex to encode a blob (one integer, not a byte string). Do not pass hex_to_bin(...) to ble_write / ble_notify. Do not wrap ble_read / on_notify with bin_to_hex.

-- fields: stay in hex
local n = bits.le16(hex, 1)
ble_write(SVC, CHR, hex.le16(n) .. hex.u8(0x03))

-- blob: binary only at the crypto / on_write edge
function on_write(input)
  local hex = bin_to_hex(input)
  local digest_hex = bin_to_hex(sha256(input))
  ble_notify(SVC, CHR, digest_hex)
  return input
end

Crypto

Graphics

These functions bind to the LVGL / WebSocket simulation UI.

Supported align strings: top_left, top_center, top_right, middle_left, middle_right, bottom_left, bottom_center, bottom_right; any other value falls back to center.

BLE peripheral

These functions are available in the ESP32 peripheral simulation runtime and in Local Sim on the phone (see OS gaps above).

Dynamic GATT hooks

Peripheral GATT dynamic hooks in JSON, such as on_read and on_write, can call into Lua. See ble_sim_gatt.c for relay-prefixed forms.

Notes

• All Lua runs on a dedicated task. BLE notify posts on_notify asynchronously via a queue.
• Many functions use multiple return values such as ok, err or nil, err, and some failures may use luaL_error.
• Prefer entries in uuids for readability; UUID strings are normalized internally for lookup.