Chargepoint API Driver Specification

Spec Version 1.1

ChargePoint operates the largest independently owned EV charging network in the US. It sells charge stations to businesses and provides a web application to manage and report on these Chargestations. Chargepoint offers a Web Services API that its customers may use to develop applications that integrate with the Chargepoint network devices.

The Chargepoint API Driver for VOLTTRON will enable real-time monitoring and control of Chargepoint EVSEs within the VOLTTRON platform by creating a standard VOLTTRON device driver on top of the Chargepoint Web Services API. Each port on each managed Chargestation will look like a standard VOLTTRON device, monitored and controlled through the VOLTTRON device driver interface.

Driver Scope & Functions

This driver will enable VOLTTRON to support the following use cases with Chargepoint EVSEs:

  • Monitoring of Chargestation status, load and energy consumption

  • Demand charge reduction

  • Time shifted charging

  • Demand response program participation

The data and functionality to be made available through the driver interface will be implemented using the following Chargepoint web services:

API Method Name

Key Data/Function Provided

getStationStatus

Port status: AVAILABLE, INUSE, UNREACHABLE, UNKNOWN

shedLoad

Limit station power by percent or max load for some time period.

clearShedState

Clear all shed state and allow normal charging

getLoad

Port load in Kw, shedState, allowedLoad, percentShed

getAlarms

Only the last alarm will be available.

clearAlarms

Clear all alarms.

getStationRights

Name of station rights profile, eg. ‘network_manager’

getChargingSessionData

Energy used in last session, start/end timestamps

getStations

Returns description/address/nameplate of chargestation.

The Chargepoint Driver will implement version 5.0 Rev 7 of the Chargepoint API. While the developer’s guide is not yet publicly available, the WSDL Schema is.

Note

Station Reservation API has been removed from the 5.0 version of the API.*

WSDL for this API is located here:

Mapping VOLTTRON Device Interface to Chargepoint APIs

The VOLTTRON driver interface represents a single device as a list of registers accessed through a simple get_point/ set_point API. In contrast, the Chargepoint web services for real-time monitoring and control are spread across eight distinct APIs that return hierarchical XML. The Chargepoint driver is the adaptor that will make a suite of web services look like a single VOLTTRON device.

Device Mapping

The Chargepoint driver will map a single VOLTTRON device (a driver instance) to one Chargestation. Since a Chargestation can have multiple ports, each with their own set of telemetry, the registry will include a port index column on attributes that are specific to a port. This will allow deployments to use an indexing convention that has been followed with other drivers. (See Registry Configuration for more details)

Requirements

The Chargepoint driver requires at least one additional Python library and has its own requirements.txt. Make sure to run

pip install -r <chargepoint driver path>/requirements.txt

before using this driver.

Driver Configuration

Each device must be configured with its own driver configuration file. The driver configuration must reference the registry configuration file, defining the set of points that will be available from the device. For Chargestation devices, the driver_config entry of the driver Configuration file will need to contain all parameters required by the web service API:

Parameter

Purpose

username

Credentials established through Chargepoint account

password

stationID

Unique station ID assigned by chargepoint

The driver_type must be chargepoint

A sample driver configuration file for a single device, looks like this:

{
    "driver_config": {
        "username"   : "1b905c936af141b98f9b0f816087f3605a30c1df1d07f146281b151",
        "password"   : "**Put your chargepoint API passqword here**",
        "stationID"  : "1:34003",
    },
    "driver_type": "chargepoint",
    "registry_config":"config://chargepoint.csv",
    "interval": 60,
    "heart_beat_point": "heartbeat"
}

API Plans & Access Rights

Chargepoint offers API plans that vary in available features and access rights. Some of the API calls to be implemented here are not available across all plans. Furthermore, the attributes returned in response to an API call may be limited by the API plan and access rights associated with the userid. Runtime exceptions related to plans and access rights will generate DriverInterfaceError exceptions. These can be avoided by using a registry configuration that does not include APIs or attributes that are not available to the <username>.

Registry Configuration

The registry file defines the individual points that will be exposed by the Chargepoint driver. It should only reference points that will actually be used since each point is potentially an additional web service call. The driver will be smart and limit API calls to those that are required to satisfy the points found in the CSV.

Naming of points will conform to the conventions established by the Chargepoint web services API whenever possible. Note that Chargepoint naming conventions are camel-cased with no spaces or hyphens. Multi-word names start with a lowercase letter. Single word names start uppercase.

The available registry entries for each API method name are shown below along with a description of any notable behavior associated with that register. Following that is a sample of the associated XML returned by the API.

getStationStatus

The getStationStatus query returns information for all ports on the Chargestation.

Note

In all the registry entries shown below, the Attribute Name column defines the unique name within the Chargepoint driver that must be used to reference this particular attribute and associated API. The VOLTTRON point name usually matches the Attribute Name in these examples but may be changed during deployment.

getStationStatus

Volttron Point Name

Attribute Name

Register Name

Port #

Type

Units

Starting Value

Writable

Notes

Status

Status

StationStatusRegister

1

string

FALSE

AVAILABLE, INUSE, UNREACHABLE, UNKNOWN

Status.TimeStamp

TimeStamp

StationStatusRegister

1

datetime

FALSE

Timestamp of the last communication between the station and ChargePoint

Sample XML returned by getStationStatus.

<ns1:getStationStatusResponse xmlns:ns1="urn:dictionary:com.chargepoint.webservices">
    <responseCode>100</responseCode>
    <responseText>API input request executed successfully.</responseText>
    <stationData>
        <stationID>1:33923</stationID>
        <Port>
            <portNumber>1</portNumber>
            <Status>AVAILABLE</Status>
            <TimeStamp>2016-11-07T19:19:19Z</TimeStamp>
        </Port>
        <Port>
            <portNumber>2</portNumber>
            <Status>INUSE</Status>
            <TimeStamp>2016-11-07T19:19:19Z</TimeStamp>
        </Port>
    </stationData>
    <moreFlag>0</moreFlag>
</ns1:getStationStatusResponse>

getLoad, shedLoad, clearShedState

Reading any of these values will return the result of a call to getLoad. Writing shedState=True will call shedLoad and pass the last written value of allowedLoad or percentShed. The API allows only one of these two values to be provided. Writing to allowedLoad will simultaneously set percentShed to None and vice versa.

getLoad, shedLoad, clearShedState

Volttron Point Name

Attribute Name

Register Name

Port #

Type

Units

Starting Value

Writable

Notes

shedState

shedState

LoadRegister

1

integer

0 or 1

0

TRUE

True when load shed limits are in place

portLoad

portLoad

LoadRegister

1

float

kw

FALSE

Load in kw

allowedLoad

allowedLoad

LoadRegister

1

float

kw

TRUE

Allowed load in kw when shedState is True

percentShed

percentShed

LoadRegister

1

integer

percent

TRUE

Percent of max power shed when shedState is True

Sample XML returned by getLoad

<ns1:getLoadResponse xmlns:ns1="urn:dictionary:com.chargepoint.webservices">
    <responseCode>100</responseCode>
    <responseText>API input request executed successfully.</responseText>
    <numStations></numStations>
    <groupName></groupName>
    <sgLoad></sgLoad>
    <stationData>
        <stationID>1:33923</stationID>
        <stationName>ALCOGARSTATIONS / ALCOPARK 8 -005</stationName><Address>165 13th St, Oakland, California,  94612, United States</Address>
        <stationLoad>3.314</stationLoad>
        <Port>
            <portNumber>1</portNumber>
            <userID></userID>
            <credentialID></credentialID>
            <shedState>0</shedState>
            <portLoad>0.000</portLoad>
            <allowedLoad>0.000</allowedLoad>
            <percentShed>0</percentShed>
        </Port>
        <Port>
            <portNumber>2</portNumber>
            <userID>664719</userID>
            <credentialID>CNCP0000481668</credentialID>
            <shedState>0</shedState>
            <portLoad>3.314</portLoad>
            <allowedLoad>0.000</allowedLoad>
            <percentShed>0</percentShed>
        </Port>
    </stationData>
</ns1:getLoadResponse>

Sample shedLoad XML query to set the allowed load on a port to 3.0kw.

<ns1:shedLoad>
     <shedQuery>
       <shedStation>
         <stationID>1:123456</stationID>
         <Ports>
           <Port>
             <portNumber>1</portNumber>
             <allowedLoadPerPort>3.0</allowedLoadPerPort>
           </Port>
         </Ports>
       </shedStation>
       <timeInterval/>
     </shedQuery>
   </ns1:shedLoad>

getAlarms, clearAlarms

The getAlarms query returns a list of all alarms since last cleared. The driver interface will only return data for the most recent alarm, if present. While the getAlarm query provides various station identifying attributes, these will be made available through registers associated with the getStations API. If an alarm is not specific to a particular port, it will be associated with all Chargestation ports and available through any of its device instances.

Write True to clearAlarms to submit the clearAlarms query to the chargestation. It will clear alarms across all ports on that Chargestation.

getAlarms, clearAlarms

Volttron Point Name

Attribute Name

Register Name

Port #

Type

Units

Starting Value

Writable

Notes

alarmType

alarmType

AlarmRegister

string

FALSE

eg. ‘GFCI Trip’

alarmTime

alarmTime

AlarmRegister

datetime

FALSE

clearAlarms

clearAlarms

AlarmRegister

int

0

TRUE

Sends the clearAlarms query when set to True

<Alarms>
    <stationID>1:33973</stationID>
    <stationName>ALCOGARSTATIONS / ALCOPARK 8 -003</stationName>
    <stationModel>CT2100-HD-CCR</stationModel>
    <orgID>1:ORG07225</orgID>
    <organizationName>Alameda County</organizationName>
    <stationManufacturer></stationManufacturer>
    <stationSerialNum>115110013418</stationSerialNum>
    <portNumber></portNumber>
    <alarmType>Reachable</alarmType>
    <alarmTime>2016-09-26T12:19:16Z</alarmTime>
    <recordNumber>1</recordNumber>
</Alarms>

getStationRights

Returns the name of the stations rights profile. A station may have multiple station rights profiles, each associated with a different station group ID. For this reason, the stationRightsProfile register will return a dictionary of (sgID, name) pairs. Since this is a Chargestation level attribute, it will be returned for all ports.

getStationRights

Volttron Point Name

Attribute Name

Register Name

Port #

Type

Units

Starting Value

Writable

Notes

stationRightsProfile

stationRightsProfile

StationRightsRegister

dictionary

FALSE

Dictionary of sgID, rights name tuples.

<rightsData>
    <sgID>39491</sgID>
    <sgName>AlcoPark 8</sgName>
    <stationRightsProfile>network_manager</stationRightsProfile>
    <stationData>
        <stationID>1:34003</stationID>
        <stationName>ALCOGARSTATIONS / ALCOPARK 8 -004</stationName>
        <stationSerialNum>115110013369</stationSerialNum>
        <stationMacAddr>000D:6F00:0154:F1FC</stationMacAddr>
    </stationData>
</rightsData>
<rightsData>
    <sgID>58279</sgID>
    <sgName>AlcoGarageStations</sgName>
    <stationRightsProfile>network_manager</stationRightsProfile>
    <stationData>
        <stationID>1:34003</stationID>
        <stationName>ALCOGARSTATIONS / ALCOPARK 8 -004</stationName>
        <stationSerialNum>115110013369</stationSerialNum>
        <stationMacAddr>000D:6F00:0154:F1FC</stationMacAddr>
    </stationData>
</rightsData>

getChargingSessionData

Like getAlarms, this query returns a list of session data. The driver interface implementation will make the last session data available.

getChargingSessionData

Volttron Point Name

Attribute Name

Register Name

Port #

Type

Units

Starting Value

Writable

Notes

sessionID

sessionID

ChargingSessionRegister

1

string

FALSE

startTime

startTime

ChargingSessionRegister

1

datetime

FALSE

endTime

endTime

ChargingSessionRegister

1

datetime

FALSE

Energy

Energy

ChargingSessionRegister

1

float

FALSE

rfidSerialNumber

rfidSerialNumber

ChargingSessionRegister

1

string

FALSE

driverAccountNumber

driverAccountNumber

ChargingSessionRegister

1

string

FALSE

driverName

driverName

ChargingSessionRegister

1

string

FALSE

<ChargingSessionData>
    <stationID>1:34003</stationID>
    <stationName>ALCOGARSTATIONS / ALCOPARK 8 -004</stationName>
    <portNumber>2</portNumber>
    <Address>165 13th St, Oakland, California, 94612, United States</Address>
    <City>Oakland</City>
    <State>California</State>
    <Country>United States</Country>
    <postalCode>94612</postalCode>
    <sessionID>53068029</sessionID>
    <Energy>12.120572</Energy>
    <startTime>2016-10-25T15:53:35Z</startTime>
    <endTime>2016-10-25T20:14:46Z</endTime>
    <userID>452777</userID>
    <recordNumber>1</recordNumber>
    <credentialID>490178743</credentialID>
</ChargingSessionData>

getStations

This API call returns a complete description of the Chargestation in 40 fields. This information is essentially static and will change infrequently. It should not be scraped on a regular basis. The list of attributes will be included in the registry CSV but are only listed here:

stationID, stationManufacturer, stationModel, portNUmber, stationName, stationMacAddr, stationSerialNum, Address, City,
State, Country, postalCode, Lat, Long, Reservable, Level, Mode, Connector, Voltage, Current, Power, numPorts, Type,
startTime, endTime, minPrice, maxPrice, unitPricePerHour, unitPricePerSession, unitPricePerKWh, unitPricePerHourThereafter,
sessionTime, Description, mainPhone, orgID, organizationName, sgID, sgName, currencyCode

Engineering Discussion

Questions

  • Allowed python-type - We propose a register with a python-type of dictionary. Is this OK?

  • Scrape Interval - Scrape all should not return all registers defined in the CSV, we propose fine grained control with a scrape-interval on each register. Response: ok to add extra settings to registry but don’t worry about publishing static data with every scrape

  • Data currency - Since devices are likely to share api calls, at least across ports, we need to think about the currency of the data and possibly allowing this to be a configurable parameter or derived from the scrape interval . Response: add to CSV with default values if not present

Performance

Web service calls across the internet will be significantly slower than typical VOLTTRON Bacnet or Modbus devices. It may be prohibitively expensive for each Chargepoint sub-agent instance to make individual requests on behalf of its own EVSE+port. We will need to examine the possibility of making a single request for all active Chargestations and sharing that information across driver instances. This could be done through a separate agent that regularly queries the Chargepoint network and makes the data available to each sub-agent via an RPC call.

3rd Party Library Dependencies

The Chargepoint driver implementation will depend on one additional 3rd part library that is not part of a standard VOLTTRON installation:

Is there a mechanism for drivers to specify their own requirements.txt ?

Driver installation and configuration documentation can reference requirement.txt