.. _Chargepoint-Specification: ==================================== 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: https://webservices.chargepoint.com/cp_api_5.0.wsdl 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 .. code-block:: bash pip install -r /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: .. code-block:: json { "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 ``. 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. .. csv-table:: getStationStatus :header: 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`. .. code-block:: xml 100 API input request executed successfully. 1:33923 1 AVAILABLE 2016-11-07T19:19:19Z 2 INUSE 2016-11-07T19:19:19Z 0 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. .. csv-table:: getLoad, shedLoad, clearShedState :header: 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` .. code-block:: xml 100 API input request executed successfully. 1:33923 ALCOGARSTATIONS / ALCOPARK 8 -005
165 13th St, Oakland, California, 94612, United States
3.314 1 0 0.000 0.000 0 2 664719 CNCP0000481668 0 3.314 0.000 0 Sample `shedLoad` XML query to set the allowed load on a port to 3.0kw. .. code-block:: xml 1:123456 1 3.0 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. .. csv-table:: getAlarms, clearAlarms :header: 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 .. code-block:: xml 1:33973 ALCOGARSTATIONS / ALCOPARK 8 -003 CT2100-HD-CCR 1:ORG07225 Alameda County 115110013418 Reachable 2016-09-26T12:19:16Z 1 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. .. csv-table:: getStationRights :header: 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." .. code-block:: xml 39491 AlcoPark 8 network_manager 1:34003 ALCOGARSTATIONS / ALCOPARK 8 -004 115110013369 000D:6F00:0154:F1FC 58279 AlcoGarageStations network_manager 1:34003 ALCOGARSTATIONS / ALCOPARK 8 -004 115110013369 000D:6F00:0154:F1FC getChargingSessionData ---------------------- Like `getAlarms`, this query returns a list of session data. The driver interface implementation will make the last session data available. .. csv-table:: getChargingSessionData :header: 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, .. code-block:: xml 1:34003 ALCOGARSTATIONS / ALCOPARK 8 -004 2
165 13th St, Oakland, California, 94612, United States
Oakland California United States 94612 53068029 12.120572 2016-10-25T15:53:35Z 2016-10-25T20:14:46Z 452777 1 490178743 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: .. code-block:: text 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: .. https://pypi.org/project/suds-jurko/ Is there a mechanism for drivers to specify their own requirements.txt ? Driver installation and configuration documentation can reference requirement.txt