feat: MQTT integration

2025-10-26 18:37:07 +01:00
parent 55c3aebb3f
commit 42ed391120
13 changed files with 998 additions and 3 deletions
--- a/hack/README.md
+++ b/hack/README.md
@@ -0,0 +1,130 @@
+# Hack Directory
+
+This directory contains utility scripts for testing and development of the SPORE Gateway.
+
+## Scripts
+
+### mosquitto.sh
+Starts a local Mosquitto MQTT broker using Docker.
+
+**Usage:**
+```bash
+./mosquitto.sh
+```
+
+This will:
+- Start a Mosquitto broker on port 1883
+- Use the configuration from `mosquitto.conf`
+- Allow anonymous connections (no authentication required)
+
+### mqtt-test.sh
+Sends various test events to the local MQTT broker to test the gateway's MQTT integration.
+
+**Usage:**
+```bash
+# Make sure the broker is running first
+./mosquitto.sh  # In terminal 1
+
+# In another terminal, run the tests
+./mqtt-test.sh
+```
+
+This script will send 16 different test messages covering:
+
+## Test Message Coverage
+
+The full `mqtt-test.sh` script will send 16 different test messages covering:
+- Simple text messages
+- JSON sensor data (temperature, humidity)
+- Device status updates
+- System events and alerts
+- Configuration updates
+- Metrics
+- Cluster/node discovery events
+- Firmware updates
+- Task status
+- Error logs
+- Light control (SPORE nodes)
+- Binary data
+- Edge cases (empty messages, large payloads)
+
+## Testing MQTT Integration
+
+### Complete Test Workflow
+
+1. **Start the MQTT broker:**
+   ```bash
+   cd hack
+   ./mosquitto.sh
+   ```
+
+2. **In a new terminal, start the SPORE gateway with MQTT enabled:**
+   ```bash
+   cd /path/to/spore-gateway
+   ./spore-gateway -mqtt tcp://localhost:1883
+   ```
+
+3. **In another terminal, run the test script:**
+   ```bash
+   cd hack
+   ./mqtt-test.sh
+   ```
+
+4. **Monitor the WebSocket connection** to see the events being forwarded.
+   You can use a WebSocket client or the SPORE UI to connect to `ws://localhost:3001/ws`.
+
+### Expected Output
+
+All MQTT messages will be forwarded through the WebSocket with this format:
+
+```json
+{
+  "topic": "sensor/temperature/living-room",
+  "data": "{\"temperature\": 23.5, \"unit\": \"celsius\", \"timestamp\": \"2024-01-15T10:30:00Z\"}",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+## Customization
+
+### Using a Different MQTT Broker
+
+You can change the broker URL using the `MQTT_BROKER` environment variable:
+
+```bash
+MQTT_BROKER=tcp://broker.example.com:1883 ./mqtt-test.sh
+```
+
+### Adding Your Own Test Messages
+
+Edit `mqtt-test.sh` and add your custom test case:
+
+```bash
+# Test N: Your custom test
+echo -e "${YELLOW}=== Test N: Your Description ===${NC}"
+publish_json "your/topic" '{"your": "data"}'
+```
+
+## Troubleshooting
+
+### Broker Not Starting
+- Make sure Docker is running
+- Check if port 1883 is already in use
+- Verify the Mosquitto image is available: `docker pull eclipse-mosquitto:latest`
+
+### Messages Not Being Received
+- Verify the gateway is running with `-mqtt tcp://localhost:1883`
+- Check the gateway logs for connection errors
+- Ensure the WebSocket client is connected to `ws://localhost:3001/ws`
+
+### Port Conflicts
+If port 1883 is in use, modify `mosquitto.sh` to use a different port:
+```bash
+-p 1884:1883  # Maps host port 1884 to container port 1883
+```
+
+Then update your gateway command:
+```bash
+./spore-gateway -mqtt tcp://localhost:1884
+```
+