How to setup and use Digitraffic ETSI-library and Clients SDK:s in java
This is a short “Hello World” example of how to produce, consume, send and recive C-ITS compliant V2X messages with Digitraffic SDK:s
This HowTo is based on the usage of Digitraffic:s Link SDK:s. Both the ETSI-library and the Connect SDK. The ETSI-library is used to Encode and Decode binary-encoded ETSI-messages (with our without geonet basic or security headers). The Connect SDK is used to send or receive messages via either the SI-interface or the BI-interface.
Both the C# and Java SDK:s has the same object structure and you can read the documentation here.
Step 1 - Download java .jar file and generate licensekey
The first step is to download the SDK as jar files and generate a valid licensekey. The jar files and your test-licensekey can be found in Digitraffic:s customer area.
- Follow this link to create an account. https://www.digitraffic.se/downloads/
- When you have created an account, you will get to the download page.
- Download the latest Digitraffic JAVA SDK:s by clicking the download buttons. If you intend to encode and decode messages, you´ll need the “ETSI library” SDK. If you intend to send and receive messages you´ll need the “Clients” library.
- In the bottom of the page you can activie your one month trial subscription by clicking “Start free trial”. (It´s the same licensekey for both the C# and JAVA libraries).
- Your license will appear instead of the button and has a validity one month from when the button was clicked.
Step 2 - Reference .jar file in your solution
Add reference to the dowloaded .jar file in your project according to your development environment / IDE
Step 3 - Initialize libraries
To run Digitraffic SDK:s you´ll need to use a valid licensekey.
If you havn´t created a valid licenskey look at “Step 1 – Download .jar file and generate licensekey” in this guide
- Follow this link to create an account. https://www.digitraffic.se/downloads/
- When you have created an account, you will get to the download page. In the bottom of the page you can activie your one month trial subscription by clicking “Start free trial”. (It´s the same licensekey for both the C# and JAVA libraries).
- Your license will appear instead of the button. Cut and paste the licenskey into your code as visualised bellow.
//Add desired namespace
import connect.ConnectInitializer;
import etsilibrary.LibInitializer;
//Add valid license to SDK;
String key = "<your_key>";
//Optional: Add a logger to SDK
ConsoleLogger log = new ConsoleLogger(Level.Info)
//Initialize library (pass null for argument log to disable logging)
LibInitializer.Initialize(key, log);
//Initialize clients (pass null for argument log to disable logging)
ConnectInitializer.Initialize(key, log);
Step 4 - Create a connection to a central broker
You need a valid connection to a central broker to send and recive messages. The Digitraffic library contains the “Subject Interface” as defined in the dutch program Talking Traffic.
- The dutch company “Monotch” can provide testing facilities for the “Subject interface”.
- If you don´t have access to a central broker send an email to info@digitraffic.se for further support.
//Connecting to central broker with SI-interface (Exemplary arguments)
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
"<Identifier>",
SecurityMode.NONE);
//Or
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
"<Identifier>",
SecurityMode.NONE,
SessionProtocol.TCPStreaming_Singleplex,
SessionType.TLC);
//Or
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
List.of("<Associated Identifier1>", "<Associated Identifier2>", ...),
SecurityMode.NONE);
//Or
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
List.of("<Associated Identifier1>", "<Associated Identifier2>", ...),
SecurityMode.NONE,
SessionProtocol.TCPStreaming_Singleplex,
SessionType.TLC);
Step 5 - Listen to incomming messages from central broker
To listen for incoming message you´ll need to hook up your code to the “recive” message event in the client-connection.
//Create an event function for receiving messages
static Consumer<SiPayload> messageConsumer = (payload) -> {
// Process the payload
IETSIMessage receivedMessage = ETSIFactory.decodeByteArray(payload.getMessage());
//Parse payload
switch (MessageId.fromValue(receivedMessage.getPayload().getHeader().getMessageId())) {
case DENM:
DENM receivedDenm = (DENM) receivedMessage.getPayload();
break;
case CAM:
//...
break;
//...
}
};
//Register listener function for incoming message events
siClient1.setMessageReceivedBytes(messageConsumer);
Step 6 - Decode a binary encoded ETSI message with Digitraffic ETSI library
If you intend to decoded an binary encoded ETSI message you can use the Digitraffic ETSI-library as described bellow. Make sure you have followed “Step 3 – Initialize library” before the code example bellow;
//Add this code snippet in the Listen function created in "Step 5 - Listen to incomming messages from central broker"
byte[] messageBytes = XXXX;
String messageHex = "XXXX";
String messageBinary = "10100111..";
//Decode the message
IETSIMessage message = ETSIFactory.decodeByteArray(messageBytes);
//Or
IETSIMessage message = ETSIFactory.decodeHexString(messageHex);
//Or
IETSIMessage message = ETSIFactory.decodeBinaryString(messageBinary);
//Check messagetype and cast content
switch(MessageId.fromValue(message.getHeader().getMessageId()))
case DENM:
DENM content = (DENM) message.getPayload()
//Do something with the content...
Step 7 - Create a binary encoded ETSI message according to ETSI standards
If you intend to encode an binary encoded ETSI message you can use the Digitraffic ETSI-library as described bellow. Make sure you have followed “Step 3 – Initialize library” before the code example bellow;
//Create an ETSIMessage with geonet-header and Security envelope according to ETSI TS 103 097
IETSIMessage message = ETSIFactory.createMessage(CompileFlags.Basic);
//Create payload in IETSIMessage;
DENM denm = new DENM();
denm.getHeader().setMessageId(MessageId.DENM);
//...
denm.getDenm().getManagement().setStationType(StationType.Cyclist);
denm.getDenm().getLocation().getEventPositionHeading().setValue((short) 10);
//...
//Add payload to message;
message.setPayload(denm);
//Encode message
byte[] messageByte = message.encode();
Step 8 - Send message to central broker
You can use the Digitraffic.Client SDK:s to send messages to a central broker. Make sure you have followed step 3 and 4 ahead of this code-snippet.
//Message created with Digitraffic ETSI-library...
byte[] byteMessage = message.encode();
//Send byteMessage with siClient to central broker
siClient.Send(byteMessage, PayloadType.DENM);
A full example
//Add desired namespace
import connect.ConnectInitializer;
import connect.SubjectInterface.SiClient;
import connect.SubjectInterface.Model.PayloadType;
import connect.SubjectInterface.Model.SecurityMode;
import connect.SubjectInterface.Model.SessionProtocol;
import connect.SubjectInterface.Model.SessionType;
import connect.SubjectInterface.Model.SiPayload;
import etsilibrary.LibInitializer;
import etsilibrary.ETSI.CompileFlags;
import etsilibrary.ETSI.ETSIFactory;
import etsilibrary.ETSI.IETSIMessage;
import etsilibrary.ETSI.BaseTypes.CDD.base.Enumerations.MessageId;
import etsilibrary.ETSI.BaseTypes.CDD.base.Enumerations.StationType;
import etsilibrary.ETSI.DENM.v2.DENM;
import tools.Logging.ConsoleLogger;
import tools.Logging.Level;
//Add valid license to SDK;
String key = "<your_key>"
void Program(string args){
//You can create your own logger by deriving and implement "tools.Logging.ILogger;
ConsoleLogger log = new ConsoleLogger(Level.Info);
//Initialize ETSI library
LibInitializer.initialize(key, log);
//Initialize clients
ConnectInitializer.initialize(key, log);
//Connecting to central broker with SI-interface (Exemplary arguments)
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
"<Identifier>",
SecurityMode.NONE);
//Or
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
"<Identifier>",
SecurityMode.NONE,
SessionProtocol.TCPStreaming_Singleplex,
SessionType.TLC);
//Or
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
List.of("<Associated Identifier1>", "<Associated Identifier2>", ...),
SecurityMode.NONE);
//Or
SiClient siClient = new SiClient(
"<Uri for SI broker>",
"<Valid security token>",
"<SI-Domain>",
List.of("<Associated Identifier1>", "<Associated Identifier2>", ...),
SecurityMode.NONE,
SessionProtocol.TCPStreaming_Singleplex,
SessionType.TLC);
//Add additional associated identifiers
siClient.AddAssociatedTcl("<Identifier>");
//Or
siClient.AddAssociatedTlcs(List.of("<Identifier1>", "<Identifier2>"));
//Create an ETSIMessage with geonet-header and Security envelope according to ETSI TS 103 097
IETSIMessage message = ETSIFactory.createMessage(CompileFlags.Secure);
//Create payload in IETSIMessage;
DENM denm = new DENM();
denm.getHeader().setStationId(1234567);
//...
denm.getDenm().getManagement().setStationType(StationType.Cyclist);
denm.getDenm().getLocation().getEventPositionHeading().setValue((short) 10);
//...
//Add payload to message;
message.setPayload(denm);
//Encode message
byte[] messageByte = message.encode();
//Send message to central broker
siClient1.Send(messageByte, PayloadType.DENM);
//Register listener function for incoming message events
siClient1.setMessageReceivedBytes(messageConsumer);
//Stop execution and wait for message to be received
scanner.nextLine();
}
//Event function for receiving messages
static Consumer<SiPayload> messageConsumer = (payload) -> {
// Process the payload
IETSIMessage receivedMessage = ETSIFactory.decodeByteArray(payload.getMessage());
//Parse payload
switch (MessageId.fromValue(receivedMessage.getPayload().getHeader().getMessageId())) {
case DENM:
DENM receivedDenm = (DENM) receivedMessage.getPayload();
break;
case CAM:
//...
break;
//...
}
};
