openTCS
Developer’s Guide
The openTCS developers
openTCS 4.15.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
1.7. openTCS kernel APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê4
2. The kernel’s Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê5
2.1. Acquiring service objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê5
2.2. Working with transport orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê6
2.2.1. A transport order’s life cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê6
2.2.2. Structure and processing of transport orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê8
2.2.3. How to create a new transport order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê9
2.2.4. How to create a transport order that sends a vehicle to a point instead of a location . . . Ê10
2.2.5. Using order sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê11
2.2.6. How to withdraw a transport order that is currently being processed . . . . . . . . . . . . . . . . Ê12
2.2.7. How to withdraw a transport order via a reference on the vehicle processing it . . . . . . . Ê13
2.3. Using the event bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê13
3. TCP/IP-based interfaces to other systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê15
3.1. Creating orders via TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê15
3.1.1. XML telegrams for creating orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê16
3.1.2. XML telegrams referencing order batches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê16
3.1.3. Receipts for created orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê17
3.1.4. Receipts for order batches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê17
3.2. Status messages via TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê18
3.3. XML Schema definitions for telegrams and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê19
4. Generating an integration project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê20
5. Customizing and extending the kernel application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê21
5.1. Guice modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê21
5.2. Replacing default kernel components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê21
5.3. Developing vehicle drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê22
5.3.1. Classes and interfaces for the kernel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê22
5.3.2. Classes and interfaces for the control center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê23
5.3.3. Steps to create a new vehicle driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê24
5.3.4. Registering a vehicle driver with the kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê24
5.4. Sending messages to communication adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê25
5.5. Acquiring data from communication adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê25
5.6. Executing code in kernel context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê26
6. Customizing and extending the control center application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28
6.1. Guice modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28
6.2. Registering driver panels with the control center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê28
7. Customizing and extending the plant overview application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê30
7.1. Guice modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê30
7.2. How to create a plugin panel for the plant overview client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê30
7.3. How to create a location/vehicle theme for openTCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê31
8. Translating the user interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê32
8.1. Extracting default language files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê32
8.2. Creating a translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê33
8.3. Integrating a translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê33
8.4. Updating a translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê34
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. To run the resulting binaries, you need a Java Runtime Environment (JRE) 1.8. 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.15.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 The base API for clients and extensions. This is
what most developers probably want to use.
opentcs-api-injection
Yes 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 A collection of utility classes used by openTCS
components.
opentcs-impl-
configuration-cfg4j
No An implementation of the base API’s
configuration interfaces based on cfg4j.
1
Artifact name API compatibility
between minor
releases
Content
opentcs-kernel-
extension-http-
services
No A kernel extension providing the web API
implementation.
opentcs-kernel-
extension-rmi-services
No A kernel extension providing the RMI interface
implementation.
opentcs-kernel-
extension-statistics
No A kernel extension providing the statistics
collection implementation.
opentcs-kernel-
extension-tcp-host-
interface
No A kernel extension providing the (deprecated)
TCP/IP host interface implementation.
opentcs-plantoverview-
panel-loadgenerator
No The load generator panel implementation for
the plant overview.
opentcs-plantoverview-
panel-
resourceallocation
No The resource allocation panel implemenation
for the plant overview.
opentcs-plantoverview-
panel-statistics
No The statistics panel implementation for the plant
overview.
opentcs-plantoverview-
themes-default
No The default themes implementation for the plant
overview.
opentcs-commadapter-
loopback
No A very basic vehicle driver simulating a virtual
vehicle.
opentcs-strategies-
default
No The default implementations of strategies that
are used by the kernel application.
opentcs-kernel
No The kernel application.
opentcs-
kernelcontrolcenter
No The kernel control center application.
opentcs-plantoverview
No 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.
2
