Added agent.md to make ai workflows more efficient and save tokens (#15)
Reviewed-on: #15
This commit was merged in pull request #15.
This commit is contained in:
@@ -0,0 +1,91 @@
|
||||
# Agent guide
|
||||
|
||||
Use this file as the first-pass context for changes in this package. Read only
|
||||
the module(s) relevant to the task; the public interfaces in `src/*.h` usually
|
||||
provide enough context before opening an implementation.
|
||||
|
||||
## Project in one paragraph
|
||||
|
||||
openUF is a single-process C daemon for OpenWrt. It makes an OpenWrt access
|
||||
point look like a UniFi AP: `main.c` periodically sends L2 discovery, LLDP, and
|
||||
encrypted HTTP inform packets. Controller responses can update persistent
|
||||
adoption state and apply WiFi configuration through UCI. There is no internal
|
||||
threading or event framework; the main loop runs once per second.
|
||||
|
||||
## Source map
|
||||
|
||||
| Concern | Start here | Responsibility |
|
||||
| --- | --- | --- |
|
||||
| Lifecycle and scheduling | `src/main.c` | Load config/state, choose model, run announce/inform/LLDP timers |
|
||||
| User configuration | `src/config.[ch]`, `files/openuf.conf` | Parse static daemon settings and defaults |
|
||||
| Persistent controller state | `src/state.[ch]` | Read/write `/etc/openuf/state.json` |
|
||||
| Inform/adoption protocol | `src/inform.[ch]` | Build telemetry, encode TNBU packets, handle controller commands |
|
||||
| Transport and encryption | `src/http.[ch]`, `src/crypto.[ch]` | Raw HTTP/1.0 client and AES-CBC/AES-GCM helpers |
|
||||
| WiFi provisioning | `src/wlan.[ch]` | Translate controller config to UCI and report VAP state |
|
||||
| Device telemetry | `src/sysinfo.[ch]`, `src/clients.[ch]` | Read proc/sysfs/`iw`/bridge/dnsmasq data |
|
||||
| Discovery/topology | `src/announce.[ch]`, `src/lldp.[ch]` | UniFi UDP announce and LLDP send/read |
|
||||
| Emulated hardware | `src/models.c`, `src/ufmodel.h` | Model registry, radios, ports, and band-to-radio mapping |
|
||||
| Packaging/service | `Makefile`, `files/openuf.init` | OpenWrt package recipe and procd service |
|
||||
|
||||
Runtime flow: `main()` -> `inform_send()` -> build telemetry -> encrypt ->
|
||||
`http_post()` -> decrypt response -> `handle_response()` -> optionally
|
||||
`wlan_apply_config()`/`wlan_apply_system_cfg()` and `state_save()`.
|
||||
|
||||
## Important invariants
|
||||
|
||||
- Treat the TNBU packet layout, byte order, flags, and key selection as protocol
|
||||
compatibility constraints. An unadopted device must use `DEFAULT_AUTH_KEY`.
|
||||
- `cfgversion` means successfully applied controller configuration. On an apply
|
||||
failure it is reset to `"0"` so the controller retries.
|
||||
- Increment `OPENUF_CONFIG_SCHEMA` when a persisted configuration must be
|
||||
reapplied after an upgrade.
|
||||
- Only WiFi sections managed by this daemon may be removed. Their names start
|
||||
with `openuf_`; preserve unrelated UCI sections.
|
||||
- Keep model-specific radio and port assumptions in `models.c`, not scattered
|
||||
across protocol or WLAN code.
|
||||
- Logging is opt-in because persistent writes wear flash. Debug level 2 may log
|
||||
decrypted credentials; never enable it by default or expose full auth keys.
|
||||
- This daemon runs as root and can change network config, send raw frames, and
|
||||
reboot. Do not run it on a development host as a test.
|
||||
- The target uses OpenWrt/musl and constrained hardware. Prefer bounded buffers,
|
||||
explicit ownership, no new heavy dependency, and no background thread unless
|
||||
the design requires one.
|
||||
|
||||
## Build and validation
|
||||
|
||||
The primary validation is the package cross-build. From the OpenWrt root (two
|
||||
directories above this package), run:
|
||||
|
||||
```sh
|
||||
make package/OpenUniFi/compile
|
||||
```
|
||||
|
||||
Use `V=s` when compiler diagnostics need more context. Avoid a top-level
|
||||
`make clean`; if a clean rebuild is necessary, use:
|
||||
|
||||
```sh
|
||||
make package/OpenUniFi/clean
|
||||
make package/OpenUniFi/compile
|
||||
```
|
||||
|
||||
`Makefile.standalone` is for compiling on an OpenWrt device with development
|
||||
packages installed; it is not a host-side substitute for the cross-build.
|
||||
There is currently no automated test suite. For documentation-only changes,
|
||||
check paths and commands against the source and package Makefile. For C changes,
|
||||
the cross-build is the minimum verification; report any device/controller
|
||||
behavior that still needs manual testing.
|
||||
|
||||
## Change discipline
|
||||
|
||||
- Keep headers as the concise contract and implementation detail in `.c` files.
|
||||
- Update `Makefile` and `Makefile.standalone` together when adding/removing a
|
||||
source file or library.
|
||||
- Update `files/openuf.conf`, `config.[ch]`, and the README together when changing
|
||||
a user-facing setting.
|
||||
- Update `ufmodel.h`, every affected model entry, and telemetry/WLAN consumers
|
||||
together when changing model data.
|
||||
- Preserve controller compatibility unless the task explicitly changes it.
|
||||
Call out changes to payload fields, encryption, adoption, UCI, or persistent
|
||||
state in the handoff.
|
||||
- Do not commit generated binaries, OpenWrt build output, runtime state, logs, or
|
||||
captured protocol payloads.
|
||||
Reference in New Issue
Block a user