leehughes/znet-temp-sensor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add LoRa sensor network support

Browse Source 
- Design LoRa packet protocol with CRC16 validation
- Add protocol header files (lora_protocol.h, lora_packet.h)
- Create battery-powered remote node firmware template
  - Support for DHT22, BME680, DS18B20 sensors
  - Deep sleep for battery conservation
  - Automatic gateway registration
- Add LoRa receive to gateway firmware
  - RadioLib SX1262 integration
  - Node registry for tracking up to 16 nodes
  - HTTP forwarding of received readings
  - ACK responses to remote nodes
- Create comprehensive setup guide with wiring diagrams

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
leehughes
2026-01-24 17:50:53 -06:00
co-authored by Claude Opus 4.5
parent 265a53768e
commit 5554341b49
11 changed files with 3199 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/SETUP_GUIDE.md
+315
View File
@@ -0,0 +1,315 @@
# ZNET Temperature Sensor System - Setup Guide
Complete guide for setting up the ZNET temperature monitoring system with gateway and remote sensor nodes.
## System Overview
```
┌──────────────────────────────────────────────────────────────────────────┐
│ ZNET Temperature System │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ LoRa 915MHz ┌────────────┐ │
│ │ Remote #1 │◄──────────────────────────►│ │ │
│ │ DHT22 │ │ Gateway │ WiFi │
│ │ ambient │ LoRa 915MHz │ ESP32 │◄──────┐ │
│ └────────────┘◄──────────────────────────►│ LoRa V3 │ │ │
│ ┌────────────┐ │ │ │ │
│ │ Remote #2 │ LoRa 915MHz │ DS18B20 x2 │ │ │
│ │ BME680 │◄──────────────────────────►│ (in tank) │ │ │
│ │ VOC/air │ └─────┬──────┘ │ │
│ └────────────┘ │ │ │
│ │ OLED │ │
│ │ Display │ │
│ ▼ ▼ │
│ ┌──────────────────────────┐ │
│ │ ZNET Web Backend │ │
│ │ (FastAPI + PostgreSQL)│ │
│ └──────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
```
## Hardware Required
### Gateway (1x per tank)
| Part | Model | Qty | Purpose | Notes |
|------|-------|-----|---------|-------|
| MCU | Meshnology ESP32 LoRa V3 | 1 | Main controller | Built-in OLED, LoRa |
| Sensor | DS18B20 waterproof | 2 | Tank temperature | Stainless steel, 1m cable |
| Resistor | 4.7kΩ 1/4W | 1 | 1-Wire pullup | Between DATA and VCC |
| Enclosure | IP65 junction box | 1 | Protection | At least 120x80x50mm |
| Cable gland | PG9 | 2 | Wire entry | For sensor cables |
| Power | 5V 2A USB adapter | 1 | Gateway power | Or 3.7V LiPo with USB charging |
### Remote Nodes (optional, 0-16 per gateway)
| Part | Model | Qty | Purpose | Notes |
|------|-------|-----|---------|-------|
| MCU | Heltec WiFi LoRa 32 V3 | 1 | Node controller | Or TTGO LoRa32 |
| Sensor | DHT22 or BME680 | 1 | Temp/humidity/VOC | Choose based on need |
| Battery | 3.7V LiPo 1000mAh | 1 | Power | With JST connector |
| Enclosure | Weatherproof box | 1 | Protection | IP54 minimum |
## Wiring Diagrams
### Gateway Wiring (ESP32 LoRa V3 + DS18B20 x2)
```
ESP32 LoRa V3
┌─────────────────────┐
│ │
│ GPIO7 ─────┬───────┼──► DS18B20 #1 DATA (yellow)
│ │ │
│ └───────┼──► DS18B20 #2 DATA (yellow)
│ │
│ 3.3V ──────┬───────┼──► DS18B20 #1 VCC (red)
│ │ │
│ └───────┼──► DS18B20 #2 VCC (red)
│ │
│ GND ───────┬───────┼──► DS18B20 #1 GND (black)
│ │ │
│ └───────┼──► DS18B20 #2 GND (black)
│ │
└─────────────────────┘
Add 4.7kΩ resistor between GPIO7 and 3.3V (pullup)
DS18B20 Color Code:
- Red: VCC (3.3V)
- Black: GND
- Yellow: DATA (1-Wire)
```
### Remote Node Wiring (ESP32 LoRa V3 + DHT22)
```
ESP32 LoRa V3
┌─────────────────────┐
│ │ DHT22 Module
│ GPIO7 ─────────────┼──────► DATA
│ │
│ 3.3V ──────────────┼──────► VCC
│ │
│ GND ───────────────┼──────► GND
│ │
│ │
│ VBAT ◄─────────────┼────── LiPo + (red)
│ │
│ GND ◄──────────────┼────── LiPo - (black)
│ │
└─────────────────────┘
DHT22 Module (4-pin with PCB):
- VCC: 3.3V
- DATA: GPIO7 (10kΩ pullup usually built-in)
- NC: Not connected
- GND: Ground
```
### Remote Node Wiring (ESP32 + BME680 via I2C)
```
ESP32 LoRa V3
┌─────────────────────┐
│ │ BME680 Module
│ GPIO21 (SDA)───────┼──────► SDA
│ │
│ GPIO22 (SCL)───────┼──────► SCL
│ │
│ 3.3V ──────────────┼──────► VCC
│ │
│ GND ───────────────┼──────► GND
│ │
│ VBAT ◄─────────────┼────── LiPo + (red)
│ │
│ GND ◄──────────────┼────── LiPo - (black)
│ │
└─────────────────────┘
BME680 I2C Address: 0x76 (default) or 0x77
```
## Firmware Installation
### Prerequisites
```bash
# Install PlatformIO
pip install platformio
# Clone firmware repository
cd ~/Nextcloud/Dev
git clone https://git.ecoat.us/leehughes/znet-temp-sensor.git
cd znet-temp-sensor
```
### Flash Gateway
1. **Connect ESP32 via USB**
2. **Configure settings** - Edit `include/config.h`:
```cpp
// Set your ZNET Web API endpoint
#define ZNET_API_URL "http://192.168.1.100:8000/api/v1/sensors/readings"
// Set unique device ID
#define DEVICE_ID "tank_gateway_tulsa"
#define DEVICE_NAME "Tulsa E-Coat Tank Gateway"
```
3. **Build and upload**:
```bash
pio run --target upload
```
4. **Monitor serial output**:
```bash
pio device monitor
```
5. **Configure WiFi**:
- On first boot, gateway creates WiFi network: `ZNET-TempSensor`
- Connect to it with password: `znettemp123`
- Browser opens captive portal - enter your WiFi credentials
- Gateway reboots and connects
### Flash Remote Node
1. **Connect ESP32 via USB**
2. **Configure node** - Edit `remote-node/include/config.h`:
```cpp
// Set unique node ID (or 0xFFFF for auto-assign)
#define NODE_ID 0x0101
// Human-readable name (max 8 chars)
#define NODE_NAME "Ambient1"
// Report interval (seconds)
#define REPORT_INTERVAL_SEC 60
```
3. **Build and upload** (choose variant):
```bash
cd remote-node
# For DHT22 sensor:
pio run -e heltec_v3_dht22 --target upload
# For BME680 sensor:
pio run -e heltec_v3_bme680 --target upload
```
4. **Verify operation**:
- Check serial output for successful registration
- Gateway should show increased node count on OLED
## Backend Setup
### Database Migration
```bash
cd ~/Nextcloud/Dev/znet-web/backend
# Run migration to create temperature tables
uv run alembic upgrade head
```
### Verify API Endpoint
```bash
# Check sensors endpoint is working
curl http://localhost:8000/api/v1/sensors/
# Test posting a reading
curl -X POST http://localhost:8000/api/v1/sensors/readings \
-H "Content-Type: application/json" \
-d '{
"device_id": "test_gateway",
"device_name": "Test Gateway",
"readings": [
{
"sensor_id": "tank_primary",
"temperature_f": 85.5,
"is_valid": true
}
]
}'
```
## Testing
### Test Gateway Locally
1. Power on gateway
2. Verify OLED shows temperature readings
3. Check serial output for API POST success:
```
Reading temperatures...
Sensor 1: 85.50°F (valid)
Sensor 2: 85.30°F (valid)
Posting to ZNET Web API...
API POST success (code 200)
```
### Test Remote Node
1. Power on remote node
2. Watch gateway serial output:
```
LoRa RX: 15 bytes, RSSI -45 dBm
Packet from 0x0101, type 0, seq 42
DHT22 from 0x0101: 74.3°F, 55.0% RH
LoRa reading forwarded (0x0101)
ACK sent to 0x0101 seq 42
```
### Test WebSocket Updates
1. Open ZNET Web dashboard in browser
2. Verify temperature displays update without page refresh
3. Check browser console for WebSocket messages
## Troubleshooting
### Gateway Issues
| Problem | Cause | Solution |
|---------|-------|----------|
| "No sensors found" | Wiring issue | Check DATA line, pullup resistor |
| "WiFi failed" | Wrong credentials | Reset and reconfigure via portal |
| "API POST failed" | Network/server issue | Check URL, firewall, server logs |
| OLED blank | I2C issue | Check SDA/SCL connections |
### Remote Node Issues
| Problem | Cause | Solution |
|---------|-------|----------|
| "LoRa init failed" | SPI issue | Check pin definitions match board |
| No ACK received | Out of range | Move closer, increase SF |
| Short battery life | Wake too often | Increase REPORT_INTERVAL_SEC |
| Sensor read fails | Bad wiring | Check connections, I2C address |
### LoRa Range Issues
| Symptom | Solution |
|---------|----------|
| RSSI < -100 dBm | Move nodes closer or add gain antenna |
| Many CRC errors | Reduce spreading factor (SF) |
| ACK timeouts | Increase ACK_TIMEOUT_MS |
## Production Deployment Checklist
- [ ] Gateway powered via stable 5V supply (not USB from laptop)
- [ ] Tank sensors fully submerged in paint bath
- [ ] Gateway enclosure sealed against moisture/fumes
- [ ] WiFi signal strength verified at gateway location
- [ ] API endpoint accessible from gateway network
- [ ] Remote nodes battery charged and secured
- [ ] Remote node enclosures sealed
- [ ] All sensors reading within expected range
- [ ] Alert thresholds configured by lab manager
- [ ] WebSocket updates verified in browser
- [ ] Backup sensors agree within 5°F