> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Device settings

> One settings record per device, shared with the VPP operator: how to write it and how sync is tracked.

Each device has one settings record, covering backup reserve, strategy, storm mode, export rule and charge limits. The user can change it in your app, in the VPP operator's app or on the device; Flatpeak holds the record and notifies both sides of every change. Read and write it with [retrieve](/docs/energy-api/reference/device-settings/retrieve.md) and [update device settings](/docs/energy-api/reference/device-settings/update.md).

Settings are desired values, and [device state](/docs/energy-api/guides/vpp/telemetry.md#device-state) carries reported values at the same paths. Flatpeak compares the two and sets `sync_status`: `IN_SYNC`, `PENDING` or `FAILED`.

## The record

* Settings are grouped by domain: `battery`, `evse`, `vehicle`. Other device types have none.
* `supported` lists the paths you can write, from the device's `device_type` and `capabilities`. A write outside it returns `422`.
* A capabilities update recomputes `supported`, so re-read it on `device.update`.
* A device with no settings is seeded from its first reported state.

## Write

Send only the changed fields under their domain.

```json theme={"system"}
{ "battery": { "backup_reserve_percent": 30 } }
```

When you and the VPP operator change the same field, the last write wins, and `updated_by` says who wrote last. Debounce continuous controls such as a slider.

## Sync loop

1. A write from either API fires `device.settings.update` to you and the VPP operator. The payload names the device only.
2. Retrieve the settings and apply them to the device.
3. Your next device state submission reports the values, and that is the confirmation; there is no acknowledgment endpoint.
4. A device that does not apply the change in time moves to `FAILED`, and `device.settings.sync_failed` fires.

Numbers compare within a tolerance, and comparison pauses while the device's state feed is delayed.

A change made on the device reaches Flatpeak through your state submission. Flatpeak adopts it and fires `device.settings.update` with `updated_by` set to `OEM`, so you do not write settings for device-local changes.

## One-off charge

`one_off_charge`, on `battery`, `evse` and `vehicle`, starts a charge now and once, regardless of plans, VPP events and the other settings. A battery charges to full.

1. The user sets it to `true` in your app or the VPP operator's, and `device.settings.update` fires.
2. Start the charge. An instruction it overrides is recorded as a [deviation](/docs/energy-api/guides/vpp/dispatch.md#declining-and-deviating).
3. When the charge ends, write `one_off_charge` `false` with [update device settings](/docs/energy-api/reference/device-settings/update.md). Flatpeak does not clear it for you.

The field is not compared in `sync_status`, because device state does not report it. `true` for an unplugged vehicle returns `422`.

## Limits

* The VPP operator can write settings only while the device has an `ACTIVE` enrollment with the `SETTINGS` scope.
* The user sets `backup_reserve_percent` freely. No VPP program constrains it, and energy under the reserve is never dispatched.
* `strategy` is stored and shared, but Flatpeak does not act on it: your planning decides what it means, and instructions stay binding under any strategy.
* `export_rule` and `charge_from_grid_enabled` bound dispatch, and affected intervals are recorded as declined, so they do not count as a shortfall.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.