States of smart charging

Copy linkIntroduction

DownloadFullscreen

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.

Copy linkDisabled

To enable smart charging for a vehicle, call the Smart Charging PolicyAPI 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. For more information on the smart charging policy endpoints, see our API referenceAPI.

Copy linkPre-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

{
   "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.

Copy linkFully 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.

Copy linkConsidering

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 StatusAPI.

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

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.

Copy linkUnknown

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.

Copy linkPlan

DownloadFullscreen

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.

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.

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

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 or via Smart Charging PlansAPI.

Copy linkThe 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 StatusAPI or Smart Charging PlansAPI endpoints.

Example

{
  "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.

Copy linkSmart 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 OverrideAPI 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 OverrideAPI endpoint.

At any point in time, the state of smart overrides for the vehicle can be found via the smartOverride object in Smart Charging StatusAPI response. This will be null if a smart override has not been created.

Example

{
  "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 chargingAPI will return errors to avoid unwanted smart charging interruptions.

Example error

{
  "type": "https://docs.enode.io/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."
}

Copy linkPrice data sources

DownloadFullscreen

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

Copy linkTariffs

If you provide prices as tariffs via TariffsAPI, our smart charging algorithm will use these when finding the optimal charging window.

Copy linkDay-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, some values in the plan object will be null.

{
  "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": null,
  "estimatedFinishAt": null,
  "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"
}

Copy linkEdge 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 OverrideAPI 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.