openTCS: Developer’s Guide

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.

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:

Set the version number of the openTCS release you actually want to work with, and select the appropriate ${ARTIFACT} name from the following table:

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.

The kernel and the client applications depend on the following external frameworks and libraries:

The kernel application also depends on the following libraries:

The plant overview application has the following additional dependencies:

For automatic tests, the following dependencies are used:

The artifacts for these dependencies are downloaded automatically when building the applications.

The openTCS project heavily relies on Guice for dependency injection and wiring of components as well as for providing plugin-like extension mechanisms. In the injection API, relevant classes can be found in the package org.opentcs.customizations. For examples, see Customizing and extending the kernel application, Customizing and extending the plant overview application and Customizing and extending the control center application.

The code in the official openTCS distribution uses SLF4J for logging. Thus, the actual logging implementation is easily interchangeable by replacing the SLF4J binding in the respective application’s classpath. The kernel and plant overview client applications come with SLF4J’s bindings for java.util.logging by default. For more information on how to change the actual logging implementation, e.g. to use log4j, please see the SLF4J documentation.

The openTCS project itself uses Gradle as its build management tool. To build openTCS from source code, just run gradlew build from the source distribution’s main directory. For details on how to work with Gradle, please see its documentation.

These are the main Gradle tasks of the root project you need to know to get started:

To work with the source code in your IDE, see the IDE’s documentation for Gradle integration. There is no general recommendation for any specific IDE. Note, however, that the openTCS source code contains GUI components that have been created with the NetBeans GUI builder. If you want to edit these, you may want to use the NetBeans IDE.

In case you use NetBeans, install the Gradle Support plugin from the NetBeans plugin portal. You should then be able to open the source distribution’s root directory as a Gradle project and compile and run the components from within NetBeans.

openTCS provides the following APIs to interact with the kernel:

To use the services in code running inside the kernel JVM, e.g. a vehicle driver, simply request an instance of e.g. PlantModelService to be provided via dependency injection. You may also work with an instance of InternalPlantModelService here, which provides additional methods available only to kernel application components.

To access the services from another JVM, e.g. in a client that is supposed to create transport orders or to receive status updates for transport orders or vehicles, you need to connect to them via Remote Method Invocation (RMI). The easiest way to do this is by creating an instance of the KernelServicePortalBuilder class and letting it build a KernelServicePortal instance for you. (For now, there isn’t much support for user management, so it is recommended to ignore the methods that require user credentials.) After creating the KernelServicePortal instance, you can use it to get service instances and fetch kernel events from it. See also the class documentation for KernelServicePortalBuilder in the base API’s JavaDoc documentation.

A transport order, represented by an instance of the class TransportOrder, describes a process to be executed by a vehicle. Usually, this process is an actual transport of goods from one location to another. A TransportOrder may, however, also just describe a vehicle’s movement to a destination position and an optional vehicle operation to be performed.

All of the following are examples for "transport orders" in openTCS, even if nothing is actually being transported:

Each of the main openTCS applications — Kernel, Kernel Control Center and Plant Overview — provides an event bus that can be used to receive or emit event objects application-wide. To acquire the respective application’s event bus instance, request it to be provided via dependency injection. Any of the following three variants of constructor parameters are equivalent:

Having acquired the EventHandler, EventSource or EventBus instance that way, you can use it to emit event objects to it and/or subscribe to receive event objects.

Note that, within the Kernel application, event objects should be emitted via the kernel executor to avoid concurrency issues — see Executing code in kernel context.

For creating transport orders, the openTCS kernel accepts connections to a TCP port (default: port 55555). The communication between openTCS and the host works as follows:

The following points should be respected:

To receive status messages for transport orders in the system, connections to another TCP port (default: port 44444) may be established. Whenever the state of a transport order changes, an XML telegram will be sent to each connnected client, describing the new state of the order. Each of these telegrams is followed by a string that does not appear in the telegrams themselves (by default, a single pipe symbol: "|"), marking the end of the respective telegram. Status messages will be sent until the peer closes the TCP connection.

The following points should be respected:

The following example shows a status message as it would be sent via the status channel after the first of the two transport orders defined in Example 1 has been created and activated.

The following example shows a status message as it would be sent via the status channel for a vehicle state update.

XML schemas describing the expected structure of XML order telegrams and order batch files as well as the structure of receipt telegrams as sent by openTCS are part of the openTCS distribution and can be found in the directory containing the developer documentation.

The openTCS kernel application uses Guice to configure its components. To modify the wiring of components within the application and to add your own components, you can register custom Guice modules. Modules are found and registered automatically via java.util.ServiceLoader.

Basically, the following steps are required for customizing the application:

For more information on how the automatic registration works, see the documentation of java.util.ServiceLoader in the Java class library. For more information on how Guice works, see the Guice documentation.

The kernel application comes with default implementations for the dispatching, routing and scheduling components. These default implementations allow the kernel to fulfil all of its responsibilities, but specific use cases might make it necessary to replace them with custom ones. In such cases, they can be replaced with a custom Guice configuration.

For each of these components, KernelInjectionModule provides a convenience method for (re)binding the implementation. To replace e.g. the default Dispatcher implementation, simply register a Guice module in which you call bindDispatcher(). The module’s implementation could look like this:

openTCS supports integration of custom vehicle drivers that implement vehicle-specific communication protocols and thus mediate between the kernel and the vehicle. Due to its function, a vehicle driver is also called a communication adapter. The following sections describe which requirements must be met by a driver and which steps are necessary to create and use it.

Sometimes it is required to have some influence on the behaviour of a communication adapter (and thus the vehicle it is associated with) directly from a kernel client - to send a special telegram to the vehicle, for instance. For these cases, VehicleService.sendCommAdapterMessage(TCSObjectReference<Vehicle>, Object) provides a one-way communication channel for a client to send a message object to a communication adapter currently associated with a vehicle. A comm adapter implementing processMessage() may interpret message objects sent to it and react in an appropriate way. Note that the client sending the message may not know which communication adapter implementation is currently associated with the vehicle, so the adapter may or may not be able to understand the message.

For getting information from a communication adapter to a kernel client, there are the following ways:

Communication adapters may publish events via their VehicleProcessModel instance to emit information encapsulated in an event for any listeners registered with the kernel. Apparently, listeners must already be registered before such an event is emitted by the communication adapter, or they will miss it. To register a client as a listener, use EventSource.subscribe(). You can get the EventSource instance used by the kernel through dependency injection by using the qualifier annotation org.opentcs.customizations.ApplicationEventBus.

Alternatively, communication adapters may use their VehicleProcessModel to set properties in the corresponding Vehicle object. Kernel clients may then retrieve the information from it:

Communication adapters may also use their VehicleProcessModel to set properties in the corresponding TransportOrder object a vehicle is currently processing. This basically works the same way as with the Vehicle object:

Unlike information published via events, data stored as properties in Vehicle or TransportOrder objects can be retrieved at any time.

Within the kernel, concurrent modifications of the data model — e.g. contents of the plant model or transport order properties — need to be synchronized carefully. Similar to e.g. the Swing framework’s Event Dispatcher Thread, a single thread is used for executing one-shot or periodics tasks performing data modifications. To help with this, an instance of java.util.concurrent.ScheduledExecutorService is provided. Custom code running within the kernel application, including vehicle drivers and implementations of additional funcionality, should also perform changes of the data model via this executor only to avoid concurrency issues.

To make use of the kernel’s executor, use the @KernelExecutor qualifier annotation and inject a ScheduledExecutorService:

You can also inject it as a java.util.concurrent.ExecutorService:

Injecting a java.util.concurrent.Executor is also possible:

Then, you can use it e.g. to lock a path in the plant model in kernel context:

Due to the single-threaded nature of the kernel executor, tasks submitted to it are executed sequentially, one after another. This implies that submitting long-running tasks should be avoided, as they would block the execution of subsequent tasks.

When event objects, e.g. instances of TCSObjectEvent, are distributed within the kernel, this always happens in kernel context, i.e. from a task that is run by the kernel executor. Event handlers should behave accordingly and finish quickly/not block execution for too long. If processing an event requires time-consuming actions to be taken, these should be executed on a different thread.

The openTCS kernel control center application uses Guice to configure its components. To modify the wiring of components within the application and to add your own components, you can register custom Guice modules. Modules are found and registered automatically via java.util.ServiceLoader.

Basically, the following steps are required for customizing the application:

For more information on how the automatic registration works, see the documentation of java.util.ServiceLoader in the Java class library. For more information on how Guice works, see the Guice documentation.

Panels meeting these requirements are found automatically when you start the kernel control center application.

Analogous to the kernel application, the plant overview application uses Guice to configure its components. To modify the wiring of components within the application and to add your own components, you can register custom Guice modules. Modules are found and registered automatically via java.util.ServiceLoader.

Basically, the following steps are required for customizing the application:

For more information on how the automatic registration works, see the documentation of java.util.ServiceLoader in the Java class library. For more information on how Guice works, see the Guice documentation.

The plant overview client offers to integrate custom panels providing project-specific functionality.

Locations and vehicles are visualized in the plant overview client using configurable themes. To customize the appearance of locations and vehicles, new theme implementations can be created and integrated into the plant overview client.

Vehicles or locations in plant models are then rendered using your custom theme.

To create a new translation pack for an application, you first need to know what texts to translate. The best way to do this is to look at the existing language files in the openTCS distribution. These are contained in the applications' JAR files (opentcs-*.jar), and are by convention kept in a common directory /i18n/org/opentcs inside these JAR files.

To start your translation work, extract all of the application’s language files into a single directory first. Since JAR files are really only ZIP files, this can be done using any ZIP utility you like. As an example, to use unzip in a shell on a Linux system, issue the following command from the application’s lib/ directory:

Alternatively, to use 7-Zip in a shell on a Windows system, issue the following command from the application’s lib/ directory:

You will find the extracted language files in the i18n/ directory, then. For the Plant Overview application, an excerpt of that directory’s contents would look similar to this:

Files whose names end with _de.properties are German translations. You will not need these and can delete them.

Copy the whole i18n/ directory with the English language files to a new, separate directory, e.g. translation/. Working with a copy ensures that you still have the English version at hand to look up the original texts when translating.

Then rename all property files in the new directory so their names contain the appropriate language tag for your translation. If you are e.g. translating to Norwegian, rename mainMenu.properties to mainMenu_no.properties and the other files accordingly. It is important that the base name of the file remains the same and only the language tag is added to it.

The next step is doing the actual translation work — open each property file in a text editor and translate the properties' values in it.

After translating all the files, create a JAR file containing the i18n/ directory with your language files. You can do this for instance by simply creating a ZIP file and changing its name to end with .jar.

The result could be a file named e.g. language-pack-norwegian.jar, whose contents should look similar to this:

Finally, you merely need to add the JAR file you created to the translated application’s class path. After configuring the application to the respective language and restarting it, you should see your translations in the user interface.

As development of openTCS proceeds, parts of the applications' language files may change. This means that your translations may also need to be updated when you move from one version of openTCS to a more recent one.

To find out what changes were made and may need to be applied to your translations, you could do the following:

Based on the information from the diff, you can apply appropriate changes to your own language files. Then you merely need to create new JAR files for your translations and add them to the applications' class paths.