spx-ble-adapter

SPX BLE Adapter is a lightweight service that exposes a configurable BLE peripheral controlled by SPX models. Through a simple HTTP/JSON Control API, SPX can define GATT services/characteristics and push values (Notify). macOS CoreBluetooth and Linux BlueZ backends are supported. Ships as a standalone binary with examples, OpenAPI spec, docs, and tests.

Requirements

• Node.js 16.x (as recommended by @abandonware/bleno)
• macOS with Bluetooth enabled and Terminal granted Bluetooth permission
• iOS device with a BLE client app (for testing)

Run locally

npm install
npm start

On macOS you may need sudo npm start (or sudo node index.js) so CoreBluetooth can expose the peripheral.

iOS testing notes

• Peripheral advertises as SPX-Sim (or BLE_DEVICE_NAME env override) with Environmental Sensing service 0x181A.
• Temperature characteristic 0x2A6E currently supports read. Live updates will require adding notify handling in a later iteration.
• Custom write characteristic (f0c09111-8b3a-4e69-bdd0-9f0f613d1a90) accepts UTF-8. Text writes (e.g. 23.5) are parsed to float, clamped to -40…125 °C, and stored in adapter state.
• onWrite actions run sequentially. Right now they only log ([BLE] emit event -> …) to make it easy to hook an HTTP call to SPX later.

Device configuration

• Default config: config/default.json (empty adapter, no advertising, waits for PUT /config). Override path with BLE_DEVICE_CONFIG.
• Example profile: config/template-spx-sim.json matches the classic temperature POC.
• JSON defines device name (device.name), advertised UUIDs (advertiseServiceUuids), initial state (state.temperatureC), and the full list of services/characteristics.
• Each characteristic defines properties, data encoding (codec.format, scale), and a sequence of onWrite actions so the adapter can log, parse, and forward data. (Currently descriptor 0x2901; 0x2904 can be added once macOS support is polished.)
• When properties include notify, set notify to control behavior:

  "notify": {
    "triggers": ["state", "timer"], // default ["state"]
    "intervalMs": 1000              // for timer trigger (optional)
  }

  By default the adapter notifies on every state change (e.g. PUT /state). Adding timer enables periodic publishes regardless of state changes.
• To load a custom config, add a file under config/ and start with BLE_DEVICE_CONFIG=/path/to/config.json npm start.

HTTP API

• HTTP server binds 0.0.0.0:8085 by default (HTTP_HOST, HTTP_PORT can override).
• Endpoints:
  • GET /health – adapter status, device name, last config update.
  • GET /config – current config (path + JSON data).
  • PUT /config – runtime BLE config update (rebuilds services, restarts advertising).
  • GET /state – dump of current state (keys from state section).
  • PUT /state – bulk state update (e.g. {"temperatureC": 23.5}).
  • POST /events – ingress for BLE → SPX events (currently logged locally).

Tests

• Run npm test to execute the unit suite (node --test, Node 16.17+ required).
• Coverage includes: config loading (lib/config), state handling (lib/state), codecs (lib/codecs), onWrite actions (lib/actions), GATT service build (lib/build-services), and HTTP routing (server/http).