This is the documentation map. The root README.md is the short router that points you at one of three setup paths; this page lists everything.
Documentation is split by audience:
- docs/user/ — start here for setup, everyday operation and help.
- docs/technical/ — architecture, internals and reference.
- docs/developer/ — source checkout, tests, CI and design notes.
Normal users should start with User documentation. Use Technical reference only when you need deeper behavior or implementation details. Use Developer documentation only for source checkout, tests, local builds and contributing.
Admin Console, Docker Bootstrap and the appliance image are the three user setup
paths; all converge on the same standard config/config.json layout. The
appliance is not confirmed on physical hardware -- see
what that means. Developer Setup is a
source-checkout path for development and contributing, not a normal user setup.
| Path | Audience | Start here |
|---|---|---|
| Admin Console | Most users | Admin Console |
| Docker Bootstrap | Shell-only Docker users | Docker Bootstrap |
| Appliance image | A Raspberry Pi dedicated to EMS — Pi 3, 3B+, 4 or 5 | Appliance guides |
| Developer Setup | Developers and contributors only | Developer Setup |
Setup, everyday operation and help. Normal users only need this section. user/index.md is the "Start here" landing page.
Screenshot-led walkthroughs. Each states what you see, what to select, what it changes, and what to do when the result differs.
| Area | Document | Use |
|---|---|---|
| Admin Console | user/admin/index.md | First start, Guided Setup, Guided Upgrade, Maintenance, devices, MQTT, backups, recovery. |
| EMS Dashboard | user/dashboard/index.md | Overview, device cards, energy, control pipeline, runtime settings, diagnostics. |
The three paths named under Operating models, in detail.
The first two install onto a machine you already run and converge on the same
standard config/config.json layout; the third is a whole system.
| Model | Document | Use |
|---|---|---|
| Admin Console | user/admin-console.md | Recommended browser-guided setup, discovery, maintenance, updates and backups. |
| Docker Bootstrap | user/docker-bootstrap.md | Shell-only Docker install without the browser wizard. |
| Appliance image | user/appliance/index.md | A flashed Raspberry Pi that runs EMS and nothing else, and updates itself. |
| Topic | Document | Use |
|---|---|---|
| Admin setup | user/admin-setup.md | "Set up a new system" flow: discovery, config generation and apply. |
| Admin maintenance | user/admin-maintenance.md | "Manage my existing system" flow: guided upgrade, overview, config editor, backup. |
| Backup and restore | user/admin-backup-restore.md | Preview-first backup and restore from the Admin Console. |
| Topic | Document | Use |
|---|---|---|
| Quickstart | quickstart.md | Docker-first beginner setup from install check to dashboard. |
| First-run checklist | first-run-checklist.md | Safe validation sequence after the first config edit. |
| Common commands | common-commands.md | Daily Docker-first command sheet with native equivalents. |
| Config layout | user/config-layout.md | Standard config/config.json layout and legacy migration. |
| Hardware requirements | user/hardware-requirements.md | RAM, storage and which Raspberry Pi models fit which install shape. |
| Supported setups | user/supported-setups.md | Whether your grid meter and devices fit EMS. |
| Connection types | user/connection-types.md | Local API, Local MQTT and Zendure cloud MQTT — which hardware fits which. |
| FAQ | user/faq.md | Short answers for Admin, Docker, the appliance, config, dashboard, backups and updates. |
| Troubleshooting | user/troubleshooting.md | Short, Admin-first guide for common problems. |
| Safety | user/safety.md | Simple pre-live checklist for hardware writes. |
| Topic | Document | Use |
|---|---|---|
| Install Docker | install-docker.md | Docker Engine and Compose plugin install help. |
| Docker reference | docker.md | Compose reference, first-run bootstrap and persisted data. |
| Native Python / advanced | native-python.md | Manual venv setup with local config and dry-run checks. |
| Standalone dashboard | dashboard.md | Read-only live dashboard, Control Explain view and history. |
| Home Assistant | home-assistant.md | Optional HA publishing, helpers and sensors. |
| Winter mode | winter-mode.md | Optional winter minSoc ramp and reconciliation. |
| Battery full-charge assist | battery-full-charge-assist.md | Optional EMS-managed full-charge assist. |
| Quality and maintenance | quality-and-maintenance.md | How the project is tested, packaged and maintained. |
Technical reference. For flashing a card and everyday use, see the appliance user guides.
Host management and recovery for a Raspberry Pi appliance. It runs as systemd services outside Docker and stays reachable when the EMS Admin container, the Docker daemon or EMS itself are unavailable. It never edits EMS configuration.
| Topic | Document | Use |
|---|---|---|
| Architecture | appliance/architecture.md | Product boundaries, the two host services and the operation model. |
| Installation | appliance/installation.md | Supported Raspberry Pi models, the .deb, the layout and first-run setup. |
| Admin recovery | appliance/admin-recovery.md | Install, reinstall, repair and roll back the EMS Admin container. |
| Console recovery | appliance/console-recovery.md | The rescue account and its documented password, and the order of attempts when the appliance will not come up. |
| OS updates | appliance/os-updates.md | Security updates, full updates, package-manager recovery, and the Appliance Manager's own signed-package update and its deadline. |
| Hardware gate | appliance/hardware-validation.md | The physical Raspberry Pi cases the image is not claimed without, and the authority on what is still NOT RUN. |
| SSH and backup access | appliance/ssh-backup-access.md | SSH keys and the read-only, chroot-confined ems-backup account. SFTP only — rsync and scp are refused. |
| Network recovery | appliance/network-recovery.md | WLAN with automatic revert, hostname changes and lockout recovery. |
| Security model | appliance/security-model.md | The privilege boundary, the operation allowlist and secret handling. |
| Manager releases | appliance/manager-releases.md | Cutting, signing and publishing the package that is the appliance web interface, and what the index carries so an operator can go back. |
| Troubleshooting | appliance/troubleshooting.md | Symptom-driven recovery and the error codes you may see. |
| Decision records | appliance/adr/ | Why the appliance is shaped the way it is. |
Architecture, internals and reference. You do not need this for a normal setup.
| Topic | Document | Use |
|---|---|---|
| Architecture | technical/architecture.md | Project structure and runtime component boundaries. |
| Admin architecture | technical/admin-architecture.md | Admin Console = UI/orchestration, Docker Bootstrap layout, EMS/Core as source of truth. |
| Admin discovery | technical/admin-discovery.md | Full Admin Console internals: wizard, release/build identity, discovery, Docker setup, security. |
| System-build pairing | technical/system-build-pairing.md | Admin and EMS as one paired system build: pair identity, alignment, embedded resources, known-good. |
| Admin workflow state | technical/admin-workflow-state.md | Persisted workflow-state inventory, config write paths, transition matrix and abandonment invariants. |
| Configuration | technical/configuration.md | Static config.json keys, safety flags, devices, grid meters and winter settings. |
| Configuration examples | configuration-examples.md | Copy/paste starting points for standalone, HA, dry-run and live writes. |
| Control logic | technical/control-logic.md | Target calculation, filtering, allocation and write suppression. |
| Control flow | technical/control-flow.md | Visual map of where config values affect one control cycle. |
| Runtime state | technical/runtime-state.md | Mutable operator state and fields changed by CLI or HA helpers. |
| Safety model | technical/safety-model.md | Write gates, runtime write types and the Zendure fields EMS writes. |
| Troubleshooting reference | technical/troubleshooting-reference.md | Command-level diagnostics, log events and deeper failure analysis. |
| Backup/restore internals | technical/backup-restore.md | CLI backup, dry-run restore checks, encrypted backups and full restore. |
| Analytics / InfluxDB | technical/influxdb.md | Optional long-range analytics with bundled or external InfluxDB. |
| Dashboard performance | technical/dashboard-performance.md | Live-path render gating, SSE recovery, static caching, and the measured cost of the flow animation. |
| CLI reference | cli.md | Full emsctl.py reference for runtime-state, diagnostics, config and backups. |
| Observed firmware behavior | observed-firmware-no-energy-path.md | Observed Zendure behavior when no energy path is available. |
For contributors and maintainers. Git clone and build-from-source belong here.
| Topic | Document | Use |
|---|---|---|
| Agent rules | developer/agent-rules.md | Canonical project-wide rules for coding agents and maintainers. |
| Developer setup | developer/developer-setup.md | Source checkout, venv, local config and dry-run validation. |
| Development notes | developer/development.md | Module layout and developer workflow. |
| Developer notes | developer/developer.md | Additional development and maintenance context. |
| Testing | developer/testing.md | Compile checks, self-test, simulation and the pytest suite. |
| MQTT write-latency probe | developer/mqtt-write-latency-probe.md | On-hardware tool measuring how fast an MQTT outputLimit write reaches the inverter. |
| CI / release | developer/ci-release.md | Continuous integration, image publishing and release archives. |
| Third-party licenses | ../THIRD_PARTY_LICENSES.md | Full inventory of runtime, development, vendored, optional and container dependencies. |
| Dashboard style guide | developer/dashboard-style-guide.md | Dashboard UI style conventions. |
| Design notes | developer/design-notes/ | Development tools and deeper design notes. |