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

# Devices

> Read a device, its settings, state, meter records and location meter records.

A device appears in your account when your customer [connects it](/docs/fleet-api/guides/connect.md). Read it with [retrieve a device](/docs/fleet-api/reference/devices/retrieve.md); its program membership is on the [enrollment](/docs/fleet-api/reference/vpp-enrollments/list.md).

## The device

| Field | Use it to |
| :- | :- |
| `dispatch_limits` | Size plans. Flatpeak rejects a plan that exceeds the envelope |
| `consent_scopes` | Check scopes: `TELEMETRY` for state and meter records, `CONTROL` for dispatch, `LOCATION` for the address, `SETTINGS` for settings |
| `telemetry` | Spot a late feed. Each `*_data_delayed` flag is `true` when its feed is behind |
| `response_time` | Pick devices for short notice. Median seconds from instruction to OEM confirmation |
| `location_id` | Find devices at one property, and aggregate per location to avoid double counting. [Retrieve the location](/docs/fleet-api/reference/locations/retrieve.md) for its `timezone`, and for its `postal_address` and `geo_location`, which are `null` without the `LOCATION` scope |

The device is read-only: the OEM declares it and Flatpeak derives the rest. Cache it and refresh it on `device.update`, which fires when the object changes; telemetry does not trigger it. See [events](/docs/fleet-api/guides/platform/events.md).

## Settings

Backup reserve, strategy, storm mode, export rule and charge limits are one record, shared with the OEM. Read it with [retrieve device settings](/docs/fleet-api/reference/devices/retrieve-settings.md) and change it with [update device settings](/docs/fleet-api/reference/devices/update-settings.md).

Send only the fields that change, under their namespace (`battery`, `evse`, `vehicle`):

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

| Rule | Detail |
| :- | :- |
| Access | The enrollment is `ACTIVE` and the customer granted `SETTINGS`. When the enrollment ends, your access ends and the values stay |
| Conflicts | When you and the OEM change the same field, the last write wins. `updated_by` says who wrote last |
| Backup reserve | The customer sets `backup_reserve_percent` freely. None of your programs constrains it |
| Writable fields | Only the paths in `supported`; others return `422`. Build your settings UI from `supported`, which is empty for device types without settings |
| One-off charge | `one_off_charge: true`, on `battery`, `evse` or `vehicle`, starts a charge now and once, regardless of plans and VPP events. A battery charges to full. The OEM sets it back to `false` when the charge ends. An instruction it overrides is recorded as a deviation |
| Sync | The OEM applies the change and `sync_status` shows the result. `device.settings.sync_failed` fires if the device does not apply it |

The OEM's app writes the same record, and both sides receive `device.settings.update` on every change.

## State

[Retrieve a device state](/docs/fleet-api/reference/device-state/retrieve.md) returns the latest snapshot the OEM submitted. It is the live envelope at the grid connection point, where positive power is import and negative power is export.

* `time_recorded` is when the snapshot was taken. `telemetry.state_data_delayed` is `true` when snapshots are late.
* The OEM samples state at the program's `eligibility.telemetry_requirements.state_interval_seconds`, down to every minute.
* State changes send no webhook, so read state on demand, for live displays and before you submit a plan.
* Energy under `backup_reserve_percent` is not dispatched.

## Meter records

State is a snapshot, while meter records are energy over time, so use meter records to measure energy.

[List device meter records](/docs/fleet-api/reference/meter-records/list-device.md) returns interval energy for one device, positive into the device and negative out of it, over a window of up to 90 days. `flow_basis` `GROSS` splits import from export, and `aggregate_by` returns period totals.

To check a plan, compare the records with the periods you sent. At 4.3 kW, a half hour records about 2.15 kWh.

## Location meter records

Location records measure the property's grid connection point, so they include household load and generation that no device controls. Use them to see whether a dispatch reached the grid. [Settlement](/docs/fleet-api/guides/settle/settlement.md) uses device meter records only.

[List location meter records](/docs/fleet-api/reference/meter-records/list-location.md) takes the device's `location_id`. Positive is import from the grid and negative is export. Records exist only where a device at the location meters the grid connection point; otherwise the list is empty. `metering.device_id` on the [location](/docs/fleet-api/reference/locations/retrieve.md) names that device, and is `null` when there is none.


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