Hladinac/AGENTS.md

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.
• server/data-checker.php is intended for hourly CRON runs and checks whether recent measurements are still being written.
• server/functions.inc.php contains shared PHP helpers, including JSON responses, HTTP requests, and Telegram notifications.
• data/YYYY.jsonl is created at runtime for logged measurements and should not be treated as source code.
• docs/ contains project documentation images referenced from README.md.
• README.md is the user- and developer-facing project documentation.
• 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
php -l server/data-checker.php
php -l server/functions.inc.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 scripts 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/.

Keep shared PHP helpers in server/functions.inc.php. Use the existing telegram() helper for Telegram notifications, and wrap notification calls so delivery failures do not change the HTTP response or stop measurement logging.

Keep README.md as complete human-facing documentation for both users and developers. When hardware pins, measurement intervals, server endpoints, notifications, or documented photos change, update the README in the same change. Reference documentation images with relative paths such as docs/example.jpg so they render on GitHub.

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.
• Run php -l server/data-checker.php when the CRON checker changes.
• Run php -l server/functions.inc.php when shared helpers change.
• 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.
• Verify the CRON checker stays silent when data/YYYY.jsonl is missing, empty, younger than 45 minutes, or older than 3 hours and 45 minutes.
• Verify the CRON checker walks backward to the nearest valid JSON line when the last line is invalid.
• For notification changes, verify that Telegram messages are sent only when level1..level4 differ from the previous saved measurement.
• Verify invalid level combinations such as 0100, 1010, and 1101 produce the measurement error notification without causing an HTTP error.

Before committing documentation changes:

• Verify every image referenced from README.md exists under docs/.
• Verify hardware details in README.md match arduino/arduino.ino.
• Verify server behavior in README.md matches server/log.php, server/data-checker.php, and server/functions.inc.php.

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.