openTCS
Developer’s Guide
The openTCS developers
openTCS 4.10.0
Table of Contents
1. Development with openTCS in general . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1
1.1. System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1
1.2. Available artifacts and API compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1
1.3. Third-party dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê2
1.4. Modularity and extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê3
1.5. Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê3
1.6. Working with the openTCS source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê3
2. The kernel’s Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê4
2.1. Acquiring service objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê4
2.2. Working with transport orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê5
2.2.1. A transport order’s life cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê5
2.2.2. Structure and processing of transport orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê7
2.2.3. How to create a new transport order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê8
2.2.4. How to create a transport order that sends a vehicle to a point instead of a location . . . . Ê9
2.2.5. Using order sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê10
2.2.6. How to withdraw a transport order that is currently being processed . . . . . . . . . . . . . . . . Ê11
2.2.7. How to withdraw a transport order via a reference on the vehicle processing it . . . . . . . Ê12
3. TCP/IP-based interfaces to other systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê13
3.1. Creating orders via TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê13
3.1.1. XML telegrams for creating orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê14
3.1.2. XML telegrams referencing order batches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê14
3.1.3. Receipts for created orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê15
3.1.4. Receipts for order batches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê15
3.2. Status messages via TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê16
3.3. XML Schema definitions for telegrams and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê17
4. Generating an integration project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê18
5. Customizing and extending the kernel application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê19
5.1. Guice modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê19
5.2. Replacing default kernel components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê19
5.3. Developing vehicle drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê20
5.3.1. Classes and interfaces for the kernel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê20
5.3.2. Classes and interfaces for the control center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê21
5.3.3. Steps to create a new vehicle driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê22
5.3.4. Registering a vehicle driver with the kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê23
5.4. Sending messages to communication adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê24
5.5. Acquiring data from communication adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê24
5.6. Executing code in kernel context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê25
6. Customizing and extending the control center application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê27
6.1. Guice modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê27
6.2. Registering driver panels with the control center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê27
7. Customizing and extending the plant overview application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê29
7.1. Guice modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê29
7.2. How to create a plugin panel for the plant overview client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê29
7.3. How to create a location/vehicle theme for openTCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê30
Chapter 1. Development with openTCS in
general
1.1. System requirements
The openTCS source code is written in Java. To compile it, you need a Java Development Kit (JDK)
1.8 or later. To run the resulting binaries, you need a Java Runtime Environment (JRE) 1.8 or later.
All other required libraries are included in the openTCS distribution or will be downloaded
automatically when building it from source code.
1.2. Available artifacts and API compatibility
The openTCS project publishes artifacts for releases via JCenter, so you can easily integrate them
with build systems such as Gradle or Maven. In Gradle build scripts, for example, use something
like the following to integrate an openTCS library:
repositories {
Ê jcenter()
}
dependencies {
Ê compile group: 'org.opentcs', name: '${ARTIFACT}', version: '4.10.0'
}
Set the version number of the openTCS release you actually want to work with, and select the
appropriate ${ARTIFACT} name from the following table:
Table 1. Artifacts published by the openTCS project
Artifact name API compatibility
between minor
releases
Content
opentcs-api-base
Yes Contains the base API for clients and extensions.
This is what most developer’s probably want to
use.
opentcs-api-injection
Yes Contains API interfaces and classes used for
dependency injection within the kernel and
plant overview applications. This is required in
integration projects customizing these
applications, e.g. adding components like vehicle
driver implementations.
opentcs-common
No Contains a collection of utility classes used by
openTCS components.
1
Artifact name API compatibility
between minor
releases
Content
opentcs-commadapter-
loopback
No Contains a very basic vehicle driver simulating a
virtual vehicle.
opentcs-strategies-
default
No Contains the default implementations of
strategies that are used by the kernel
application.
opentcs-kernel
No Contains the kernel application.
opentcs-
kernelcontrolcenter
No Contains the kernel control center application.
opentcs-plantoverview
No Contains the plant overview application.
Note that only the basic API libraries provide a documented API that the openTCS developers try to
keep compatible between minor releases. (For these libraries, the rules of semantic versioning are
applied.) All other artifacts' contents can and will change regardless of any compatibility concerns,
so if you use these and switch to a different version of openTCS, you may have to adjust and
recompile your code.
1.3. Third-party dependencies
The kernel and the client applications depend on the following external frameworks and libraries:
• SLF4J (https://www.slf4j.org/): A simple logging facade to keep the actual logging
implementation replaceable.
• Google Guice (https://github.com/google/guice): A light-weight dependency injection framework.
• Cfg4j (http://www.cfg4j.org/): A configuration library supporting binding interfaces.
• Google Guava (https://github.com/google/guava): A collection of small helper classes and
methods.
The kernel application also depends on the following libraries:
• JGraphT (http://jgrapht.org/): A library for working with graphs and using algorithms on them.
• Spark (http://sparkjava.com/): A framework for creating web applications.
• Jackson (https://github.com/FasterXML/jackson): Provides JSON bindings for Java objects.
• JDOM (http://www.jdom.org/): A library for reading and writing XML data.
The plant overview application has the following additional dependencies:
• JHotDraw (http://www.jhotdraw.org/): A framework for drawing graph structures (like driving
course models).
• Docking Frames (http://www.docking-frames.org/): A framework for docking and undocking of
GUI panels
2
