mirror of
https://gitlab.com/wirelos/sprocket-plugin-mqtt.git
synced 2025-12-14 05:46:49 +01:00
115 lines
3.2 KiB
Markdown
115 lines
3.2 KiB
Markdown
# Sprocket MQTT Plugin
|
|
|
|
A message queuing plugin for the Sprocket framework that provides seamless integration between local Sprocket events and MQTT message brokers.
|
|
|
|
## Overview
|
|
|
|
The MQTT plugin enables bidirectional communication between Sprocket devices and MQTT message brokers, allowing for distributed IoT applications and cloud integration.
|
|
|
|
## Features
|
|
|
|
- **Bidirectional Communication**: Upstream (local → MQTT) and downstream (MQTT → local) message routing
|
|
- **Automatic Topic Mapping**: Seamless integration between local Sprocket topics and MQTT topics
|
|
- **Configurable Broker Settings**: Support for authentication and custom topic roots
|
|
- **Task-Based Operation**: Integrated with Sprocket's task scheduler for reliable operation
|
|
- **Connection Management**: Automatic reconnection with configurable retry limits
|
|
- **JSON Configuration**: Easy setup through JSON configuration files
|
|
|
|
## Configuration
|
|
|
|
```cpp
|
|
struct MqttConfig {
|
|
const char *clientName; // Unique client identifier
|
|
const char *brokerHost; // MQTT broker hostname/IP
|
|
int brokerPort; // MQTT broker port (usually 1883)
|
|
const char *topicRoot; // Topic prefix for routing
|
|
const char *user; // MQTT username (optional)
|
|
const char *pass; // MQTT password (optional)
|
|
};
|
|
```
|
|
|
|
## Message Flow
|
|
|
|
### Upstream (Local → MQTT)
|
|
- Local Sprocket events are automatically published to MQTT broker
|
|
- Topics are prefixed with the configured `topicRoot`
|
|
- Enables cloud monitoring and logging of device events
|
|
|
|
### Downstream (MQTT → Local)
|
|
- MQTT messages are received and routed to local Sprocket topics
|
|
- Topic prefixes are stripped for local processing
|
|
- Allows remote control and configuration of devices
|
|
|
|
## Usage Example
|
|
|
|
```cpp
|
|
#include <MqttPlugin.h>
|
|
#include <MqttConfig.h>
|
|
|
|
// Configure MQTT connection
|
|
MqttConfig mqttConfig = {
|
|
.clientName = "myDevice",
|
|
.brokerHost = "mqtt.example.com",
|
|
.brokerPort = 1883,
|
|
.topicRoot = "home/device1",
|
|
.user = "username",
|
|
.pass = "password"
|
|
};
|
|
|
|
// Create plugin with bidirectional binding
|
|
MqttPlugin mqttPlugin(mqttConfig, true, true);
|
|
|
|
// Activate plugin
|
|
mqttPlugin.activate(scheduler);
|
|
```
|
|
|
|
## Configuration File
|
|
|
|
The plugin can also be configured via JSON files:
|
|
|
|
```json
|
|
{
|
|
"mqttClientName": "myDevice",
|
|
"mqttBrokerHost": "mqtt.example.com",
|
|
"mqttBrokerPort": 1883,
|
|
"mqttRootTopic": "home/device1",
|
|
"mqttUser": "username",
|
|
"mqttPass": "password"
|
|
}
|
|
```
|
|
|
|
## Installation
|
|
|
|
1. Include the MQTT plugin in your Sprocket project
|
|
2. Configure MQTT broker settings
|
|
3. Initialize the plugin with your configuration
|
|
4. Activate the plugin through the Sprocket scheduler
|
|
|
|
## Dependencies
|
|
|
|
- Sprocket-Core framework
|
|
- Arduino framework
|
|
- PubSubClient library
|
|
- WiFiClient (ESP8266/ESP32)
|
|
- TaskScheduler library
|
|
|
|
## Platform Support
|
|
|
|
- ESP8266
|
|
- ESP32
|
|
|
|
## Examples
|
|
|
|
See the `examples/` directory for complete usage examples:
|
|
- `basic/` - Basic MQTT setup and communication
|
|
- `chat/` - Multi-device chat application
|
|
|
|
## Architecture
|
|
|
|
The plugin creates a bridge between:
|
|
- **Local Event Channel**: Sprocket's internal pub/sub system
|
|
- **MQTT Broker**: External message queue for distributed communication
|
|
|
|
## License
|
|
|
|
See LICENSE file for details. |