Skip to main content
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 and update device settings. Settings are desired values, and 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.
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.
  3. When the charge ends, write one_off_charge false with update device settings. 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.