The Open Charge Point Protocol (OCPP) is a network protocol for communication between electric vehicle chargers and a central backoffice system. It is developed by the Open Charge Alliance (OCA). You can find more details on the official website of the OCA.
Open source users of this library will want to use the IHomer fork which is more actively supported and published to Maven Central.
This library is the implementation of OCPP developed and used by NewMotion, one of Europe's largest Electric Vehicle Charge Point Operators.
This library only implements the network protocol. That is, it provides data types for the OCPP messages, remote procedure call using those request and response messages, and error reporting about those remote procedure calls. It does not provide any actual handling of the message contents. For an actual app speaking OCPP using this library, see docile-charge-point.
The library is designed with versatility in mind. OCPP comes in 4 versions (1.2, 1.5, 1.6 and 2.0), two transport variants (SOAP/XML aka OCPP-S and WebSocket/JSON aka OCPP-J), and two roles ("Charge Point" and "Central System"). This library will help you with 1.5 and 1.6 over JSON. For 1.2 and 1.5 over SOAP, there is a separate library by NewMotion that depends on this one. Some OCPP 2.0 support is present, but not a full implementation yet. The main body of this README will be writing about the OCPP 1.5 and 1.6 support; for OCPP 2.0 see here.
Version 2.0 with SOAP/XML is not possible. Version 1.2 with WebSocket/JSON and version 1.6 with SOAP/XML are not supported by this library.
Users of this library probably want to use different WebSocket libraries for different scenarios: a production back-office server with tens of thousands of concurrent connections, a client in a load testing tool, or a simple one-off script to test a certain behavior. This library uses the cake pattern to make it easy to swap out the underlying WebSocket implementation while still using the same concise high-level API.
The library is divided into three separate modules so applications using it won't get too many dependencies dragged in. Those are:
ocpp-j-api
: high-level interface to OCPP-J connectionsocpp-json
: serialization of OCPP messages to/from JSONocpp-messages
: The definitions of OCPP messages, independent from
the transport variant usedSo if you want to use the high-level OCPP-J connection interface, and you're
using SBT, you can declare the dependency by adding this this to your build.sbt
after publishing the library:
libraryDependencies += "com.thenewmotion.ocpp" %% "ocpp-j-api" % "9.2.2"
With Maven, add this to your dependencies:
<dependency>
<groupId>com.thenewmotion.ocpp</groupId>
<artifactId>ocpp-j-api_2.11</artifactId>
<version>9.2.2</version>
</dependency>
An example OCPP-J client application included. You can run it like this:
sbt "project example-json-client" "run 01234567 ws://localhost:8017/ocppws 1.5,1.6"
This means: connect to the Central System running at
ws://localhost:8017/ocppws
, as a charge point with ID 01234567, using OCPP
version 1.5 and if that is not supported try 1.6 instead. If you don't specify
a version, 1.6 is used by default.
If you look at the code of the example by clicking here, you can see how the client API is used:
A connection is established by creating an instance of OcppJsonClient
using the OcppJsonClient.forVersion1x
factory method.
The server endpoint URI, charge point ID and OCPP version to use are passed
to the method, followed by a handler for incoming OCPP requests in a
second parameter list.
To send OCPP messages to the Central System, you call the send
method on
the OcppJsonClient
instance. You will get a Future
back that will be
completed with the Central System's response. If the Central System fails
to respond to your request, the Future
will fail.
OcppJsonClient
is an instance of the OutgoingOcppEndpoint
trait. This trait defines this interface.
To specify the request handler, we use a magnet pattern.
You can specify the request handler in different ways. After the
val requestHandler: ChargePointRequestHandler =
, you see a
ChargePoint
instance in the example program. But you can also specify the request handler
as a function from ChargePointReq
to Future[ChargePointRes]
:
val ocppJsonClient = OcppJsonClient.forVersion1x(chargerId, new URI(centralSystemUri), versions) {
(req: ChargePointReq) =>
req match {
case GetConfigurationReq(keys) =>
System.out.println(s"Received GetConfiguration for $keys")
Future.successful(GetConfigurationRes(
values = List(),
unknownKeys = keys
))
case x =>
val opName = x.getClass.getSimpleName
Future.failed(OcppException(
PayloadErrorCode.NotSupported,
s"Demo app doesn't support $opName"
))
}
}
This behavior of this request handler is more or less equivalent to that of the one in the example app. It is shorter at the price of being less type-safe: this code does not check if you generate the right response type for the request, so if you generate a GetConfigurationRes in response to a GetConfigurationReq for instance.
Sending requests is simple, as explained. You call the send
method of your
endpoint and off you go, like this:
connection.send(HeartbeatReq)
The set of messages you can send with OCPP 1.x connections is defined in
ocpp-messages.
For every request type, you represent requests as instances of a case class
named <Operation Name>Req
, e.g. StatusNotificationReq
, HeartbeatReq
.
For OCPP 1.x, these case classes in ocpp-messages
are designed
according to two principles:
vendorErrorCode
in status notifications that
are not about errors). This makes it easier to write the code dealing with
those requests, which does not have to validate things first.This does mean that sometimes the way these case classes are defined may be a bit surprising to people familiar with the OCPP specification. It be so. Use the link to the file above, or use ⌘P in IntelliJ IDEA, to see how to give these case classes the right parameters to formulate the request you want to send.
This also means that it is possible to send requests that cannot be represented
in the OCPP version that is used for the connection you send them over. In that
case send
will return a failed future with an OcppError
with error code
NotSupported
.
The result of the send
method is a Future[RES]
, where RES
is the type
of the response that belongs to the request you sent. So the type of this
expression:
connection.send(AuthorizeReq(idTag = "12345678"))
is Future[AuthorizeRes]
.
And if you want to do something with the result, the code could look like this:
connection.send(AuthorizeReq(idTag = "12345678")).map { res =>
if (res.idTag.status == AuthorizationStatus.Accepted)
System.out.println("12345678 is authorized.")
else
System.out.println("12345678 has been rejected. No power to you!")
}
Note that the library does not by itself
enforce the OCPP requirement that you wait for the response before sending the
next request. A simple way to obey it is chaining the send operations in a for
comprehension, as shown in the example app.
If the remote side responds to your OCPP requests with a CALLERROR
message
indicating a failure to process your request, the future returned from .send
will be failed. The exception in there will be an OcppException
object, which
contains an OcppError
object, which contains the error code and description
sent from the other side.
It works the same way in your own request handlers. You can return a failed
future with an OcppException
, and the library will turn this into a
CALLERROR
message and sends it back to the remote side.
If you want to build an OCPP-J client using a different WebSocket implementation, or an OCPP-J server, you'll have to use the cake layers directly.
The OCPP cake has three layers:
OcppConnectionComponent
: handles serialization and deserialization between OCPP request/response objects and SRPC messagesSrpcComponent
: matches requests to responses, and serializes and deserializes SRPC messages to JSONWebSocketComponent
: reads and writes JSON messages from and to a WebSocket connectionThere are default implementations for the OcppConnectionComponent
and
SrpcComponent
. The WebSocketComponent
you will have to create yourself to
integrate with your WebSocket implementation of choice.
To put it in a diagram:
(your application logic)
+--------------V--------------------^--------------+
| com.thenewmotion.ocpp.messages.v1x.{Req, Res} |
| |
| OcppConnectionComponent layer |
| |
+--------------V--------------------^--------------+
| com.thenewmotion.ocpp.json.TransportMessage |
| |
| SrpcComponent layer |
| |
+--------------V--------------------^--------------+
| org.json4s.JValue |
| |
| WebSocketComponent layer |
| |
+--------------V--------------------^--------------+
(WebSocket lib specific types)
So the OcppConnectionComponent
layer exchanges OCPP requests and responses
with your app. It exchanges SRPC messages, represented as
TransportMessage
objects, with the SrpcComponent
layer. The SrpcComponent
layer exchanges
JSON messages, represented as org.json4s.JValue
objects, with the WebSocket
layer. The WebSocket layer then speaks to the WebSocket library, using whatever
types that library uses, usually just String
s.
Now this is not the whole picture yet: besides just OCPP messages, the layers
also exchange connection commands and events, like "close this connection!" or
"an error occurred sending that request". The traits also define methods to
exchange those, and so the total amount of methods in your
OcppConnectionComponent with SrpcComponent with WebSocketComponent
instance
may be intimidating at first. Let's make a version of the above diagram that
shows the methods defined by each layer:
OcppConnectionComponent.ocppConnection.sendRequest (call) OcppConnectionComponent.onRequest (override)
+------------------V-----------------------------------------------^-----------------------------------------------------------+
| |
| OcppConnectionComponent layer |
| |
| SrpcConnectionComponent.srpcConnection.sendCall (call) |
| SrpcConnectionComponent.srpcConnection.close (call) |
| SrpcConnectionComponent.srpcConnection.forceClose (call) |
| SrpcConnectionComponent.srpcConnection.onClose (call) SrpcConnectionComponent.onSrpcCall (override) |
+------------------V-----------------------------------------------^-----------------------------------------------------------+
| |
| SrpcComponent layer |
| |
| WebSocketConnectionComponent.onMessage (override) |
| WebSocketConnectionComponent.webSocketConnection.send (call) WebSocketConnectionComponent.onWebSocketDisconnect (override) |
| WebSocketConnectionComponent.webSocketConnection.close (call) WebSocketConnectionComponent.onError (override) |
+------------------V-----------------------------------------------^-----------------------------------------------------------+
| |
| WebSocketComponent layer |
| |
| (WebSocket library dependent) (WebSocket library dependent) |
+------------------V-----------------------------------------------^-----------------------------------------------------------+
So each layer defines the interface that the higher layers can use to communicate with it. For every layer, you see on the left how the higher layer can give it information, and on the right how the higher layer gets information from it.
For instance, on top you see that the user of the whole cake can give
information to the OCPP layer by calling the ocppConnection.sendRequest
method. And on the lower middle right you see that the SRPC cake layer
can get information from the WebSocket layer by overriding the
onMessage
, onDisconnect
and onError
methods of the
WebSocketComponent
.
There has to be one instance of the whole cake for every open WebSocket
connection in the system. A server would typically maintain a mapping of
WebSocket connection IDs from the underlying library to
OcppConnectionComponent with SrpcComponent with WebSocketComponent
instances
for them. When it receives an incoming WebSocket message, it will look up the
cake for that connection, and pass the message to the WebSocket layer of that
cake.
So now with this background information, the steps to constructing your cake would be:
Determine the kind of interface you want to the logic in the rest of your app
Create a trait extending WebSocketComponent
that uses your WebSocket
implementation of choice
Create the cake:
Do either new CentralSystemOcpp1XConnectionComponent with DefaultSrpcComponent with MyWebSocketComponent { ... }
or new ChargePointOcpp1XConnectionComponent with DefaultSrpcComponent with MyWebSocketComponent { ... }
Define in it a val webSocketConnection
, val srpcConnection
and
val ocppConnection
. For ocppConnection
, use one of the
defaultChargePointOcppConnection
and
defaultCentralSystemOcppConnection
methods defined by the
*Ocpp1XConnectionComponent
traits. For val srpcConnection
, use
new DefaultSrpcConnection
.
Define all the "(override)" methods shown at the top of the cake to connect your app's request and response processing to the OCPP cake
Make the WebSocket layer call your WebSocket library to send messages over the socket, and make your WebSocket library call the cake for it to receive messages
Because that bit about the cake pattern is still quite abstract, let's look at how we can implement an OCPP server using the cake pattern.
According to the list of steps above, we first have to determine the interface that we want or OCPP server component to have.
The interface I am thinking of here is something like this:
abstract class OcppJsonServer(listenPort: Int, ocppVersion: Version) {
type OutgoingEndpoint = OutgoingOcppEndpoint[ChargePointReq, ChargePointRes, ChargePointReqRes]
def handleConnection: OutgoingEndpoint => CentralSystemRequestHandler
}
So if someone writes a back-office system using this server component, she has to provide three things:
the TCP port to listen on, as a constructor argument
The OCPP version to use, as a constructor argument (I'm too lazy to worry about version negotiation right now)
Her own logic for how to handle and send OCPP messages over the
connections to this server. She should specify this as a method
handleConnection
that gets an endpoint for sending outgoing
requests as an argument, and returns to the server component a
request handler for handling incoming requests
So now we have decided on an interface and we move to step two: create
a trait extending WebSocketComponent
that uses our WebSocket
implementation of choice. Here we are using java-websocket, so we'll
end up using WebSocketServer.
If we look at the WebSocketServer API, we see that it is based on
instantiating a WebSocketServer
object with overridden methods to
handle incoming messages. The interface looks like this:
public abstract class WebSocketServer extends AbstractWebSocket implements Runnable {
// These methods are provided by the implementation...
public WebSocketServer(InetSocketAddress address) { ... }
public void start() { ... }
public void stop() { ... }
// ...and these are to be overridden by the user
public abstract void onStart();
public abstract void onOpen( WebSocket conn, ClientHandshake handshake );
public abstract void onClose( WebSocket conn, int code, String reason, boolean remote );
public abstract void onMessage( WebSocket conn, String message );
public abstract void onError( WebSocket conn, Exception ex );
}
So for each connection, WebSocketServer
creates a WebSocket
object,
and then passes that into the callback. We will create our
WebSocketComponent
instance so that it calls the send
method on such
a WebSocket
to send outgoing messages. That means a first stab at our
WebSocketComponent
looks like this:
import org.java_websocket.WebSocket
import org.json4s.JValue
import org.json4s.native.JsonMethods.{compact, render}
trait SimpleServerWebSocketComponent extends WebSocketComponent {
trait SimpleServerWebSocketConnection extends WebSocketConnection {
def webSocket: WebSocket
def send(msg: JValue): Unit = webSocket.send(compact(render(msg)))
def close(): Unit = webSocket.close()
}
}
That brings us to step 3: creating the cake. Now we want to create a
cake for every incoming WebSocket connection to the server, so that
means we also have to create a WebSocket server that will create a cake
in its onOpen
method:
import java.net.InetSocketAddress
import scala.concurrent.ExecutionContext
import org.java_websocket.WebSocket
import org.java_websocket.handshake.ClientHandshake
import org.java_websocket.server.WebSocketServer
import messages.v1x._
abstract class OcppJsonServer(listenPort: Int, ocppVersion: Version)
extends WebSocketServer(new InetSocketAddress(listenPort)) {
type OutgoingEndpoint = OutgoingOcppEndpoint[ChargePointReq, ChargePointRes, ChargePointReqRes]
def handleConnection: OutgoingEndpoint => CentralSystemRequestHandler
override def onStart(): Unit = {}
override def onOpen(conn: WebSocket, hndshk: ClientHandshake): Unit = {
val ocppConnection = new CentralSystemOcpp1XConnectionComponent with DefaultSrpcComponent with SimpleServerWebSocketComponent {
override val ocppConnection: DefaultOcppConnection = defaultCentralSystemOcppConnection
override val srpcConnection: DefaultSrpcConnection = new DefaultSrpcConnection()
override val webSocketConnection: SimpleServerWebSocketConnection = new SimpleServerWebSocketConnection {
val webSocket: WebSocket = conn
}
def onRequest[REQ <: CentralSystemReq, RES <: CentralSystemRes](req: REQ)(implicit reqRes: CentralSystemReqRes[REQ, RES]) = ???
implicit val executionContext: ExecutionContext = ???
def ocppVersion: Version = ???
}
}
override def onClose(
conn: WebSocket,
code: Int,
reason: IdTag,
remote: Boolean
): Unit = ???
override def onMessage(conn: WebSocket, message: String): Unit = ???
override def onError(conn: WebSocket, ex: Exception): Unit = ???
}
Ouch, that's a big load of code there. Still, it came about after a few simple steps:
???
implementations of
its abstract methodsonOpen
method from the WebSocketServer
abstract class,
create a cake with the three layers: CentralSystemOcpp1XConnectionComponent with DefaultSrpcComponent with SimpleServerWebSOcketComponent
???
implementations of all the abstract methods in the cakeocppConnection
, srpcConnection
and webSocketConnection
members of the three cake layers.Note that at step 5, we have passed the WebSocket
argument to the
onOpen
method on into the SimpleServerWebSocketConnection
so that
the cake can later use this WebSocket
to send OCPP messages over.
So by now we're at the fourth point of the five-step cake plan: connect our
app's logic to the OCPP cake. The app's logic, in our case, is the
handleConnection
that the library user specifies. And then, inside
the OCPP cake definition in onOpen
, we create the outgoing endpoint,
and call the user-defined handleConnection
on it so a request handler
for incoming messages is created:
private val outgoingEndpoint = new OutgoingEndpoint {
def send[REQ <: ChargePointReq, RES <: ChargePointRes](req: REQ)(implicit reqRes: ChargePointReqRes[REQ, RES]): Future[RES] =
ocppConnection.sendRequest(req)
def close(): Future[Unit] = srpcConnection.close()
}
private val requestHandler = handleConnection(outgoingEndpoint)
Now that we have the incoming request handler, we can also fill
in definitions for the onRequest
handler in the OCPP cake:
def onRequest[REQ <: CentralSystemReq, RES <: CentralSystemRes](req: REQ)(implicit reqRes: CentralSystemReqRes[REQ, RES]) =
requestHandler(req)
And then, there is the ocppVersion
method in OcppConnectionComponent
that will tell it which OCPP version to use to serialize and deserialize
OCPP messages to JSON. We have to fill in the OCPP version that was
passed in to the OcppJsonServer
constructor. To avoid name clashes,
we rename the argument to requestedOcppVersion
:
abstract class OcppJsonServer(listenPort: Int, requestedOcppVersion: Version)
and then fill in this requestedOcppVersion
argument in the cake's
ocppVersion
method:
def ocppVersion: Version = requestedOcppVersion
By now, the OCPP cake definition body is free of any reference to "???". The cake is fully linked to the app's business logic.
That means we're at the fifth and last step of the five-step plan: We have to
make sure that when a new connection is opened, we will call this function to
create a CentralSystemRequestHandler
, and that we later call this CentralSystemRequestHandler
whenever a message comes in on the connection. To make this happen, we will need
a map from WebSocket
instances that the server gets in its onMessage
method,
to the OCPP cake instance that will process messages for that connection.
So let's add this to the OcppJsonServer
class: link the WebSocket connections
we're using to their OCPP cakes.
private type OcppCake = CentralSystemOcppConnectionComponent with DefaultSrpcComponent with SimpleServerWebSocketComponent
object connectionMap {
private val ocppConnections: mutable.Map[WebSocket, BaseConnectionCake] =
mutable.HashMap[WebSocket, BaseConnectionCake]()
def put(conn: WebSocket, cake: BaseConnectionCake): Unit = connectionMap.synchronized {
ocppConnections.put(conn, cake)
()
}
def remove(conn: WebSocket): Option[BaseConnectionCake] = connectionMap.synchronized {
ocppConnections.remove(conn)
}
def get(conn: WebSocket): Option[BaseConnectionCake] = connectionMap.synchronized {
ocppConnections.get(conn)
}
}
We use a mutable map, wrapped in its own little object connectionMap
that assures thread-safety.
To fill the map, we add this line at the bottom of onOpen
in our
OcppJsonServer
:
connectionMap.put(conn, ocppConnection)
and as responsible professionals, let's also remove the entry from the map again
when a connection is closed, by changing the definition of onClose
to this:
override def onClose(
conn: WebSocket,
code: Int,
reason: IdTag,
remote: Boolean
): Unit = ocppConnections.remove(conn)
Now the last thing to be done on the way to a working server, is making the
onMessage
, onClose
and onError
callbacks of WebSocketServer
actually call into the connection's OCPP cake to let it process the message. It
turns out that to do this, we have to add three methods to the
SimpleWebSocketServerComponent
:
def feedIncomingMessage(msg: String) = self.onMessage(org.json4s.native.JsonMethods.parse(msg))
def feedIncomingDisconnect(): Unit = self.onWebSocketDisconnect()
def feedIncomingError(err: Exception) = self.onError(err)
to make that work, we also have to make SimpleServerWebSocketComponent aware that it is to be mixed into something that is also an SrpcComponent, by adding a self-type:
trait SimpleServerWebSocketComponent extends WebSocketComponent {
self: SrpcComponent =>
...
and back in OcppJsonServer
, we change the implementation of onMessage
,
onClose
and onError
to feed those events into the cake for the right
connection:
override def onClose(
conn: WebSocket,
code: Int,
reason: IdTag,
remote: Boolean
): Unit = {
connectionMap.remove(conn) foreach { c =>
c.feedIncomingDisconnect()
}
}
override def onMessage(conn: WebSocket, message: String): Unit =
connectionMap.get(conn) foreach { c =>
c.feedIncomingMessage(message)
}
override def onError(conn: WebSocket, ex: Exception): Unit =
connectionMap.get(conn) foreach { c =>
c.feedIncomingError(ex)
}
That's it, it should work now!
In fact, upon testing it, I realize that with this interface, the server-side
code doesn't know the ChargePointIdentity of the client. That's not very
helpful; an OCPP back-office system will probably want to know which charge
points are connected to it. So let's change the definition of handleConnection
in OcppJsonServer
to this:
def handleConnection(clientChargePointIdentity: String, remote: OutgoingEndpoint): CentralSystemRequestHandler
and let's pass the ChargePointIdentity into it by changing onOpen
to this:
override def onOpen(conn: WebSocket, hndshk: ClientHandshake): Unit = {
val uri = hndshk.getResourceDescriptor
uri.split("/").lastOption match {
case None =>
conn.close(1003, "No ChargePointIdentity in path")
case Some(chargePointIdentity) =>
onOpenWithCPIdentity(conn, chargePointIdentity)
}
}
private def onOpenWithCPIdentity(conn : WebSocket, chargePointIdentity: String): Unit = {
val ocppConnection = new CentralSystemOcppConnectionComponent with DefaultSrpcComponent with SimpleServerWebSocketComponent {
... // continues as in earlier definition of onOpen
So there we check if the URL includes the charge point identity. If it doesn't, we immediately close the WebSocket connection with an error message. If we do have a ChargePointIdentity, we proceed to handle the open as we did before. And now it should really be done.
In order to save you the typing and bugfixing, an actual tested version of the server developed while writing this is included. With the OCPP 2.0 work though, it has become a bit more involved because it is now an abstract class that is extended by 1.x and 2.0 specific classes.
And there is also a small
example app
that shows how to use the OcppJsonServer
interface. It will listen on port
2345, and return NotImplemented
to any request except BootNotification. In
response to a BootNotification, it will send a response and also send a
GetConfiguration request back to the client. To run it, you do:
$ sbt "project example-json-server" run
There is also an OCPP 2.0 version of this server. You can run it with:
$ sbt "project example-json-server-20" run
If you do not need the connection management provided by the high-level API,
you can still use the ocpp-json
module for serializing and deserializing OCPP
messages that you will send or receive using other libraries.
To do so, call the methods in the Serialization
object after importing either
com.thenewmotion.ocpp.json.v1x.v15.SerializationV15._
or com.thenewmotion.ocpp.json.v1x.v16.SerializationV16._
to select which OCPP
version to use:
import com.thenewmotion.ocpp.json.OcppJ
import com.thenewmotion.ocpp.messages.{v1x => messages}
import com.thenewmotion.ocpp.Version
import com.thenewmotion.ocpp.json.v16.SerializationV16._
OcppJ.write(messages.AuthorizeReq(idTag = "ABCDEF012"))
// this results in:
// res6: String = {"idTag":"ABCDEF012"}
OcppJ.read[messages.AuthorizeReq, Version.V16.type]("""{"idTag":"ABCDEF012"}""")
// this results in:
// res10: com.thenewmotion.ocpp.messages.AuthorizeReq = AuthorizeReq(ABCDEF012)
There are also serialize
and deserialize
methods on the Serialization
object that
use json4s JValue
s as the representation of JSON instead of raw String
s.
You can use those to build the SRPC
messages that are sent over the WebSocket. See TransportMessage
and TransportMessageJsonSerializers
for how to work with those.
OCPP 2.0 presents a major revision of the OCPP protocol, vastly improving authentication and encryption of the connection, and bringing new, more refined models of the charging station's configuration and the lifecycle of a charge transaction.
This means that it is not possible to write code that will transparently work with OCPP 2.0 or other OCPP versions, as is possible with this library when using the 1.x versions of OCPP.
You can use this library already to exchange OCPP 2.0 messages, but not all message types, error codes, security mechanisms etc added by 2.0 are supported yet. We're "glass half full" people, so we'll first explain what works, and then move on to explain what still remains to be done.
Using the OcppJsonClient.forversion20
, you can create an instance of
OcppJsonClient
, more specifically Ocpp20JsonClient
, that will let you send
and receive OCPP 2.0 messages.
For OCPP 2.0, the message case classes are named <Operation Name>Request
and
<Operation Name>Response
, e.g. BootNotificationRequest
and
BootNotificationResponse
. They live in the
com.thenewmotion.ocpp.messages.v20
package. They extend the
com.thenewmotion.ocpp.messages.Request
and
com.thenewmotion.ocpp.messages.Response
types depending on whether they are
requests or responses. They also extend the CsRequest
, CsResponse
,
CsmsRequest
and CsmsResponse
types defined in the
com.thenewmotion.ocpp.messages.v20
package, depending on which side is
executing the request. CsRequest
and CsResponse
are for operations executed
by the "Cs" (Charging Station, equivalent to the "Charge Point" of OCPP 1.x);
CsmsRequest
and CsmsResponse
are for operations executed by the "Csms"
(Charging Station Management System, equivalent to the "Central System" of OCPP
1.X).
Unlike the 1.5/1.6 message case classes, the OCPP 2.0 case classes for requests and responses directly reflect the message structures defined in the OCPP 2.0 specification. This is done to reduce the cognitive load when comparing message definitions in Scala code to the OCPP specification, and because OCPP 2.0 as of now has no protocol versions that are similar enough to write code that can transparently deal with multiple protocol versions.
The price of giving up the version-independent message case classes is that some counterintuitive idiosyncracies of the OCPP specification, like starting to count at 1 instead of 0 and using 0 as a sentinel, are now inflicted upon unsuspecting Scala developers.
Currently the library has message case classes in place for the following operations:
Charging Station operations:
Charging Station Management System operations:
support new RPC-level error codes
Message case classes and serializers for all operations
To add a message, you should:
Maybe we can find a way to make it easier to add this messages, or at least make it straightforward so that you can just follow the compiler errors until it compiles and then it also works.
Factory method on OcppJsonClient to give caller a 1.x or 2.0 client depending on negotiation with server
Similarly on OcppJsonServer
, create a factory method that lets people
create a server with two request handlers, one for 1.x and for 2.0, and
let the server negotiate the OCPP version to use with the client.
Add a mechanism for the library to report standardized security events about the connection
Add support for the 3 security profiles for authenticated encryption
Perhaps then add a note that the ready-made server class and app in this library are not intended for production use, do not support the authenticated encryption of the OCPP channel, and are as such insecure.
Support for JSON web signatures in the RPC-level encoding
Added support for v1x.ChargePointDataTransferReq
and v1x.ChargePointDataTransferRes
to
com.thenewmotion.ocpp.json.v1x.v15.SerializationV15
and com.thenewmotion.ocpp.json.v1x.v16.SerializationV16
Add a Scala 2.13 build
Add OpenJDK 8 and 11 builds
Added more OCPP 2.0 messages
Added an OCPP 2.0 example server app
com.thenewmotion.ocpp.VersionFamily.V1XCentralSystemRequest
to
com.thenewmotion.ocpp.VersionFamily.V1XCentralSystemMessages
as it should
have been named all along.A start was made with support for OCPP 2.0
OcppJsonServer
has now been split into two classes, depending on
whether you want to serve OCPP 2.0 or OCPP 1.5/1.6:
Ocpp1XJsonServer
and Ocpp20JsonServer
OcppJsonClient
has similarly been split into Ocpp1XJsonClient
and
Ocpp20JsonClient
. Factory methods OcppJsonClient.forVersion1x
and OcppJsonClient.forVersion20
are available for easier
instantiation of OcppJsonClient
instances.
The connection
member of OcppJsonClient
was made private. To
see the version of OCPP used by an OcppJsonClient
, you can now use
the ocppVersion
method on the OcppJsonClient
class.
The interfaces of the ocpp-messages
and ocpp-json
projects dealing
with OCPP 1.x messages have moved to the com.thenewmotion.ocpp.messages.v1x
and com.thenewmotion.ocpp.json.v1x
packages, respectively.
So code that used com.thenewmotion.ocpp.messages.AuthorizationReq
must be changed to use com.thenewmotion.ocpp.messages.v1x.AuthorizationReq
,
and code that used com.thenewmotion.ocpp.json.JsonOperation
must be changed
to use com.thenewmotion.ocpp.json.v1x.JsonOperation
.
com.thenewmotion.ocpp.json.OcppJ
was renamed to
com.thenemwotion.ocpp.json.v1x.Serialization
Move the code for handling OCPP over SOAP to another project
Add a Scala 2.12 build
Wait for pending incoming requests to be answered before closing a WebSocket connection
OcppJsonClient.close
is now asynchronous; it returns a future that is
completed once the connection is closed.
OcppJsonClient
now has an apply method to construct
OcppJsonClient
instances without overriding any members
The IncomingOcppEndpoint
trait is gone because the onError
and
onDisconnect
methods were removed, so that only the
requestHandler
member was left and can simply take a
RequestHandler
in every place where the library previously
expected an IncomingOcppEndpoint
.
The rudimentary onError
method is removed from OcppJsonClient
.
All OCPP errors are reported as failed futures returned from
OcppJsonClient.send
.
As part of the same dead code removal, the onOcppError
method in
OcppComponent
is also gone
The onDisconnect
method is removed from OcppJsonClient
because
closes are now signaled via an onClose
member which returns a
future which is completed once the connection is closed.
Because it is no longer needed to implement
IncomingOcppEndpoint.onDisconnect
, the
SrpcComponent.onSrpcDisconnect
method is removed.
The more robust closing involved changing some method names in the SrpcConnectionComponent
and WebSocketComponent
:
SrpcComponent#SrpcConnection.send
is now SrpcComponent#SrpcConnection.sendCall
SrpcComponent#SrpcConnection.close
now works asynchronously and returns a Future[Unit]
SrpcComponent#SrpcConnection.forceClose
was added and works like the old .close
, immediately closing the underlying WebSocket without waiting for processing to completeSrpcComponent.onSrpcRequest
is now SrpcComponent.onSrpcCall
WebSocketComponent.onDisconnect
was renamed to WebSocketComponent.onWebSocketDisconnect
The case classes for SRPC messages were renamed to reflect the names used in the specification
Fixed a bug in the serialization of SendLocalListReq, where a member was called "localAuthorisationList" instead of "localAuthorizationList"
VersionMismatch
when an OcppJsonClient
fails to connectThis library had been stable for a few years between 2014 and 2017, with 4.x.x version numbers, supporting OCPP-S 1.2 and 1.5, and OCPP-J 1.5, but not 1.6. Now that 1.6 support has been added with version 6.0.0, many wildly incompatible changes to the library interface were made while we were at it. The most important ones to be aware of when porting older code:
CentralSystem
and ChargePoint
traits were renamed to
SyncCentralSystem
and SyncChargePoint
. The names CentralSystem
and
ChargePoint
are now used for asynchronous versions of these traits that
return Future
s.RequestHandler
which will also verify that you
produce the right response type for the given request.Enumeration
sjava.time
for date and time handling instead
of com.thenewmotion.time
.JsonDeserializable
was renamed to JsonOperation
and now handles not only
deserialization but also serialization of OCPP messages for OCPP-J.OcppJsonClient
now takes a version parameterThe contents of this repository are © 2012 - 2018 The New Motion B.V., licensed under the GPL version 3, except:
The example messages for OCPP 1.5 in the ocpp-json unit tests, which were taken from GIR ocppjs.
The JSON schema files for OCPP 1.6 are part of the OCPP 1.6 Specification, distributed under the following conditions:
Copyright © 2010 – 2015 Open Charge Alliance. All rights reserved.
This document is made available under the *Creative Commons Attribution- NoDerivatives 4.0 International Public License* (https://creativecommons.org/licenses/by-nd/4.0/legalcode).
The JSON schema files for OCPP 2.0 are part of the OCPP 2.0 Specification, distributed under the following conditions:
Copyright © 2010 – 2018 Open Charge Alliance. All rights reserved.
This document is made available under the *Creative Commons Attribution-NoDerivatives 4.0 International Public License*
(https://creativecommons.org/licenses/by-nd/4.0/legalcode).