org.opentcs.drivers.vehicle.VehicleCommAdapter Maven / Gradle / Ivy
/**
* Copyright (c) The openTCS Authors.
*
* This program is free software and subject to the MIT license. (For details,
* see the licensing information (LICENSE.txt) you should have received with
* this copy of the software.)
*/
package org.opentcs.drivers.vehicle;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import java.util.Queue;
import org.opentcs.components.Lifecycle;
import org.opentcs.components.kernel.services.VehicleService;
import org.opentcs.data.order.TransportOrder;
import org.opentcs.drivers.vehicle.management.VehicleProcessModelTO;
import org.opentcs.util.ExplainedBoolean;
/**
* This interface declares the methods that a driver communicating with and
* controlling a physical vehicle must implement.
*
* A communication adapter is basically a driver that converts high-level
* commands sent by openTCS to a form that the controlled vehicles understand.
*
*/
public interface VehicleCommAdapter
extends
Lifecycle {
/**
* Enables this comm adapter, i.e. turns it on.
*/
void enable();
/**
* Disables this comm adapter, i.e. turns it off.
*/
void disable();
/**
* Checks whether this communication adapter is enabled.
*
* @return true if, and only if, this communication adapter is
* enabled.
*/
boolean isEnabled();
/**
* Returns an observable model of the vehicle's and its comm adapter's attributes.
*
* @return An observable model of the vehicle's and its comm adapter's attributes.
*/
@Nonnull
VehicleProcessModel getProcessModel();
/**
* Returns a transferable/serializable model of the vehicle's and its comm adapter's attributes.
*
* @return A transferable/serializable model of the vehicle's and its comm adapter's attributes.
*/
@Nonnull
VehicleProcessModelTO createTransferableProcessModel();
/**
* Returns this adapter's queue of unsent commands.
*
* Unsent {@link MovementCommand}s are commands that the comm adapter received from the
* {@link VehicleController} it's associated with. When a command is sent to the vehicle, the
* command is removed from this queue and added to the {@link #getSentCommands() queue of sent
* commands}.
*
*
* @return This adapter's queue of unsent commands.
* @see #getCommandsCapacity()
*/
Queue getUnsentCommands();
/**
* Returns this adapter's queue of sent commands.
*
* Sent {@link MovementCommand}s are commands that the comm adapter has sent to the vehicle
* already but which have not yet been processed by it.
*
*
* @return This adapter's queue of sent commands.
* @see #getCommandsCapacity()
*/
Queue getSentCommands();
/**
* Indicates how many commands this comm adapter accepts.
*
* This capacity considers both the {@link #getUnsentCommands() queue of unsent commands} and the
* {@link #getSentCommands() queue of sent commands}. This means that:
*
* - The number of elements in both queues combined must not exceed this number.
* - The vehicle will have at most this number of (not yet completed) commands at any given
* point of time.
*
*
*
* @return The number of commands this comm adapter accepts.
*/
int getCommandsCapacity();
/**
* Checks whether this comm adapter can accept the next (i.e. one more)
* {@link MovementCommand command}.
*
* @return {@code true}, if this adapter can accept another command, otherwise {@code false}.
*/
boolean canAcceptNextCommand();
/**
* Returns the string the comm adapter recognizes as a recharge operation.
*
* @return The string the comm adapter recognizes as a recharge operation.
*/
String getRechargeOperation();
/**
* Appends a command to this communication adapter's queue of
* {@link #getUnsentCommands() unsent commands}.
*
* The return value of this method indicates whether the command was really added to the queue.
* The primary reason for a commmand not being added to the queue is that it would exceed the
* adapter's {@link #getCommandsCapacity() commands capacity}.
*
*
* @param newCommand The command to be added to this adapter's queue of
* {@link #getUnsentCommands() unsent commands}.
* @return true if, and only if, the new command was added to the queue.
*/
boolean enqueueCommand(
@Nonnull
MovementCommand newCommand
);
/**
* Clears this communication adapter's command queues (i.e. the queues of
* {@link #getUnsentCommands() unsent} and {@link #getSentCommands() sent} commands).
*
* All commands in the queue that have not been sent to this adapter's vehicle, yet, will be
* removed. Whether commands the vehicle has already received are still executed is up to the
* implementation and/or the vehicle.
*
*/
void clearCommandQueue();
/**
* Checks if the vehicle would be able to process the given transport order, taking into account
* its current state.
*
* @param order The transport order to be checked.
* @return An ExplainedBoolean indicating whether the vehicle would be able to
* process the given order.
*/
@Nonnull
ExplainedBoolean canProcess(
@Nonnull
TransportOrder order
);
/**
* Notifies the implementation that the vehicle's paused state in the kernel has changed.
* If pausing between points in the plant model is supported by the vehicle, the communication
* adapter may want to inform the vehicle about this change of state.
*
* @param paused The vehicle's new paused state.
*/
void onVehiclePaused(boolean paused);
/**
* Processes a generic message to the communication adapter.
* This method provides a generic one-way communication channel to the comm adapter. The message
* can be anything, including null, and since
* {@link VehicleService#sendCommAdapterMessage(org.opentcs.data.TCSObjectReference, Object)}
* provides a way to send a message from outside the kernel, it can basically originate from any
* source. The message thus does not necessarily have to be meaningful to the concrete comm
* adapter implementation at all.
*
*
* Implementation notes:
* Meaningless messages should simply be ignored and not result in exceptions being thrown.
* If a comm adapter implementation does not support processing messages, it should simply provide
* an empty implementation.
* A call to this method should return quickly, i.e. this method should not execute long
* computations directly but start them in a separate thread.
*
*
* @param message The message to be processed.
*/
void processMessage(
@Nullable
Object message
);
/**
* Executes the given {@link AdapterCommand}.
*
* @param command The command to execute.
*/
void execute(
@Nonnull
AdapterCommand command
);
}