FTW makes a home's energy equipment work together. It runs locally, plans ahead, controls against current measurements and shows what actually happened. Its default experience must be simple enough for a first-time user and good enough to earn the trust of someone who builds their own energy system.
The product is a lean core: FTW Core and the Energy Planner. They are the primitives an agent or another automation needs in order to work with the home's energy system. Home Assistant, MQTT and a database the owner runs for their own analysis sit on top. Core does not absorb those tools.
This is the product direction set by Fredrik. It guides design and review; it does not claim that every outcome below has shipped. The roadmap names the work and evidence needed to reach it. The architecture describes the running system.
Mixed makes and generations are a main use case: for example, an older SolarEdge inverter, a Pixii battery and a separate charger. Support must state which models, firmware, measurements and commands have been verified. A catalog entry alone is not proof that a device can be controlled.
FTW reasons from site physics: energy balance, storage capacity, conversion losses, equipment response and physical limits. Models and state estimation help it combine readings that arrive at different times and rates. They must retain the difference between a measurement, an estimate and missing data. Algorithms serve that result; their names are not a product promise.
The normal mode gives FTW authority to plan and control within the user's goals and the site's limits. It does not ask for approval on each action. Core validates every plan and command, including plans supplied by another system. Fuse, equipment, SoC, freshness and other quantified safety limits always apply. Stale required site-meter data stops dispatch.
Trust what you read, not what you sent.
For each device function FTW commands, such as a battery, a car charger, a solar cap or V2X, the normal view answers one question: is the device doing what FTW asked? A successful driver call, an API reply or an echoed setpoint does not prove a physical effect.
Core decides the answer and its urgency; clients only render it:
- Following FTW: fresh readings show the device doing what FTW asked.
- Waiting: a response is still due, or there is nothing to verify yet.
- Limited: the device follows within a known limit, such as a nearly full battery, the main fuse or a charger setting.
- Not following: fresh readings disagree with the command after the device's response time.
- No contact: readings or commands fail. Losing a device FTW had measured is an alarm.
- Not controlled: FTW only reads the device or has handed control back.
Show the evidence as a receipt, not as the headline: sent, accepted, measured and confirmed. Accepted means the driver took the command. Measured means fresh, distinct device readings across the response window. Confirmed means a separate physical meter saw the matching change. Keep the target separate: a battery can be confirmed at 4.4 kW against a 5 kW command, and the shortfall stays visible.
- Freshness follows the source. A slow cloud source stays current for as long as it declares; a repeated or cached sample never extends proof.
- Compare each reading with the commands that could still be in force during the response time. Retuning every tick is normal control, not a new test. A material step starts a new comparison.
- Confirmation needs a separate physical sensor, aligned readings and a clear step. Subtract other measured flows, and never let an unmeasured load disappear into an average. A confirmed step stays confirmed while the device keeps following with fresh readings.
- Explain a shortfall only with a fresh, relevant fact, such as state of charge or a reported limit. Say when the cause is unknown.
- Keep the overview quiet while FTW is in control. Mark warnings amber and alarms red, and clear them when fresh evidence shows recovery.
- Never change a power target just to create a test signal without the owner's consent.
- Give authorized agents and support reports the same evidence.
This is the product direction. Each implementation states which devices, paths and physical outcomes it has verified.
The live view is a core product feature. It must feel local and fast, and make these separate facts easy to follow:
- what the user, agent or planner requested;
- what Core accepted and why it changed or rejected a request;
- the command sent to a device and its response;
- the measured physical effect, its age and any delay or difference.
A sent command is not proof of a changed power flow. Smooth rendering must not make old readings look live. The normal Flow experience should carry this clarity; the user should not need a separate diagnostic tool to trust it. Whether the existing Live and Flow views become one view is a design decision to validate in the browser, not a requirement to keep two interfaces.
Show a failed integration and its effect in plain language. If battery control is not working, planning and dispatch must stop relying on that battery. Valid read-only telemetry may remain useful. Other devices may keep working when the required measurements and safety conditions still hold. Recovery must establish that control works again before relying on it.
Discovery should obtain what the equipment can report. Ask only for what FTW cannot establish reliably. The user must confirm the main fuse limit and FTW needs a working site meter before active control.
Ask for battery energy capacity in kWh when it cannot be read. Battery and inverter power ratings should not normally be required form fields: obtain verified device limits where available and learn the usable response within safe bounds. Advanced users may set limits explicitly. Do not treat an observed power level as proof of an absolute hardware or installation limit.
Develop the per-device battery and inverter model into a digital twin grounded in normal operation. Learn charge and discharge response, delay, usable power and losses under the observed state of charge, temperature and device mode. Keep energy capacity in kWh separate from power in kW. A 10 kWh battery may have a 5 kW inverter; reaching 5 kW says nothing by itself about its capacity. If user input conflicts with repeated measurements or device ratings, explain the conflict and propose a correction rather than silently changing that input.
Keep user input, reported limits and learned estimates distinct, with source, age, tested conditions and uncertainty. Prefer independently confirmed samples for learning, label device-only samples, and never train on an inferred site effect as though it were another meter. A plateau at one state of charge is evidence for those conditions, not a permanent nameplate limit. Learn capacity only from suitable energy and state-of-charge observations. Detect changed behaviour and rebuild confidence after equipment or mode changes. Use the model to plan achievable work within verified safety limits; learned estimates must never raise those limits or replace fresh measurements as proof of an effect. This is the target for the model, not a claim that the full twin has shipped.
For solar, the target is that "I have solar" is enough to start learning. Installed kWp is an optional starting estimate. Approximate user input must not permanently constrain a model when measurements support a better fit. Panel drawings, orientations and engineering knowledge are not prerequisites.
STRÅNG, roof geometry and panel drawing are outside the selected Core scope. They may serve a future optional extension if a concrete need warrants it; the module boundary and delivery are not decided. Normal setup must work without choosing an irradiance source, azimuth or panel layout.
Initial load and solar models must already support useful first-day planning. On-site learning improves them as evidence arrives. Elapsed days alone do not prove model quality; state uncertainty honestly and handle cold start.
Commissioning should include a short, controlled check of commands and physical response, within known limits and with fresh site measurements. Give the user a clear result showing what worked, what failed and what remains unverified. A quick response check is not full-range hardware qualification.
The default planner uses energy prices and charge/discharge efficiency. Battery wear cost defaults to zero. This is a deliberate product choice. Users may add a wear cost in settings; do not silently introduce one through another penalty or hidden preference.
Keep three concepts separate:
- Battery operating limits: user-configured min/max SoC and equipment limits remain binding.
- Forecast caution: extra reserve in a grid-connected home reflects expected future demand, supply and uncertainty, and how much the user wants to trust the forecast. It is not another fixed SoC floor.
- Explicit backup needs: an off-grid or backup use case may need a stated reserve floor. This policy does not by itself establish off-grid support.
Explain forecast caution through its effect on the plan. Users should be able to understand why FTW keeps energy for later without choosing model internals. Keep useful expert controls available, but require a clear need for each setting in the normal experience.
Plugging in should normally be enough. A persistent schedule can say "80% by 07:00 every weekday". FTW plans toward that need and reports when it cannot meet it. Cloud vehicle access must not be a prerequisite for charging.
An offline car is a supported product use case. When its SoC is unknown, use a stated default or estimate and distinguish it from a confirmed reading. After plugging in, opening the webapp should expose the car's SoC slider directly. Changing it needs no extra Save action; show the resulting plan as soon as Core accepts the change and replans. Keep pending and rejected changes visible.
"Charge now" takes one action. The rest of the site adapts within its limits. The user should not have to reconfigure battery policy to charge the car.
Notifications are part of the charging product. Tell the user promptly when charging fails or the goal is at risk, including when the app is closed. Explain the problem and take the user to the relevant action. An estimated SoC is not proof that the requested percentage was reached.
The energy system serves household comfort. The first heat-pump phase reads data to improve load forecasts and planning; it leaves comfort control with the heat pump. Batteries and other flexible assets adapt around those needs.
Later, support bounded heat storage where the installation makes it useful: for example, heating a buffer tank or hot water during cheap periods. That requires known storage and temperature bounds, a safe control path and a clear user goal. Do not make a detailed thermal model a setup requirement for every home, or turn data-only support into active heat control by implication.
FTW works on its own and also serves as a local core for Home Assistant, MQTT automation and agents. They can change goals, modes and charging schedules, and propose plans. They use Core's admission and safety checks.
Temporary external control has a watchdog limit. It must be renewed; on expiry FTW returns to its defined local automatic behaviour. Show who is currently directing the action and why. A durable schedule or user goal remains after its caller disconnects; it is not a control lease.
Agent first means a supported way to use FTW, not just agent-friendly source code. An authorized agent needs structured access to measurements, history, forecasts, plans, decisions, command results and actual outcomes for analysis. It must be able to change schedules and goals, submit a proposed plan and verify the result without operating the UI. Report freshness, provenance, rejection reasons and the distinction between acceptance and physical effect.
Local access and cloud MCP access are part of the direction. Reuse the webapp's encrypted session and relay where they fit; verify the fit before adding another transport. Access requires the user's authorization and must be revocable. The relay and escrow stay unable to read site data. An authorized cloud agent is an endpoint that can read the data the user grants it; do not describe that access as blind. The box keeps operating when the agent, MCP service or network is unavailable.
This document adds no new protocol operation, credential or access grant. New shared names belong in the contract registry and must ship with their validation and matching clients.
The intended main savings comparison is the same site with the same solar, battery, efficiency, limits, tariff and household needs under ordinary self-consumption control. It should estimate the benefit of FTW's coordination. The current comparison against no solar and no battery describes broader site value; it must not be presented as the incremental value of FTW.
Show actual grid cost and export revenue separately from the modelled comparison. A fair comparison needs stated charging behaviour, comparable starting stored energy, an account of ending stored energy and sufficient measurement and price coverage. Show negative results and missing evidence. Neither a forecast nor a replay is a measured alternative electricity bill.
Installation, settings, local and remote UI, diagnostics, updates and recovery are part of the product. Prefer fewer features that work together and fewer decisions required from the user. Preserve useful expert access and flexible Lua drivers. Removing a setting also requires handling its persisted state; hiding it must not leave an old policy active without explanation.
Choose the design with the least total complexity. A smaller Core that needs more services, contracts and deployment steps may make the product harder. Require a concrete reason for a new module or general framework.
Scope exclusions will be decided as needs arise. There is no standing list of banned protocols or features. A roadmap entry, green CI or available agent capacity does not by itself establish priority. Fredrik sets the work; finish coherent user outcomes and keep necessary maintenance moving.
The version stays in 0.x until FTW is actually a 1.0. Real sites already run it, and it is still an early project. The 1.x, 2.x and 3.x numbers came from removals, not from a decision that the product was finished. The native line continues the earlier 0.x counter at 0.131 so tags that were already published stay unique. ADR 0007 records that choice.
2.x and 3.x receive no more updates. All new releases use the new 0.x line. People who want current fixes and features should switch now using the install and update guide. A new setup is available; guided migration of old data remains work to prove. Do not recommend 3.x beta as a new install or a step towards the new line.
A person who runs FTW on their own machine is using an early project that already works. They should be able to follow a guide, take a backup and apply an update. systemd and a container are both valid ways to run it. The project documents those ways.
FTW's own work is the EMS and the Energy Planner. The owner operates the machine it runs on: the service manager, when to update, backups kept off the box and logs. They can do that by hand or through their own automation or agent. The project gives them a few documented steps and does not take over running their host.
Those steps are short commands on the machine, and the same operations are available over the API. Each one runs without questions, shows its progress and ends with a clear result, so it can be wrapped. The web UI shows the running version, whether a newer release exists and the command that installs it. On a native install it does not update, roll back or restore.
The update itself stays small and must be robust enough to run unattended. On a native install, Core downloads the next verified release and swaps to it. A new release that does not stay up falls back to the previous one without operator action. A release that changes stored data first makes a verified full backup. On a Docker install, the owner sets the new version and rebuilds from the same release package. A privileged sidecar whose job is to update Core is not part of the product. The machinery around that sidecar is retired as sites leave it. The same ADR records the shape.
A hosted service, in the spirit of the Sourceful Blixt gateway, is the later path for a household that wants FTW to just work and does not want to operate the box. It has not shipped. Until it exists, the project does not promise individual support for every self-hosted site that can report only a version number while releases still move quickly. Support that an agent can carry out needs the user's authorization and access to that gateway. The box keeps planning and controlling when the agent and the network are gone.
Fredrik owns FTW's direction. Sourceful develops and maintains the product. Agents work within the scope and authority given to them. Reviews should provide an independent assessment and evidence; file-based reviewer lists do not define product ownership.
External contributions are welcome, including code, drivers, documentation and website PRs. Prefer an issue that states the need and evidence. A broad product or architecture proposal can start as a short Markdown PR; a concrete fix can include code and tests. Hardware changes need relevant hardware evidence before we claim working support.
Development is agentic first. Make problems, scope, test steps and results clear enough for people and agents to assess and continue the work. The submitter checks the result; agent output alone is not test evidence. Sourceful reviews and maintains changes; Fredrik sets direction and priority. An accepted issue or proposal does not promise implementation or delivery. This policy changes no license, copyright attribution or release authority.
The operating rules live in AGENTS.md, review routing in APPROVAL_POLICY.md, and contribution details in CONTRIBUTING.md.