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

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

#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

{
  "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

{
  "success": true,
  "readings_stored": 2,
  "alerts_generated": 0
}

Features

Implemented

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

Phase 3: LoRa Network (Complete)

• LoRa packet protocol design (docs/LORA_PROTOCOL.md)
• Protocol header files (include/lora_protocol.h, include/lora_packet.h)
• Battery-powered remote node firmware (remote-node/)
• LoRa receive for gateway (RadioLib SX1262)
• Gateway LoRa → HTTP forwarding
• 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

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