Intial commit

2026-08-27 22:16:23 +03:00
commit a5963c9ed6
12 changed files with 3178 additions and 0 deletions
@@ -0,0 +1,240 @@
+# AGENTS.md
+
+## Purpose
+
+This repository contains firmware and a web application for an ESP32-C6 Mini built with Visual Studio Code and PlatformIO.
+
+These instructions are intended for Codex and other coding agents working in this repository. Prefer small, reviewable changes and keep the firmware suitable for a resource-constrained embedded device.
+
+## Sources and instruction scope
+
+- Treat every file under `sources/` as read-only reference material.
+- Do not edit, rename, move, or delete files under `sources/`.
+- Files under `sources/` may be replaced when the ChatGPT project is synchronized.
+- A more deeply nested `AGENTS.md`, if present, takes precedence for files in its directory tree.
+- Read `MVP.md` before making architectural or gameplay changes.
+- Once present, treat `platformio.ini` as the source of truth for the PlatformIO environments, board identifier, framework, build flags, dependency versions, flash layout, and upload settings.
+- Do not assume that every board sold as “ESP32-C6 Mini” has the same flash size, pinout, LED polarity, or PlatformIO board identifier.
+
+## Expected project layout
+
+Use the conventional PlatformIO layout unless the existing project deliberately uses another structure:
+
+```text
+.
+├── platformio.ini          # PlatformIO environments and dependencies
+├── include/                # Public project headers
+├── src/                    # Firmware sources and main.cpp
+├── lib/                    # Project-specific reusable libraries
+├── data/                   # LittleFS web assets
+├── test/                   # PlatformIO unit tests
+├── scripts/                # Build and validation helpers
+├── MVP.md                  # Product and architecture requirements
+└── AGENTS.md               # Repository instructions
+```
+
+Do not edit generated content under `.pio/`. Do not commit build products, serial logs, local secrets, or editor-specific temporary files.
+
+## Working method
+
+Before editing:
+
+1. Read the relevant requirements and existing implementation.
+2. Inspect `platformio.ini` and use an existing environment instead of inventing one.
+3. Search for repository conventions, existing abstractions, and tests.
+4. Identify whether the change affects firmware, browser assets, the API contract, stored data, or hardware configuration.
+
+While editing:
+
+- Make the smallest coherent change that satisfies the request.
+- Preserve unrelated user changes and avoid broad formatting rewrites.
+- Keep hardware-specific values in configuration rather than scattering them through the code.
+- Update documentation and tests when behavior or public interfaces change.
+- Do not add a dependency when a small, clear implementation using the existing stack is sufficient.
+- Pin third-party PlatformIO dependencies to known compatible versions in `platformio.ini`.
+- Never patch dependency sources inside `.pio/libdeps`.
+
+After editing:
+
+1. Run the narrowest relevant tests.
+2. Build every affected PlatformIO environment.
+3. Check compiler output for new warnings, memory pressure, and image-size regressions.
+4. Summarize what changed, what was verified, and anything that still requires physical hardware.
+
+## PlatformIO commands
+
+Use the repository's actual environment names. List environments or inspect `platformio.ini` before supplying `-e <environment>`.
+
+Common non-destructive checks:
+
+```sh
+pio run
+pio run -e <environment>
+pio test
+pio test -e <test-environment>
+pio run -t size
+```
+
+Use project-provided formatting, linting, or validation scripts when available. Do not invent a formatting command without checking the repository configuration.
+
+The following operations affect connected hardware and must only be performed when the user asks for them or clearly authorizes hardware interaction:
+
+```sh
+pio run -e <environment> -t upload
+pio run -e <environment> -t uploadfs
+pio device monitor
+pio run -t erase
+```
+
+Treat flash erase as destructive. Confirm the target device and environment before uploading or erasing. Never leave a serial monitor running indefinitely.
+
+## Firmware design rules
+
+### Architecture
+
+- Keep domain logic independent from Arduino callbacks and transport code where practical.
+- Separate Wi-Fi, HTTP/WebSocket transport, session handling, persistence, device control, and application logic.
+- Route all state-changing requests through a single validated application layer.
+- Keep the ESP32 authoritative. Browser-side validation improves usability but must not enforce the only copy of a rule.
+- Use explicit state machines for multi-step workflows rather than loosely related Boolean flags.
+- Keep public headers small and avoid unnecessary global state.
+
+### Memory and performance
+
+- Prefer fixed-size arrays, fixed-width integer types, bounded buffers, and predictable ownership.
+- Avoid unbounded `String` concatenation, repeated heap allocation, large temporary JSON documents, and unnecessary copies.
+- Set explicit limits for sessions, WebSocket clients, request bodies, queue sizes, names, and messages.
+- Parse all external input with bounds checks.
+- Stream or serve files from LittleFS instead of embedding large duplicate assets in RAM.
+- Measure rather than guess when changing task stacks, JSON capacity, filesystem partitions, or connection limits.
+- Check final flash and RAM usage after meaningful changes.
+
+### Timing and responsiveness
+
+- Avoid long blocking calls and long `delay()` operations.
+- Use `millis()`-based scheduling, timers, queues, or tasks for delayed work.
+- Keep HTTP, WebSocket, timer, and interrupt callbacks short.
+- Never perform filesystem writes, large serialization, or expensive game logic in an interrupt service routine.
+- Ensure the main loop and network stack remain responsive under reconnects and multiple clients.
+- Add timeouts to network and peripheral operations.
+
+### Concurrency
+
+- Document which task or callback owns mutable state.
+- Protect state shared between callbacks or FreeRTOS tasks with an appropriate mutex, queue, or critical section.
+- Do not hold locks while sending network data or performing slow I/O.
+- Prefer taking a bounded snapshot before serializing state for clients.
+- Make repeated requests idempotent where retries are expected.
+
+### C++ conventions
+
+- Follow the C++ standard and warning flags configured by the project.
+- Use `enum class`, `constexpr`, `const`, fixed-width integers, and RAII where supported.
+- Prefer clear value types and explicit ownership over raw heap allocation.
+- Check return values from Wi-Fi, filesystem, JSON, and server operations.
+- Avoid macros except for compile-time configuration, platform compatibility, or logging wrappers.
+- Keep functions focused and name units in identifiers when values represent milliseconds, bytes, volts, or similar quantities.
+- Do not enable exceptions or RTTI unless the project already uses and budgets for them.
+
+### Logging and errors
+
+- Use consistent log levels and concise messages.
+- Never log Wi-Fi passwords, session tokens, private payloads, or other credentials.
+- Avoid high-frequency logs in normal operation.
+- Return stable machine-readable error codes from APIs and separate them from Russian user-facing messages.
+- Fail safely: reject invalid commands without partially modifying application state.
+
+## Wi-Fi and configuration
+
+- The ESP32-C6 Mini operates as a station on the home Wi-Fi network unless requirements say otherwise.
+- Keep SSIDs, passwords, tokens, certificates, and private endpoints out of tracked source files.
+- Store local secrets in a gitignored file or inject them through build-time configuration.
+- Provide a tracked example file with placeholder values when setup would otherwise be unclear.
+- Never replace real credentials or erase device configuration unless explicitly requested.
+- Reconnect with bounded exponential backoff; do not block the application indefinitely while Wi-Fi is unavailable.
+- The application must handle a changing DHCP address. mDNS may be added as a convenience but must not be the only documented access method unless verified on the target network.
+
+## Web server and browser application
+
+- Store required HTML, CSS, and JavaScript locally in `data/` so the application does not depend on internet access or a CDN.
+- Prefer framework-free browser code for small interfaces. Justify large client dependencies by a concrete requirement.
+- Keep the HTTP API versionable and document changes to request and response schemas.
+- Validate authentication token, role, current state, game ID, coordinates, lengths, and content type on the server.
+- Generate role-specific responses. Never send hidden or privileged state and rely on CSS or JavaScript to conceal it.
+- Escape user-provided text before rendering it in HTML.
+- Use WebSocket for immediate updates and provide the HTTP polling fallback required by `MVP.md`.
+- Implement reconnect backoff, heartbeat handling, state versioning, and full resynchronization after missed events.
+- Avoid broadcasting one privileged payload to all clients; construct a safe view for each role.
+- Set appropriate cache headers. Do not cache personalized API responses.
+- Compress static assets during the build when supported, but keep the uncompressed sources maintainable.
+- Design touch interactions for phones and tablets. Do not rely on hover or color alone.
+
+## Filesystem and persistence
+
+- Treat LittleFS layout and the flash partition table as part of the product configuration.
+- Check mount failures and report them clearly; do not silently format a filesystem unless the product explicitly requires that behavior.
+- Use atomic replace patterns for important persisted files where possible.
+- Minimize flash writes and avoid writing frequently changing counters on every event.
+- The MVP keeps active game state and statistics in RAM and resets them after reboot, as specified in `MVP.md`.
+
+## Testing expectations
+
+### Host or native tests
+
+Keep pure application logic buildable without ESP32 hardware where practical. Unit-test at least:
+
+- state transitions;
+- bounds and malformed input;
+- game or domain rules;
+- random-generation invariants;
+- serialization and role-specific data filtering;
+- retry and idempotency behavior;
+- bot or automation logic.
+
+Use a deterministic random seed in tests and do not use the production seed as an assertion target.
+
+### Device tests
+
+Features involving Wi-Fi, LittleFS, WebSocket, timing, heap behavior, or peripherals require a final device check. When hardware is available, verify:
+
+- cold boot and reconnect behavior;
+- static asset loading from LittleFS;
+- multiple simultaneous clients;
+- WebSocket loss and HTTP fallback;
+- repeated workflows without heap degradation;
+- flash/RAM usage and watchdog stability;
+- operation on the exact ESP32-C6 Mini variant.
+
+Do not claim device verification when only a local build or host test was performed.
+
+## Security and robustness
+
+- Treat every HTTP, WebSocket, serial, and persisted value as untrusted input.
+- Reject oversized, malformed, stale, unauthorized, and out-of-state requests.
+- Use cryptographically strong random session tokens when the platform API provides suitable entropy.
+- Do not put credentials in browser assets, logs, examples, tests, or error responses.
+- Avoid undefined behavior, unchecked indexing, integer overflow, and unsafe string functions.
+- Add rate or queue limits where one client could exhaust device memory or monopolize processing.
+- A home network is not a security boundary. Document any deliberately simplified MVP security assumptions.
+
+## Documentation
+
+- Keep setup steps reproducible for a new developer using VS Code and PlatformIO.
+- Document the exact board variant, USB/serial behavior, flash size, PlatformIO environment, filesystem upload step, and access URL once known.
+- Update `MVP.md` only when product scope or agreed behavior changes.
+- Update API documentation whenever routes, messages, events, error codes, or authorization rules change.
+- Record hardware-only verification steps rather than implying they were automated.
+
+## Definition of done
+
+A change is complete when all applicable conditions are met:
+
+- The requested behavior is implemented with no unrelated changes.
+- Affected PlatformIO environments build successfully.
+- Relevant automated tests pass.
+- No new compiler warnings or exposed secrets are introduced.
+- Input bounds, failure paths, reconnects, and role permissions are handled.
+- Flash and RAM impact are acceptable for the target ESP32-C6 Mini.
+- Web assets work without an external internet dependency.
+- Documentation and examples reflect the new behavior.
+- Any remaining physical-device checks are explicitly listed in the handoff.