# 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