Controlling devices

Copy linkActions

Actions are an asynchronous API pattern that represent a request for a device to perform an action, such as requesting a vehicle to start charging or changing the mode on an HVAC. You create actions by calling the appropriate endpoint, such as 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 all 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 until it succeeds, fails (times out), or is cancelled. All vendor actions sent through Enode will at all times be in one of the following states.

State	Description
`PENDING`	The initial state. Enode is actively sending commands and monitoring the asset for changes.
`CONFIRMED`	Successful state. We have verified via device data that the action was accepted and performed by the device.
`FAILED`	Enode’s attempts to perform and validate the action on the device were unsuccessful and we have timed out. Actions transition to this state after a number of unsuccessful attempts and Enode becomes confident that subsequent retries won't succeed. Once an action has `FAILED`, Enode will no longer attempt this action. The number of attempts we make and timeout window varies by vendor and device.
`CANCELLED`	One of the following is true... A "precondition" for the action was not met. Some actions have “preconditions,” such as a vehicle needing to be plugged in to a charger or being reachable via the cloud. Another action targeted the same device, overriding this one.

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

Vehicle charging actions that end up in CANCELLED or FAILED may have an associated failureReason with an explanation for why the vehicle ended up in that state (e.g., NO_RESPONSE for when a device doesn’t respond). For a full list, see our docs for controlling charging for vehiclesAPI and chargersAPI .

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 the /{deviceType}/actions/{actionId} endpoints for updates.

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 (e.g., 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 Large, sophisticated energy retailers who have the capacity to manage complex optimization schemes in-house
Scheduling	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 Products with users in regions with static energy pricing
Smart charging	Our most sophisticated off-the-shelf optimization product that considers energy costs, charge deadlines, and minimum charge levels	Low	Products with users in regions with dynamic energy pricing

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

{
	"id": "0637f895-1796-49d2-affb-16814f7efa10",
	"vendor": "VOLKSWAGEN",
	...
	"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.

The controls found on some devices may differ from the semantics of Enode’s API—for example, a vehicle may not have the native ability to arbitrarily “stop” charging but will have the ability to create charging schedules. In these cases, you should educate and reassure them about potential side effects such as schedules being created in the 1st party app.

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 detailed guide , apps controlled by charger, vehicle, 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.

Previous articleDevice data

Next articleSad paths and errors