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:*

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 /vehicles/{vehicleId}/smart-charging-policy 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, we ensure that the following requisites are in place:

• The vehicle must support the necessary queries and commands for smart charging.
• The vehicle must be linked to a single user account to enable smart charging. This prevents multiple users from applying conflicting smart charging plans to the same vehicle.

If either of these cases applies, a 400 error will be returned.

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 vehicles/{vehicleId}/smart-charging-status.

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. Unfortunately, estimating how long the vehicle will remain in the CONSIDERING state is difficult. Still, most vehicles receive a smart charging plan immediately after Enode identifies that the vehicle is charging at a charging location.

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 /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

{
  "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 /vehicles/{vehicleId}/smart-override 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 /vehicles/{vehicleId}/smart-override endpoint.

At any point in time, the state of smart overrides for the vehicle can be found via the smartOverride object in /vehicles/{vehicleId}/smart-charging-status 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 /vehicles/{vehicleId}/charging 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 our /tariffs/{tariffId} endpoint, 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 /vehicles/{vehicleId}/smart-override 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.