103 lines
5.3 KiB
Markdown
103 lines
5.3 KiB
Markdown
# 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.
|
|
- `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:
|
|
|
|
```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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|