Solidstudio is happy to introduce you to the Open Standards course led by our e-mobility expert - Bartlomiej. Throughout the following lessons, we will uncover the technicalities and functionalities of the OICP - a protocol developed by Hubject - as well as business aspects for e-Mobility Service Providers and Charge Point Operators.
Such a knowledge-pack should serve everyone operating in the e-mobility industry as it unfolds the most crucial aspects of navigating through Open Standards utilization and many more!
Subscribe to our YouTube channel to make sure you don't miss out on the upcoming training entries.
See the first lesson here! And the second one here!
Open InterCharge Protocol Training - Lesson 3
OICP Training Transcript
Transport and availability
In this module, let's cover some basic technical details characteristic for OICP.
Beginning with OICP version 2.2, every communication must be based on HTTP protocol and use JSON data format in messages. In the past, it was also possible to use SOAP protocol but now it's deprecated and cannot be used anymore. Every service in OICP is synchronous, therefore for each request there must be a response. In most of the services, the response format is an acknowledgement message. When it comes to the character encoding in OICP, there must be in UTF-8. Worth mentioning is the fact that the Hubject platform is highly available. All the details regarding the SLA are individually specified in your partner contracts.
POI Data Check
Speaking of data, Hubject aims for high quality data management to enable all partners further scaling. In order to avoid data-related issues, Hubject provides point-of-interest data quality guidelines. Each guideline is a list of property names together with type, description, example and information whether this data is mandatory or not. The other reason for that step is to guarantee a good charging experience for customers and a unique selling point. Each partner is obliged to fill in a point-of-interest data check form and mark if they are able to meet the requirements for specific property. Building form should be sent to your support onboarding team before end-to-end test.
Status Codes
As I've just said, a response message should be a result of any kind of operation in services. In this response message, you must also include information about the status of a given operation. OICP has its own standardized status code and description format. State is called message property - a carrier of that information. The general status code is 000. Below, you can find an example: how it looks like in practice and what is the typical status code response.
Internal System Codes
Hubject distinguishes between four different types of status codes. The first type is internal system code; here we can include information that an error is about the Hubject system, Hubject database, data transaction, unauthorized access, inconsistent EVcoID, inconsistent EVseID, more general system or data errors.
Authentication codes
The next types of status codes are the authentication ones. Here, we can specify more details regarding authentication related errors i.e. we may specify that we had invalid credentials for QR code, that we had invalid UID or cards not readable for RFID, that we have invalid EVcoID for PLC, that we had no positive authentication response, that we have received timeout error on QR code authentication, that we had invalid underlying EVcoID, invalid certificate or timeout error on PLC or that EVcoID was blocked.
Session codes
Then, we have session related codes. What's more important, those are not the codes related with the charging session itself, but with the session mechanism. So, we may specify that there is no valid contract, that partner is not found, that partner did not respond, that the service is unavailable or that the session is invalid.
EVSE codes
Finally, we have EVSE related codes which can specify more details about problems with charging station i.e. we can specify that communication with EVSE has failed, that there is no electric vehicle connected to EVSE , that EVSE is already reserved, that EVSE is already in use or that we have received wrong token, that we don't know EVSE ID and it is unknown, that EVSE ID is not Hubject-compatible or that EVSE is out of a service.
Session handling
Some services, especially authorization service, require a session mechanism in order to correlate a series of individual operations. The typical scenario is i.e. charging start and stop, as well as pushing CDR correlated with the already finished charging session. If that happens, then session ID must be returned in a response for every initial request i.e. eRoamingAuthorizeStart. Session ID must be provided in each subsequence request. It's good to know that the session ID created by Hubject is in GUID format.
Custom sessions
Hubject also offers a possibility to use your own session mechanism by adding two additional properties to each initial request: CPO partner session ID or EMP partner session ID. If the value in one of those properties is provided, then it will be used as a session ID after the initial request. The same value beside the session ID will be also returned as a CPO partner session ID or EMP partner session ID in order to make processing a little bit easier.
Partner roles
In OICP, the message format can be the same for both types of roles: CPO or EMP. Because of that, Hubject needed to create another mechanism in order to differentiate service operations between those two rows. You, as a partner, need to provide in each request either provider ID if you're an EMP or operator ID if you are a CPO. Those two identifiers are unique within the whole Hubject platform and they are assigned to you as a partner during the onboarding process. You, as a partner, may also have both rows CPO and EMP; in this case you need to provide only one value either provider ID or operator ID in each request. Operator ID and provider ID have similar format but with the small differences which we will see in examples later. In general, they are created according to the ISO15118 specification. When it comes to the date and time, it's pretty simple; it needs to be delivered in a given ISO format. It's good to know that Hubject will store those values in their databases in their original form - there will be no conversion to UTC, timestamp or any other form. Below, you can find an example of what it looks like and what the format is.
Data push
One of the most important things to remember about OICP protocol is that the data push request for the same service operation needs to be sent sequentially. For example: if you push EVSE data in a few requests, then please make sure that they are being executed one by one after a response from a server is received. The reason for that is because Hubject can process those requests in parallel, therefore sending many requests at the same time may change the expected result or even unintentionally override the data set.
Pagination
Pagination was introduced in some services in the latest OCIP version. Nothing extraordinary, but it's good to know what the response looks like with properties; content which is a list of elements: number, size, total elements, number of elements, first, last and total pages. When it comes to the query itself, it's also pretty straightforward, you need to provide page and size.
Security
Security aspect of the OICP protocol is also very convenient. Hubject will compare if the provider ID or operator ID is compliant with your SSL client certificate in every request. That should prevent the situation when some partner will perform an operation in the name of the other partner just by providing the correct ID. If there will be a mismatch, then the 017 status code should be returned with an unauthorized access message. Please remember also that Hubject will validate if the IP is on the white list, so your server must have a static IP.
Details of certificate signing request generation will be delivered to you during the pre-contract phase, but in general this process is quite simple. But first, you need to generate private and public key in order to encrypt and decrypt some messages. Then, you need to generate CSR with PKSCS10 standard. After that, you need to send it to Hubject via email and also send the passwords or encrypted files in some other way. Onboarding manager will verify if everything went correctly and they will sign those certificates. Also, in the QA phase, you will receive signed partner certificates together with CA certificates to convert them and finally you can access web services with client authentication.