# States of smart charging

Before building and designing your smart charging experience, it is worth understanding the overall mechanism and the different states.

## Introduction

![A diagram visualizing the four primary states: DISABLED, CONSIDERING, FULLY_CHARGED, UNKNOWN and PLAN:*](https://developers.enode.com/images/smart-charging/States_of_smart_charging__Overview.png)

At any point, smart charging for a specific vehicle finds itself in the following states.

- `DISABLED`
- `CONSIDERING`
- `FULLY_CHARGED`
- `PLAN:*`
- `UNKNOWN`

In short, smart charging for a specific vehicle is in the state `DISABLED` by default. The user needs to enable it. Once enabled, smart charging remains in the `CONSIDERING` state until all considerations are met. A plan is then generated, and smart charging transitions to the `PLAN:*` states based on a pre-determined logic. If the vehicle is fully charged, it transitions to the `FULLY_CHARGED` state until it detects it needs charging. Then, it goes back into the `CONSIDERING` state again.

## Disabled

To enable smart charging for a vehicle, call the [Smart Charging Policy](https://developers.enode.com/api/reference#updateVehicleSmartChargingPolicy) endpoint and include a request body schema with `isEnabled`, `deadline`, and optionally a `minimumChargeLimit` (defaults to zero). For more information on building and designing this experience, see our [guide](https://developers.enode.com/docs/smart-charging/onboarding). For more information on the smart charging policy endpoints, see [our API reference](https://developers.enode.com/api/reference#updateVehicleSmartChargingPolicy).

### Pre-requisites

Before enabling smart charging, the system verifies several key requirements:

- **Control Scope Validation**: Ensures that the vehicle supports necessary smart charging controls.
- **Deadline Requirement**: Smart charging must be enabled with a valid deadline.
- **Charge Limits**: The minimum charge limit must not exceed the current charge state limit.
- **Price Area and Tariffs**: If smart charging is enabled, the user must have valid pricing data for their area.
- **Vendor-Specific Conditions**: For certain vendors (e.g., Mercedes), the minimum charge limit cannot be below 50%.
- **Exclusive Access**: Smart charging must be linked to a single user account to avoid conflicts; it cannot be activated if another user already has smart charging enabled for the same vehicle.

If any of these conditions are not met, the system will return a 400 error, indicating that smart charging cannot be activated due to conflicting or missing requirements.

**Example**

```javascript
{
   "isEnabled": true,
   "deadline": "08:00",
   "minimumChargeLimit": 0
}
```

Once a valid smart charging policy is established, the smart charging feature will transition from the `DISABLED` state to either the `FULLY_CHARGED` state or the `CONSIDERING` state.

## Fully charged

When the vehicle's battery is sufficiently charged (up to the charging limit or close to 100%), it transitions into the `FULLY_CHARGED` state. It remains in this state until the battery drains again, at which point it will enter the `CONSIDERING` state.

## Considering

In the `CONSIDERING` state, considerations are re-evaluated every time the vehicle is updated. Vehicles are polled every 2-10 minutes. Considerations come in flags (or booleans) and can be observed via the `consideration` object from [Smart Charging Status](https://developers.enode.com/api/reference#getVehiclesVehicleidSmartchargingstatus).

Considerations are mainly made up of physical conditions and charge time estimation.

| Flag | Description |
| --- | --- |
| `isPluggedIn` | The vehicle must be connected to a charger. |
| `isCharging` | Necessary only if no historical charging data is available. Validates that the vehicle is actively charging, ensuring compatibility with the connected charger. This enables the calculation of the remaining charge time (`hasTimeEstimate`). |
| `atChargingLocation` | The vehicle should be within 200 meters of any predefined [Locations](https://developers.enode.com/api/reference#locations) to avoid unintended smart charging at public or superchargers. |
| `hasTimeEstimate` | Provides time estimates based on historical charging data. If no data is available, estimates are derived from a model analyzing charge rates and curves. The flag remains `false` until an estimate is available. |

Our algorithm will check for flag updates every seven minutes and every two minutes while the vehicle charges. Once these flags are true, a smart charging plan is generated and will transition into its `PLAN:*` states. Most vehicles receive a smart charging plan immediately after Enode identifies that the vehicle is plugged in at a charging location.

## Unknown

The `UNKNOWN` state indicates that the vehicle cannot engage in smart charging. This may be due to the vehicle's lack of support for start/stop commands, charge information, or battery capacity data. Additionally, this state is assigned if price data for the vehicle's location is unavailable.

## Plan

![A zoomed-in diagram of the PLAN:* states](https://developers.enode.com/images/smart-charging/States_of_smart_charging__PLAN__.png)

Once entering the `PLAN:*` states, smart charging will transition between states in a pre-determined manner unless other external events or connection issues occur on its path.

| State | Description |
| --- | --- |
| `PLAN:EXECUTING:STOPPING` | Charging should be stopped according to the charging plan. Commands are being sent to the car to stop charging. |
| `PLAN:EXECUTING:STOP_FAILED` | Thirty minutes (and multiple attempts to stop charging) have passed, but the car still reports charging. After this, attempts are halted, and the vehicle will eventually transition into `PLAN:ENDED:FAILED` when fully charged. |
| `PLAN:EXECUTING:STOPPED:AWAITING_PRICES` | Charging has stopped; awaiting updated prices to find the optimal charging window and finalize the plan. `smartCost` will be null until price data is updated. Once price data is updated, the vehicle will transition into `PLAN:EXECUTING:STOPPED. |
| `PLAN:EXECUTING:STOPPED` | Charging has stopped as part of the plan's schedule. |
| `PLAN:EXECUTING:STARTING` | Charging should be started according to the charging plan. Commands are being sent to the car to start charging |
| `PLAN:EXECUTING:START_FAILED` | Thirty minutes (and multiple attempts to start charging) have passed, but the car still reports not charging. Recovery will still be attempted, but should it fail, the plan will transition into `PLAN:ENDED:FAILED` when the deadline passes. |
| `PLAN:EXECUTING:STARTED` | The charging has started. Either because the plan wants it to charge or the user began charging using our API, the first-party app, or from within the vehicle itself. |

If the user starts charging, it will be flagged via `smartOverride`. You can read more about smart overrides in our section about it below.

Other events can influence the pre-determined logic during the `PLAN:EXECUTING:*` states.

| State | Description |
| --- | --- |
| `PLAN:EXECUTING:OVERRIDDEN` | After being previously stopped, charging has been started by our [Smart Override](https://developers.enode.com/api/reference#vehicleCreateSmartOverride) endpoint. |
| `PLAN:EXECUTING:CHARGE_INTERRUPTED` | The vehicle was charging but stopped for external reasons. The algorithm will not fight this user intervention, and unless the user starts charging again, it will stay in this state until the deadline and end up in `PLAN:ENDED:FAILED` state. |

Execution concludes in one of five ways, describing why the plan ended.

| State | Description |
| --- | --- |
| `PLAN:ENDED:FINISHED` | The vehicle has finished charging ahead of the deadline, as planned. |
| `PLAN:ENDED:FAILED` | The smart charging plan failed. The failure is described via `failureCondition` in the plan object. |
| `PLAN:ENDED:UNPLUGGED` | The user unplugged the vehicle during the execution of the plan. |
| `PLAN:ENDED:DISABLED` | The user disabled smart charging during the execution. |
| `PLAN:ENDED:DEADLINE_CHANGED` | The user has changed their deadline, so this plan is invalidated. |

Once any of the `PLAN:ENDED:*` states are reached, smart charging transitions back to `FULLY_CHARGED` or `CONSIDERING`, depending on the outcome of the plan. The ended state can be observed by recording [webhooks](https://developers.enode.com/docs/webhooks) or via [Smart Charging Plans](https://developers.enode.com/api/reference#getVehiclesVehicleidSmartchargingplans).

### The plan object

The plan object is made available as soon as smart charging transitions into the `PLAN:*` states. This object can be accessed via the [Smart Charging Status](https://developers.enode.com/api/reference#getVehiclesVehicleidSmartchargingstatus) or [Smart Charging Plans](https://developers.enode.com/api/reference#getVehiclesVehicleidSmartchargingplans) endpoints.

**Example**

```json
{
  "id": "string",
  "chargingLocationId": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
  "vehicleId": "string",
  "userId": "string",
  "vendor": "string",
  "currency": "NOK",
  "nonSmartCost": 52.1,
  "smartCost": 26.7,
  "stopAt": "2019-08-24T14:15:22Z",
  "startAt": "2019-08-24T14:15:22Z",
  "estimatedFinishAt": "2019-08-24T14:15:22Z",
  "stopConfirmedAt": "2019-08-24T14:15:22Z",
  "startConfirmedAt": "2019-08-24T14:15:22Z",
  "endedAt": "2019-08-24T14:15:22Z",
  "finalState": "PLAN:ENDED:FINISHED",
  "failureCondition": "STOP_FAILED"
}
```

Each charging plan has an ID and will contain information such as scheduled charging, actual charging, estimated savings, and the final state.

If a plan ends up in the failed state, the `failureCondition` field will be populated with its reason.

| Condition | Description |
| --- | --- |
| `STOP_FAILED` | We were unable to stop charging after multiple tries. |
| `START_FAILED` | We were unable to start charging according to plan after multiple tries. |
| `FINISHED_LATE` | Charging was completed after the deadline. |
| `PLAN:ENDED:DISABLED` | The user disabled smart charging during the execution. |

### Smart override

If your user wishes to charge the vehicle during any of the `PLAN:EXECUTING:*` states, a smart override can be created via the [Smart Override](https://developers.enode.com/api/reference#vehicleCreateSmartOverride) endpoint. This will start charging the vehicle immediately and transition smart charging into the `PLAN:EXECUTING:OVERRIDDEN` state.

To stop the smart override and make smart charging for the vehicle return to the state dictated by `PLAN:*` or `CONSIDERING`, the `DELETE` method can be provided to the same [Smart Override](https://developers.enode.com/api/reference#vehicleCreateSmartOverride) endpoint.

At any point in time, the state of smart overrides for the vehicle can be found via the `smartOverride` object in [Smart Charging Status](https://developers.enode.com/api/reference#getVehiclesVehicleidSmartchargingstatus) response. This will be `null` if a smart override has not been created.

**Example**

```json
{
  "createdAt": "2020-04-07T17:04:26Z",
  "endedAt": "2020-04-07T17:04:26Z",
  "targetType": "vehicle",
  "targetId": "string",
  "vendorActionId": "string"
}
```

Please note that once smart charging is in any of the `PLAN:EXECUTING:*` states, the regular charging commands via [Control charging](https://developers.enode.com/api/reference#postVehiclesVehicleidCharging) will return errors to avoid unwanted smart charging interruptions.

**Example error**

```json
{
  "type": "https://developers.enode.com/problems/enode-controlled-entity",
  "title": "Direct Charge Commands Not Allowed",
  "detail": "Chargeable is under schedule or smart charging control. Manual commands not allowed, use smart override API instead."
}
```

## Price data sources

![Two timelines: one showing smart charging based on tariffs, and one showing smart charging based on Nord Pool day-ahead prices](https://developers.enode.com/images/smart-charging/States_of_smart_charging__Price_input.png)

Our algorithm reviews price data to find the optimal charge window when creating a plan. It considers one of two sources of price data.

### Tariffs

If you provide prices as tariffs via [Tariffs](https://developers.enode.com/api/reference#sendTariffInformation), our smart charging algorithm will use these when finding the optimal charging window.

### Day-ahead prices

If a tariff is not provided, we will match the charging location to a region with price data. Prices are released at the same time every day, depending on the data source.

If a user plugs their vehicle in before prices are released and the deadline is the next day, we will not have price data for the entire time until the deadline. In that case, our algorithm will consider whether it is worth waiting for updated price data based on a series of checks, looking at:

- Whether there is enough time between the estimated price update and the deadline
- Whether the majority of the charge window can fall within the missing price data

If these checks pass, we will await updated prices to calculate the optimal charge window based on complete data. The vehicle will transition to the `PLAN:EXECUTING:STOPPED:AWAITING_PRICES` state to indicate this. Since the price data is incomplete in this state, the `smartCost` value will be `null`.

```json
{
  "id": "string",
  "chargingLocationId": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
  "vehicleId": "string",
  "userId": "string",
  "vendor": "string",
  "currency": "NOK",
  "nonSmartCost": 52.1,
  "smartCost": null,
  "stopAt": "2019-08-24T14:15:22Z",
  "startAt": "2019-08-24T15:15:22Z",
  "estimatedFinishAt": "2019-08-24T23:00:00Z",
  "stopConfirmedAt": "2019-08-24T14:15:22Z",
  "startConfirmedAt": "2019-08-24T15:15:22Z",
  "endedAt": "2019-08-24T14:15:22Z",
  "finalState": "PLAN:ENDED:FINISHED",
  "failureCondition": "STOP_FAILED"
}
```

## Edge cases

- A user turns on smart charging for a vehicle that is not charging but plugged in.
  - The vehicle will be stuck in the `CONSIDERING` state as the `isCharging` flag is false.
- A vehicle is in the `PLAN:EXECUTING:STOPPED` state, and a user starts charging (either via the OEM app or charger) and then stops charging **after** the start time of the charge plan (i.e., the vehicle is supposed to charge according to the plan).
  - Starting charging will transition into `PLAN:EXECUTING:STARTED`. Then, when charging is stopped, we don't try to start charging and leave the car in the `PLAN:EXECUTING:CHARGE_INTERRUPTED` state until the deadline.
  - If charging was started via the [Smart Override](https://developers.enode.com/api/reference#vehicleCreateSmartOverride) endpoint, charging will continue according to the plan.
- The charge rate is changed through the chargers during the `PLAN*` state.
  - The existing plan will not be affected, and execution will continue based on the original charge rate.

[Next article: Onboarding and setup](https://developers.enode.com/docs/smart-charging/onboarding)