Enode Developers

States of smart charging

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

Copy linkIntroduction

Download

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

  • DISABLED
  • CONSIDERING
  • PLAN:*

In short, smart charging for the specific vehicle stays DISABLED until the user enables smart charging. Then, when smart charging is enabled, it remains in the CONSIDERING state until all considerations check out. Once all considerations are true, a plan gets generated, and smart charging transitions into the PLAN:* states by the pre-determined logic.

Copy linkDisabled

Enabling smart charging for a vehicle is done by calling the /vehicles/{vehicleId}/smart-charging-policy endpoint and including a request body schema with isEnabled, deadline and optionally a minimumChargeLimit (Defaults to zero). You can read more about building and designing this experience in our following guide and more about the smart charging policy endpoints in our API reference.

Example

Sample

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

Once a valid smart charging policy is in place, smart charging will transition from the DISABLED state to the CONSIDERING state.

Copy linkConsidering

In the CONSIDERING state, considerations are re-evaluated every time the vehicle is updated. Vehicles are polled every 7-10 minutes. Considerations come in the form of flags (or booleans) and can be observed via the consideration object from vehicles/{vehicleId}/smart-charging-status.

Considerations are mainly made up of physical conditions, charge time estimation, and capability checks. In addition, since there are slight risks attached to delaying charging — like not being able to resume charging according to the plan because the vehicle lost its internet connection — a few extra checks are put in place to make sure it’s worth transitioning to the PLAN:* states.

Flag Description
isSmartChargeCapableThe vehicle has the capability of smart charging, indicating that it supports the required queries and commands.
isPluggedInThe vehicle needs to be plugged in.
isChargingThe vehicle needs to be charging for a certain amount of time to be able to calculate the charge time remaining (reflected by hasTimeEstimate). Also validates that the vehicle can charge via the charger it is plugged in at.
recentlyAtChargingLocationThe vehicle must be located at any user-configured charging locations to avoid unwanted charging behavior, i.e., when plugged in at public chargers or superchargers. The vehicle is considered at the charging location if it is located within 200 meters of the defined coordinates.
hasTimeEstimateAn estimate for the charge time remaining is calculated through a model reviewing charge rate and charge curves over time. It stays false until a time estimate is present.
needsSignificantChargeThe vehicle needs at least 5% or more than 60 minutes of charge time to reach its chargeLimit.
hasChargeAboveThresholdThe vehicle has a charge level above SmartChargingPolicy minimumChargeLimit. When below, the flag stays false in order to charge the battery regardless of energy prices. Once above, the flag is true.
singleUserThe vehicle must be linked to a single Enode user to avoid situations where two competing smart charging plans or charging schedules would be applied to the same vehicle. This could happen if you are testing against the same vehicle in staging and production environments. Therefore, it stays false until the vehicle is only attached to one user.
wontStopExistingChargingSessionA smart charging plan will not stop a current charging session. For instance, if charging started (i.e., at 03:00) before the deadline (i.e., 06:00) and the charge time remaining (i.e., 6 hours) exceeds the deadline (needs to charge until 09:00), the flag will stay false to avoid stopping a charge session. In other words, this kicks in when the estimated charge time exceeds the time between now and the deadline. The flag resets the next time the vehicle changes charging state.
likelyToGenerateSavingsThe price data available indicates that shifting the charging window will result in price savings, or is likely to result in price savings.

Our algorithm will poll for flag updates every two minutes. Once all of these flags are true, smart charging will transition into its PLAN:* states. Some of the flags are updated instantly, but some take a longer time to complete. One example is hasTimeEstimate, which requires a minimum of 7 minutes to update. Estimating the time the vehicle stays in CONSIDERING is difficult, but most vehicles that should be smart charging stay in this state between 7-15 minutes.

Copy linkPlan

Download

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:STOPPINGCharging should be stopped according to the charging plan. Commands are being sent to the car to stop charging.
PLAN:EXECUTING:STOP_FAILEDThirty 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:FINISHED when fully charged.
PLAN:EXECUTING:STOPPED:AWAITING_PRICESCharging has stopped, and is awaiting updated prices to find the optimal charging window and finalise the plan. startAt, smartCost and estimatedFinishAt will be null until price data is updated. Once price data is updated, the vehicle will transition into PLAN:EXECUTING:STOPPED.
PLAN:EXECUTING:STOPPEDCharging has stopped as part of the plan's schedule.
PLAN:EXECUTING:STARTINGCharging should be started according to the charging plan. Commands are being sent to the car to start charging
PLAN:EXECUTING:START_FAILEDThirty 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:STARTEDThe charging has started. Either because the plan wants it to charge or because 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 externalStart. You can read more about external starts in our section about it below.

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

State Description
PLAN:EXECUTING:OVERRIDDENAfter being previously stopped, charging has been started by our vehicles/{vehicleId}/external-start endpoint.
PLAN:EXECUTING:CHARGE_INTERRUPTEDThe 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:FINISHEDThe vehicle has finished charging ahead of the deadline, as planned.
PLAN:ENDED:FAILEDThe smart charging plan failed. The failure is described via failureCondition in the plan object.
PLAN:ENDED:UNPLUGGEDThe user unplugged the vehicle during the execution of the plan.
PLAN:ENDED:DISABLEDThe user disabled smart charging during the execution.
PLAN:ENDED:DEADLINE_CHANGEDThe user has changed their deadline, so this plan is invalidated. In this case, charging will be started again to calculate a new charging plan based on the new deadline.

Once any of the PLAN:ENDED:* states are reached, smart charging immediately transitions back to CONSIDERING. The ended state can be observed by recording webhooks or via /vehicles/{vehicleId}/smart-charging-plans/{smartChargingPlanId}.

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 /vehicles/{vehicleId}/smart-charging-status, /vehicles/{vehicleId}/smart-charging-plans/{smartChargingPlanId} or /vehicles/{vehicleId}/smart-charging-plans/latest endpoints.

Example

Sample

{
  "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_FAILEDWe were unable to stop charging after multiple tries.
START_FAILEDWe were unable to start charging according to plan after multiple tries.
FINISHED_LATECharging was completed after the deadline.
PLAN:ENDED:DISABLEDThe user disabled smart charging during the execution.

Copy linkExternal start

If your user wishes to charge the vehicle during any of the PLAN:EXECUTING:* states, an external start can be created via the /vehicles/{vehicleId}/external-start endpoint. This will start charging the vehicle immediately and transition smart charging into the PLAN:EXECUTING:OVERRIDDEN state.

To stop the external start 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 /vehicles/{vehicleId}/external-start endpoint.

At any point in time, the state of external starts for the vehicle can be found via the externalStart object in /vehicles/{vehicleId}/smart-charging-status response. This will be null if an external start has not been created.

Example

Sample

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

Example error

Sample

{
  "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 external start API instead."
}

Copy linkPrice data sources

Download

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 our /tariffs/{tariffId} endpoint, our smart charging algorithm will use these when finding the optimal charging window.

Copy linkNord Pool day-ahead prices

If a tariff is not provided, we will match the charging location to a region of Nord Pool day-ahead price data. Nord Pool updates prices for the coming day around 12:00 UTC every day.

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

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

If these check out, our updated prices will be awaited to calculate the optimal charge window based on the complete picture. To indicate this state, the likelyToGenerateSavings consideration flag will be true and the vehicle will transition to PLAN:EXECUTING:STOPPED:AWAITING_PRICES. Since the price data is incomplete in this state, some values in the plan object will be null.

Sample

{
  "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.
    • In that case, 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 /vehicles/{vehicleId}/external-start 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 by this, and execution will continue based on the original charge rate.
Next article: Onboarding and setup

Recommendations for onboarding your users to smart charging

Was this article helpful?