website/asciidoc/modules/developers/pages/tutorials/writing-driver.adoc

//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      https://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
:imagesdir: ../../images/

= 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.