Device Model: Addressing Components and Variables
The Device Model refers to a generalized mechanism within OCPP to enable any model of Charging Station to report how it is build up, so it can be managed from any CSMS. To manage a Charging Station with the Device Model (i.e. "to manage a device") a number of messages and use cases is defined to configure and monitor a Charging Station in detail, without defining the structure of the Charging Station in advance. To be able do do this, OCPP provides a generalized mechanism to allow the exchange of a wide range of information about Charging Station. This version of the Device Model has the 3-tier model (Charging Station, EVSE, Connector) as its starting point, which means that any description created with the Device Model follows these three tiers. The remainder of this chapter describes how the data (and associated meta-data) looks like that can be exchanged between a Charging Station and a CSMS. The use cases and messages that are used to manage a device are not described here, but in Part 2 of the specification. This chapter only focuses on the data model.'
Components
In OCPP 2.0.1, a Charging Station is modelled as a set of "Components", typically representing physical devices (including any external equipment to which it is connected for data gathering and/or control), logical functionality, or logical data entities. Components of different types are primarily identified by a ComponentName, that is either the name of a standardized component (see OCPP part 2c), or a custom/non-standardized component name, for new, pre-standardized equipment, vendor specific extensions, etc.
ChargingStation (TopLevel), EVSE, and Connector represent the three major "tiers" of a Charging Station, and constitute an implicit "location-based" addressing scheme that is widely used in many OCPP data structures. By default, all components are located at the ChargingStation tier, but individual instances of any component can be associated with a specific EVSE, or a specific Connector (on a specific EVSE) by including EVSE or EVSE and Connector identification numbers as part of a component addressing reference.
Additionally, there can be more than one instance of a component (in the functional dimension), representing multi-occurrence physical or logical components (e.g. power converter modules, fan banks, resident firmware images, etc.). Each distinct component instance is uniquely identified by an (optional) componentInstance addressing key. When no componentInstance is provided, then the default or only instance of a component is referenced. Components do not in themselves hold data: all externally accessible data associated with each component instance is represented by a set of variables that can be read, set, and/or monitored for changes. The relationship of a Component with one or more Variables is illustrated in below.
The table below illustrates some common components (by their standardized component-names), and examples of the hierarchical location levels at which they typically occur for a basic home charger and a typical public Charging Station.
Basic home charger example configuration
| ChargingStation tier | EVSE tier | Connector tier |
|---|---|---|
| ChargingStation (itself, as a whole) | EVSE (itself, as a whole) | Connector (itself, as a whole) |
| RadioLink | ControlMetering | PlugRetentionLock |
| TokenReader | OverCurrentBreaker | |
| Controller | RCD | |
| ChargingStatusIndicator |
Public Charging Station example configuration
| ChargingStation tier | EVSE tier | Connector tier |
|---|---|---|
| ChargingStation (itself, as a whole) | EVSE (itself, as a whole) | Connector (itself, as a whole) |
| ElectricalFeed | ElectricalFeed | AccessProtection |
| TokenReader | TokenReader | PlugRetentionLock |
| Display | Display | |
| FiscalMetering | FiscalMetering | |
| Clock | ControlMetering | |
| Controller | OverCurrentBreaker | |
| RCD | ||
| ChargingStatusIndicator |
Variables
Every component has a number of variables, that can, as appropriate, be used to hold, set, read, and/or report on all (externally visible) data applicable to that component, including configuration parameters, measured values (e.g. a current or a temperature) and/or monitored changes to variable values.
Although many components can have associated variables that are, by their nature, specific to the component type (e.g. ConnectorType for a Connector component), there are a minimal set of standardized variables that are used to provide standardized high level event notification and state/status reporting (e.g. Problem, Active) on a global and/or selective basis, and also to report component presence, availability, etc. during the inventorying/discovery process (e.g. Available, Enabled). A Charging Station is not required to report the base variables: Present, Available and Enabled when they are readonly and set to true. When a Charging Station does not report: Present, Available and/or Enabled the Central System SHALL assume them to be readonly and set to true Variables can be any of a range of common general-purpose data types (boolean, integer, decimal, date-time, string), but also can have their allowable values constrained to particular ranges, enumeration lists, sets, or ordered lists. To support complex components, there can be more than one instance of any given variable name associated with any components (e.g. power converter modules reporting temperature, current, or voltage at multiple points). Each distinct variable instance is uniquely identified by an (optional) variableInstance addressing key string value. When no variableInstance is provided, then the default or only instance of a variable is referenced.
Characteristics and Attributes
Each variable, in addition to its primary ("Actual") value, can have a set of associated secondary data that is linked to the same primary variable name and variableInstance.
This greatly avoids cluttering the variables namespace with confusing clusters of ancillary variable names (e.g. FanSpeed, FanSpeedUnits, MinimumFanSpeed, BaseFanSpeed) that lack consistence and discoverability. The ancillary variable data includes:
- Variable characteristics meta-data (read-only)
- Unit of measure (V,W,kW,kWh, etc.)
- Data type (Integer, Decimal, String, Date, OptionList, etc.)
- Lower limit
- Upper limit
- List of allowed values for enumerated variables
- Variable attributes (read-write):
- Actual value
- Target value
- Configured lower limit
- Configured upper limit
- Mutability (whether the value can be altered or not, e.g. ReadOnly or ReadWrite)
- Persistence (whether the value is preserved in case of a reboot or power loss) The relationship of a Variable with one or more VariableAttributes is illustrated in the figure below'
There is a difference between how to implement (physical) devices and (virtual) controller components, using the DeviceModel. A (virtual) controller component has to be implementing as described in part 2 chapter the "Referenced Components and Variables". These kind of components/variables are only using the variableAttribute type 'Actual'. Depending on if this variableAttribute is writable, the CSMS can use this to set a new value.
(Physical) devices are a bit more complex to implement. For example, there is a fan with a fan speed, that has a (physical) limit with a range of 0 - 1000. But it should not be allowed to set the value below 200, because the fan can stop functioning. And it should not be set above 500, because that would be bad for the fan on the long run. When implementing this device using the DeviceModel, it can be defined as follows:
| Component | name | Fan | |
|---|---|---|---|
| Variable | name | FanSpeed | |
| variableAttribute 1 | type | Actual | |
| value | |||
| mutability | ReadOnly | ||
| variableAttribute 2 | type | Target | |
| value | |||
| mutability | ReadWrite | ||
| variableAttribute 3 | type | MaxSet | |
| value | <The value "500" from the example. The target may not be set above this value.> | ||
| variableAttribute 4 | type | MinSet | |
| value | <The value "200" from the example. The target may not be set below this value.> | ||
| variableCharacteristics | maxLimit | <The value "1000" from the example. This could be the physical max limit of the fan.> | |
| minLimit | <The value "0" from the example. This could be the physical min limit of the fan. This could also be -1000, if the fan is also able to rotate in the other direction.> | ||
| Description | This is an example of how a fan could be defined using the DeviceModel. | ||
When trying to set the target with value 600, the Charging Station will first check the allowed min and max values/limits and reject the set. If the target value is set to 500, the value is within range and the Charging Station will allow the set and start to adjust the actual fan speed. If the actual fan speed is measured to be 502, it’s out of range. But it should be reported to the CSMS, so the actual value of a physical component should be updated without checking the min and max values/limits.
Monitoring
Optional monitoring settings can be associated with a variable, that allow changes to variable (Actual) values are to be reported to the CSMS as event notifications. These include:
- Monitoring value
- Monitoring type: upper threshold, lower threshold, delta, periodic
- Severity level when reporting the event
The following table show which MonitorType/dataType combinations are possible.
| string | decimal | integer | dateTime | boolean | OptionList | SequenceList | MemberList | |
|---|---|---|---|---|---|---|---|---|
| UpperThreshold | X | X | ||||||
| LowerThreshold | X | X | ||||||
| Delta | X | X | X | X | X | X | X | X |
| Periodic | X | X | X | X | X | X | X | |
| PeriodicClockAligned | X | X | X | X | X | X | X |
- For UpperThreshold and LowerThreshold the value represents the to be exceeded value by the actual value of the variable.
- For Delta this value represents the change in value comparing with the actual value from the moment the monitor was set.
- When the dataType of the variable is integer or decimal, this value represents the difference to be reached to trigger the monitor.
- When the dataType of the variable is dateTime the unit of measure will be in seconds.
- When the dataType of the variable is string, boolean, OptionList, SequenceList or MemberList, this value is ignored. The monitor will be triggered by every change in the actual value.
- When a delta monitor is triggered OR when the Charging Station has rebooted, the Charging Station shall set a new momentary value.
- For Periodic and PeriodicClockAligned the value represents the interval in seconds.
The relationship between a Variable and one or more VariableMonitoring elements is illustrated in the figure below.
Standardized lists of Components and Variables
To provide some level of interoperability between different Charging Stations and CSMSs, besides the above defined model of Components and Variables, part 2 - appendices of the OCPP specification provides a list of standardized names for Components and Variables. The idea of this lists is to make sure that if a Charging Station and CSMS want to exchange information about a component, they both use the same name and description if it is listed in the OCPP specification. For names of a Components or Variables that are not listed in the specification, bilateral appointments between Charging Station manufacturer and CSMS are to be made. In these cases it is advised to provide feedback to the Open Charge Alliance to be able to include new/additional Components and Variables in new versions of OCPP.
Minimum Device Model
Since the Device Model is a generalized mechanism which can be applied to any model of Charging Station, the complexity of different implementations can vary. It consists of a number of use cases and messages that are not all required. This section describes the minimum part of the Device Model that needs to be implemented to create a working implementation of OCPP 2.0.1.
The Device Model introduces Components and Variables that can be used for configuring and monitoring a Charging Station. A number of these Components and Variables are included in the list of Referenced Components and Variables (grouped by Functional Block) in Part 2 of the specification. When implementing a Functional Block, ALL required Configuration Variables that belong to a Functional Block SHALL be implemented. The required Configuration Variables from the General section SHALL also be implemented for all implementations of OCPP 2.0.1.
The following table describes which messages are required or optional to implement for all use cases that are part of the Device Model implementation.
Use cases / messages that are part of a minimum Device Model implementation
| Use case | Messages |
|---|---|
| B05 Set Variables | SetVariables message MUST be implemented |
| B06 Get Variables | GetVariables message MUST be implemented. |
| B07 Get Base Report | GetBaseReport message MUST be implemented and MUST support all 3 ‘ReportBases’. The content of these reports depends on the implementation of the Charging Station. It is up to the implementer to decide which components and variables exist in the implementation. |
Additional use cases/messages that are not part of a minimium Device Model implementation
| Use case | Messages |
|---|---|
| B08 Get Custom Report | GetCustomReport message is optional. |
| N02 Get Monitoring Report | GetMonitoringReportRequest message is optional. |
| N03 Set Monitoring Base | SetMonitoringBaseRequest message is optional. |
| N04 Set Variable Monitoring | SetVariableMonitoringRequest message is optional. |
| N05 Set Monitoring Level | SetMonitoringLevelRequest message is optional. |
| N06 Clear/Remove Monitoring | ClearVariableMonitoringRequest message is optional. |
| N07 Alert Event | it is RECOMMENDED that NotifyEventRequest is implemented in the Charging Station even when monitoring is not implemented, so that this can be used to report built-in monitoring events |
| N08 Periodic Event | see N07. |