Open Charge Point Protocol for Scala

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.

Functionality

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.

How to use

Setup

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 connections
• ocpp-json: serialization of OCPP messages to/from JSON
• ocpp-messages: The definitions of OCPP messages, independent from the transport variant used

So 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 to your plugins.sbt:

resolvers += "TNM" at "http://nexus.thenewmotion.com/content/groups/public"

and this to your build.sbt:

libraryDependencies += "com.thenewmotion.ocpp" %% "ocpp-j-api" % "9.2.2"

With Maven, you'd set up the repository in your pom.xml:

    <repository>
        <id>thenewmotion</id>
        <name>The New Motion Repository</name>
        <url>http://nexus.thenewmotion.com/content/repositories/releases-public</url>
    </repository>

and add this to your dependencies:

    <dependency>
        <groupId>com.thenewmotion.ocpp</groupId>
        <artifactId>ocpp-j-api_2.11</artifactId>
        <version>9.2.2</version>
    </dependency>

Using the simple client API

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.

Handling requests

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

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:

• They are independent of OCPP version, so you have one interface to charging stations that use different versions
• They sometimes group and rearrange fields to make it impossible to specify nonsense messages (e.g., no 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.

Error handling

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.

Using the cake pattern directly

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 messages
• SrpcComponent: matches requests to responses, and serializes and deserializes SRPC messages to JSON
• WebSocketComponent: reads and writes JSON messages from and to a WebSocket connection

There 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 Strings.

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

Putting this together for a server

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:

1. Take the interface template for OcppJsonServer that we started this example with
2. Make it extend WebSocketServer, and add ??? implementations of its abstract methods
3. In the onOpen method from the WebSocketServer abstract class, create a cake with the three layers: CentralSystemOcpp1XConnectionComponent with DefaultSrpcComponent with SimpleServerWebSOcketComponent
4. Add ??? implementations of all the abstract methods in the cake
5. Add actual definitions of the ocppConnection, 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

Just serializing

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 JValues as the representation of JSON instead of raw Strings. 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 support

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.

What this library offers

Creating an OCPP 2.0 connection

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.

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.

Supported operations

Currently the library has message case classes in place for the following operations:

Charging Station operations:

• GetBaseReport
• GetTransactionStatus
• GetVariables
• RequestStartTransaction
• RequestStopTransaction
• SendLocalList
• SetVariables

Charging Station Management System operations:

• Authorize
• BootNotification
• Heartbeat
• StatusNotification
• TransactionEvent

What remains to be done

• support new RPC-level error codes

  • Although this is actually about SRPC, perhaps the simplest implementation would be in the OCPP layer, where we already distinguish the versions. The Ocpp1XConnectionComponent could filter error codes sent and received and map the ones unsupported by OCPP 1.X to the closest alternative that is supported. That would save us the complexity of multiple SrpcComponent implementations and choosing between them.

• Message case classes and serializers for all operations

  • To add a message, you should:

    • Add Request and Response case classes here
    • Add a ReqRes instance here
    • Add a Ocpp20Procedure here
    • Add necessary JSON serializers (e.g. for new Enumerables) here
    • Add a JSON schema validation test here
    • Add a JSON serialization/deserialization round-trip test here

  • 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

Changelog

Changes in 9.2.2

• JsonOperations.reqRes: handle serialization and deserialisation both within Future context

Changes in 9.2.1

• Remove a Scala 2.13 build until dependencies are fixed

Changes in 9.2.0

• 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

Changes in 9.1.0

• Added more OCPP 2.0 messages

• Added an OCPP 2.0 example server app

Changes in 9.0.1

• Renamed com.thenewmotion.ocpp.VersionFamily.V1XCentralSystemRequest to com.thenewmotion.ocpp.VersionFamily.V1XCentralSystemMessages as it should have been named all along.

Changes in 9.0.0

• 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

Changes in 8.0.0

• Move the code for handling OCPP over SOAP to another project

• Add a Scala 2.12 build

Changes in 7.0.0

• 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 complete
  • SrpcComponent.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"

Changes in 6.0.3

• Support DataTransfer messages from Charge Point to Central System also over SOAP

Changes in 6.0.2

• Support DataTransfer messages from Charge Point to Central System

Changes in 6.0.1

• Throw more meaningful exceptions instead of always VersionMismatch when an OcppJsonClient fails to connect

Changes in 6.0.0 compared to version 4.x

This 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:

• The 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 Futures.
• In the high-level JSON API, request-response-handling has become more type-safe. Your request handler is no longer just a function from requests to responses, but now a RequestHandler which will also verify that you produce the right response type for the given request.
• The library now uses enum-utils instead of Scala's Enumerations
• The library now uses Java 8's java.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 parameter

Licensing and acknowledgements

The 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).