openTCS: Developer’s Guide

The openTCS source code is written in Java. To compile it, you need a Java Development Kit (JDK) 21. To run the resulting binaries, you need a Java Runtime Environment (JRE) 21. 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 the Maven Central artifact repository, 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 explicitly use these as dependencies 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 Model Editor and Operations Desk applications have 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 Model Editor and the Operations Desk applications 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 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.

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, Model Editor and Operations Desk — 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.

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:

For transforming data sent to / received from vehicles, the following interfaces in the openTCS API are used:

To integrate your own transformation implementations, do the following:

To make your factory implementation usable in the kernel, register it as a binding for VehicleDataTransformerFactory in your KernelInjectionModule implementation. For example, the transformer factory the kernel already comes with is registered with the following line:

Finally, to select your transformer (factory) to be used for a specific vehicle, set a property on the vehicle element in the plant model with key tcs:vehicleDataTransformer to the value that your factory’s getName() method provides.

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

In addition to vehicle drivers, openTCS supports the integration of custom peripheral drivers that implement peripheral-specific communication protocols and thus mediate between the kernel and the peripheral device. In openTCS, a peripheral device is a device a vehicle may interact with along its route, e.g. an elevator or a fire door. Due to its function, a peripheral driver is also called a peripheral communication adapter. The following sections describe which requirements must be met by a driver and which steps are necessary to create and use it.

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 Operations Desk 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.

It is not uncommon for plant model data to be shared with other systems. For instance, it is possible that the navigation computer of a vehicle already has detailed information about the plant environment such as important positions and connections between them. Entering this data manually via the Model Editor application would be a tiresome and error-prone work. To help relieve users from such work, the Model Editor supports integrating components for importing plant model data from external resources — e.g. files in a foreign file format — or exporting plant model data to such resources.

To integrate a model import component, do the following:

To integrate a model export component, you follow the same steps, but implement the interface PlantModelExporter instead of PlantModelImporter.

The Operations Desk client offers to integrate custom panels providing project-specific functionality.

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

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

It is possible to register additional configuration sources, e.g. for reading configuration data from network resources or files in different formats. The mechanism provided by java.util.ServiceLoader is used for this. The following steps are required for registering a configuration source:

It is possible to register multiple supplementary configuration sources this way.

The configuration entries provided by any registered supplementary configuration source may override configuration entries provided by the properties files that are read by default. Note that the order in which these additional configuration sources are processed is unspecified.

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

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 Model Editor or Operations Desk 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.