Repository Guidelines

Project Structure & Module Organization

This repository contains a small ESP8266/ESP32 Arduino project for monitoring water level with conductive electrodes and a small PHP endpoint for logging measurements.

arduino/arduino.ino contains the Arduino sketch and main application logic.
server/log.php accepts measurement POST requests and appends them as JSON Lines.
data/YYYY.jsonl is created at runtime for logged measurements and should not be treated as source code.
README.md gives the high-level project purpose.
LICENSE contains licensing information.
.agents/ is reserved for agent/tooling metadata and should not be treated as firmware source.

Keep Arduino source files inside the arduino/ sketch directory so Arduino IDE can open and build the project correctly.

Build, Test, and Development Commands

Use Arduino IDE or arduino-cli with the ESP8266 or ESP32 board package installed.

Examples:

arduino-cli compile --fqbn esp8266:esp8266:nodemcuv2 arduino
arduino-cli upload -p COM3 --fqbn esp8266:esp8266:nodemcuv2 arduino
arduino-cli monitor -p COM3 -c baudrate=115200

arduino-cli compile --fqbn esp32:esp32:esp32 arduino
arduino-cli upload -p COM3 --fqbn esp32:esp32:esp32 arduino
arduino-cli monitor -p COM3 -c baudrate=115200

php -l server/log.php

compile verifies the sketch builds for the selected board.
upload flashes the firmware to the connected board.
monitor opens the serial console used by debug output.
php -l checks the PHP logging endpoint for syntax errors.

Adjust --fqbn and COM3 for the actual board and port.

Coding Style & Naming Conventions

Write C++ compatible with Arduino IDE and the ESP8266/ESP32 cores. Use two-space indentation, braces on the same line, and descriptive names.

Constants: uppercase or clearly prefixed names, for example PIN_LEVEL1, SLEEP_TIME_SEC.
Structs and types: PascalCase, for example WaterLevels.
Functions: lower camelCase, for example readLevels() and connectWifi().

Prefer small functions with one responsibility. Keep hardware pins, URLs, timings, and debug flags as constants near the top of the sketch.

For PHP scripts, keep them framework-free unless the project grows. Return JSON responses, use explicit HTTP status codes, and keep generated log files under data/.

Hardware Notes

For ESP8266 conductive level sensing, use external pull-down resistors from each PIN_LEVEL1..4 input to GND. The common electrode is driven to positive voltage only during measurement.

Avoid ESP8266 boot/strap pins for level inputs when possible, especially GPIO0, GPIO2, and GPIO15. Also avoid GPIO1/GPIO3 unless intentionally sharing the serial port. Prefer ordinary GPIO pins such as GPIO5, GPIO4, GPIO14, GPIO12, or GPIO13, depending on the board and wiring.

Testing Guidelines

There is no automated test framework in this repository. Validate changes by compiling the sketch and testing on hardware.

Before committing firmware changes:

Compile for the target ESP8266 or ESP32 board.
Test DEBUG == 1 for local level readings without Wi-Fi.
Test DEBUG == 2 for repeated Wi-Fi POST requests.
Test DEBUG == 0 for production sleep/wake behavior.

Before committing server changes:

Run php -l server/log.php.
Test that non-POST requests return HTTP 405 with Allow: POST.
Test a form POST such as level1=1&level2=0&level3=0&level4=1.
Verify that a single compact JSON object is appended to data/YYYY.jsonl.

Commit & Pull Request Guidelines

Current Git history is minimal and uses a simple message such as Initial commit. Keep future commits short, imperative, and specific, for example Add WiFi timeout handling.

Pull requests should include:

A brief description of firmware behavior changed.
Board model and Arduino ESP8266/ESP32 core version used for testing.
Serial output or screenshots when debugging behavior changes.
Any required configuration changes, especially Wi-Fi, server URL, or pin mapping.

Security & Configuration Tips

Avoid committing real Wi-Fi passwords or private server endpoints when possible. For shared changes, replace secrets with placeholders and document required local values.

4.2 KiB Raw Blame History