{"id":51777387,"url":"https://github.com/srcfl/ftw","last_synced_at":"2026-07-20T07:04:42.236Z","repository":{"id":350908883,"uuid":"1208673229","full_name":"srcfl/ftw","owner":"srcfl","description":"FTW — local-first home energy coordination for solar, batteries, grid, and EV charging.","archived":false,"fork":false,"pushed_at":"2026-07-16T11:59:26.000Z","size":49519,"stargazers_count":11,"open_issues_count":19,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-07-16T12:22:29.312Z","etag":null,"topics":["battery-storage","energy-management","ev-charging","golang","home-assistant","home-energy-management","lua","raspberry-pi","self-hosted","solar-energy","sourceful"],"latest_commit_sha":null,"homepage":"https://ftw.sourceful.energy","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srcfl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-12T15:47:50.000Z","updated_at":"2026-07-16T10:57:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"b97e85be-93fb-4f2f-90f2-048c0e4e085f","html_url":"https://github.com/srcfl/ftw","commit_stats":null,"previous_names":["frahlg/home-ems","srcfl/ftw"],"tags_count":235,"template":false,"template_full_name":null,"purl":"pkg:github/srcfl/ftw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fftw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fftw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fftw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fftw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srcfl","download_url":"https://codeload.github.com/srcfl/ftw/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fftw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35676395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["battery-storage","energy-management","ev-charging","golang","home-assistant","home-energy-management","lua","raspberry-pi","self-hosted","solar-energy","sourceful"],"created_at":"2026-07-20T07:04:41.588Z","updated_at":"2026-07-20T07:04:42.221Z","avatar_url":"https://github.com/srcfl.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FTW\n\n\u003cimg src=\"web/logo.svg\" alt=\"FTW\" width=\"120\" align=\"right\"\u003e\n\n\u003e Local-first home energy coordination.\n\nFTW coordinates solar, batteries, grid power, EV charging and thermal assets\non a Raspberry Pi or Linux host. The safety-critical runtime is one Go binary,\nhardware integrations are sandboxed Lua drivers, and an optional Python/CVXPY\noptimizer handles long-horizon planning.\n\nThe control path stays on the local network. Cloud price, weather and device\nintegrations degrade independently; they are not required for safe local\noperation.\n\nFTW Community is Apache-2.0 software maintained by Sourceful Energy and project\ncontributors. Community help is best effort. See [SUPPORT.md](SUPPORT.md) for\nthe boundary between community use and separate commercial services.\n\n## Architecture\n\nFTW has three explicit modules:\n\n- **Core** owns configuration, telemetry, state, safety, dispatch, API and UI.\n- **Drivers** translate vendor protocols and power signs in isolated Lua VMs.\n- **Optimizer** proposes plans over a versioned contract; core validates every\n  result and keeps a Go fallback.\n\nThis separation lets drivers and the optimizer evolve independently without\nmoving safety authority out of core. New module types should follow the same\nrule. See [docs/architecture.md](docs/architecture.md).\n\n## Capabilities\n\n- self-consumption, peak shaving and explicit grid targets;\n- multi-battery allocation with fuse, SoC, slew and stale-data protection;\n- price-, weather-, PV- and load-aware planning;\n- EV charging, V2X and thermal planning;\n- local web UI, SQLite history and Parquet rolloff;\n- Home Assistant MQTT discovery;\n- CalDAV planning intents and published schedules;\n- hot-reloadable, independently released Lua drivers.\n\nThe current device catalog is generated from the `DRIVER` metadata in\n[`drivers/*.lua`](drivers/); that source is authoritative.\n\n## Install on Linux\n\nThe installer supports Raspberry Pi OS, Debian and Ubuntu:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/srcfl/ftw/master/scripts/install.sh | bash\n```\n\nIt installs Docker when needed, creates `~/ftw`, downloads the Compose file\nand starts core, optimizer, updater and the local MQTT broker. Open\n`http://\u003chost\u003e:8080/setup` on the LAN.\n\nExisting Forty Two Watts or older FTW deployments must use the\n[legacy upgrade guide](docs/upgrade-from-legacy.md) so configuration and state\nare preserved. Raspberry Pi image installation is covered by\n[docs/rpi-image.md](docs/rpi-image.md).\n\nThe dashboard is intentionally local. Use a VPN or another operator-managed\nprivate network when access is needed away from home; FTW does not ship a\npublic relay.\n\n## Local development\n\nRequirements are Go, Python 3 and Node.js. The optimizer environment is cached\nafter its first install.\n\n```bash\ngit clone https://github.com/srcfl/ftw.git\ncd ftw\nmake dev\n```\n\nUseful checks:\n\n```bash\nmake test      # Go + Python, parallel where independent\nnpm test       # web\nmake verify    # fast test, compose, vet and build checks\nmake e2e       # simulator-backed full stack\nmake ci        # e2e, builds and browser smoke\n```\n\nSee [docs/development.md](docs/development.md) for the small set of development\nworkflows.\n\n## Configuration\n\n`config.example.yaml` and the validation types in `go/internal/config` are\nthe configuration reference. Copy the example for a native development setup:\n\n```bash\ncp config.local.example.yaml config.local.yaml\n```\n\nPower values above a driver use one convention: positive means into the site,\nnegative means out. Drivers alone translate vendor conventions. Read\n[docs/site-convention.md](docs/site-convention.md) before editing power math or\nwriting a driver.\n\n## Drivers\n\nDrivers are plain Lua files and need no compilation. A driver declares its\ncatalog metadata, lifecycle and required capabilities in one file. The Go host\nprovides capability-scoped Modbus, MQTT, HTTP, WebSocket and TCP access.\n\nStart with [docs/writing-a-driver.md](docs/writing-a-driver.md). Signed driver\nartifacts use the same `beta` → `stable` progression as core and can be\ninstalled or rolled back independently.\n\n## Releases\n\nThere are two channels:\n\n- **beta** receives new release candidates for real-site validation;\n- **stable** promotes the exact commit already published and tested as beta.\n\nThere is no edge channel. Changesets produce versions and changelog entries;\nGitHub Actions builds the binaries, containers and installer assets. Details\nfor operators and maintainers are in [docs/self-update.md](docs/self-update.md).\n\n## Documentation\n\nThe repository deliberately keeps prose small. Code, types, tests and driver\nmetadata are the detailed reference.\n\n- [Architecture](docs/architecture.md)\n- [Power sign convention](docs/site-convention.md)\n- [Safety invariants](docs/safety.md)\n- [Operations and recovery](docs/operations.md)\n- [Full backup and safe restore](docs/backup-and-restore.md)\n- [Writing a driver](docs/writing-a-driver.md)\n- [Self-update and release channels](docs/self-update.md)\n- [Home Assistant](docs/ha-integration.md)\n- [CalDAV](docs/caldav-integration.md)\n\nOther files under `docs/` are focused installation or external-integration\nguides.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md). User-visible changes need a Changeset.\n\nApache-2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrcfl%2Fftw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrcfl%2Fftw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrcfl%2Fftw/lists"}