Integration steps

Copy linkStep 1: Implement the linking flows with LinkUI

You must update your application to allow the same end user to sequentially link both their vehicle and charger through Enode LinkUI. This requires your backend to be able to request distinct link session for each device type.

The technical process for linking a charger is identical to linking a vehicle; the only difference is the scopes your backend requests when generating the token.

Here is the recommended implementation flow:

1. Link the vehicle: First, initiate a standard Enode LinkUI session to connect the user's vehicle. To do this, your backend must request a linkToken with vehicle: specific scopes (i.e. vehicle:read:data, vehicle:read:location and vehicle:control:charging). Your frontend then uses this token to open LinkUI. For complete implementation details, please see our official LinkUI Developer Guide.
2. Prompt to link the charger: After the vehicle is successfully linked, we recommend a separate step in your user journey to prompt the user to also link their charger. You should clearly explain the benefits, such as enabling smart charging for an otherwise incapable vehicle or improving the reliability of an existing connection. See section UX Recommendations for further guidance.
3. Link the charger: When the user proceeds, your backend must request a new linkToken, this time with charger: specific scopes (e.g. charger:read:data, charger:control:charging). Your frontend then uses this new token to open a second LinkUI session for the charger.

Copy linkStep 2: Set the charging location for chargers

To reliably verify that a vehicle is charging at a specific supply address (e.g. the user's home), you must associate the user's charger with a defined Location.

When a vehicle is dynamically paired with this charger, you can be confident of the vehicle's location without relying on its native GPS which is crucial for a number of vehicle OEMs where the location capability is not supported or is unreliable (e.g. poor GPS signal due to environmental factors).

Setting the charging location is a two-step process:

1. Create a Location: If you haven't already, create a location object representing the user's supply address by making a POST request to the /locations endpoint. This will return a unique locationId.
2. Assign the Location to the charger: Use the PATCH /chargers/{chargerId} endpoint to assign the newly created locationId to the user's charger.

Note: Assigning a Location to the vehicle is not possible nor is it necessary. Whenever the location capability is supported by vehicle, the locationId will be returned automatically whenever the vehicle is within the location’s geofence (200m radius).

Copy linkStep 3: Use the Vehicle API for data and controls

Understanding the basics

Once both devices are linked to the same user, Enode establishes the logical EV System automatically and all relevant data and controls are then exposed through the Vehicle API:

• pluggedInChargerId is returned when the vehicle is currently plugged into a charger that has been linked to the same user. Typically this will be at home where managed charging can then be planned and executed. When pluggedInChargerId is null then we have determined that the vehicle is NOT currently plugged into a charger linked to the same user.
• The vehicle remains free to charge at different locations (E.g. public charging) or use chargers that have not been linked. In this case pluggedInChargerId will be null but the Vehicle API will continue to return live data for the vehicle.
• The inverse relationship is also exposed on the Charger API, where a pluggedInVehicleId is returned.

Working with unlocked capabilities

The vehicle’s charge state data and capabilities are enabled by the paired charger:

• chargeRate , if previously null, is sourced from the charger (when available)
• startCharging, stopCharging and location capabilities become isCapable: trueand any associated interventions are not returned.
• For location this is particularly useful for vehicles without native location (GPS) support where location is then inferred from the charger.

The unlocked capabilities and the suppression of interventions are persisted as soon as the assets are linked to ensure a stable user experience. Persistence is cleared after ten consecutive failed control commands (start/stop) are sent to the unplugged vehicle. The pair will be automatically re-established if the two devices are plugged into one another again.

Working with unified controls

The Vehicle Control ChargingAPI endpoint (for initiating async charging actions) and ActionAPI endpoint + webhooks (for retrieving the current status) continue to work the same from an integration perspective. If a vehicle is unplugged or connected to a different charger, control remains the same as it was before. Behind the scenes, Enode will orchestrate commands across the vehicle and charger for optimal control. Action failures and reasons from either the vehicle OR the charger will be returned.

Example Vehicle API response for an ACTIVE / CONNECTED charging pair

{
  "id": "05ee9df5-d072-4ee8-b773-399dec8f5693",
  "userId": "bb28471e-cde6-4eff-ace4-9a7f4f50882a",
  "vendor": "TESLA",
  "lastSeen": "2024-01-07T17:04:26.000Z",
  "isReachable": true,
  "information": {
    "vin": "2HGFB2F5XEH542858",
    "model": "Model S P85",
    "year": 2020
  },
  "chargeState": {
    "batteryLevel": 66,
    "range": 228,
    "batteryCapacity": 48.1,
    // Charger Pairing: When available, the chargeRate from the charger
    // will be returned when not provided by the vehicle
    "chargeRate": 2.3,
    "chargeTimeRemaining": 285,
    "lastUpdated": "2020-04-07T17:04:26Z",
    "maxCurrent": 16,
    "powerDeliveryState": "PLUGGED_IN:CHARGING",
    // Charger Pairing: Will be "null" when not currently
    // plugged into a charger
    "pluggedInChargerId": "07f8368d-be7e-4dbd-8cf0-94d00dd67ad3"
  },
  "capabilities": {
    "information": {
      "isCapable": true,
      "interventionIds": []
    },
    "chargeState": {
      "isCapable": true,
      "interventionIds": []
    },
    "odometer": {
      "isCapable": false,
      "interventionIds": ["4eaeb363-296d-4ccc-a973-7805e6f400bd"]
    },
    "setMaxCurrent": {
      "isCapable": false,
      "interventionIds": []
    },
    // Charger Pairing: Once a charger and vehicle have been
    // linked to the same user, the following vehicle
    // capabilities (startCharging, stopCharging and location)
    // are set to "true" and interventions are suppressed.
    // In order to ensure a stable user experience, these
    // capabilities are persisted across charging sessions.
    "startCharging": {
      "isCapable": true,
      "interventionIds": []
    },
    "stopCharging": {
      "isCapable": true,
      "interventionIds": []
    },
    "location": {
      "isCapable": true,
      "interventionIds": []
    }
  }
}

Example Charger API response for an ACTIVE / CONNECTED charging pair

{
  ...
  "chargeState": {
    "isPluggedIn": true,
    "isCharging": true,
    "chargeRate": 2.3,
    "lastUpdated": "2020-04-07T17:04:26Z",
    "maxCurrent": 16,
    "powerDeliveryState": "PLUGGED_IN:CHARGING"
    // Charger Pairing: Will be "null" when not currently
    // plugged into a vehicle
    "pluggedInVehicleId": "05ee9df5-d072-4ee8-b773-399dec8f5693"
  }
  ...
}

Knowing when the vehicle is plugged in at the correct charging location

Listen for changes in both pluggedInChargerId and location.id. When pluggedInChargerId is returned and the expected location.id is returned, you can be certain that the vehicle is plugged in and at the correct charging location.