Protocols & API

Local HTTP API

Direct device access over your local network

📊 Dashboard Data

Retrieve current sensor readings in binary format for efficient transfer.

GET /dashboard-bin

# Response: Binary payload
# [version:1][count:1][sensors...]
# Each sensor: [type_id:1][name_len:1][name][flags:1][order:1]
#              [packed_len:1][packed_data][csv_len:2][csv_fields]

📋 Sensor List

Get list of configured sensors with their types and settings.

GET /dashboard-list

# Response: CSV format
name,s,temperature
type,s,TemperatureSensor
interval,i,10
enabled,b,1

📖 Historical Readings

Retrieve buffered readings for sparklines and history charts.

GET /readings-buffer

# Response: Binary payload with historical entries
# [version:1][sensor_count:1][entry_count:2][entries...]
# Each entry: [name_len:1][name][type_id:1][timestamp:4][data_len:1][data]

⚙️ REPL Commands

Execute commands on the device via HTTP POST.

POST /repl
Content-Type: application/x-www-form-urlencoded

command=status&trace_id=abc123

# Response: CSV format with command result
status,s,ok
output,s,Device running - uptime 3h 45m

📝 Log Stream

Retrieve device log entries for debugging.

GET /log?limit=100

# Response: Binary log entries
# [version:1][count:2][entries...]
# Each: [seq:4][timestamp:4][level:1][msg_len:2][msg][trace_len:1][trace]

❓ Help Tab

The built-in Help tab in the web interface provides complete API documentation, available commands, and sensor configuration details—accessible directly from your device at any time.

# Access the Help tab from your device's web UI:
http://<device-ip>/help

# Includes:
# - All available REPL commands
# - Sensor configuration options
# - Service settings reference
# - API endpoint documentation

Cloud API (Twin)

Azure-hosted REST API for remote device management

🔐 Authentication

All cloud endpoints require device credentials.

# Query parameter authentication (Web UI)
GET /api/readings?device_id=T-XXXX&device_key=YOUR_KEY

# Header authentication (Device)
POST /api/reading
X-Device-ID: T-XXXXXXXXXXXX
X-Device-Key: your_device_key_here

📤 Push Readings

Device pushes sensor readings to cloud storage.

POST /api/reading
Content-Type: application/json
X-Device-ID: T-XXXXXXXXXXXX
X-Device-Key: your_key

{
  "readings": [
    {"sensor": "temperature", "value": 72.4, "unit": "F"},
    {"sensor": "humidity", "value": 45.2, "unit": "%"}
  ]
}

📥 Get Readings

Retrieve stored readings with filtering and aggregation.

GET /api/readings?device_id=XXX&device_key=XXX&limit=100&sensor=temperature&agg=hour

# Query parameters:
#   sensor  - Filter by sensor name
#   start   - Start timestamp (ISO format)
#   end     - End timestamp (ISO format)
#   limit   - Max readings (default 100, max 1000)
#   agg     - Aggregation: none, hour, day

# Response:
{
  "readings": [
    {"sensor": "temperature", "value": 72.4, "timestamp": "2025-01-15T14:30:00Z"}
  ]
}

📨 Command Queue

Send commands to device (queued until device polls).

# Web UI queues command
POST /api/command
{
  "device_id": "T-XXXX",
  "device_key": "XXX",
  "command": "sensor read temperature"
}

# Device polls for commands
GET /api/commands
X-Device-ID: T-XXXX
X-Device-Key: XXX

# Device acknowledges with result
POST /api/ack
{"command_id": "xxx", "status": "completed", "output": "72.4°F"}

💓 Heartbeat

Device sends periodic status updates.

POST /api/heartbeat
X-Device-ID: T-XXXX
X-Device-Key: XXX

{
  "uptime": 3600,
  "memory_free": 180000,
  "wifi_rssi": -45,
  "firmware": "1.0.42"
}

📋 Device Logs

Retrieve logs stored in cloud.

GET /api/log?device_id=XXX&device_key=XXX&limit=100

{
  "logs": [
    {
      "timestamp": "2025-01-15T14:30:00Z",
      "level": 1,
      "message": "Sensor read complete"
    }
  ]
}

Data Formats

Sensor Type IDs

1Temperature

2Memory

3Counter

4Uptime

5Device

6Network

Log Levels

-1 / 255SYSTEM

0ERROR

1INFO

2DEBUG

Binary Pack Formats

b / Bint8 / uint8

h / Hint16 / uint16

i / Iint32 / uint32

CSV Value Types

sstring

iinteger

ffloat

bboolean (0/1)

nnull

Integration Examples

🐍 Python - Read Temperature

import requests

# Local device
response = requests.get("http://tick-abc123.local/dashboard-list")
print(response.text)

# Cloud API
response = requests.get(
    "https://your-api.azurewebsites.net/api/readings",
    params={
        "device_id": "T-XXXX",
        "device_key": "your_key",
        "sensor": "temperature",
        "limit": 10
    }
)
data = response.json()
for r in data["readings"]:
    print(f"{r['timestamp']}: {r['value']}°F")

📜 JavaScript - Fetch Dashboard

// Fetch from local device
fetch('http://192.168.1.100/dashboard-bin')
  .then(r => r.arrayBuffer())
  .then(buffer => {
    const view = new DataView(buffer);
    const version = view.getUint8(0);
    const count = view.getUint8(1);
    console.log(`Version: ${version}, Sensors: ${count}`);
  });

// Fetch from cloud
const params = new URLSearchParams({
  device_id: 'T-XXXX',
  device_key: 'your_key'
});
fetch(`https://api.example.com/api/readings?${params}`)
  .then(r => r.json())
  .then(data => console.log(data.readings));

🔧 cURL - Send Command

# Send command to device via cloud
curl -X POST https://your-api.azurewebsites.net/api/command \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "T-XXXX",
    "device_key": "your_key",
    "command": "sensor read temperature"
  }'

# Check command history
curl "https://your-api.azurewebsites.net/api/history?device_id=T-XXXX&device_key=your_key"