Start
Documentation
Start here to find the right page. The docs are grouped by what you want to do: use Wellfed, understand how it works, learn the hardware, or help build it.
Every finding carries an evidence level that says how we know it. Outside sources are listed in references. A documented finding is not a request to repeat an experiment. Historical bench diaries and raw evidence live outside this repository.
Using Wellfed#
| Page | What it covers |
|---|---|
| Roadmap | What works today and what comes next |
| Glossary | The words the rest of the docs use without explaining |
| Supported devices | Which feeders Wellfed runs on |
| Consumer installation | Moving a stock feeder to Wellfed over the air, and going back |
How it works#
The firmware docs describe Wellfed's own replacement, which isn't tied to one device.
| Page | What it covers |
|---|---|
| Product architecture | The product we are building toward, and why each choice was made |
| Firmware architecture | How the replacement firmware is put together |
| Device API | The feeder's encrypted local API |
| Pairing | Keys, randomness and how clients pair |
| Bluetooth | Bluetooth LE and setup mode |
| OTA design | Over-the-air updates |
| Bank policy | Which bank boots, and how a trial image is confirmed |
| Startup diagnostics | What every boot checks before firmware code runs |
| QA firmware | The guided self-test image |
| Resource budget | Flash, RAM and task limits of the product image |
| Device layer | Where the board's assumptions live, so a second model can be added |
| The server | What the optional server adds, running it, and how it's built |
| Web UI design | The server's browser UI |
| well-fed.dev | The project's landing page |
| docs.well-fed.dev | This documentation as a website |
Feeder components:
| Page | What it covers |
|---|---|
| Motor pulse | The supervised motor drive |
| Portions and calibration | Counting portions and calibrating them |
| Jams and sensor faults | What happens when food or feedback goes missing |
| Optical inputs | The food, outlet and feedback sensors |
| Buttons | Panel buttons and gestures |
| Indicators | The panel lights |
| Audio | The speaker and built-in tunes |
| Clock | Wall clock, offline time and missed time |
| Power | The supply, the battery floor, brownout and sleep |
Hardware#
Facts about a chip hold for every board built on it. Facts about a device hold for one feeder model and its stock firmware. Adding a model adds a folder under devices/ and reuses the rest.
| Page | What it covers |
|---|---|
| PLAF103 | The feeder: identification, chips and feature support |
| Board and signal map | What each chip pin connects to |
| Motor driver | The motor driver and its electrical checks |
| UART | Console wiring and loader entry |
| Flash layout | Boot flow and what lives where in flash |
| Recovery | The experimental UART recovery writers |
| Relay bench | Powering and flashing the feeder from the bench |
| Stock behavior and protocol | What stock firmware 1.1.15 does |
| Stock OTA requirements | What stock's updater accepts |
| RTL8721DM (AmebaD) | The SoC and its SDK |
| RTL8721DM pins | Each pin's job on each device |
| Device template | The starting point for a new device folder |
Contributing#
| Page | What it covers |
|---|---|
| Development setup | Toolchain, check targets and fuzzing |
| Writing docs | How these docs are written |
| Rust standard | Rules for every Rust crate |
| TypeScript standard | Rules for the web frontends |
| SDK builds | Full firmware images with the vendor SDK |
| Stock server | The bench's server for stock 1.1.15 |
| Rust flash client | Reading and writing flash over UART |
| UART development updates | Faster region-scoped updates during development |
| Optional fixtures | Checks that need private binary inputs |
| Import provenance | Where the first code came from |
| Host tools | Every host tool and what it does |
| Firmwares | Every firmware crate and how to build one |