Sensors API

Read status and sensor data from Wala Works devices.

Overview

All devices expose sensor endpoints for monitoring:

Device status and health
Position and state (MotorWala)
Relay states (RelayWala)
Environmental data (optional sensors)
System metrics

Device Status

Get Status

Retrieve current device status and configuration.

GET /api/status

MotorWala Response:

{
  "device": "MotorWala",
  "version": "1.2.0",
  "name": "Living Room Blinds",
  "uptime": 86400,
  "position": 50,
  "state": "stopped",
  "target_position": 50,
  "wifi": {
    "ssid": "HomeNetwork",
    "rssi": -45,
    "ip": "192.168.1.100",
    "mac": "AA:BB:CC:DD:EE:FF"
  },
  "mqtt": {
    "connected": true,
    "broker": "192.168.1.50:1883"
  },
  "calibration": {
    "status": "calibrated",
    "full_travel_time": 30000
  },
  "system": {
    "heap_free": 45000,
    "cpu_freq": 240,
    "temperature": 45.2
  }
}

RelayWala Response:

{
  "device": "RelayWala",
  "version": "1.1.0",
  "name": "Living Room Controller",
  "uptime": 172800,
  "relays": [
    {
      "channel": 1,
      "name": "Main Light",
      "state": "on",
      "mode": "normal",
      "uptime": 3600
    },
    {
      "channel": 2,
      "name": "Fan",
      "state": "off",
      "mode": "normal",
      "uptime": 0
    },
    {
      "channel": 3,
      "name": "Garage Door",
      "state": "off",
      "mode": "momentary",
      "uptime": 0
    },
    {
      "channel": 4,
      "name": "Spare",
      "state": "off",
      "mode": "normal",
      "uptime": 0
    }
  ],
  "wifi": {
    "ssid": "HomeNetwork",
    "rssi": -52,
    "ip": "192.168.1.101",
    "mac": "FF:EE:DD:CC:BB:AA"
  },
  "mqtt": {
    "connected": true,
    "broker": "192.168.1.50:1883"
  },
  "system": {
    "heap_free": 48000,
    "cpu_freq": 240,
    "temperature": 42.8
  }
}

Status Fields:

| Field | Type | Description | |-------|------|-------------| | device | string | Device type | | version | string | Firmware version | | name | string | User-defined name | | uptime | integer | Seconds since boot | | wifi.ssid | string | Connected network | | wifi.rssi | integer | Signal strength (dBm) | | wifi.ip | string | Device IP address | | mqtt.connected | boolean | MQTT connection status | | system.heap_free | integer | Free memory (bytes) | | system.temperature | float | CPU temperature (°C) |

Health Check

Lightweight endpoint for uptime monitoring:

GET /api/health

Response:

{
  "status": "ok",
  "uptime": 86400,
  "timestamp": "2025-11-05T14:30:00Z"
}

Status values:

ok - Device operating normally
warning - Minor issues (low memory, weak WiFi)
error - Critical issues (disconnected, stalled)

MotorWala Sensors

Position Sensor

Get current motor position:

GET /api/motor/position

Response:

{
  "position": 75,
  "target": 75,
  "state": "stopped",
  "calibrated": true,
  "last_updated": "2025-11-05T14:30:00Z"
}

Position values:

0 - Fully closed
100 - Fully open
1-99 - Partially open

State values:

stopped - Motor not moving
opening - Motor moving to open
closing - Motor moving to close
unknown - Not calibrated

Movement History

Get recent movement events:

GET /api/motor/history?limit=10

Response:

{
  "events": [
    {
      "timestamp": "2025-11-05T14:30:00Z",
      "action": "set_position",
      "from": 50,
      "to": 75,
      "duration": 7500,
      "source": "mqtt"
    },
    {
      "timestamp": "2025-11-05T12:00:00Z",
      "action": "close",
      "from": 100,
      "to": 0,
      "duration": 30000,
      "source": "automation"
    }
  ]
}

Calibration Status

Check calibration details:

GET /api/motor/calibration

Response:

{
  "status": "calibrated",
  "full_travel_time": 30000,
  "calibrated_at": "2025-01-15T10:00:00Z",
  "cycles": 247,
  "last_calibration": "2025-01-15T10:00:00Z",
  "next_calibration": "2025-02-14T10:00:00Z"
}

Status values:

not_calibrated - Needs calibration
calibrated - Ready to use
calibrating - Calibration in progress
failed - Calibration error

Motor Metrics

Get motor performance data:

GET /api/motor/metrics

Response:

{
  "total_cycles": 247,
  "total_distance": 24700,
  "average_speed": 3.33,
  "current_draw": {
    "idle": 0.05,
    "moving": 1.2,
    "peak": 2.8
  },
  "stall_events": 2,
  "last_stall": "2025-03-10T15:45:00Z"
}

RelayWala Sensors

Relay Status

Get status of specific relay:

GET /api/relay/{channel}

Response:

{
  "channel": 1,
  "name": "Main Light",
  "state": "on",
  "mode": "normal",
  "uptime": 3600,
  "switch_count": 1247,
  "last_switched": "2025-11-05T13:30:00Z"
}

All Relays Status

Get status of all relays:

GET /api/relays

Response:

{
  "relays": [
    {
      "channel": 1,
      "name": "Main Light",
      "state": "on",
      "uptime": 3600
    },
    {
      "channel": 2,
      "name": "Fan",
      "state": "off",
      "uptime": 0
    },
    {
      "channel": 3,
      "name": "Garage Door",
      "state": "off",
      "uptime": 0
    },
    {
      "channel": 4,
      "name": "Spare",
      "state": "off",
      "uptime": 0
    }
  ]
}

Relay History

Get switching history:

GET /api/relay/{channel}/history?limit=20

Response:

{
  "channel": 1,
  "events": [
    {
      "timestamp": "2025-11-05T13:30:00Z",
      "action": "on",
      "source": "automation",
      "duration": 3600
    },
    {
      "timestamp": "2025-11-05T09:30:00Z",
      "action": "off",
      "source": "mqtt",
      "duration": 14400
    }
  ]
}

Current Monitoring

If current sensing is enabled:

GET /api/relay/{channel}/current

Response:

{
  "channel": 1,
  "current": 0.45,
  "voltage": 230,
  "power": 103.5,
  "energy_today": 1.2,
  "sampling_rate": 1000
}

Units:

Current: Amperes (A)
Voltage: Volts (V)
Power: Watts (W)
Energy: Kilowatt-hours (kWh)

Relay Metrics

Get lifetime statistics:

GET /api/relay/{channel}/metrics

Response:

{
  "channel": 1,
  "total_switches": 1247,
  "total_on_time": 892800,
  "average_on_duration": 3600,
  "energy_lifetime": 245.7,
  "last_maintenance": "2025-01-01T00:00:00Z",
  "estimated_life_remaining": 98.5
}

System Sensors

WiFi Signal

Monitor WiFi connection quality:

GET /api/system/wifi

Response:

{
  "ssid": "HomeNetwork",
  "bssid": "AA:BB:CC:DD:EE:FF",
  "rssi": -45,
  "quality": "excellent",
  "channel": 6,
  "ip": "192.168.1.100",
  "mac": "FF:EE:DD:CC:BB:AA",
  "gateway": "192.168.1.1",
  "dns": "8.8.8.8"
}

Signal quality:

excellent: -30 to -50 dBm
good: -50 to -60 dBm
fair: -60 to -70 dBm
poor: -70 to -80 dBm
unusable: Below -80 dBm

System Metrics

Get system performance data:

GET /api/system/metrics

Response:

{
  "cpu": {
    "frequency": 240,
    "usage": 15.5,
    "temperature": 45.2
  },
  "memory": {
    "total": 320000,
    "free": 45000,
    "used": 275000,
    "usage_percent": 85.9
  },
  "storage": {
    "total": 4000000,
    "free": 3200000,
    "used": 800000,
    "usage_percent": 20.0
  },
  "network": {
    "bytes_sent": 1024000,
    "bytes_received": 2048000,
    "packets_sent": 10000,
    "packets_received": 15000
  }
}

System Logs

Retrieve recent log entries:

GET /api/system/logs?level=info&limit=100

Query parameters:

level: debug, info, warning, error
limit: Number of entries (default: 100, max: 1000)
since: ISO 8601 timestamp

Response:

{
  "logs": [
    {
      "timestamp": "2025-11-05T14:30:00Z",
      "level": "info",
      "component": "motor",
      "message": "Position reached: 75"
    },
    {
      "timestamp": "2025-11-05T14:29:55Z",
      "level": "debug",
      "component": "mqtt",
      "message": "Published: motorwala/living-room/position = 75"
    }
  ]
}

MQTT Sensor Topics

MotorWala Topics

State:

motorwala/[device-id]/state
Payload: "opening" | "closing" | "stopped"

Position:

motorwala/[device-id]/position
Payload: 0-100 (integer)

Availability:

motorwala/[device-id]/availability
Payload: "online" | "offline"

WiFi RSSI:

motorwala/[device-id]/wifi/rssi
Payload: -30 to -90 (integer)

RelayWala Topics

Relay State:

relaywala/[device-id]/relay/[1-4]/state
Payload: "ON" | "OFF"

All Relays:

relaywala/[device-id]/state
Payload: {"1":"ON","2":"OFF","3":"OFF","4":"OFF"}

Availability:

relaywala/[device-id]/availability
Payload: "online" | "offline"

Current (if available):

relaywala/[device-id]/relay/[1-4]/current
Payload: 0.00-10.00 (float)

WebSocket Streaming

Real-time sensor data via WebSocket:

Connect

const ws = new WebSocket('ws://192.168.1.100/ws');

ws.onopen = () => {
  console.log('Connected');

  // Subscribe to updates
  ws.send(JSON.stringify({
    action: 'subscribe',
    topics: ['position', 'state', 'wifi']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update:', data);
};

Message Format

Position update:

{
  "type": "position",
  "value": 75,
  "timestamp": "2025-11-05T14:30:00Z"
}

State update:

{
  "type": "state",
  "value": "stopped",
  "timestamp": "2025-11-05T14:30:00Z"
}

Relay update:

{
  "type": "relay",
  "channel": 1,
  "state": "on",
  "timestamp": "2025-11-05T14:30:00Z"
}

Polling vs. Streaming

REST API Polling

Advantages:

Simple to implement
Works with any HTTP client
No persistent connection

Disadvantages:

Higher latency
More network overhead
Polling interval trade-off

Example:

import time
import requests

while True:
    response = requests.get('http://192.168.1.100/api/status')
    print(response.json()['position'])
    time.sleep(1)  # Poll every second

MQTT Streaming

Advantages:

Real-time updates
Low bandwidth
Publish-subscribe pattern

Disadvantages:

Requires MQTT broker
More complex setup
Persistent connection

Example:

import paho.mqtt.client as mqtt

def on_message(client, userdata, msg):
    print(f"Position: {msg.payload.decode()}")

client = mqtt.Client()
client.on_message = on_message
client.connect('192.168.1.50', 1883)
client.subscribe('motorwala/living-room/position')
client.loop_forever()

WebSocket Streaming

Advantages:

Real-time updates
No broker required
Bidirectional

Disadvantages:

Single client typically
More complex than REST
Persistent connection

Integration Examples

Home Assistant Sensors

MotorWala position sensor:

sensor:
  - platform: mqtt
    name: "Blinds Position"
    state_topic: "motorwala/living-room/position"
    unit_of_measurement: "%"
    icon: mdi:window-shutter

  - platform: mqtt
    name: "Blinds WiFi Signal"
    state_topic: "motorwala/living-room/wifi/rssi"
    unit_of_measurement: "dBm"
    device_class: signal_strength

RelayWala power monitoring:

sensor:
  - platform: mqtt
    name: "Light Power"
    state_topic: "relaywala/living-room/relay/1/power"
    unit_of_measurement: "W"
    device_class: power

Grafana Dashboard

Monitor metrics over time:

InfluxDB + Telegraf:

# telegraf.conf
[[inputs.mqtt_consumer]]
  servers = ["tcp://192.168.1.50:1883"]
  topics = [
    "motorwala/+/position",
    "motorwala/+/wifi/rssi",
    "relaywala/+/relay/+/power"
  ]
  data_format = "value"
  data_type = "float"

Node-RED Dashboard

Create real-time dashboard:

[MQTT In] → [Gauge: Position] → [Chart: History]
[MQTT In] → [LED: State] → [Chart: Activity]

Troubleshooting

No sensor data:

Verify device is online (ping)
Check API endpoint URL
Ensure authentication token (if enabled)
Review device logs

Stale data:

Check MQTT connection
Verify publish intervals
Review network quality
Check broker logs

Inaccurate position:

Run calibration
Check for mechanical slippage
Verify motor connections
Review calibration logs

WebSocket disconnects:

Check network stability
Verify firewall rules
Monitor connection logs
Implement reconnection logic

Next Steps

Controllers API - Control endpoints
Automations API - Automation rules
First Automation - Create automation

Monitoring questions? Check FAQ or contact support

Sensors API

Overview

Device Status

Get Status

Health Check

MotorWala Sensors

Position Sensor

Movement History

Calibration Status

Motor Metrics

RelayWala Sensors

Relay Status

All Relays Status

Relay History

Current Monitoring

Relay Metrics

System Sensors

WiFi Signal

System Metrics

System Logs

MQTT Sensor Topics

MotorWala Topics

RelayWala Topics

WebSocket Streaming

Connect

Message Format

Polling vs. Streaming

REST API Polling

MQTT Streaming

WebSocket Streaming

Integration Examples

Home Assistant Sensors

Grafana Dashboard

Node-RED Dashboard

Troubleshooting

Next Steps

On This Page