leehughes/znet-temp-sensor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
znet-temp-sensor/docs/SETUP_GUIDE.md
T
leehughesandClaude Opus 4.5 5554341b49 Add LoRa sensor network support 
- 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>
2026-01-24 17:50:53 -06:00

316 lines
12 KiB
Markdown
Raw Permalink Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink