├── docs └── Datenformat_OCMF_v1.0.1-DRAFT.PDF ├── README.md ├── OCMF-en.md └── resources └── import-energy-flow-ocmf.svg /docs/Datenformat_OCMF_v1.0.1-DRAFT.PDF: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SAFE-eV/OCMF-Open-Charge-Metering-Format/HEAD/docs/Datenformat_OCMF_v1.0.1-DRAFT.PDF -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Open Charge Metering Format (OCMF) 2 | 3 | This is a markdown version of the OCMF specification for further development within the SAFE Group. 4 | 5 | Latest english version: [OCMF-en.md](OCMF-en.md) 6 | 7 | Upcoming versions can be found in branches. 8 | 9 | # Modus operandi 10 | Everybody is allowed to bring a suggestion with a Pull request in the OCMF GitHub repository. The suggestions will be discussed in the UAG OCMF which takes place biweekly on Thursdays between 2p.m and 3p.m CET / CEST. 11 | If you are a member of SAFE e.V. and you want to participate the meetings contact Matthias Grote (matthias.grote@safe-ev.de) and Florian Riegler (rief@keba.com) 12 | 13 | All credits to the authors of the document. 14 | -------------------------------------------------------------------------------- /OCMF-en.md: -------------------------------------------------------------------------------- 1 | # Open Charge Metering Format 2 | 3 | ## Contributors 4 | 5 | | Role | Responsible | Company | 6 | |---------------|--------------------------------------------|-------------------------------------------| 7 | | Authors | Andreas Mull, ABL (AM), Daniel Müller (DM) | [ABL](https://www.abl.de/) | 8 | | Editors | Gerhard Weidinger, Riegler Florian (FR) | [KEBA](https://www.keba.com/) | 9 | | Contributors | Martin Klässner, Roland Angerer | [has.to.be](https://has-to-be.com/) | 10 | | Contributors | Andreas Weber | [Allego](https://www.allego.eu/) | 11 | | Contributors | Michael Staubermann | [Webolution](https://www.webolution.de/) | 12 | | Contributors | Michael Heimpold | [chargebyte](https://www.chargebyte.com/) | 13 | | Contributors | Mathieu Lémont | [LEM](https://www.lem.com/) | 14 | | Contributors | Stefan Zenger, Luca Horn | [DZG](https://www.dzg.de/en/) | 15 | 16 | 17 | ## Revision Overview 18 | 19 | Changes from the previous version are marked with change tracking. 20 | 21 | | Revision | Content | Date | 22 | |----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| 23 | | 1.4.1 | Improved description of unified OBIS definition in OCMF version 1.4 | 2025-01-15/FR | 24 | | 1.4.0 | Added unified OBIS definition compliant with IEC62056-6-1 | 2024-12-05/FR | 25 | | 1.3.1 | Removed redundant version string on top of the file, using this table as a singularity for versioning instead | 2024-05-16/FR | 26 | | 1.3.0 | Add optional field "CF" for EVSE charge controller firmware version | 2024-04-18/FR | 27 | | 1.2.0 | Cable loss compensation data, definition of new parameters used for compensating Energy loss due to EVSE's charging Cable Resistance | 2023-05-24/AM | 28 | | 1.1.0 | Ad-hoc charging, added tariff information. | 2023-02-09/FR | 29 | | 1.0.2 | Removal of the no longer needed OBIS code table, which was needed for the deleted binary format. Added best practice examples to enable consistent implementation and transfer of OCMF records via OCPP. | 2020-02-15/FR | 30 | | 1.0.1 | Definition of the meaning of the version numbers. More detailed definition on the structure of the format. Delete binary format and transmission format (transformation is not possible without recalculation of the signature). | 2020-02-15/FR | 31 | | 1.0 | Final state for integration in transparency software. Feedback from SAFE AG Technik incorporated: Signature algorithm not in data-to-be-signed space after all, so that theoretically multiple different signatures can be appended independently. Reading type optional. Additional state on time status: relative time accounting based on info clock. OBIS codes expanded to applicable options according to comments from Mr. Weber. | 21.02.2019/AM | 2009-02-21/AM | 32 | | 0.5 | Further feedback from DKE/GAK 461.0.21 AP5 from January 2019 incorporated: Clarifications on pagination, reference of serial numbers, charge point and public key. Optional user data section for charging point relation. Error index replaced by erroneous quantities; error during charge as reason for reading. Feedback from Mr. Weber on version 0.3 incorporated: power generation, current types. Byte offset in binary descriptions removed, because they contradicted with StrEnum types. Feedback from Mr. Staubermann on elliptic curve cryptography: synonymous names of curves, correction of block lengths for public key types. | 2019-02-11/AM | 33 | | 0.4 | Results and clarifications after feedback from conference calls with DKE/GAK 461.0.21 AP5: Document and format versions corrected; binary format clarified: Network byte order; pagination count clarified, pagination defined; signature device identification (gateway) placed above meter identification, integrated into general details, vendor renamed to gateway, serial number mandatory for either gateway or meter; user mapping: status split into general yes/no and mapping level, level split into groups; all status details other than yes/no are now optional. Usage of event counter clarified, pagination defined; note on accuracy for measured value; signature algorithm moved to signed area; signature algorithms extended by future candidates, key types analog; defaults provided with OCMF version. Authorization features extended according to OCPP 2.0; extension points for OCMF defined in user data and signature sections. | 2019-01-11/AM | 34 | | 0.3 | State of the meter added for incorrectly read values. | 2018-12-11/DM | 35 | | 0.2 | Binary format adapted according to the changes with 0.1, description of the signature algorithm concretized, StrEnum type introduced as flexible extension point into the binary format. | 2018-08-16/AM | 36 | | 0.1 | This document is based on ABL data format version 1.14 and replaces it. Initial version after discussion of ABL's data format (v1.13) with KEBA and has.to.be: decoupling of the binary transmission format from the custody transfer relevant part, JSON as primary transmission format. Header and overall structure defined. Fields aligned with draft "Requirements for the data structure for metering tuples in electromobility" of 2018-04.26. JSON format structurally simplified, keys shortened. Possibility of multiple readings in one data set created. Firmware version of the meter optionally added. Errors as abort reasons for charging processes. Hash type for signature defined. | 2018-08-09/AM | 37 | 38 | 39 | ## General 40 | 41 | ### Goal 42 | 43 | The aim of this concept is to describe an independent and generally usable data format for recording meter readings from 44 | charging stations that are relevant under calibration law. Furthermore, this concept can serve as a basis for discussion 45 | for utilization in the DKE. In addition, it is to serve for the implementation of the evaluation and signature 46 | verification of the format by the [Transparency Software](https://transparenz.software/) to be created within 47 | the SAFE initiative. 48 | 49 | At the time of writing, no uniform data format for the transmission of signed meter readings has been adopted at the 50 | standardization level. A corresponding application guideline is currently being developed. The presented data format 51 | originates from an internal draft of ABL and was discussed with has.to.be and KEBA. 52 | 53 | A uniform format brings the advantage of interoperability and enables uniform verification software at the operator and 54 | the end user. The concept presented here is based on the end-to-end security concept for a custody transfer ("GL") 55 | solution for the transmission of measurement data to remote displays by Dr. Martin Kahmann [MEMOGL]. 56 | It further builds on ABL's internal concept for legal metrology compliance. 57 | 58 | This document is structured as follows: first, a classification and presentation of the transmission of the 59 | data format is given, in the further sections the data format is explained. 60 | 61 | 62 | ### License 63 | 64 | This document is licensed under the [Creative Commons Attribution-NoDerivatives 4.0 International Public 65 | License](https://creativecommons.org/licenses/by-nd/4.0/legalcode). 66 | 67 | 68 | ### References 69 | 70 | - OCPP 1.5: Open Charge Alliance: Open Charge Point Protocol - Interface description between 71 | Charge Point and Central System, Version 1.5, as of June 8, 2012. 72 | - MEMO-GL: Messsysteme für Ladeeinrichtungen: Ende-zu-Ende-Sicherungskonzept für eine eichrechtlich 73 | günstige Lösung („GL“) für die Übertragung von Messdaten auf Fernanzeigen, Dr. Martin Kahmann, Braunschweig 74 | - OBIS: IEC 62056-6-1 and IEC 62056-6-2. 75 | - JSON: Introducing JSON, https://www.json.org/json-de.html (retrieved: 2018-04-04). 76 | 77 | 78 | ### Used Abbreviations 79 | 80 | * API: Application Programming Interface 81 | * ASCII: American Standard Code for Information Interchange 82 | * CDR: Charge Data Record 83 | * CPO: Charge Point Operator 84 | * DKE: Deutsche Kommission Elektrotechnik Elektronik Informationstechnik 85 | (German Commission for Electrical, Electronic & Information Technologies) 86 | * ECDSA: Elliptic Curve Digital Signature Algorithm 87 | * EMP: Electric Mobility Provider 88 | * ISO: International Standards Organization 89 | * MID: Measuring Instruments Directive, european directive 2014/32/EU 90 | * OBIS: Object Identification System 91 | * OCPP: Open Charge Point Protocol 92 | * PIN: Personal Identification Number 93 | * PTB: Physikalisch-Technische Bundesanstalt (German national metrology institute) 94 | * RFC: Request For Comments 95 | * RFID: Radio Frequency Identification 96 | * RTU: Remote Terminal Unit 97 | * SHA: Secure Hash Algorithm 98 | * TLS: Transport Layer Security 99 | * UID: Unique Identification 100 | * UTC: Universal Time Coordinated 101 | 102 | 103 | ### Versioning of the Document 104 | 105 | The version number of this document is structured as follows: 106 | 107 | **Major Version:** 108 | Changes at this point mean that the format has changed fundamentally. 109 | Changes have been made to the format that are no longer compatible with previous versions. 110 | 111 | **Minor:** 112 | The format has been supplemented new fields or new values of a field have been added. 113 | (Changes to the format. Backward compatibility is given) 114 | 115 | **Revision:** 116 | Changes in the documentation. No changes in the format. 117 | Increasing the revision does not change the format itself. The documentation is adapted or improved. 118 | 119 | Example: 1.0.2 120 | 1 = Major 121 | 0 = Minor 122 | 2 = Revision 123 | 124 | 125 | ## Transmission of Signed meter Readings 126 | 127 | ### Embedding in OCPP 128 | 129 | OCPP version 1.5 already allows the simultaneous transmission of any number of MeterValue objects as part of the 130 | MeterValue.req and StopTransaction.req messages. Each such object may in turn have a timestamp noted along with 131 | one or more meter reading values. Each value may optionally be accompanied by attributes, one of which is of the 132 | ValueFormat enum type, which has two possible values: 133 | 134 | * Raw: Data is to be interpreted as integer/decimal numeric data. 135 | * SignedData: Data is represented as a signed binary data block, encoded as hex data. 136 | 137 | _Source: [OCPP 1.5]_ 138 | 139 | This makes it possible to continue using the functionality provided by OCPP and to combine it with the possibility 140 | of transmitting signed meter values. 141 | 142 | The data format presented here is therefore intended for parallel transmission of such a SignedData "value" in 143 | addition to the usual raw values. 144 | 145 | While the reading of the usual values may be based on a time that does not conform to the calibration law (OCPP based), 146 | the signed meter values however __are__ based on a time that conforms to the calibration law. 147 | Even the two resulting times can be correctly represented separately in two MeterValue objects. 148 | 149 | This mechanism is used in the context of: 150 | 151 | - start of a transaction (StartTransaction) 152 | - readings during a transaction (MeterValues) 153 | - end of transaction (StopTransaction) 154 | - Charge Data Record over the whole transaction with values at start and end (optional) 155 | - Readings for so-called "Fiscal Metering" (MeterValuesAlignedData): here, no reference to ongoing transactions 156 | is recorded, but only the absolute meter values of all charge points at previously determined points in time. 157 | 158 | It should be noted that, as a rule, the following readings are relevant under calibration law: 159 | 160 | - start and end value in relation to the charging transaction 161 | - tariff changes (common practice is have tariff changes only at the quarter hours of the clock). 162 | 163 | Thus the following OCPP configuration is typically useful: 164 | 165 | - ClockAlignedDataInterval = 900 (15 min) 166 | - MeterValuesAlignedData = Active.Energy.Register.Import 167 | - Controller software takes care of generating additional MeterValues with signed values at the start and end 168 | of the charging process beyond the simple integer value that can be part of 169 | the StartTransaction.req/StopTransaction.req messages. 170 | 171 | 172 | ### Signing and Verification Process 173 | 174 | In order to verify a data set, the data that has been signed must first be restored to its original form. 175 | A hash calculation is performed on this original form. The result is verified with a digital signature using ECDSA. 176 | 177 | To produce the original form, the header and signature are separated from the data record. 178 | If necessary, the public key is verified via a separate transmission path. 179 | 180 | This means that the signature and the public key are shown separately in the unified data record. 181 | 182 | The cohesion between several individual data records is ensured by continuous pagination. 183 | In addition to the signature, this must be verified by a check component. The first record 184 | must be marked as the start of a charging process, the last as the end of the charging process. 185 | In between, no data records may have been removed or added. Likewise, intermediate 186 | error conditions (error counters) and the detection of unusable variables must lead 187 | to an error during the test. 188 | Furthermore, all data records must come from the same source (serial number). 189 | 190 | 191 | ## Data Format 192 | 193 | The data format should be as simple as possible and comprehensible by the experienced user. From a 194 | manufacturer point of view, a modular data format is desirable, so that extensions can be implemented 195 | in future. 196 | Another concern is to make the verification process as generic as possible, i.e. also 197 | applicable to other source formats. For this reason, a header section was included in the format. 198 | 199 | The format consists of several sections: 200 | 201 | 1. a **Header** to unambiguously identify the format 202 | 2. the actual **Payload Data** 203 | 3. a **Signature** over the payload data 204 | 205 | The contents of the record serve as the input format into [Transparency Software](https://transparenz.software/). 206 | This software is available online for anyone to use to validate the dataset. 207 | 208 | In the following chapters, the data format for the representation and transmission of the signed meter values is defined. 209 | 210 | 211 | ## JSON based OCMF Format 212 | 213 | The JSON notation was chosen for the individual sections of the format for better readability and easier traceability. 214 | To save data volume, the following measures were taken: 215 | 216 | - Identifiers are kept short (since some need explanation anyway, not much clarity is lost here) 217 | - In some places encapsulation was deliberately omitted. Instead, the identifiers are canonicalized. 218 | 219 | The sections within the data format are separated with the special pipe character "|". 220 | Within the sections, the format corresponds to the JSON notation. 221 | Thus, the use of the special pipe character "|" is not allowed within the sections. 222 | 223 | The fact, that the format can be enriched according to the JSON notation with spaces and line feeds at 224 | at any position - called white space - for display purposes, also makes it easier for a user to read. 225 | 226 | Between signing and validation, the payload section must not be manipulated (removing and adding white spaces), 227 | otherwise positive validation is not possible. 228 | 229 | In the following, the different sections of the format are explained. Furthermore, an example is given. 230 | 231 | 232 | ### Sections 233 | 234 | At the beginning of the format, there is a header for unique identification of the format. 235 | The user data section and the signature section follow, separated by pipe characters. 236 | This results in the following structure for the sections: 237 | 238 | OCMF|| 239 | 240 | The placeholders ** and ** are to be replaced 241 | by the contents of the respective sections. 242 | 243 | 244 | #### Header 245 | 246 | The header is used to unambiguously identify the transmission format. 247 | In the case of OCMF, the string "OCMF" must be specified in this section. 248 | 249 | 250 | #### Payload Data Section 251 | 252 | The payload data section consists of a JSON object. This contains several value mappings or 253 | sub-objects. The contents of the payload data section must not be modified between signing 254 | and verification of the signature. 255 | 256 | 257 | ##### General Information 258 | 259 | The information in this section refers primarily to the signature-generating component, 260 | which is referred here as the gateway for the sake of simplicity. 261 | Depending on the structure, it would be more appropriate to refer to it using *measuring capsule* 262 | or *the signing component*. 263 | 264 | | Key | Type | Cardinality | Description | 265 | |-----|--------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 266 | | FV | String | 0..1 | Format Version: Version of the data format in the representation . The version specification is coded according to the version of this document, i.e. 0.4 corresponds to major 0 and minor 4. The revision (third digit) is not transmitted, since this does not change anything in the format itself. | 267 | | GI | String | 0..1 | Gateway Identification: Identifier of the manufacturer for the system which has generated the present data (manufacturer, model, variant, etc.). | 268 | | GS | String | 0..1 | Gateway Serial: Serial number of the above mentioned system. This field is conditionally mandatory. | 269 | | GV | String | 0..1 | Gateway Version: Version designation of the manufacturer for the software of the above mentioned system. This field is optional. | 270 | Table 1: General Information Fields 271 | 272 | 273 | ##### Pagination 274 | 275 | The pagination indicates the reference to a transaction and arranges the total data record in the stream of the 276 | readings via the meters in a comprehensible way. Several contexts are available for pagination, 277 | each context has its own counter. The respective pagination counter is counted monotonically in 278 | ascending order with an increment of 1. That means, successive values of the pagination counter count continuously 279 | in the space of natural numbers. 280 | 281 | The transaction context (T) must be supported in any case. The fiscal context (F) is optional and can be supported 282 | by the signature component as an option if signed readings outside of transactions are desired. 283 | 284 | | Key | Type | Cardinality | Description | 285 | |-----|--------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 286 | | PG | String | 1..1 | Pagination of the entire data set, i.e. the data that is combined in one signature. Format: ``
The string is composed of an identifying letter for the context and a number without leading zeros. There is a separate independent pagination counter for each context. The following indicators are defined:
T: Transaction – readings in transaction reference (mandatory)
F: Fiscal – readings independent of transactions (optional)
The respective pagination counter is incremented after each use for a record. | 287 | Table 2: Pagination Field 288 | 289 | 290 | ##### Meter Identification 291 | 292 | The meter identification is optional if the signature generating component has already been identified in the general data. 293 | 294 | | Key | Type | Cardinality | Description | 295 | |-----|--------|-------------|----------------------------------------------------------------------------------| 296 | | MV | String | 0..1 | Meter Vendor: Manufacturer identification of the meter, name of the manufacturer | 297 | | MM | String | 0..1 | Meter Model: Model identification of the meter | 298 | | MS | String | 1..1 | Meter Serial: Serial number of the meter | 299 | | MF | String | 0..1 | Meter Firmware: Firmware version of the meter | 300 | Table 3: Fields for Identification of the Meter 301 | 302 | 303 | ##### User Assignment 304 | 305 | Fields belonging to this are included exactly when there is a transaction reference. 306 | Even if no user can be assigned yet in transaction reference case, the section is included. 307 | If no transaction reference exists, this group of fields is missing. 308 | 309 | | Key | Type | Cardinality | Description | 310 | |-----|------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 311 | | IS | Boolean | 1..1 | Identification Status: General status for user assignment:
true: user successfully assigned
false: user not assigned | 312 | | IL | String | 0..1 | Identification Level: Encoded overall status of the user assignment, represented by an identifier from table 11. | 313 | | IF | Array of Strings | 0..4 | Identification Flags: Detailed statements about the user assignment, represented by one or more identifiers from table 13 to table 16. The identifiers are always noted as string elements in an array. Also one or no element must be noted as an array. | 314 | | IT | String | 1..1 | Identification Type: Type of identification data, identifier see table 17. | 315 | | ID | String | 0..1 | Identification Data: The actual identification data according to the type from table 17, e.g. a hex-coded UID according to ISO 14443. | 316 | | TT | String (0..250) | 0..1 | Tariff Text: A textual description used to identify a unique tariff. This field is intended for the tariff designation in "Direct Payment" use case. | 317 | Table 4: Fields for User Assignment 318 | 319 | ##### EVSE Metrologic parameters 320 | 321 | Fields described in this section trace EVSE parameters that are influent for metrology. 322 | 323 | | Key | Type | Cardinality | Description | 324 | |-----|--------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 325 | | CF | String
(0..25) | 0..1 | Charge Controller Firmware Version: Firmware version of the charge controller on the EVSE.
This optional value is, e.g., required by (some) notified bodies to ensure traceability of any OCMF data set to the documentation of the corresponding Schalt-Mess-Koordination ("switch-measure-coordination"). 326 | | LC | Object | 0..1 | Loss Compensation: Characteristics of EVSE's charging cable used for identifying and processing cable loss compensation algorithm. Parameters of these characteristics are defined in table 24. | 327 | Table 5: Fields for EVSE Metrologic Parameters 328 | 329 | 330 | ##### Assignment of the Charge Point 331 | 332 | This optional user data section provides a way to identify the charging point. 333 | This can be an alternative to identification by serial numbers or can be used additionally. 334 | 335 | | Key | Type | Cardinality | Description | 336 | |-----|--------|-------------|----------------------------------------------------------------------------------------------------------------------------------| 337 | | CT | String | 0..1 | Charge Point Identification Type: Type of the specification for the identification of the charge point, identifier see table 18. | 338 | | CI | String | 0..1 | Charge Point Identification: Identification information for the charge point. | 339 | Table 6: Fields for Identification of the Charge Point 340 | 341 | 342 | ##### Readings 343 | 344 | One or more readings can be stored in a record. Each reading is encapsulated in a sub-object. 345 | These objects are noted as an array under the key "RD" for Reading(s). 346 | This array thus contains one or more anonymous objects. 347 | Each of these objects is constructed as described in table 7. 348 | For the readings, fields that have an identical value to the previous reading are omitted. 349 | However, this only applies within a signed record. This means concretely that, for example, only in the first 350 | sub-object the field "RI" is defined with a value (here the OBIS code) and is thus valid for all further readings. 351 | Likewise, for example, the field "TX" can be defined in the first sub-object as `B`, in the second as `C`, 352 | in the last with `E`, which means that the readings three to the penultimate take the value `C`. 353 | The fields `RV`, `RI` , `RU` and `RT` can be omitted if only the occurrence of an error condition (event) 354 | of the meter is to be indicated. 355 | The fields `RI` and `RU` form a group. Fields of a group are either all present together or omitted together. 356 | A power failure during time-based billing represents an error event. 357 | 358 | | Key | Type | Cardinality | Description | 359 | |-----|--------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 360 | | TM | String | 1..1 | Time: Specification to the system time of the reading and synchronization state.
The time is described according to ISO 8601 with a resolution of milliseconds. Accordingly, the format is according to the following scheme:
`--T::,