znet-temp-sensor/CLAUDE.md

# ZNET Temperature Sensor - ESP32 LoRa Gateway

## Project Overview

ESP32-based temperature monitoring system for e-coat paint tanks. Reads DS18B20 waterproof temperature probes immersed in the paint tank and sends data to ZNET Web for real-time monitoring and ML feature collection.

## Hardware

| Component | Model | Purpose |
|-----------|-------|---------|
| MCU | Meshnology ESP32 LoRa V3 | Main controller with WiFi, LoRa, OLED |
| Temp Sensor | DS18B20 (x2) | Waterproof stainless steel probes in paint tank |
| Display | Built-in 0.96" OLED | Local temperature display for operators |
| Radio | Built-in SX1262 | LoRa 915MHz for future remote sensors |

## Quick Start

### Build & Upload
```bash
# Install PlatformIO CLI
pip install platformio

# Build
cd ~/Nextcloud/Dev/znet-temp-sensor
pio run

# Upload to ESP32 (connect via USB)
pio run --target upload

# Monitor serial output
pio device monitor
```

### Configure WiFi
1. Power on the ESP32
2. Connect to WiFi network: `ZNET-TempSensor` (password: `znettemp123`)
3. Browser opens captive portal - enter your WiFi credentials
4. Device connects and starts posting to ZNET Web

### Configure API Endpoint
Edit `include/config.h`:
```cpp
#define ZNET_API_URL "http://192.168.1.100:8000/api/v1/sensors/readings"
```

## Wiring

### DS18B20 Connection (1-Wire bus, both sensors on same pin)
```
ESP32 GPIO7 ─────┬───────────── DS18B20 #1 DATA (yellow)
                 │
                 └───────────── DS18B20 #2 DATA (yellow)

ESP32 3.3V ──────┬───────────── DS18B20 #1 VCC (red)
                 │
                 └───────────── DS18B20 #2 VCC (red)

ESP32 GND ───────┬───────────── DS18B20 #1 GND (black)
                 │
                 └───────────── DS18B20 #2 GND (black)

4.7kΩ pullup resistor between DATA and VCC
```

### GPIO Pinout (Heltec V3 / Meshnology)
| Function | GPIO |
|----------|------|
| OneWire Data | 7 |
| OLED SDA | 17 |
| OLED SCL | 18 |
| OLED RST | 21 |
| LoRa SCK | 9 |
| LoRa MISO | 11 |
| LoRa MOSI | 10 |
| LoRa SS | 8 |
| LoRa RST | 12 |
| LoRa DIO1 | 14 |
| LoRa BUSY | 13 |

## Configuration

All configuration in `include/config.h`:

| Setting | Default | Description |
|---------|---------|-------------|
| `ZNET_API_URL` | - | ZNET Web API endpoint |
| `DEVICE_ID` | `tank_gateway_1` | Unique device identifier |
| `TEMP_READ_INTERVAL_MS` | 30000 | Reading interval (30 sec) |
| `TEMP_MIN_VALID_F` | 32.0 | Minimum valid temperature |
| `TEMP_MAX_VALID_F` | 150.0 | Maximum valid temperature |

## API Integration

### POST /api/v1/sensors/readings
```json
{
  "device_id": "tank_gateway_1",
  "device_name": "E-Coat Tank Gateway",
  "readings": [
    {
      "sensor_id": "tank_primary",
      "temperature_f": 85.5,
      "is_valid": true
    },
    {
      "sensor_id": "tank_secondary",
      "temperature_f": 85.3,
      "is_valid": true
    }
  ]
}
```

### Response
```json
{
  "success": true,
  "readings_stored": 2,
  "alerts_generated": 0
}
```

## Features

### Implemented
- [x] Dual DS18B20 sensor reading with validation
- [x] OLED display showing current temperature
- [x] WiFiManager for easy WiFi setup
- [x] HTTP POST to ZNET Web API
- [x] Offline buffering when network unavailable
- [x] Automatic sensor discovery (1-Wire)

### Phase 3: LoRa Network (Complete)
- [x] LoRa packet protocol design (docs/LORA_PROTOCOL.md)
- [x] Protocol header files (include/lora_protocol.h, include/lora_packet.h)
- [x] Battery-powered remote node firmware (remote-node/)
- [x] LoRa receive for gateway (RadioLib SX1262)
- [x] Gateway LoRa → HTTP forwarding
- [x] Automatic node registration and ACK responses

### Future
- [ ] Sensor agreement monitoring
- [ ] Flash storage for offline buffer persistence

## Remote Sensor Nodes

Battery-powered sensor nodes in `remote-node/` that transmit to the gateway via LoRa.

### Build & Upload
```bash
cd remote-node

# DHT22 variant (ambient temp/humidity)
pio run -e heltec_v3_dht22 --target upload

# BME680 variant (temp/humidity/pressure/VOC)
pio run -e heltec_v3_bme680 --target upload
```

### Configuration
Edit `remote-node/include/config.h`:
- `NODE_ID` - Unique ID or 0xFFFF for auto-assign
- `NODE_NAME` - Human-readable name (8 chars max)
- `REPORT_INTERVAL_SEC` - How often to transmit (default 60s)

### Power Consumption
- Deep sleep: ~10 μA
- Average @ 60s interval: ~1 mA
- 1000mAh LiPo battery life: ~1 month

## LoRa Protocol

The gateway will receive data from remote sensor nodes via LoRa 915MHz. Full specification in `docs/LORA_PROTOCOL.md`.

### Key Files
| File | Purpose |
|------|---------|
| `docs/LORA_PROTOCOL.md` | Full protocol specification |
| `include/lora_protocol.h` | Constants, types, CRC functions |
| `include/lora_packet.h` | Packet builder/parser helpers |

### Supported Sensors
| Type | Code | Payload Size | Data |
|------|------|--------------|------|
| DHT22 | 0x01 | 7 bytes | Temp, Humidity, Battery, RSSI |
| BME680 | 0x02 | 12 bytes | Temp, Humidity, Pressure, Gas, IAQ |
| DS18B20 | 0x03 | 5 bytes | Temp (high precision), Battery, RSSI |

### Node ID Ranges
| Range | Purpose |
|-------|---------|
| 0x0001-0x00FF | Tank sensors |
| 0x0100-0x01FF | Ambient sensors (DHT22) |
| 0x0200-0x02FF | Environmental (BME680) |
| 0xFFFF | Auto-assign request |

## Documentation

| Document | Purpose |
|----------|---------|
| `docs/SETUP_GUIDE.md` | Complete setup guide with wiring diagrams |
| `docs/LORA_PROTOCOL.md` | LoRa packet format specification |
| `remote-node/README.md` | Remote node firmware guide |

## Related Projects

- **ZNET Web**: `~/Nextcloud/Dev/znet-web` - Backend receives temperature data
- **Baserow**: Table for lab temperature logs (to be created)

## Git Repository

- **Remote:** https://git.ecoat.us/leehughes/znet-temp-sensor.git
- **Main branch:** `main`

## Change Log

| Date | Version | Change |
|------|---------|--------|
| 2026-01-24 | 1.0.0 | Initial implementation |
| 2026-01-24 | 1.1.0 | LoRa protocol design, header files |
| 2026-01-24 | 1.2.0 | Remote node firmware template (DHT22, BME680, DS18B20) |
| 2026-01-24 | 1.3.0 | Gateway LoRa receive, node registry, HTTP forwarding |