Controlling devices

Once linked there are a few ways you can control devices. This document gives you a high level overview of these methods along with some best practices.

Copy linkActions

Actions are an asynchronous API pattern that represent a request for a device to perform a change, such as requesting a vehicle to start charging or changing the mode on an HVAC. You create actions by calling the appropriate endpoint, for example Control ChargingAPI.

Sample

curl {API_URL}/vehicles/{vehicleId}/charging \
-X POST \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-d '{"action": "START"}'

For the latest supported actions across our devices, see our API referenceAPI.

Copy linkVendor action states

When you create an action in the API, Enode will attempt to execute that action on the device. Enode will reattempt to execute the action until it succeeds, fails, or is cancelled. If the action has not succeeded after 30 minutes it will fail. All vendor actions sent through Enode will at all times be in one of the following states.

State	Description
`PENDING`	Initial state. Enode is actively attempting to change the device and is monitoring the device for changes.
`CONFIRMED`	Successful state. We have verified via device data that the change was accepted and performed by the device.
`FAILED`	Enode’s attempts to perform the change on the device were unsuccessful. Actions transition to this state after 30 minutes of unsuccessful attempts, and Enode will no longer attempt this action.
`CANCELLED`	One of following scenarios has happened: Another action targeted the same device, overriding this one. Some actions have “preconditions,” such as a vehicle needing to be plugged in to a charger or being reachable via the cloud. If Enode realizes a precondition is not met before the 30 minute timeout, the action is cancelled and won't be reattempted.

The state parameter on all actions reflects the latest state.

Sample

{
  "id": "1e289a23-cc8a-4989-b465-4f5a9acaff15",
  "state": "PENDING",
  "createdAt": "2023-07-25T16:54:42.939Z",
  "updatedAt": "2023-07-25T16:54:42.939Z",
  "completedAt": null,
  "targetId": "83d32591-9931-4f62-878c-0d3933ca98c4",
  "targetType": "vehicle",
  "kind": "START",
  "failureReason": null
}

All actions begin in PENDING unless we know the action will fail due to an unmet precondition that is unlikely to change within 30 minutes, for which the API request to create the action will return a CANCELLED state. Common scenarios include:

an action to begin charging a vehicle that’s already fully charged
sending an action to change state of a device when the device is already in that state e.g.,
- asking a vehicle to start charging when it is already charging
- setting an HVAC’s mode to SCHEDULED when it is already in SCHEDULED

Actions that end up in CANCELLED or FAILED may have an associated failureReason with an explanation for why the action ended up in that state (e.g., NO_RESPONSE for when a device doesn’t respond for 30 minutes). For a full list, see our docs for Control ChargingAPI for vehicles and Control ChargingAPI for chargers.

Copy linkListen to action updates

We recommend listening to the user:vendor-action:updated webhook to understand when actions have transitioned states. Alternatively, you can periodically poll Get Vehicle ActionAPI or Get Charger ActionAPI.

Copy linkLevels of control

Enode gives you flexibility to build automation and optimize energy usage how you want. You can always build advanced functionality on top of our basic actions, but Enode also offers Schedules and Smart Charging APIs that will manage additional complexity for you.

API	Description	Complexity	Recommendation
Basic actions, such as Control ChargingAPI	Send actions when and how you wish, leveraging your own data and algorithms for optimization	Low to High	Users with simple use cases that exclude energy optimization. Alternatively; Large, sophisticated energy retailers who have the capacity to manage complex optimization schemes in-house
Schedules	Define rules for device behavior based on time of day, and day of week, allowing for basic energy optimization or demand response solutions	Low	Users who want a simple, intuitive strategy for energy optimization. Alternatively, Users with customers in regions with static energy prices.
Smart Charging	Our most sophisticated off-the-shelf optimization product that considers energy costs, charge deadlines, and minimum charge levels	Low	Users with customers in regions with dynamic energy prices

Copy linkBest practices

Copy linkInterventions

capabilities found on a device resource will let you know if there are any steps your users have to take before specific actions will work:

Sample

"capabilities": {
  "startCharging": {
    "interventionIds": ["87012776-355f-4d2c-b515-f53a78e3c582"],
    "isCapable": false
  },
  ...
}

Review our guide on Interventions to ensure you are handling known scenarios that may prevent actions from succeeding.

Copy linkNative device limitations

Enode can control devices through a number of means, but we may have to deal with limitations found on devices or vendors themselves.

For example, some vehicles may not support remote charging commands. Others might only support remote charging through a "Scheduled Charging" feature that we'll leverage for our basic charge actions. For more on the specific capabilities of a device, see our capabilities table.

Copy linkOne action at a time

Only one action from your integration should be active for a device at any given time. If Enode receives a new action for the same device before the previous one completes, the previous action transitions to the CANCELLED state. There is thus no benefit to sending a new identical command to override an existing command in a PENDING state.

Copy linkInterference by third parties

Ask your users to make sure no other third parties are interfering with your application.

As described in our Smart Charging Guide, devices controlled by other devices, or other apps can interfere with smart charging. Any other connected third parties can also make actions in your app confusing to interpret.

You can listen for user:{deviceType}:updated webhooks to understand when actions may have taken place on a device that you did not control (e.g., if a vehicle stopped charging outside of your actions).

Copy linkLimit daily commands dispatched

For maximum reliability, limit your application to sending at most 6 commands per device, per day. Exceeding this can lead to connectivity errors that decrease action success rates and will result in a poor experience for your users.