adam/Meshcore-Repeater-MQTT-Gateway
1
0 Fork 0
mirror of https://github.com/jmead/Meshcore-Repeater-MQTT-Gateway.git synced 2026-10-30 22:11:57 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs cleanup: remove outdated INTEGRATION_GUIDE.md and PROJECT_SUMMARY.md; scrub references; clarify integration is complete

Browse Source
This commit is contained in:
Jason Mead committed 2025-10-10 12:51:17 +11:00
1 parent 29392cba17
commit 4839380be1
5 files changed
+4 -758
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

INTEGRATION_GUIDE.md
-449
View File
@@ -1,449 +0,0 @@
# MeshCore Integration Guide
This guide explains how to integrate this MQTT Gateway firmware with the actual MeshCore library.
## Understanding MeshCore Library Structure
First, you need to understand the MeshCore library API. Based on the simple_repeater example from the MeshCore repository, you'll need to:
1. Include the appropriate MeshCore headers
2. Initialize the radio and mesh protocol
3. Set up packet handlers
4. Configure repeater mode
## Step-by-Step Integration
### Step 1: Examine the simple_repeater Example
Go to the MeshCore repository and examine:
```
examples/simple_repeater/simple_repeater.ino
```
Look for:
- Include statements
- Radio initialization code
- Packet receive handlers
- Packet send functions
- Repeater configuration
### Step 2: Identify Key Functions
From the simple_repeater example, identify these key functions:
```cpp
// Common patterns in MeshCore (adjust based on actual API)
void setup() {
// Radio initialization
radio.begin(frequency);
radio.setSpreadingFactor(sf);
radio.setBandwidth(bw);
// ... etc
// Mesh protocol initialization
mesh.begin(nodeId);
mesh.setRepeater(true);
mesh.onReceive(onReceiveCallback);
}
void loop() {
mesh.update(); // Process mesh protocol
}
void onReceiveCallback(uint32_t from, uint32_t to, uint8_t* payload, size_t len) {
// Handle received packet
}
```
### Step 3: Update src/main.cpp
Based on what you find in the simple_repeater example, update the following sections in `src/main.cpp`:
#### A. Add Includes
Replace the commented include at the top:
```cpp
// Replace this:
// #include <MeshCore.h>
// With actual includes from simple_repeater:
#include <RadioLib.h> // If MeshCore uses RadioLib
#include <MeshCore.h> // Or whatever the actual header is
```
#### B. Add Global Objects
Add the radio and mesh objects:
```cpp
// Add after global object declarations
SX1276 radio = new Module(LORA_CS, LORA_DIO0, LORA_RST, LORA_DIO1);
MeshCore mesh(&radio); // Adjust constructor based on actual API
```
#### C. Complete setupLoRa()
Update the `setupLoRa()` function:
```cpp
void setupLoRa() {
SPI.begin(LORA_SCK, LORA_MISO, LORA_MOSI, LORA_CS);
// Initialize radio (example - adjust to actual API)
int state = radio.begin(
config.lora.frequency,
config.lora.bandwidth,
config.lora.spreadingFactor,
config.lora.codingRate,
config.lora.syncWord,
config.lora.txPower
);
if (state != RADIOLIB_ERR_NONE) {
Serial.printf("Radio initialization failed: %d\n", state);
while (true);
}
// Initialize mesh protocol
mesh.begin(config.repeater.nodeId);
mesh.setNodeName(config.repeater.nodeName);
mesh.setMaxHops(config.repeater.maxHops);
mesh.setRepeaterMode(true);
// Set receive callback
mesh.onReceive([](uint32_t from, uint32_t to, uint8_t* payload, size_t len, int16_t rssi, float snr) {
handleMeshPacket(from, to, payload, len, rssi, snr);
});
Serial.println(F("✓ MeshCore initialized"));
}
```
#### D. Complete handleLoRaReceive()
Update the packet receive function:
```cpp
void handleLoRaReceive() {
// Call mesh update to process any pending packets
mesh.update();
// The actual packet handling is done in the callback
// set up in setupLoRa()
}
```
#### E. Add Mesh Packet Handler
Add a new function to handle mesh packets:
```cpp
void handleMeshPacket(uint32_t fromId, uint32_t toId, uint8_t* payload,
size_t length, int16_t rssi, float snr) {
packetsReceived++;
Serial.printf("Mesh packet: from=0x%08X to=0x%08X len=%d rssi=%d snr=%.1f\n",
fromId, toId, length, rssi, snr);
// Forward to MQTT if connected
if (mqttHandler && mqttHandler->isConnected()) {
// Publish raw packet data
if (config.mqtt.publishRaw) {
mqttHandler->publishRawPacket(payload, length, rssi, snr);
}
// Publish decoded message
if (config.mqtt.publishDecoded) {
// Convert payload to string (if it's a text message)
char message[256] = {0};
size_t msgLen = min(length, sizeof(message) - 1);
memcpy(message, payload, msgLen);
mqttHandler->publishDecodedMessage(
fromId, toId, message,
0, // message type - you may need to extract this from packet
rssi, snr,
0 // hop count - extract from packet if available
);
}
packetsForwarded++;
}
// MeshCore should automatically handle repeating if in repeater mode
}
```
#### F. Complete sendLoRaPacket()
Update the send function:
```cpp
void sendLoRaPacket(const uint8_t* data, size_t length) {
Serial.printf("Sending LoRa packet: %d bytes\n", length);
// Parse destination from MQTT message if in JSON format
// For simple case, broadcast:
uint32_t destId = 0xFFFFFFFF; // Broadcast
if (mesh.send(destId, data, length)) {
packetsSent++;
Serial.println(F("✓ Packet sent"));
} else {
packetsFailed++;
Serial.println(F("✗ Packet send failed"));
}
}
```
### Step 4: Update MQTT Message Format
Based on the actual MeshCore packet structure, you may need to update the MQTT message format in `mqtt_handler.h` to include additional fields like:
- Packet type
- Hop count
- Time-to-live (TTL)
- Route information
- Sequence numbers
### Step 5: Handle Different Packet Types
MeshCore likely supports different packet types (data, ack, route discovery, etc.). Add handlers for each:
```cpp
void handleMeshPacket(uint32_t fromId, uint32_t toId, uint8_t* payload,
size_t length, int16_t rssi, float snr, uint8_t packetType) {
switch (packetType) {
case PACKET_TYPE_DATA:
handleDataPacket(fromId, toId, payload, length, rssi, snr);
break;
case PACKET_TYPE_ACK:
handleAckPacket(fromId, toId, payload, length);
break;
case PACKET_TYPE_ROUTE_DISCOVERY:
handleRouteDiscovery(fromId, toId, payload, length);
break;
default:
Serial.printf("Unknown packet type: %d\n", packetType);
break;
}
}
```
### Step 6: Implement Node Tracking
Track active nodes in the mesh and publish their status:
```cpp
#include <map>
struct NodeInfo {
char name[32];
unsigned long lastSeen;
int16_t lastRssi;
float lastSnr;
};
std::map<uint32_t, NodeInfo> activeNodes;
void updateNodeInfo(uint32_t nodeId, const char* name, int16_t rssi, float snr) {
NodeInfo& node = activeNodes[nodeId];
strncpy(node.name, name, sizeof(node.name) - 1);
node.lastSeen = millis();
node.lastRssi = rssi;
node.lastSnr = snr;
// Publish to MQTT
if (mqttHandler && mqttHandler->isConnected()) {
mqttHandler->publishNodeInfo(nodeId, name, true);
}
}
void checkNodeTimeout() {
unsigned long now = millis();
for (auto& pair : activeNodes) {
if (now - pair.second.lastSeen > 300000) { // 5 minutes
if (mqttHandler && mqttHandler->isConnected()) {
mqttHandler->publishNodeInfo(pair.first, pair.second.name, false);
}
}
}
}
```
### Step 7: Add Route Information
If MeshCore provides route information, publish it to MQTT:
```cpp
void publishRouteInfo(uint32_t destId, uint32_t nextHop, uint8_t hopCount) {
if (!mqttHandler || !mqttHandler->isConnected()) return;
char topic[128];
snprintf(topic, sizeof(topic), "%s/routes/%08X",
config.mqtt.topicPrefix, destId);
StaticJsonDocument<256> doc;
doc["destination"] = destId;
doc["nextHop"] = nextHop;
doc["hopCount"] = hopCount;
doc["timestamp"] = millis();
doc["gateway"] = config.mqtt.clientId;
String output;
serializeJson(doc, output);
mqttHandler->publish(topic, output.c_str());
}
```
## Testing the Integration
### 1. Basic Connectivity Test
```cpp
// In setup(), after initialization:
Serial.println("\n=== Testing MeshCore ===");
Serial.printf("Node ID: 0x%08X\n", mesh.getNodeId());
Serial.printf("Is Repeater: %s\n", mesh.isRepeater() ? "Yes" : "No");
```
### 2. Send Test Packet
```cpp
// Add a test command in checkSerialInput()
case 't':
case 'T':
{
const char* testMsg = "Test from MQTT Gateway";
sendLoRaPacket((uint8_t*)testMsg, strlen(testMsg));
}
break;
```
### 3. Monitor MQTT
```bash
# Subscribe to all topics
mosquitto_sub -h your-broker -t "MESHCORE/#" -v
# Or use MQTT Explorer GUI tool
```
### 4. Test Repeater Function
- Set up multiple MeshCore nodes
- Send messages between distant nodes
- Verify gateway forwards packets
- Check hop count increases
## Common Issues and Solutions
### Issue: Radio Won't Initialize
**Solution**:
- Double-check pin definitions
- Verify SPI wiring
- Check radio power supply
- Try lowering SPI clock speed
### Issue: Packets Not Being Repeated
**Solution**:
- Verify repeater mode is enabled
- Check max hop count setting
- Ensure sync word matches other nodes
- Verify frequency and bandwidth match
### Issue: High Memory Usage
**Solution**:
- Reduce MQTT buffer size
- Limit number of tracked nodes
- Decrease JSON document sizes
- Enable PSRAM if available
### Issue: TLS fails with hostname mismatch
**Solution**:
- Use the broker hostname in MQTT Settings. The firmware embeds the CA and attempts hostname first.
- If the certificate CN is bound to the broker IP, the firmware automatically retries via resolved IP.
- Ensure time is synced (Clock menu) before TLS.
### Issue: Missed Packets
**Solution**:
- Increase processing speed in loop()
- Remove delays in packet handlers
- Use interrupts for radio events
- Optimize MQTT publishing
## Advanced Features
### Packet Filtering
```cpp
bool shouldForwardPacket(uint32_t fromId, uint32_t toId, uint8_t packetType) {
// Don't forward packets from ourselves
if (fromId == config.repeater.nodeId) {
return false;
}
// Only forward data packets to MQTT
if (packetType != PACKET_TYPE_DATA) {
return false;
}
// Add custom filtering logic here
return true;
}
```
### Packet Queuing
```cpp
#include <queue>
struct QueuedPacket {
uint32_t destId;
uint8_t data[256];
size_t length;
unsigned long queueTime;
};
std::queue<QueuedPacket> sendQueue;
void queuePacket(uint32_t destId, const uint8_t* data, size_t length) {
if (sendQueue.size() >= 10) {
Serial.println("Send queue full!");
return;
}
QueuedPacket packet;
packet.destId = destId;
packet.length = min(length, sizeof(packet.data));
memcpy(packet.data, data, packet.length);
packet.queueTime = millis();
sendQueue.push(packet);
}
void processSendQueue() {
if (sendQueue.empty()) return;
QueuedPacket& packet = sendQueue.front();
if (mesh.canSend()) {
sendLoRaPacket(packet.data, packet.length);
sendQueue.pop();
}
}
```
## Reference Documentation
Make sure to read:
- MeshCore library documentation
- Simple_repeater example code
- RadioLib documentation (if used)
- ESP32 Arduino core docs
## Support
If you encounter issues:
1. Check MeshCore Discord for help
2. Review MeshCore GitHub issues
3. Compare with working simple_repeater example
4. Enable debug logging to trace packet flow
---
Good luck with your integration! The MeshCore community is friendly and helpful if you need assistance.
LILYGO_SETUP.md
+1 -1
View File
@@ -307,7 +307,7 @@ void updateDisplay() {
## 🆘 Need Help?
- Check [SERIAL_COMMANDS.md](SERIAL_COMMANDS.md) for command reference
- Read [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) for MeshCore integration
- MeshCore integration is already complete in this firmware
- Visit [MeshCore Discord](https://discord.gg/meshcore) for community support
- Open an issue on GitHub for bugs
PROJECT_SUMMARY.md
-303
View File
@@ -1,303 +0,0 @@
# MeshCore MQTT Gateway - Project Summary
## ✅ Project Complete!
Your MeshCore MQTT Gateway is ready to build and deploy on your **LilyGo LoRa32 V2.1_1.6** board.
## 📦 What's Included
### Core Firmware Files
```
src/
├── main.cpp # Main gateway firmware with MeshCore integration
├── config.h # Configuration structures and pin definitions
├── mqtt_handler.h # MQTT client and message bridging
├── serial_config.h # Interactive serial configuration menu
└── settings_manager.h # Persistent storage (NVS/EEPROM)
```
### Configuration
```
platformio.ini # Build configuration (pre-configured for your board!)
```
**Your board is set as the default:**
- Board: LilyGo LoRa32 V2.1_1.6 (ttgo-lora32-v21)
- Upload Port: COM7
- Monitor Port: COM7
- Pin mappings: Pre-configured for your hardware
### Documentation
```
README.md # Comprehensive project documentation
QUICKSTART.md # 5-step quick start guide
LILYGO_SETUP.md # LilyGo-specific setup guide (START HERE!)
INTEGRATION_GUIDE.md # How to integrate with MeshCore library
SERIAL_COMMANDS.md # Complete serial command reference
```
### Examples
```
examples/
├── mqtt_test_client.py # Python MQTT test client
└── README.md # Integration examples (Node-RED, Home Assistant, etc.)
```
### Other Files
```
.gitignore # Git ignore rules
LICENSE # MIT License
```
## 🎯 Key Features Implemented
### ✅ MeshCore Repeater
- Full repeater functionality (template ready for MeshCore integration)
- Configurable max hops, auto-ACK, broadcast
- Route timeout management
- Node ID auto-generation from chip MAC
### ✅ MQTT Bridging
- Bidirectional LoRa ↔ MQTT message forwarding
- Publish raw packets (hex format)
- Publish decoded messages (JSON format)
- Node status tracking and publishing
- Gateway statistics and health monitoring
- Command reception from MQTT
- Last Will and Testament for offline detection
### ✅ Serial Configuration
- Interactive menu system (press `c`)
- WiFi settings (SSID, password, enable/disable)
- MQTT settings (server, port, auth, topics)
- LoRa settings (frequency, bandwidth, SF, CR, power)
- Repeater settings (name, hops, timeouts)
- Save/load configuration from flash
- Reset to factory defaults
- Runtime statistics (press `s`)
### ✅ Persistent Storage
- ESP32 NVS (Non-Volatile Storage)
- Survives power cycles and resets
- Config validation with magic number
- Easy backup and restore
### ✅ Hardware Support
- LilyGo LoRa32 V2.1_1.6 (your board!) ✨
- Heltec WiFi LoRa 32 V3
- Generic ESP32 + SX127x boards
- Pin definitions included for OLED display
## 📊 MQTT Topics Published
| Topic | Description | Retained |
|-------|-------------|----------|
| `{prefix}/raw` | Raw LoRa packets (hex) | No |
| `{prefix}/messages` | Decoded mesh messages | No |
| `{prefix}/nodes/{nodeId}` | Node online/offline status | Yes |
| `{prefix}/gateway/{id}/status` | Gateway online/offline | Yes |
| `{prefix}/gateway/{id}/stats` | Gateway statistics | No |
## 📨 MQTT Topics Subscribed
| Topic | Description |
|-------|-------------|
| `{prefix}/commands/send` | Send message to mesh |
| `{prefix}/commands/restart` | Restart gateway |
## 🚀 Next Steps
### 1. Upload Firmware (5 minutes)
```bash
# In VS Code with PlatformIO
1. Open project folder
2. Click PlatformIO icon
3. Click "Upload" under lilygo_lora32_v21
4. Wait for upload to complete
```
**OR** command line:
```bash
pio run --target upload
```
### 2. Configure Settings (5 minutes)
```bash
# Open serial monitor (115200 baud)
1. Press 'c' to enter config menu
2. Configure WiFi (option 1)
3. Configure MQTT (option 2)
4. Adjust LoRa if needed (option 3)
5. Save config (option 6)
6. Restart (option 8)
```
See [LILYGO_SETUP.md](LILYGO_SETUP.md) for detailed steps!
### 3. Integrate MeshCore Library (10-30 minutes)
The firmware includes placeholder comments where MeshCore integration is needed:
```cpp
// TODO: Initialize MeshCore library with configuration
// TODO: Check for incoming LoRa packets using MeshCore
// TODO: Send packet via MeshCore
```
Follow [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) to:
1. Examine the `simple_repeater` example from MeshCore
2. Add MeshCore initialization code
3. Implement packet receive handlers
4. Connect send/receive functions
### 4. Test Everything (10 minutes)
1. Verify firmware uploads successfully
2. Check WiFi connection in serial monitor
3. Verify MQTT connection
4. Test with another MeshCore node
5. Monitor MQTT topics
6. Send test commands
### 5. Deploy! 🎉
Your gateway is ready for real-world use!
## 🔧 Configuration Examples
### Basic Home Gateway
```
WiFi: Home network
MQTT: Local broker (192.168.1.100:1883)
LoRa: 915MHz, SF7, 125kHz, 20dBm
Max Hops: 3
```
### Remote Gateway (4G/5G Hotspot)
```
WiFi: Mobile hotspot
MQTT: Cloud broker (mqtt.example.com:1883)
LoRa: 915MHz, SF9, 125kHz, 17dBm
Max Hops: 2
```
### Testing/Development
```
WiFi: Local network
MQTT: Public test broker (test.mosquitto.org:1883)
LoRa: 915MHz, SF7, 250kHz, 10dBm
Max Hops: 2
```
## 📚 Documentation Quick Links
**Getting Started:**
- 🚀 [LILYGO_SETUP.md](LILYGO_SETUP.md) - **START HERE!**
- ⚡ [QUICKSTART.md](QUICKSTART.md) - Fast 5-step guide
- 📖 [README.md](README.md) - Full documentation
**Configuration:**
- ⌨️ [SERIAL_COMMANDS.md](SERIAL_COMMANDS.md) - Command reference
- 🔧 Settings are configured via serial menu (press `c`)
**Integration:**
- 🔌 [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) - MeshCore integration
- 💻 [examples/](examples/) - MQTT client examples
## 🎓 Learning Resources
### MeshCore
- [MeshCore GitHub](https://github.com/meshcore-dev/MeshCore)
- [MeshCore Discord](https://discord.gg/meshcore)
- [Simple Repeater Example](https://github.com/meshcore-dev/MeshCore/tree/main/examples/simple_repeater)
### MQTT
- [MQTT.org](https://mqtt.org/)
- [Eclipse Mosquitto](https://mosquitto.org/)
- [MQTT Explorer](http://mqtt-explorer.com/) - GUI client
### ESP32 & LoRa
- [LilyGo GitHub](https://github.com/LilyGO/TTGO-LORA32)
- [PlatformIO Docs](https://docs.platformio.org/)
- [RadioLib](https://github.com/jgromes/RadioLib)
## ⚙️ Build Information
**Platform:** PlatformIO on ESP32
**Framework:** Arduino
**Libraries:**
- MeshCore (from GitHub)
- PubSubClient v2.8 (MQTT)
- ArduinoJson v6.21.3 (JSON parsing)
**Build Flags:**
- `LILYGO_LORA32_V21` - Board identification
- `MeshCore_MQTT_GATEWAY` - Gateway mode
- `CORE_DEBUG_LEVEL=3` - Debug logging
## 🐛 Troubleshooting
**Can't upload firmware?**
→ See [LILYGO_SETUP.md](LILYGO_SETUP.md#upload-issues)
**WiFi won't connect?**
→ See [LILYGO_SETUP.md](LILYGO_SETUP.md#wifi-not-connecting)
**LoRa not working?**
→ See [LILYGO_SETUP.md](LILYGO_SETUP.md#lora-not-working)
**MQTT connection fails?**
→ See [LILYGO_SETUP.md](LILYGO_SETUP.md#mqtt-not-connecting)
## 💡 Pro Tips
1. **Always connect antenna before powering on!** 🚨
2. Start with default LoRa settings (SF7, 125kHz)
3. Test WiFi and MQTT separately before combined testing
4. Use `mosquitto_sub` to monitor all MQTT traffic
5. Keep serial monitor open for debugging
6. Save configuration after making changes!
7. Use the Python test client for quick MQTT testing
## 🎯 Project Status
| Component | Status | Notes |
|-----------|--------|-------|
| Firmware Structure | ✅ Complete | Ready to build |
| Board Configuration | ✅ Complete | LilyGo V2.1_1.6 on COM7 |
| Serial Config Menu | ✅ Complete | Full interactive menu |
| Settings Storage | ✅ Complete | ESP32 NVS integration |
| MQTT Handler | ✅ Complete | Bidirectional bridging |
| WiFi Support | ✅ Complete | Auto-reconnect |
| Documentation | ✅ Complete | Comprehensive guides |
| MeshCore Integration | ⏳ Template | Follow INTEGRATION_GUIDE.md |
| Testing | ⏳ Pending | After upload and config |
## 📞 Support
**Community:**
- MeshCore Discord: Best place for help!
- GitHub Issues: For bugs and features
**Documentation:**
- All documentation is included in the project
- Start with [LILYGO_SETUP.md](LILYGO_SETUP.md)
## 🎉 You're Ready!
Everything is configured and ready for your LilyGo LoRa32 V2.1_1.6 board on COM7.
**Next action:** Open [LILYGO_SETUP.md](LILYGO_SETUP.md) and follow the Quick Start!
---
**Built with ❤️ for the MeshCore community**
**Happy Meshing! 📡✨**
QUICKSTART.md
+1 -2
View File
@@ -50,7 +50,7 @@ pio run --target upload
Port: 1883 (use 8883 for TLS)
[Rest can use defaults]
```
Note: Country/Region inputs are normalized to uppercase and spaces removed. Use ISO2 for country (e.g., AU). For TLS:
Note: Country/Region inputs are normalized to uppercase and spaces removed. Use ISO2 for country (e.g., AU) and state (e.g. NSW). For TLS:
- Set Port to 8883 and Enable TLS = y
- Use custom CA = n (firmware embeds the broker CA)
- The firmware will retry via resolved IP if the certificate CN is an IP.
@@ -128,7 +128,6 @@ mosquitto_pub -h mqtt.example.com \
## 📚 Learn More
- **Full README**: Detailed documentation → [README.md](README.md)
- **Integration Guide**: Connect to real MeshCore → [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)
- **Examples**: MQTT clients and integrations → [examples/](examples/)
- **MeshCore Docs**: <https://github.com/meshcore-dev/MeshCore>
README.md
+2 -3
View File
@@ -13,7 +13,6 @@ A powerful gateway firmware that bridges MeshCore LoRa mesh networks with MQTT b
- **Multiple Publishing Modes** - Publish raw hex packets and/or decoded messages
- **Remote Commands** - Send commands from MQTT to the gateway
- **Gateway Status Reporting** - Automatic online/offline status with last will
- **NTP Clock Sync** - Automatic time sync (NTP) with timezone support; required for TLS certificate validation
## 📚 Documentation Index
@@ -31,8 +30,8 @@ A powerful gateway firmware that bridges MeshCore LoRa mesh networks with MQTT b
- [tools/configure_mqtt_topic_selector.py](tools/configure_mqtt_topic_selector.py) — Pick ISO-coded MQTT topic prefixes
- **Development and integration**
- [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) — Wire the firmware to the MeshCore library
- [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) — Repository map, components, and status
- MeshCore integration is already complete in this firmware.
- **Reference**
- [platformio.ini](platformio.ini) — Build environments and dependencies