Transporter API

All transporters operating in a Material Handling Library flowchart provide the functions listed below:

General

Function	Description
TransporterFleet getFleet()	Returns the TransporterFleet block this transporter belongs to.
ILocation getCurrentLocation()	Returns the current location of the transporter.

Utilization statistics

Function	Description
TransporterState getState()	Returns the current state of the transporter. Valid values are: TransporterState.DELIVERING — the transporter is transporting the material item TransporterState.GOING_TO_AGENT — the transporter is moving to the agent TransporterState.GOING_HOME — the transporter is returning to its home location TransporterState.IDLE — the transporter is not busy TransporterState.PROCESSING — the transporter is interacting with an agent (material item), that is, loading or unloading TransporterState.MOVING_IDLE — the transporter is in the manual movement mode TransporterState.FAILED — Failure caused by the Downtime task of the Failure / repair type. TransporterState.MAINTENANCE — Maintenance caused by the Downtime task of the Maintenance type. TransporterState.CUSTOM_DOWNTIME — The transporter is in the Custom downtime. TransporterState.WAITING — The transporter (a multiload transporter or a tugger train) is waiting for additional agents (material items) to pick according to the set timeout.
double timeInState(TransporterState state, TimeUnits units)	Returns the time this particular transporter has spent in the given state so far (in the specified time units). state — the transporter’s state units — a constant defining the time units
double timeInState(TransporterState state)	Returns the time this particular transporter has spent in the given state so far. state — the transporter’s state
double getUtilization()	Returns the transporter's utilization: the fraction of time the transporter was busy. The returned unit utilization value lies in the range [0..1].
void resetStats()	Resets the transporter's utilization statistics, including the distance travelled, which is calculated by the getDistanceTravelled() function.

Failure and repair statistics

Function	Description
double mttr()	Returns MTTR (Mean Time to Repair), in model time units. MTTR is the average time required to repair an equipment after a failure occurs. The value is calculated for all Downtime blocks.
double mttr(TimeUnits units)	Returns MTTR (Mean Time to Repair), in the specified time units. MTTR is the average time required to repair an equipment after a failure occurs. The value is calculated for all Downtime blocks. units — a constant defining the time units
double mttr(Downtime downtime)	Returns MTTR (Mean Time to Repair) for the given Downtime block, in model time units. MTTR is the average time required to repair an equipment after a failure occurs. downtime — Downtime block
double mttr(Downtime downtime, TimeUnits units)	Returns MTTR (Mean Time to Repair) for the given Downtime block, in the specified time units. MTTR is the average time required to repair an equipment after a failure occurs. downtime — Downtime block units — a constant defining the time units
double mtbf()	Returns MTBF (Mean Time Between Failures), in model time units. MTBF is the average time between failures of a piece of equipment. MTBF starts counting when the Failure downtime task is triggered. The time spent in the IDLE or FAILED state is not included. The value is calculated for all Downtime blocks.
double mtbf(TimeUnits units)	Returns MTBF (Mean Time Between Failures), in the specified time units. MTBF is the average time between failures of a piece of equipment. MTBF starts counting when the Failure downtime task is triggered. The time spent in the IDLE or FAILED state is not included. The value is calculated for all Downtime blocks. units — a constant defining the time units
double mtbf(Downtime downtime)	Returns MTBF (Mean Time Between Failures) for the given Downtime block, in model time units. MTBF is the average time between failures of a piece of equipment. MTBF starts counting when the Failure downtime task is triggered. The time spent in the IDLE or FAILED state is not included. downtime — Downtime block
double mtbf(Downtime downtime, TimeUnits units)	Returns MTBF (Mean Time Between Failures) for the given Downtime block, in the specified time units. MTBF is the average time between failures of a piece of equipment. MTBF starts counting when the Failure downtime task is triggered. The time spent in the IDLE or FAILED state is not included. downtime — Downtime block units — a constant defining the time units

Speed

Function	Description
double getMaximumSpeed(SpeedUnits units)	Returns maximum speed value of the transporter. units — a constant defining the speed units
void setMaximumSpeed(double speed, SpeedUnits units)	Sets a new maximum speed value of the transporter. speed — a new maximum speed value units — a constant defining the speed units
double getMaximumSpeedOnCurvedSegments(SpeedUnits units)	Returns maximum permitted speed value of the transporter movement on curved segments. units — a constant defining the speed units
void setMaximumSpeedOnCurvedSegments(double speed, SpeedUnits units)	Sets a new maximum speed value of the transporter movement on curved segments. Note, that if the value you provide here exceeds the maximum speed value of the transporter, then transporter will ignore it and only accelerate to the maximum speed set by the setMaximumSpeed(double speed, SpeedUnits units) function. speed — a new maximum speed value on curved segments units — a constant defining the speed units

Acceleration, deceleration

Function	Description
double getAcceleration(AccelerationUnits units)	Returns the acceleration value of the transporter. units — a constant defining the acceleration units
void setAcceleration(double acceleration, AccelerationUnits units)	Sets the new acceleration value of the transporter. A value of 0 is treated as infinite acceleration, so the transporter reaches its target speed on the next simulation step. acceleration — a new acceleration value units — a constant defining the acceleration units
double getDeceleration(AccelerationUnits units)	Returns the deceleration value of the transporter. units — a constant defining the acceleration units
void setDeceleration(double deceleration, AccelerationUnits units)	Sets the deceleration value of the transporter. A value of 0 is treated as infinite deceleration, so the transporter reaches its target speed on the next simulation step. deceleration — a new deceleration value units — a constant defining the acceleration units

Material item position

Function	Description
Position getCargoPosition()	Returns the position of the material item in relation to the center point of the transporter (in the specified length units).
void setCargoPosition(double dx, double dy, double dz, LengthUnits units)	Sets the position of the material item in relation to the center of the transporter (in the specified length units). dx — distance to the point on X axis dy — distance to the point on Y axis dz — distance to the point on Z axis units — a constant defining the length units
void setCargoPosition(double dx, double dy, double dz, LengthUnits units, double rotation, double verticalRotation)	Sets the position of the material item in relation to the center of the transporter including its horizontal and vertical orientation. dx — distance to the point on X axis dy — distance to the point on Y axis dz — distance to the point on Z axis units — a constant defining the length units rotation — horizontal orientation of the material item verticalRotation — vertical orientation of the material item
void resetCargoPosition()	Resets the position of the material item back to its default value (to the center point of the transporter).

Routing

Function	Description
void recalculateRoute()	Recalculates the current route of the transporter. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state.
void recalculateRoute(double x, double y, double z)	Recalculates the current route of the transporter for the given coordinates of the new destination point. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. x — the X-coordinate of the transporter's new destination point y — the Y-coordinate of the transporter's new destination point z — the Z-coordinate of the transporter's new destination point
void recalculateRoute(Level level, double x, double y, double z)	Recalculates the current route of the transporter for the given coordinates of the new destination point. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. level — the new level where the transporter's destination point is located x — the X-coordinate of the transporter's new destination point y — the Y-coordinate of the transporter's new destination point z — the Z-coordinate of the transporter's new destination point
void recalculateRoute(Node node)	Recalculates the current route of the transporter for the given new destination. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. node — the node specified as the transporter's new destination
void recalculateRoute(Attractor attractor)	Recalculates the current route of the transporter for the given new destination. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. attractor — the attractor specified as the transporter's new destination
void recalculateRoute(Path path, double offset, LengthUnits units)	Recalculates the current route of the transporter for the given new destination. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. path — the path where transporter's new destination point is located offset — the distance from the starting point of the path to the transporter's new destination point units — a constant defining the length units
void recalculateRoute(ConveyorPath conveyor, double offset, LengthUnits units)	Recalculates the current route of the transporter for the given new destination. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. conveyor — the conveyor where transporter's new destination point is located offset — the distance from the starting point of the conveyor to the transporter's new destination point units — a constant defining the length units
void recalculateRoute(PositionOnConveyor positionOnConveyor)	Recalculates the current route of the transporter for the given new destination. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. conveyor — the position on conveyor that serves as transporter's new destination
void recalculateRoute(ConveyorStation station)	Recalculates the current route of the transporter for the given new destination. If you have previously specified a custom route in TransporterControl block, the route will be recalculated taking into account the conditions you have set. You can only call this function when the transporter is already in movement, i.e. in either DELIVERING, or GOING_TO_AGENT, or GOING_HOME state. station — the station that serves as transporter's new destination
RouteData getRouteData()	Returns the information about the remaining route for the transporter (from its current location to the destination). The information is returned as a list of movement tasks that the transporter will accomplish on its way to the destination. The movement tasks are listed in consecutive order from current location to target. Each task contains the information about the path and the movement type. Valid movement types are: PLAIN — movement from point node to path or within network node or, in case of transporters with free space navigation, the movement within a cell of the navigation mesh PATH — movement along the network path PORT — movement between two network ports

Collision avoidance control

Function Description

void ignoreCollisions(boolean ignore) Controls the transporter’s ability to recognize other transporters as obstacles and to be recognized as an obstacle itself. To make transporters ignore each other, pass true as an argument. To make them recognize each other again — pass false as an argument.
If the transporter is a tugger train, calling ignoreCollisions() applies to the tugger and all of its trailers.

ignore — if true, the transporter will ignore other transporters; if false — the transporter will stop ignoring other transporters.

void ignoreCollisionsFor(double time, TimeUnits units) Disables the transporter's ability to recognize other transporters as obstacles and to be recognized as an obstacle itself for a given period of time in specified time units. When the specified period of time runs out, the transporter goes back to acknowledging collisions with other transporters.
If the transporter is a tugger train, calling ignoreCollisions() applies to the tugger and all of its trailers.

time — period of time during which the transporter ignores collisions
units — a constant defining the time units

Manual movement control

Function	Description
void ignoreCollisions(boolean ignore)	Controls the transporter’s ability to recognize other transporters as obstacles and to be recognized as an obstacle itself. To make transporters ignore each other, pass true as an argument. To make them recognize each other again — pass false as an argument. If the transporter is a tugger train, calling `ignoreCollisions()` applies to the tugger and all of its trailers. ignore — if true, the transporter will ignore other transporters; if false — the transporter will stop ignoring other transporters.
void ignoreCollisionsFor(double time, TimeUnits units)	Disables the transporter's ability to recognize other transporters as obstacles and to be recognized as an obstacle itself for a given period of time in specified time units. When the specified period of time runs out, the transporter goes back to acknowledging collisions with other transporters. If the transporter is a tugger train, calling `ignoreCollisions()` applies to the tugger and all of its trailers. time — period of time during which the transporter ignores collisions units — a constant defining the time units

For more information on the specifics of manual movement control for transporters, see the corresponding sections on free space navigation and path-guided navigation.

Transporters cannot be manually moved to a point designated by its X, Y and Z coordinates or to an agent on another level. Instead, you can use a node as the destination.

Function	Description
void move(Node node)	Commands the transporter to move to the specified node in the TransporterState.MOVING_IDLE state. node — the target node
void move(Node node, TransporterState state)	Commands the transporter to move to the specified node in the specified state. node — the target node state — one of the transporter states; cannot be TransporterState.IDLE
void move(double x, double y)	Commands the transporter to move to the specified coordinates in the TransporterState.MOVING_IDLE state. x — the X-coordinate of the destination y — the Y-coordinate of the destination
void move(double x, double y, TransporterState state)	Commands the transporter to move to the specified coordinates in the specified state. x — the X-coordinate of the destination y — the Y-coordinate of the destination state — one of the transporter states; cannot be TransporterState.IDLE.
void move(T agent)	Commands the transporter to move to the specified agent in the TransporterState.MOVING_IDLE state. agent — the agent to move to
void move(T agent, TransporterState state)	Commands the transporter to move to the specified agent in the specified state. agent — the agent to move to state — one of the transporter states; cannot be TransporterState.IDLE

Distance

You can calculate the distance from the transporter to a given point with the help of agent type API inherited by the transporters.

Function	Description
double getDistanceTravelled(LengthUnits units)	Returns the distance the transporter has travelled from the model start or from the last call of either resetDistanceTravelled(), resetStats() of the individual transporters, or resetStats() of the transporter fleet. units — a constant defining the length units
void resetDistanceTravelled()	Resets the distance travelled by the transporter.

Multiload transportation

Function	Description
int getNumberOfLoads()	Returns the current maximum number of agents the transporter can carry at the same time.
void getMaxNumberOfLoads(int maxNumberOfLoads)	Set the new maximum number of agents the transporter can carry at the same type. maxNumberOfLoads — the new maximum number of transported agents (material items)
List<T> getTransportedAgents()	Returns the list of agents transported by the transporter (or the tugger train).
int nTransportedAgents()	Returns the number of agents transported by the transporter (or the tugger train).
T getControllingAgent()	Returns the agent that the tugger (or a regular transporter) is currently operating with: either moving toward it or transporting it to its destination. If the agent has already exited the MoveByTransporter block but has not yet released the transporter, this function still returns that agent. The same applies during the loading phase. As a result, the returned agent may change in the following cases: the tugger train picks up an agent and starts moving to the next one (the next agent will be returned), the current agent is replaced by a higher-priority one (at the moment of pickup), the transporter is released by the agent (the agent passes through the ReleaseTransporter block), the agent is removed from the blocks using the remove() function.
List<T> reservations()	Returns the list of agents the transporter (or the tugger train) is reserved for.

Tugger trains

These functions work for transporters designated as tugger trains in the properties of the TransporterFleet block.

Function	Description
int getNumberOfTrailers()	Returns the current number of trailers in the tugger train.
void setNumberOfTrailers(int nTrailers)	Sets the current number of trailers for the tugger train with the explicitly specified number of trailers. You cannot specify a number less than the number of loaded trailers plus the agent the tugger train is about to pick up. If the new number is greater than the current one, additional trailers are created at the end of the train. If the new number is smaller, extra trailers are removed from the end, provided that the new number is sufficient for all transported agents (including the one being approached). Otherwise, the number is not changed. Newly created trailers are placed at the end of the train, continuing its current arrangement. They also do not account for the layout (network position, walls, or other transporters) and are not considered by other transporters until the tugger starts moving. Creating trailers on a path or node does not trigger the On enter actions for that path or node. nTrailers — a new number of trailers
Position getTrailerCargoPosition()	Returns the relative X and Y coordinates and the relative rotation of the cargo in tugger trailers. For the 3D space, also returns the Z coordinate. The returned result is a Position object containing the coordinates and rotation data. If called before the agent is fully initialized (for example, in the On startup action of the agent), it is not yet possible to determine whether the agent is a tugger. In this case, the function may still work for a regular transporter, and the check is performed later.
void setTrailerCargoPosition(double dx, double dy, double dz, LengthUnits lengthUnits)	Sets the coordinates of the cargo relative to a tugger trailer carrying it, in specified length units. If called before the agent is fully initialized (for example, in the On startup action of the agent), it is not yet possible to determine whether the agent is a tugger. In this case, the function may still work for a regular transporter, and the check is performed later. dx — the relative X coordinate dy — the relative Y coordinate dz — the relative Z coordinate lengthUnits — a constant defining the length units
void setTrailerCargoPosition(double dx, double dy, double dz, LengthUnits units, double rotation, double verticalRotation)	Sets the coordinates and the orientation of the cargo relative to a tugger trailer carrying it, in specified length units. If called before the agent is fully initialized (for example, in the On startup action of the agent), it is not yet possible to determine whether the agent is a tugger. In this case, the function may still work for a regular transporter, and the check is performed later. dx — the relative X coordinate dy — the relative Y coordinate dz — the relative Z coordinate lengthUnits — a constant defining the length units rotation — the relative horizontal rotation rotation — the relative vertical rotation
void resetTrailerCargoPosition()	Resets the position of cargo in tugger trailers to default value.
List<T> getTrailers()	Returns the list of agents that serve as the trailers in the tugger train.
int nFreeTrailers()	Returns the number of non-reserved and free trailers in the tugger train. For a tugger train where the number of trailers equals the number of agents, always returns 0.
double getTuggerTrainLength()	Returns the length of the tugger train in meters. Gaps between trailers are included.
double getTuggerTrainLength(LengthUnits units)	Returns the length of the tugger train in the specified length units. Gaps between trailers are included. units — a constant defining the length units
T getTrailer(int index)	Returns the agent that is the trailer of the tugger train with the specified index. index — the index of the trailer
T getTrailer(T transportedAgent)	Returns the agent that is the trailer of the tugger train that transports the specified agent. transportedAgent — the agent being transported by the trailer
double getTrailerOffset(int index)	Returns the offset of the trailer of the tugger train with the specified index. The returned value is the distance between the center of the tugger train and the center of the specified trailer, in meters. index — the index of the trailer
double getTrailerOffset(int index, LengthUnits units)	Returns the offset of the trailer of the tugger train with the specified index. The returned value is the distance between the center of the tugger train and the center of the specified trailer, in the specified length units. index — the index of the trailer units — a constant defining the length units
Position getTrailerPosition(int index)	Returns the current X and Y coordinates of the tugger trailer with the specified index, in the continuous space. For the 3D space, also returns the Z coordinate. The returned result is a Position object containing the coordinates and rotation data. index — the index of the trailer

Spin turn and rotation

Function	Description
boolean isTurnOnPathEnabled()	Returns whether the transporter is able to do a spin turn on a path.
void enableTurnOnPath(boolean enabled)	Enables or disables the ability of a path-guided transporter to turn on a path. enabled — true to allow turning on a path; false to prohibit it
double getRotationSpeed(RotationSpeedUnits units)	Returns the rotation speed of a transporter. units — a constant defining the rotation speed units
void setRotationSpeed(double speed, RotationSpeedUnits units)	Sets the rotation speed for the transporter. speed — the new rotation speed of the transporter units — a constant defining the rotation speed units

How can we improve this article?