znet-temp-sensor/docs/SETUP_GUIDE.md

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

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

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

   pio run --target upload
   

4. Monitor serial output:

   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:

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

   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

cd ~/Nextcloud/Dev/znet-web/backend

# Run migration to create temperature tables
uv run alembic upgrade head

Verify API Endpoint

# 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