MyBeacon API Documentation

Overview

MyBeacon device provides two types of APIs:

Device API - HTTP API running on the device (port 80)
Server API - Backend endpoints that device communicates with

Device Identification:

device_id: eth0 MAC address (e.g., 38:54:39:4b:1b:ad)
device_token: Authentication token (received during registration)
device_password: 8-digit PIN for dashboard access

Device API - Running on device
Server API - Backend endpoints

Device API

Base URL: http://<device-ip> (default port 80)

All responses include CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

GET /api/status

Returns current device status including network state, scanners status, and counters.

Request:

GET /api/status HTTP/1.1
Host: 192.168.5.244

Response: 200 OK

{
  "device_id": "38:54:39:4b:1b:ad",
  "registered": true,
  "mode": "cloud",
  "uptime_sec": 45652,
  "network": {
    "eth0_ip": "192.168.5.244/24",
    "eth0_mac": "38:54:39:4b:1b:ad",
    "eth0_rx": 29226155,
    "eth0_tx": 53569343,
    "wlan0_ip": "192.168.5.100/24",
    "wlan0_mac": "38:54:39:4b:1b:ac",
    "wlan0_ssid": "MyNetwork",
    "wlan0_signal": -45,
    "wlan0_channel": 6,
    "wlan0_gateway": "192.168.5.1",
    "wlan0_dns": "192.168.5.1",
    "wlan0_rx": 1234567,
    "wlan0_tx": 7654321,
    "gateway": "192.168.5.1",
    "dns": "192.168.5.1",
    "ntp": "pool.ntp.org",
    "ap_active": false
  },
  "scanners": {
    "ble_running": true,
    "wifi_running": false
  },
  "counters": {
    "ble_events": 12345,
    "wifi_events": 6789,
    "uploads": 42,
    "errors": 0
  },
  "server_ok": true
}

Fields:

device_id: Device MAC address (eth0)
registered: Whether device is registered on server
mode: Operating mode (cloud or lan)
uptime_sec: System uptime in seconds
network.eth0_*: Ethernet interface stats
network.wlan0_*: WiFi interface stats (only when connected)
network.ap_active: Whether AP fallback is active
scanners.*_running: Scanner status
counters: Event and upload counters
server_ok: Server connection status

GET /api/metrics

Returns system metrics (CPU, memory, temperature, load).

Request:

GET /api/metrics HTTP/1.1
Host: 192.168.5.244

Response: 200 OK

{
  "cpu_percent": 15.5,
  "mem_used_mb": 42.3,
  "mem_total_mb": 245.0,
  "temperature": 45.2,
  "load_avg": 0.42,
  "load_1m": 0.42,
  "load_5m": 0.35,
  "load_15m": 0.28
}

Fields:

cpu_percent: CPU usage percentage
mem_used_mb: Used memory in MB
mem_total_mb: Total memory in MB
temperature: SoC temperature in °C
load_avg: 1-minute load average
load_1m/5m/15m: Load averages

GET /api/config

Returns current device configuration (without secrets).

Request:

GET /api/config HTTP/1.1
Host: 192.168.5.244

Response: 200 OK

{
  "mode": "cloud",
  "api_base": "http://server:8000/api/v1",
  "ble": {
    "enabled": true,
    "batch_interval_ms": 2500
  },
  "wifi": {
    "monitor_enabled": true,
    "client_enabled": false,
    "ssid": "",
    "batch_interval_ms": 10000
  },
  "network": {
    "ntp_servers": ["pool.ntp.org"],
    "eth0": {
      "static": false,
      "address": "",
      "gateway": "",
      "dns": ""
    }
  },
  "dashboard": {
    "enabled": true
  },
  "ssh_tunnel": {
    "enabled": false,
    "server": "",
    "port": 22,
    "user": "tunnel",
    "remote_port": 0
  }
}

Note: Sensitive fields (passwords, keys) are omitted from response.

GET /api/ble/recent

Returns recent BLE events (last 100, kept for 15 seconds).

Request:

GET /api/ble/recent HTTP/1.1
Host: 192.168.5.244

Response: 200 OK

[
  {
    "type": "ibeacon",
    "mac": "AA:BB:CC:DD:EE:FF",
    "rssi": -65,
    "ts_ms": 1703001234567,
    "uuid": "f7826da64fa24e988024bc5b71e0893e",
    "major": 100,
    "minor": 1,
    "tx_power": -59
  },
  {
    "type": "my-beacon_acc",
    "mac": "11:22:33:44:55:66",
    "rssi": -72,
    "ts_ms": 1703001234568,
    "x": 123,
    "y": -45,
    "z": 678,
    "bat": 95,
    "temp": 25.5
  }
]

BLE Event Types:

ibeacon: Apple iBeacon format
my-beacon_acc: Custom accelerometer beacon
rt_mybeacon: Relay beacon

GET /api/wifi/recent

Returns recent WiFi probe requests (last 100).

Request:

GET /api/wifi/recent HTTP/1.1
Host: 192.168.5.244

Response: 200 OK

[
  {
    "mac": "AA:BB:CC:DD:EE:FF",
    "rssi": -55,
    "ts_ms": 1703001234567,
    "ssid": "MyNetwork",
    "freq": 2437,
    "channel": 6
  }
]

GET /api/logs

Returns recent daemon log lines (last 500).

Request:

GET /api/logs HTTP/1.1
Host: 192.168.5.244

Response: 200 OK

[
  "12:36:28 [ble] Uploaded 2 events to server",
  "12:36:31 [ble] Uploaded 1 events to server",
  "12:36:33 [scanner] BLE scanner started (pid=1234)"
]

GET /api/kernel-logs

Returns kernel log messages from dmesg (last 500 lines).

Request:

GET /api/kernel-logs HTTP/1.1
Host: 192.168.5.244

Response: 200 OK

[
  "[45666.294334] aicwf_sdio mmc1:7a8a:1 wlan0: CLOSE",
  "[45666.295543] ieee80211 phy0: HT supp 1, VHT supp 1, HE supp 1"
]

Note: BusyBox dmesg doesn't support -T flag, timestamps are in [seconds.microseconds] format since boot.

POST /api/unlock

Validates device password and creates a session.

Request:

POST /api/unlock HTTP/1.1
Host: 192.168.5.244
Content-Type: application/json

{
  "password": "82680499"
}

Response: 200 OK

{
  "token": "abc123def456..."
}

Error Response: 401 Unauthorized

Invalid password

POST /api/settings

Updates device settings (requires valid password).

Request:

POST /api/settings HTTP/1.1
Host: 192.168.5.244
Content-Type: application/json

{
  "password": "82680499",
  "settings": {
    "mode": "cloud",
    "wifi_client_enabled": true,
    "wifi_ssid": "MyNetwork",
    "wifi_psk": "password123",
    "wifi_monitor_enabled": false,
    "eth0_mode": "dhcp",
    "ntp_servers": "pool.ntp.org,time.google.com"
  }
}

Settings Fields:

mode: "cloud" or "lan"
wifi_client_enabled: Enable WiFi client
wifi_ssid: WiFi network name
wifi_psk: WiFi password
wifi_monitor_enabled: Enable WiFi scanner (LAN mode only)
eth0_mode: "dhcp" or "static"
eth0_ip: Static IP (when eth0_mode="static")
eth0_gateway: Gateway (static mode)
eth0_dns: DNS server (static mode)
ntp_servers: Comma-separated NTP servers
ble_enabled: Enable BLE scanner (LAN mode only)
ble_batch_interval_ms: BLE batch interval
wifi_monitor_batch_interval_ms: WiFi batch interval

Response: 200 OK

{
  "success": true
}

Error Response: 401 Unauthorized

Invalid password

Note:

In Cloud mode, scanner settings come from server
In LAN mode, scanner settings are local
WiFi client settings work in both modes
Changes to WiFi credentials in Cloud mode are also sent to server

WebSocket /api/ws

Real-time event stream for dashboard updates.

Connection:

const ws = new WebSocket('ws://192.168.5.244/api/ws');

Message Format:

{
  "type": "ble",
  "event": {
    "mac": "AA:BB:CC:DD:EE:FF",
    "rssi": -65,
    "ts_ms": 1703001234567
  }
}

Message Types:

type: "ble": BLE event
type: "wifi": WiFi event
type: "log": Log message

Server API

Base URL: Configured in device settings (default: http://server:8000/api/v1)

Authentication: Bearer token in Authorization header (except registration).

POST /api/v1/registration

Registers a new device with the server. Called once on first boot.

Request:

POST /api/v1/registration HTTP/1.1
Host: server:8000
Content-Type: application/json

{
  "device_id": "38:54:39:4b:1b:ad",
  "eth_ip": "192.168.5.244",
  "wlan_ip": "192.168.5.100",
  "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA..."
}

Fields:

device_id: Device MAC address (eth0)
eth_ip: Ethernet IP address (optional)
wlan_ip: WiFi IP address (optional)
ssh_public_key: SSH public key for tunnel (optional)

Response: 201 Created

{
  "device_token": "gRMRUKnqO9KXikBzoKhs0aE3uDYUvTxHYuU4/uatyrc=",
  "device_password": "82680499",
  "ssh_tunnel": {
    "enabled": true,
    "remote_port": 50123,
    "server": "tunnel.example.com"
  }
}

Response Fields:

device_token: Authentication token for API calls (save to /opt/mybeacon/etc/device.json)
device_password: 8-digit PIN for dashboard (save to device.json)
ssh_tunnel: SSH tunnel configuration (optional)

Error Response: 400 Bad Request

{
  "error": "device_id is required"
}

GET /api/v1/config

Fetches device configuration from server (Cloud mode only, polled every 30 seconds).

Request:

GET /api/v1/config?device_id=38:54:39:4b:1b:ad HTTP/1.1
Host: server:8000
Authorization: Bearer gRMRUKnqO9KXikBzoKhs0aE3uDYUvTxHYuU4/uatyrc=

Response: 200 OK

{
  "force_cloud": false,
  "ble": {
    "enabled": true,
    "batch_interval_ms": 2500,
    "uuid_filter_hex": ""
  },
  "wifi": {
    "client_enabled": false,
    "ssid": "",
    "psk": "",
    "monitor_enabled": true,
    "batch_interval_ms": 10000
  },
  "ssh_tunnel": {
    "enabled": true,
    "server": "tunnel.example.com",
    "port": 22,
    "user": "tunnel",
    "remote_port": 50123,
    "keepalive_interval": 30
  },
  "dashboard_tunnel": {
    "enabled": true,
    "server": "tunnel.example.com",
    "port": 22,
    "user": "tunnel",
    "remote_port": 60123,
    "keepalive_interval": 30
  },
  "dashboard": {
    "enabled": true
  },
  "net": {
    "ntp": {
      "servers": ["pool.ntp.org", "time.google.com"]
    }
  },
  "debug": false
}

Configuration Priority:

Cloud mode: Server settings override local for BLE, WiFi, NTP
LAN mode: Local settings have priority
Always from server: SSH tunnel, Dashboard tunnel, Dashboard enable/disable
Always local: eth0 network settings

Error Response: 401 Unauthorized

Invalid or missing token

POST /api/v1/ble

Uploads batch of BLE events (gzip compressed).

Request:

POST /api/v1/ble HTTP/1.1
Host: server:8000
Authorization: Bearer gRMRUKnqO9KXikBzoKhs0aE3uDYUvTxHYuU4/uatyrc=
Content-Type: application/json
Content-Encoding: gzip

<gzipped JSON payload>

Uncompressed Payload:

{
  "device_id": "38:54:39:4b:1b:ad",
  "events": [
    {
      "type": "ibeacon",
      "mac": "AA:BB:CC:DD:EE:FF",
      "rssi": -65,
      "ts_ms": 1703001234567,
      "uuid": "f7826da64fa24e988024bc5b71e0893e",
      "major": 100,
      "minor": 1,
      "tx_power": -59
    },
    {
      "type": "my-beacon_acc",
      "mac": "11:22:33:44:55:66",
      "rssi": -72,
      "ts_ms": 1703001234568,
      "x": 123,
      "y": -45,
      "z": 678,
      "bat": 95,
      "temp": 25.5,
      "ff": false
    }
  ]
}

Event Types and Fields:

iBeacon:

type: "ibeacon"
mac: Device MAC address
rssi: Signal strength (dBm)
ts_ms: Timestamp (milliseconds since epoch)
uuid: iBeacon UUID (32 hex chars, no dashes)
major: Major value (0-65535)
minor: Minor value (0-65535)
tx_power: Calibrated TX power

my-beacon_acc:

type: "my-beacon_acc"
mac: Device MAC address
rssi: Signal strength (dBm)
ts_ms: Timestamp
x, y, z: Accelerometer values
bat: Battery level (0-100)
temp: Temperature (°C)
ff: Free fall detected (boolean)

rt_mybeacon (Relay):

type: "rt_mybeacon"
mac: Relay device MAC
rssi: Signal strength at relay
ts_ms: Timestamp
relay_mac: Original beacon MAC
relay_rssi: Original RSSI

Response: 200 OK

Error Response: 401 Unauthorized / 500 Internal Server Error

Notes:

Device retries up to 3 times on failure
Failed batches are spooled to /var/spool/mybeacon/ble/ (max 100MB)
Batching interval: 2.5 seconds (default)
Average batch size: 5-12 events

POST /api/v1/wifi

Uploads batch of WiFi probe requests (gzip compressed).

Request:

POST /api/v1/wifi HTTP/1.1
Host: server:8000
Authorization: Bearer gRMRUKnqO9KXikBzoKhs0aE3uDYUvTxHYuU4/uatyrc=
Content-Type: application/json
Content-Encoding: gzip

<gzipped JSON payload>

Uncompressed Payload:

{
  "device_id": "38:54:39:4b:1b:ad",
  "events": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "rssi": -55,
      "ts_ms": 1703001234567,
      "ssid": "MyNetwork",
      "freq": 2437,
      "channel": 6
    }
  ]
}

Event Fields:

mac: Device MAC address
rssi: Signal strength (dBm)
ts_ms: Timestamp (milliseconds since epoch)
ssid: Network SSID (may be empty for probe requests)
freq: Frequency (MHz)
channel: WiFi channel

Response: 200 OK

Notes:

Batching interval: 10 seconds (default)
Average batch size: 10-200 events
Spool directory: /var/spool/mybeacon/wifi/

POST /api/v1/wifi-credentials

Updates WiFi client credentials (Cloud mode only).

Request:

POST /api/v1/wifi-credentials HTTP/1.1
Host: server:8000
Authorization: Bearer gRMRUKnqO9KXikBzoKhs0aE3uDYUvTxHYuU4/uatyrc=
Content-Type: application/json

{
  "ssid": "NewNetwork",
  "psk": "password123"
}

Response: 200 OK

{
  "success": true
}

Purpose: When user changes WiFi credentials via dashboard in Cloud mode, device:

Saves credentials locally
Connects to new network
Sends credentials to server for centralized management

Server can use this for:

Displaying current WiFi config in user dashboard
Remote WiFi management via config endpoint
Syncing settings across devices

Error Codes

Device API:

200 OK: Success
401 Unauthorized: Invalid password
405 Method Not Allowed: Wrong HTTP method
500 Internal Server Error: Server error

Server API:

200 OK: Success
201 Created: Resource created
400 Bad Request: Invalid request
401 Unauthorized: Invalid/missing token
500 Internal Server Error: Server error

Data Flow

Device Startup

Device boots, reads /opt/mybeacon/etc/device.json
If device_token missing → POST /api/v1/registration
Save token and password to device.json
Start polling GET /api/v1/config every 30s (Cloud mode)

Event Upload

BLE/WiFi scanner publishes to ZMQ
Daemon batches events (2.5s for BLE, 10s for WiFi)
Gzip compress → POST /api/v1/ble or /api/v1/wifi
On failure → spool to disk, retry later

Configuration Management

Cloud mode: Server config overrides local (via /api/v1/config)
LAN mode: Local config used, no polling
User changes via dashboard → POST /api/settings → apply locally
In Cloud mode, WiFi credentials also sent to server

Authentication

Server API:

Uses Bearer token authentication
Token received during registration
Include in header: Authorization: Bearer <token>

Device API:

Most endpoints are open (read-only)
Write endpoints require device_password
Password is 8-digit number generated during registration

Network Modes

Cloud Mode (Default)

Config polled from server every 30s
BLE/WiFi scanner settings from server
Local changes to scanners ignored
WiFi client credentials sync with server
SSH/Dashboard tunnels controlled by server

LAN Mode

No config polling
All settings local
Manual configuration via dashboard
No server dependency (except registration)

Switching Modes: Via dashboard → Settings → Mode → Apply

Force Cloud: Server can set force_cloud: true in config to prevent mode switching (for support).

Files

Configuration:

/opt/mybeacon/etc/config.json - Local config
/opt/mybeacon/etc/device.json - Device state (token, password)
/opt/mybeacon/etc/tunnel_key - SSH private key

Logs:

/var/log/mybeacon.log - Daemon logs (tmpfs)
Kernel logs via dmesg

Spool:

/var/spool/mybeacon/ble/ - Failed BLE batches
/var/spool/mybeacon/wifi/ - Failed WiFi batches
Max total: 100MB

Examples

Registering a New Device

curl -X POST http://server:8000/api/v1/registration \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "38:54:39:4b:1b:ad",
    "eth_ip": "192.168.5.244"
  }'

Fetching Device Status

curl http://192.168.5.244/api/status | jq

Changing WiFi Settings

curl -X POST http://192.168.5.244/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "password": "82680499",
    "settings": {
      "wifi_client_enabled": true,
      "wifi_ssid": "MyNetwork",
      "wifi_psk": "password123"
    }
  }'

Uploading BLE Events (with gzip)

# Prepare JSON
echo '{
  "device_id": "38:54:39:4b:1b:ad",
  "events": [{"type":"ibeacon","mac":"AA:BB:CC:DD:EE:FF","rssi":-65,"ts_ms":1703001234567}]
}' | gzip > /tmp/events.json.gz

# Upload
curl -X POST http://server:8000/api/v1/ble \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @/tmp/events.json.gz

WebSocket Example (JavaScript)

const ws = new WebSocket('ws://192.168.5.244/api/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'ble') {
    console.log('BLE event:', msg.event);
  } else if (msg.type === 'wifi') {
    console.log('WiFi event:', msg.event);
  } else if (msg.type === 'log') {
    console.log('Log:', msg.message);
  }
};

ws.onopen = () => console.log('Connected');
ws.onerror = (err) => console.error('Error:', err);

Security Notes

Device Password: 8-digit numeric PIN, generated during registration
Device Token: Base64-encoded random token, store securely
HTTPS: Not implemented on device (use VPN/tunnel for remote access)
SSH Tunnel: Ed25519 key-based authentication
CORS: Enabled on device API (allow all origins)

Troubleshooting

Device not uploading events

Check GET /api/status → server_ok: true
Check logs: GET /api/logs
Verify network: GET /api/status → network
Check spool directory: ls -lh /var/spool/mybeacon/

WiFi scanner not working

Check if WiFi client active: GET /api/status → network.wlan0_ip
WiFi client and scanner can't run simultaneously
Disable client or use AP mode
Check AIC8800 chip conflicts in logs

Configuration not applying

Cloud mode: Wait for next poll (30s) or restart daemon
LAN mode: Check password and permissions
Verify mode: GET /api/config → mode

Appendix: BLE Event Formats

iBeacon Format

Company ID: 0x004C (Apple)
Type: 0x02 0x15
UUID: 16 bytes
Major: 2 bytes (big-endian)
Minor: 2 bytes (big-endian)
TX Power: 1 byte (signed)

my-beacon_acc Format

Company ID: 0x0059 (Nordic)
Prefix: "acc" (3 bytes)
X: 2 bytes (signed)
Y: 2 bytes (signed)
Z: 2 bytes (signed)
Battery: 1 byte (0-100)
Temp: 1 byte (signed, °C)
Free Fall: 1 bit

rt_mybeacon Format

Company ID: 0xFFFF (Custom)
Prefix: "rt" (2 bytes)
Original MAC: 6 bytes
Original RSSI: 1 byte (signed)
Original payload: variable

Version

API Version: 1.0 Last Updated: 2025-12-28 Device Firmware: Alpine Linux + MyBeacon Native Compatible with: Backend API v1

Support

For issues or questions:

Check device logs: GET /api/logs
Check kernel logs: GET /api/kernel-logs
SSH to device: ssh root@<device-ip> (password: 1)
Review daemon status: /etc/init.d/S98mybeacon status

API_DOCUMENTATION.md 20 KB History Raw

MyBeacon API Documentation

Overview

Table of Contents

Device API

GET /api/status

GET /api/metrics

GET /api/config

GET /api/ble/recent

GET /api/wifi/recent

GET /api/logs

GET /api/kernel-logs

POST /api/unlock

POST /api/settings

WebSocket /api/ws

Server API

POST /api/v1/registration

GET /api/v1/config

POST /api/v1/ble

POST /api/v1/wifi

POST /api/v1/wifi-credentials

Error Codes

Data Flow

Device Startup

Event Upload

Configuration Management

Authentication

Network Modes

Cloud Mode (Default)

LAN Mode

Files

Examples

Registering a New Device

Fetching Device Status

Changing WiFi Settings

Uploading BLE Events (with gzip)

WebSocket Example (JavaScript)

Security Notes

Troubleshooting

Device not uploading events

WiFi scanner not working

Configuration not applying

Appendix: BLE Event Formats

iBeacon Format

my-beacon_acc Format

rt_mybeacon Format

Version

Support

API_DOCUMENTATION.md 20 KB

History Raw