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

```sh
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.