spore-gateway/hack/README.md

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:

./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:

# 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:

   cd hack
   ./mosquitto.sh
   

2. In a new terminal, start the SPORE gateway with MQTT enabled:

   cd /path/to/spore-gateway
   ./spore-gateway -mqtt tcp://localhost:1883
   

3. In another terminal, run the test script:

   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:

{
  "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:

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:

# 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:

-p 1884:1883  # Maps host port 1884 to container port 1883

Then update your gateway command:

./spore-gateway -mqtt tcp://localhost:1884