openTCS Files

openTCS version 2.4
===================

0. Table of contents:
=====================

1. Introduction
2. System requirements
3. NetBeans project
4. Getting started
5. Limitations
6. Support
7. Changelog
8. Contributors


1. Introduction:
================

openTCS (short for "open Transportation Control System") is a free base
for controlling vehicles in an Automated Guided Vehicle System (AGVS). (It
should generally be possible to control any track-guided vehicle with it,
but AGVS are the main target.) It is being maintained at the Fraunhofer
Institute for Material Flow and Logistics in Dortmund, Germany.

The software runs on the Java platform (JDK 1.7 or later). All libraries
required for compiling and/or using it are included in the distribution.

openTCS itself is not a complete product you can use "out-of-the-box" to
control an AGVS with. It is an implementation of the basic data structures
and algorithms (routing, dispatching, scheduling) needed for running an
AGVS with more than one vehicle; it tries to be as generic as possible to
allow interoperation with track-guided vehicles of practically any vendor.
Thus it is usually necessary to at least write and integrate a vehicle
driver (called "communication adapter" in openTCS-speak) that translates
between the abstract interface of the openTCS kernel and the communication
protocol your vehicle understands. Depending on your needs, it might also
be necessary to adapt algorithms or add project-specific strategies.

The openTCS source code is licensed under the terms of the MIT License. A
copy of the license is included in the distribution. (See the file
LICENSE.txt.)

Please note that openTCS is distributed without any warranty - without
even the implied warranty of merchantibility or fitness for a particular
purpose. Please refer to the license for details.

We are grateful to any developers that have contributed to openTCS.
Section 8 contains a list of all contributors.

To download the latest version and/or read news about openTCS, please see
its web site at http://www.opentcs.org/.


2. System requirements:
=======================

The openTCS source code is written in Java. To compile it, you need a Java
Development Kit (JDK) 1.7 or later. To run the resulting binaries, you
need a Java Runtime Environment (JRE) 1.7 or later. All other required
libraries are included in the openTCS distribution.

The openTCS build process is automated based on Apache Ant. To build
openTCS, you need Apache Ant 1.8 or later. (For more information about Ant
please see http://ant.apache.org/.) The whole build process is programmed
in the Ant build script - see the file 'build.xml' in the main directory.

These are the main build targets you need to know to get started:

- buildall:
  Compiles everything to a runnable state, i.e. after running this target
  you can use the included shell scripts/batch files to start all system
  components.
- buildapidocs:
  Generates the API documentation in build/apidocs/.
- deployall:
  Build and packages all system components for production use in deploy/.
- runtests:
  Builds everything and runs all JUnit tests (located in tests/). Test
  results can be found in reports/junit/.
- cleanall:
  Cleans up everything produced by the other targets.


3. NetBeans project:
====================

The openTCS project team mainly uses NetBeans for development. The
NetBeans project data is included in every openTCS release, so if you
happen to use NetBeans, too, all you have to do is load the openTCS
project in it.

After loading the project in NetBeans, you can run e.g. the 'buildall'
target in the 'build.xml' file to build the whole system.


4. Getting started:
===================

To get started with openTCS, please refer to the introductory
documentation that should be included in the distribution.

To start developing with openTCS, the file openTCS-Base.jar should be
included in your class path. Please refer to the JavaDoc API documentation
that should also be included in the distribution, especially:

- The interface documentation of org.opentcs.kernel.Kernel describes the
  main interface of the openTCS kernel that accepts calls from clients.
- The class documentation of
  org.opentcs.remote.rmi.DynamicRemoteKernelProxy describes how to get an
  instance of org.opentcs.kernel.Kernel from a separate JVM/process.
- The package documentation of org.opentcs.data.order describes how to
  create transport orders programmatically via the kernel interface.
- The package documentation of org.opentcs.drivers describes the basic
  steps needed to create your own vehicle driver.

5. Limitations:
===============

openTCS has some known limitations that we hope we can address in the
future. Here's a (probably incomplete) list:

- The complete API of the kernel with all features is currently only
  available via RMI/the Kernel interface. This limits clients that need or
  want to use all of these features to the Java platform (and RMI).
- Parts of the documentation and the graphical frontend are currently
  available in German only.
- There is practically no code for deadlock avoidance for concurrently
  scheduled vehicles, i.e. it's possible that two or more vehicle moving
  in the same area run into a deadlock, which then needs to be resolved
  manually. This can be avoided by taking it into account when designing
  the layout of the vehicles' tracks.


6. Support:
===========

Please note that, while we are happy to be able to release openTCS to the
public as free software and would like to see it used and improved
continuously, the development team cannot provide unlimited free support
for it. Supporting, fixing bugs and improving the software requires
funding, and we depend on providing commercial openTCS-related services
for that.

If you have technical/support questions, you can send them via e-mail to
info@opentcs.org or use the project's forum at sourceforge.net. The
developers involved will try to respond when possible.


7. Changelog:
=============

Version 2.4 (2013-02-07):
-------------------------
- Updated JDOM to 2.0.4.
- Updated JHotDraw to 7.6.
- Updated Checkstyle to 5.6.
- Integrated Saxon 9.4 and Apache FOP 1.1 into the build for processing the
  DocBook manual.
- Major overhaul of the visualization client, including:
  Integration of both modes (modelling and visualization) into a single
  application, preparation for proper localization and integration of the course
  layout information into model data structures, making it easier to create
  complete models including course layout via the kernel API. (This basically
  allows to implement other clients that can create new models or import/convert
  existing models from other applications.) Using models containing "old" layout
  data is still supported but deprecated.
- Changed license of the visualization client to LGPL.
- Improved support for vehicle energy management: For each vehicle, a specific
  charging operation may be specified (default: "CHARGE"), which will be used
  by the dispatcher to automatically create orders to recharge the vehicle's
  energy source.
- Improved strategies for selecting parking positions and charging locations.
- Changed initial processing state of a vehicle to UNAVAILABLE, preventing
  immediate dispatching of vehicles on startup.
- Improved kernel methods for withdrawing orders from vehicles and allow setting
  a vehicle's processing state to UNAVAILABLE to prevent it being dispatched
  again immediately.
- Added kernel method dispatchVehicle() to allow vehicles in state UNAVAILABLE
  to be dispatched again.
- (Re-)Added 'dispensable' flag to class TransportOrder to indicate that an
  order may be withdrawn automatically by the dispatcher. (Primarily used to
  make parking orders abortable.)
- Improved handling of order sequences.
- Added a simple, preliminary implementation of data collection for statistics
  based on event data in org.opentcs.util.statistics.
- Removed class VehicleType and all references to it completely. All information
  about the vehicles themselves is stored in Vehicle, now, simplifying the code
  in which VehicleType was used.
- Added Vehicle.State.UNAVAILABLE for vehicles that are not in an ERROR state
  but currently remotely usable, either. (Examples: manual or semi-automatic
  modes)
- Added methods Kernel.sendCommAdapterMessage() and
  CommunicationAdapter.processMessage() to allow clients to send generic
  messages to communication adapters associated with vehicles.
- Removed methods stop(), pause() and resume() from communication adapter
  interface as they had not served any purpose for long time.
- Removed kernel method getInfoText(), for which the query() method has served
  as a replacement for a while, now.
- Properly propagate exceptions to clients connected via the RMI proxy.
- Small bug fixes and improvements to code and documentation.

Version 2.3 (2012-09-17):
-------------------------
- Moved sources of the generic client into the main project's source tree.
- Updated JFreeChart to 1.0.14.
- Use JFreeChart for drawing the velocity graph of a communication
  adapter.
- Instead of emitting an event only after the kernel's state changed, emit
  an additional one before the state transition.
- Implemented org.opentcs.data.order.OrderSequence for processes spanning
  more than one transport order that should be processed by a single
  vehicle.
- Added a set of properties to DriveOrder.Destination and MovementCommand,
  allowing an order/command to carry additional information for a
  communication adapter or vehicle, if necessary.
- (Re-)Added State.CHARGING and merged State.DRIVING and State.OPERATING
  into State.EXECUTING in org.opentcs.data.model.Vehicle.
- Added a settable threshold for critical and good energy levels of a
  vehicle.
- Added a vehicle specific charging operation to Vehicle, settable by the
  communication adapter.
- Recompute routing tables when (un)locking a path.
- Remove org.opentcs.data.model.Path.Action, which wasn't really used
  anywhere and doesn't provide any benefit over a Path's properties.
- Remove a lot of deprecated methods in the kernel interface.
- Replace the existing dispatcher with one that is aware of order
  sequences and vehicles' energy levels and automatically creates orders
  to recharge vehicles.
- Deprecated and largely removed references to
  org.opentcs.data.model.VehicleType, simplifying some code.
- Bug fix in KernelStateOperating.activateTransportOrder(): Use our own
  references to the transport order, not the one we received as a
  parameter, as that causes problems if the order has been renamed but a
  reference with the old name is being used by the calling client.
- Moved classes to packages properly separated by functionality, and
  removed a few utility classes that were not used and didn't provide
  much. (This effectively means the API provided by the base JAR changed.
  Fixing any resulting broken imports should be the only thing required to
  use the new version.)
- Small bug fixes and improvements to code and documentation.

Version 2.2 (2012-07-10):
-------------------------
- Published as free open source software (license: the MIT license, see
  LICENSE.txt)
- Requires Java 1.7
- Update JDOM to 2.0.2
- Integrated kernel and driver GUI into a single application
- Basic support for energy management
- Support for dynamic load handling devices reported by vehicles/vehicle
  drivers to the kernel
- Simplified integration of vehicle drivers: Vehicle drivers in the class
  path are found automatically using java.util.ServiceLoader.
- Automatic backup copies (in $KERNEL/data/backups/) when saving models
- Switched from properties to XML for configuration files
- Simplified and more consistent kernel API
- Many small bug fixes and adjustments of the included strategies


8. Contributors:
================

We are grateful for anyone helping us to improve openTCS by contributing
code or documentation. So far, the developers involved were/are (in
alphabetical order by last name):

- Hubert Buechter
- Iryna Felko
- Heinz Huber
- Olaf Krause
- Sebastian Naumann
- Volkmar Pontow
- Philipp Seifert
- Andreas Trautmann
- Stefan Walter
- Youssef Zaki

If you have contributed to openTCS and we have missed you on this list,
please accept our apologies and send us an e-mail (to info@opentcs.org).