Strategy for creating a new Driver

Please inspect other existing modules on how to implement some of this.

Prepare a new protocol module

  1. Create a new protocol module for your protocol.

  2. Create the pom.xml file for the new module.

  3. Create a new mspec file in src/main/release/ with just one or two dummy types.

  4. Create a new Protocol class in src/main/java which implements org.apache.plc4x.plugins.codegenerator.protocol.Protocol.

    • The value returned by getName() will be used in the maven driver code generation.

  5. Create a new file called src/main/resources/META-INF/services/org.apache.plc4x.plugins.codegenerator.protocol.Protocol and list the new protocol class.

  6. Test you can build the new protocol module.

Prepare a new driver module

  1. Create a new driver module under plc4j/drivers

  2. Create the pom.xml file for the new module.

    • Be sure to add a maven dependency to your protocol module.

    • Be sure you have the update-generated-code profile in there.

    • Be sure to reference the protocol name used in your protocol module.

  3. Create the Driver class in src/main/java which implements org.apache.plc4x.java.api.PlcDriver.

  4. Create a file called src/main/resources/META-INF/services/org.apache.plc4x.java.api.PlcDriver and list the new driver class.

  5. Test you can build the new driver module and the code generation works.

Start implementing the protocol parser and serializer

  1. Create a capture of the communication you want to create a driver for.

  2. Open the capture in WireShark

  3. Start defining the types you see in your mspec file

  4. Create a file ParserSerializerTestsuite.xml in the protocol modules src/test/resources directory.

  5. Start adding empty test-cases for every packet in your recording, by copying the TCP/UDP/Whatever payload in Wireshark as hex-stream and pasting that in the raw element of a test-case.

  6. In the driver module, create a ParserSerializer test that extends org.apache.plc4x.test.parserserializer.ParserSerializerTestsuiteRunner in src/test/java which references the ParserSerializerTestsuite.xml file of your protocol module.

  7. Iteratively implement all the mspec types needed to process your captures:

    • Add/update the types in the mspec file

    • Rebuild the protocol module

    • Rebuild the driver module (with the update-generate-code profile enabled)

    • Run the ParserSerializer test

Start implementing the driver logic

As soon as you are able to process all captures of your observed communication, you can start implementing a driver protocol logic.

TODO: Continue writing this.