docs: clean up docs structure

2026-02-08 00:24:24 +01:00
parent d9db2596ca
commit afd95908f1
5 changed files with 1050 additions and 26 deletions
--- a/docs/API.md
+++ b/docs/API.md
--- a/docs/DEVICE_DISCOVERY_SPEC.md
+++ b/docs/DEVICE_DISCOVERY_SPEC.md
@@ -0,0 +1,241 @@
+# Device Discovery Specification
+
+This specification defines the format and protocol that microcontroller-based IoT devices must follow to register themselves with the Lambda IoT Core system.
+
+## Overview
+
+At boot, each device must submit a single JSON message containing:
+- Device information (name, description, location)
+- List of sensors
+- List of actors (actuators)
+
+All UUIDs are **deterministically generated** based on the device's MAC address to ensure consistency across reboots.
+
+## UUID Generation
+
+### Device UUID
+Generate a UUID v5 using:
+- **Namespace**: `6ba7b810-9dad-11d1-80b4-00c04fd430c8` (DNS namespace)
+- **Name**: Device MAC address in lowercase, no separators (e.g., `aabbccddeeff`)
+
+### Sensor UUID
+Generate a UUID v5 using:
+- **Namespace**: Device UUID
+- **Name**: `sensor-{N}` where N is the 0-based sensor index
+
+### Actor UUID
+Generate a UUID v5 using:
+- **Namespace**: Device UUID
+- **Name**: `actor-{N}` where N is the 0-based actor index
+
+## Discovery Message Format
+
+### MQTT Topic
+Devices must publish to: `{MQTT_TOPIC}/discovery`
+
+Where `{MQTT_TOPIC}` is the configured MQTT topic (e.g., `lambdaiot`, resulting in `lambdaiot/discovery`)
+
+### Message Structure
+
+```json
+{
+  "mac_address": "aa:bb:cc:dd:ee:ff",
+  "device": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "name": "Living Room Sensor",
+    "description": "Multi-sensor device for home monitoring",
+    "location": "Living Room",
+    "status_id": 1
+  },
+  "sensors": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440001",
+      "name": "Temperature",
+      "type": "DHT22",
+      "data_type_id": 2
+    },
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440002",
+      "name": "Humidity",
+      "type": "DHT22",
+      "data_type_id": 2
+    },
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440003",
+      "name": "Motion",
+      "type": "PIR",
+      "data_type_id": 1
+    }
+  ],
+  "actors": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440004",
+      "name": "LED",
+      "type": "RGB_LED",
+      "data_type_id": 1
+    },
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440005",
+      "name": "Fan",
+      "type": "PWM_FAN",
+      "data_type_id": 2
+    }
+  ]
+}
+```
+
+## Field Definitions
+
+### Device Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | UUID string | Yes | Deterministic UUID v5 based on MAC |
+| `name` | String | Yes | Human-readable device name |
+| `description` | String | No | Device description |
+| `location` | String | No | Physical location (e.g., "Living Room") |
+| `status_id` | Integer | Yes | Status code: 1=ok, 2=pending, 3=lost, 4=disabled |
+
+### Sensor/Actor Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | UUID string | Yes | Deterministic UUID v5 (device UUID + "sensor-N" or "actor-N") |
+| `name` | String | Yes | Human-readable sensor/actor name |
+| `type` | String | Yes | Hardware type (e.g., "DHT22", "PIR", "RGB_LED") |
+| `data_type_id` | Integer | Yes | Data type: 1=bool, 2=float |
+
+### Root Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `mac_address` | String | Yes | Device MAC address (lowercase with colons) |
+| `device` | Object | Yes | Device information |
+| `sensors` | Array | Yes | Array of sensor objects (can be empty) |
+| `actors` | Array | Yes | Array of actor objects (can be empty) |
+
+## Behavior
+
+### On First Boot
+1. Device generates deterministic UUIDs based on its MAC address
+2. Device publishes discovery message to `{MQTT_TOPIC}/discovery`
+3. Backend receives message, creates device record with status_id=1 (ok)
+4. Sensors and actors are created
+
+### On Subsequent Boots
+1. Device uses same deterministic UUIDs (based on MAC)
+2. Device publishes discovery message again
+3. Backend detects existing device by UUID
+4. Device details (name, description, location) are updated
+5. Sensors/actors are synchronized:
+   - New sensors/actors are added
+   - Existing sensors/actors with same ID but different properties are updated
+   - Sensors/actors no longer in the message are deleted
+6. Device status is set to ok (1)
+
+### Conflict Resolution
+- If a device UUID already exists, it is updated rather than creating a duplicate
+- Sensors and actors are matched by UUID, not by position
+- Removing a sensor/actor from the discovery message will delete it from the database
+
+### UUID Collision Handling
+Devices with different MACs will generate different UUIDs. If two devices somehow share the same MAC (misconfiguration), they will overwrite each other's records. This is acceptable as MAC duplication is a network configuration error.
+
+## Data Type Codes
+
+| Code | Type | Description |
+|------|------|-------------|
+| 1 | bool | Boolean value (true/false or 0/1) |
+| 2 | float | Floating-point numeric value |
+
+## Status Codes
+
+| Code | Status | Description |
+|------|--------|-------------|
+| 1 | ok | Device is functioning normally |
+| 2 | pending | Device is initializing |
+| 3 | lost | Device has not checked in recently |
+| 4 | disabled | Device has been administratively disabled |
+
+## Example Device Implementations
+
+### Minimal Device (1 sensor, no actors)
+```json
+{
+  "mac_address": "aa:bb:cc:dd:ee:ff",
+  "device": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "name": "Temperature Sensor",
+    "description": "",
+    "location": "",
+    "status_id": 1
+  },
+  "sensors": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440001",
+      "name": "Temp",
+      "type": "DHT22",
+      "data_type_id": 2
+    }
+  ],
+  "actors": []
+}
+```
+
+### Complex Device (3 sensors, 2 actors)
+```json
+{
+  "mac_address": "11:22:33:44:55:66",
+  "device": {
+    "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
+    "name": "Greenhouse Controller",
+    "description": "Automated greenhouse monitoring and control",
+    "location": "Greenhouse A",
+    "status_id": 1
+  },
+  "sensors": [
+    {
+      "id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
+      "name": "Temperature",
+      "type": "DHT22",
+      "data_type_id": 2
+    },
+    {
+      "id": "6ba7b813-9dad-11d1-80b4-00c04fd430c8",
+      "name": "Humidity",
+      "type": "DHT22",
+      "data_type_id": 2
+    },
+    {
+      "id": "6ba7b814-9dad-11d1-80b4-00c04fd430c8",
+      "name": "Soil Moisture",
+      "type": "Capacitive",
+      "data_type_id": 2
+    }
+  ],
+  "actors": [
+    {
+      "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8",
+      "name": "Irrigation Pump",
+      "type": "Relay",
+      "data_type_id": 1
+    },
+    {
+      "id": "6ba7b816-9dad-11d1-80b4-00c04fd430c8",
+      "name": "Ventilation Fan",
+      "type": "PWM",
+      "data_type_id": 2
+    }
+  ]
+}
+```
+
+## Notes for Device Developers
+
+- Always use the same UUID generation algorithm to ensure consistency
+- Preserve sensor/actor order to maintain deterministic IDs
+- If hardware changes (sensors added/removed), rearrange the array to maintain backward compatibility, or accept that indices will shift
+- Include sufficient description and location information for users to identify devices
+- Set status_id to 1 (ok) on successful boot
+- Consider publishing discovery message periodically (e.g., every 5 minutes) as a heartbeat
+- Use MQTT QoS 1 (at-least-once) for discovery messages