PetOS BLE Gateway

PetOS BLE Gateway is a local Node.js bridge for controlling an ESP32-C3 PetOS watch over BLE.

It exposes three control surfaces over the same BLE connection:

• A browser dashboard for scanning, connecting, and sending pet commands.
• An HTTP API for scripts and local tools.
• A stdio MCP server for Codex, Claude, and other MCP clients.

Web UI / HTTP API / MCP tool
        |
        v
Node.js gateway
        |
        v
BLE JSON write
        |
        v
PetOS-C3 watch

Hardware/Firmware Assumptions

The current firmware advertises as PetOS-C3 and accepts JSON writes on:

• Service UUID: 7f2a0001-4f6d-45f6-b805-2b0a7a0f9c01
• Write characteristic UUID: 7f2a0002-4f6d-45f6-b805-2b0a7a0f9c01

The tested target is an ESP32-C3 round watch board with a 240x240 GC9A01 display.

Requirements

• macOS with Bluetooth enabled
• Node.js 20+
• A PetOS watch firmware advertising as PetOS-C3

This project uses @abandonware/noble for BLE access. On macOS, the terminal or app running Node may need Bluetooth permission in System Settings.

Install

npm install

Run The Web Gateway

npm start

Open:

http://127.0.0.1:8787

The page lets you scan, connect, send named actions, send a fixed frame, update the watch text page, or write raw JSON.

CLI Smoke Tests

Scan:

npm run scan -- 7000

Send an action:

npm run send -- '{"cmd":"pet.action","value":"review"}'

Show a fixed frame:

npm run send -- '{"cmd":"pet.frame","value":12}'

BLE JSON Protocol

Play an action:

{"cmd":"pet.action","value":"idle"}

{"cmd":"pet.action","value":"review"}

Show one fixed frame:

{"cmd":"pet.frame","value":12}

Show multiline text on the second watch page:

{"cmd":"watch.text","title":"Market","text":"#22c55e CPO +2.3%#\n#f97316 NVDA +1.1%#"}

The watch firmware supports LVGL label recolor syntax for simple rich text:

#22c55e green text# #f97316 orange text#

This is not HTML or Markdown. It supports multiline text and color spans, but not mixed font sizes, bold text, or embedded images.

Supported actions in the current firmware:

• idle
• waving
• jumping
• failed
• waiting
• running
• review

HTTP API

Status:

curl http://127.0.0.1:8787/api/status

Scan:

curl -X POST http://127.0.0.1:8787/api/scan \
  -H 'content-type: application/json' \
  -d '{"timeoutMs":7000}'

Connect:

curl -X POST http://127.0.0.1:8787/api/connect \
  -H 'content-type: application/json' \
  -d '{}'

Play an action:

curl -X POST http://127.0.0.1:8787/api/action/review \
  -H 'content-type: application/json' \
  -d '{}'

Send raw JSON:

curl -X POST http://127.0.0.1:8787/api/send \
  -H 'content-type: application/json' \
  -d '{"cmd":"pet.frame","value":12}'

Update the second watch page text:

curl -X POST http://127.0.0.1:8787/api/watch/text \
  -H 'content-type: application/json' \
  -d '{"title":"Market","text":"#22c55e CPO +2.3%#\n#f97316 NVDA +1.1%#"}'

MCP Server

Start the gateway first:

npm start

Then run the MCP server:

npm run mcp

For an MCP client, use this command:

node /absolute/path/to/petos-ble-gateway/src/mcp-server.js

Available MCP tools:

• petos_status
• petos_scan
• petos_connect
• petos_send_json
• petos_play_action
• petos_show_frame
• petos_show_text

The MCP server calls the local gateway at http://127.0.0.1:8787 by default. Override with:

PETOS_GATEWAY_URL=http://127.0.0.1:8787 npm run mcp

Troubleshooting

If the device does not appear in macOS Bluetooth settings, use this gateway or a BLE scanner such as nRF Connect/LightBlue. Ordinary BLE GATT devices often do not appear like keyboards or headphones.

If scanning hangs or returns no devices:

• Make sure the watch firmware is advertising PetOS-C3.
• Make sure the Node process has Bluetooth permission.
• Try npm run scan -- 10000.
• Restart the gateway after toggling Bluetooth permissions.

If action buttons appear to do nothing, check the log panel. A successful send looks like:

sent {"cmd":"pet.action","value":"review"}