Lua API mobile

On mobile, Lua does not run in the same environment as the ESP32 firmware Lua VM. There are three mobile Lua contexts documented here: Central, Observer, and Local Sim (peripheral). Peripheral scripts can also be executed on the ESP32 firmware; see ESP32 Lua API.

Do not assume one script sees every function listed in the ESP32 documentation. Mobile Central and mobile Observer have different globals, different entry points, and different available helpers.

Contexts

Standard library

Mobile Lua uses Luaj JSE globals, which are broader than the ESP32 firmware runtime. In practice, portable pack scripts should avoid relying on io, os, or other host-specific libraries even if Luaj exposes them.

Shared mobile globals

The following concepts appear on mobile, though not always in every context.

Common mobile helpers

These helpers are installed in Observer, Central, and Local Sim. Firmware peripheral/central Lua installs the same bits / hex tables and lowercase bin_to_hex — see ESP32 Lua API.

Hex payloads (lowercase emit)

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

Company-id map keys and first_company_id stay 4-digit uppercase identifiers (e.g. "004C"); those are not payload encode.

hex table

Pack integer arguments wrap to the field width (same mask policy as bits.tohex / n % 256 for u8), then emit lowercase hex. Non-numbers raise via checkint.

bits table

Bitwise ops use checkint (Lua 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

adv / uuid (Observer + Central only)

These are not installed on Local Sim or ESP32 (peripheral Lua must stay firmware-portable). The global table adv does not replace adv_set_data / adv_enable.

Walk BLE GAP TLV [len][type][value…] after hex.norm (whitespace + lowercase only). Odd length or a non-hex nibble stops and keeps records already found ("0x020106" is not valid AD hex). len == 0 stops. len == 1 is { type = n, data = "" }.

adv.find always returns a table (empty is truthy — use #t > 0 or [1]).

There is no adv.local_name. Use hex.to_ascii(adv.find(h, 0x09)[1] or adv.find(h, 0x08)[1] or "").

mac (Observer, Central, Local Sim)

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

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

Central ATT values (ble_write, ble_read, on_notify) are hex text. Stay in hex unless you need a binary Lua string.

Do not:

• Use bits.tohex to encode a blob — it formats one integer, not a byte string.
• Convert to binary just to read or pack fields — stay in hex.
• Pass hex_to_bin(...) to ble_write — write wants hex.
• Wrap ble_read / on_notify with bin_to_hex — they are already 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 edge
local digest_hex = bin_to_hex(sha256(hex_to_bin(payload_hex)))
ble_write(SVC, CHR, digest_hex)

Observer

Observer Lua runs during scan / fingerprint decode when roles.observer.entry matches scan conditions. This context is mobile-only.

Entry point:

parse(input) --> entries
parse(input) --> entries, ui

Observer has no crypto helpers, no ble_* client functions, and no menu functions. It is intended for scan data parsing and fingerprint enrichment only.

Observer globals

parse(input) fields

The input table built for Observer parsing may include:

Observer return value

Return an array of entries with shape:

{
  {
    id = "...",
    display_name = "...", -- optional
    attributes = {
      -- key/value attributes
    }
  }
}

You may also return a second ui table with optional keys such as:

• device_type
• beacon_format
• custom_icon — pack-relative .svg or .png (e.g. assets/icon.svg). PNG is shown with intrinsic colors.
• custom_icon_tint — hex tint for SVG only (#RRGGBB / #AARRGGBB); ignored for PNG.
• display_name
• display_info

Central

Central Lua runs after GATT connection and is the main mobile GATT-client scripting environment. It includes BLE access, crypto, menu helpers, display helpers, fingerprint helpers, and data helpers.

Central globals and helpers

Crypto

These are installed in mobile Central only, not in Observer.

BLE client API

Mobile Central BLE API details.

BLE helpers

Callbacks and entry points

Fingerprint and enrichment helpers

Data helpers

bits / hex / adv / mac in Central

Central installs the same bits / hex / adv / uuid / mac tables as Observer (see Common mobile helpers).

Peripheral note (Local Sim)

Peripheral runtime APIs (gfx_*, ble_notify, ble_notify_raw, adv_set_data, adv_enable, adv_disable, ble_connected, ble_disconnect, get_mtu, set_preferred_mtu, delay, crypto helpers, and ble.json dynamic hooks) run on this phone when you start Local → Sim.

Local Sim and ESP32 firmware both install the shared bits / hex / mac tables and lowercase bin_to_hex. They do not install adv / uuid. Peripheral scripts may use bits / hex / mac on Remote Sim and Local Sim.

On-phone simulation cannot match ESP32 Remote Sim or real hardware in every respect:

• The OS only accepts structured advertising fields (service UUIDs, and on Android also service data / manufacturer data). Raw adv_data_hex PDUs are reconstructed, not replayed.
• iOS advertising is limited to local name + service UUIDs. Service data and manufacturer data are dropped; the Sim canvas shows an OS-limit banner.
• ble_disconnect can cancel the central on Android only. iOS has no public API to kick a connected central.
• get_adv_bd_addr is often unavailable (the OS hides the adapter address).
• gpio_set / gpio_get are not applicable on a phone, Local Sim returns ok [, err] / nil [, err], not a Lua error.
• Simulation runs only while the app is in the foreground. Background advertising is not enabled in this version.

The same peripheral Lua also runs on ESP32 Remote Sim; prefer that path when you need full advertising fidelity. Details remain in ESP32 Lua API.