ANSCER FMS MQTT API Documentation

API Revisions

Version	Date	Remarks
0.1.0	19/08/2024	Initial Release of MQTT API
0.2.0	22/10/2024	Added transport order constraints
0.3.0	09/12/2024	Updated JSON structures for API
0.4.0	14/12/2024	Added topic for transport order events
0.4.1	20/02/2025	Fixed MQTT topics
0.5.0	01/05/2025	Added topic for sending instant actions
0.6.0	03/05/2025	Added some missing fields and also added connection and state array topics
0.6.1	04/05/2025	Added information about actions and how they are used
0.6.2	12/01/2026	Added start and stop charging actions for orders and instant actions respectively
0.6.3	12/01/2026	Added the graph data topic
0.7.0	16/01/2026	Added the update transport order MQTT topic
0.8.0	03/02/2026	Added a missing field in the retrieve transport order request structure
0.9.0	19/03/2026	Added new topics for vehicle based events with respect to the FMS
1.0.0	22/06/2026	Improved and added more information regarding API and updated the graph message structure

Introduction

This document contains basic usage of the MQTT API for interacting and interfacing with the ANSCER Fleet software. Messages and its structure along with how it can be used is also explained. Since MQTT does not have services, the request and response is split over two topics. The document is subject to change as the API evolves to meet real world and internal requirements. The API requires an MQTT client to be connected to the broker. To connect, the IP address or host name, port, username and password of the broker is required. The IP address or host name depends on how the FMS is connected to the client network. The default port for the MQTT broker is 1883. The username and password will be provided on a need to know basis.

The third party consumers of these APIs are expected to implement the business logic or process flow using the message structures and fields that are discussed in this document. Messages and fields that are not discussed in this document should not be used to drive the process flow logic.

How To Read This Document

It is recommended to read this document in its entirety as different concepts regarding the transport orders and vehicle state are explained throughout the document. To implement complex process flows both of these data needs to be consumed to drive the final business logic.

Some elements of the document are highlighted like this text as an example. This usually means that it is a field or constant used in the message structure or is related to it.

Some sections of the document might reference other sections of the document. It is suggested to go through those sections to have clearer understanding of how the message data and topic can be used to implement the desired application process flow.

Transport Order

Transport order or internally referenced as missions, is a list of orders containing locations (Nodes) and actions (Pick or Drop) to be executed to complete movement of the materials on the plant floor. Every transport order has a unique transport order ID which is used for tracking the progress of it in the fleet. It can also be used externally by third party Warehouse Management System (WMS) or Enterprise Resource Planning (ERP) systems.

Creation of Transport Order

The following request and response is for creating a new transport order. Once the transport order is received the fleet will automatically assign it to a vehicle which is able to execute the actions that are specified under each node. It is recommended to go through this section thoroughly as concepts explained here are used throughout in other sections related to transport orders and also vehicles. A brief explanation of the relevant fields are given below.

Request:

MQTT Topic: transport_orders/create/request

{
  "createTransportOrdersRequest": [
    {
      "header": {
        "headerId": 1,
        "transportOrderType": "TRANSPORT",
        "transportOrderId": "TO-0001",
        "tranportOrderInterface": "task_manager_interface_mqtt"
      },
      "status": {
        "startTimestamp": "2024-12-11T11:12:05.983658708Z",
        "updateTimestamp": "2024-12-11T11:12:05.983664365Z",
        "endTimestamp": "1970-01-01T00:00:00.000Z",
        "status": "QUEUED",
        "statusDescription": "",
        "currentOrder": {
          "headerId": 0,
          "timestamp": "1970-01-01T00:00:00.000Z",
          "version": "",
          "manufacturer": "",
          "serialNumber": "",
          "orderId": "",
          "orderUpdateId": 0,
          "nodes": [],
          "edges": []
        },
        "currentOrderIndex": 0,
        "transportOrderDescription": "Creating new TO"
      },
      "constraints": {
        "vehicle": {
          "serialNumber": "AR001",
          "manufacturer": "ANSCER"
        },
        "loads": [
          {
            "type": "BIN",
            "count": 1
          }
        ]
      },
      "orders": [
        {
          "nodes": [
            {
              "nodeId": "10",
              "actions": [
                {
                  "actionType": "pick",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "lhd",
                      "value": "stroke"
                    },
                    {
                      "key": "loadType",
                      "value": "BIN"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "nodes": [
            {
              "nodeId": "20",
              "actions": [
                {
                  "actionType": "drop",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "lhd",
                      "value": "stroke"
                    },
                    {
                      "key": "loadType",
                      "value": "BIN"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Response:

MQTT Topic: transport_orders/create/response

{
  "createTransportOrdersResponse": [
    {
      "transportOrder": {
        "header": {
          "headerId": 1,
          "transportOrderType": "TRANSPORT",
          "transportOrderId": "TO-0001",
          "tranportOrderInterface": "task_manager_interface_mqtt"
        },
        "status": {
          "startTimestamp": "2024-12-15T04:49:58.508133576Z",
          "updateTimestamp": "2024-12-15T04:49:58.508133736Z",
          "status": "QUEUED",
          "statusDescription": "",
          "currentOrder": {
            "headerId": 0,
            "timestamp": "1970-01-01T00:00:00.000Z",
            "version": "",
            "manufacturer": "",
            "serialNumber": "",
            "orderId": "",
            "orderUpdateId": 0,
            "nodes": [],
            "edges": []
          },
          "currentOrderIndex": 0,
          "transportOrderDescription": "Creating new TO"
        },
        "constraints": {
          "vehicle": {
            "manufacturer": "ANSCER",
            "serialNumber": "AR001"
          },
          "loads": [
            {
              "type": "BIN",
              "count": 1
            }
          ]
        },
        "orders": [
          {
            "nodes": [
              {
                "nodeId": "10",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "pick",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "nodes": [
              {
                "nodeId": "20",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "drop",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ],
        "properties": {}
      },
      "success": true,
      "message": "Successfully enqeued transport order"
    }
  ]
}

Header

The transportOrderType field specifies the type of the transport order and is an optional field that can be set by the creator of the transport order and therefore can be empty. The possible values for this field and description is provided in the following table.

Transport Order Type	Description
TRANSPORT	A transport order to transport materials
POSITIONING	A tranport order to just move the vehicle to another location
PARK	A transport order to the park the vehicle (This is internally generated by the FMS if automated parking is enabled)
CHARGE	A transport order to charge the vehicle (This is internally generated by the FMS if automated charging is enabled)

The transportOrderId has to be a unique for each new transport order. It is recommended to use UUID for this as the ID for the transport order. This ID can be used in the third party process flow to track the progress of the transport order execution.

The transportOrderInterface is an optional field that can be set by creator of the transport order to specify which component was responsible for creating it. This can be used to filter out transport orders that was not created by third party process flow for example. It can also be empty if not set. This field is preserved through out the lifecycle of the transport order.

Status

The startTimestamp, updateTimestamp and endTimestamp fields under the status object is automatically set by the FMS according to different situations. The following table explains the different timestamps

Timestamp	Description
startTimestamp	The start timestamp specifies the time at which the transport order was received. If not set to a valid time, the FMS will auto update it.
updateTimestamp	The update timestamp will change whenever the data of transport orders changes. Status changes, order or transport order updates can all change the update timestamp.
endTimestamp	The end timestamp is the last timestamp to be updated once the lifecycle of the transport order is finished. This is done when the status of the transport order has reached a terminal status which will be discussed later.

The status field under the status object for a transport order that is being created to transport materials on the factory floor should always be set to QUEUED. The different statuses and its meaning is provided in the following table.

Status	Description
QUEUED	The transport order is in the FMS internal queue. Vehicles might not currently be available to execute it.
PROCESSING	The transport order is being executed by a vehicle.
SUCCEEDED	All the orders in the transport order is completed successfully
FAILED	If a FATAL error is reported by the vehicle, connectionState for vehicle was set to OFFLINE or maximum number of order resend tries has exceeded the preset limit the transport order will be set to be failed. A transport order can also fail if the usage level of the vehicle executing it is changed to POSITION_ACKNOWLEDGED or IGNORED during operation or if it is deleted from the system.
CANCELLING	The transport order is marked for cancelling and a cancel order instant action is being sent to the vehicle to stop the vehicle from executing the order. While in this status, the vehicle associated with the transport order will not be free to execute other transport orders until a terminal status is reached. The terminal status while CANCELLING is CANCELLED if the vehicle is able to cancel it's order correctly.
CANCELLED	The cancel order instant action has finished successfully as a result the transport order is said to be cancelled.
INVALID	This status is set when the transport order ID is invalid or because of invalid plans
LOST	This status is set if the vehicle is reporting a state that does not match with the transport order's state in the FMS buffer. The transport order execution cannot proceed in such cases and therefore, is said to be lost.

The transport orders is said to be executing if the status is set to PROCESSING or CANCELLING. The terminal statuses for a transport order after which it is no longer considered to be executing are SUCCEEDED, FAILED, CANCELLED, INVALID or LOST. The QUEUED status is the initial status for the transport order's lifecycle.

The statusDescription field under status object for the transport order gives a human understandable description of the status.

The currentOrder field contains the order that will be sent to the vehicle. While the status of the transport order is QUEUED the currentOrder field will not be valid as no vehicle was found by the FMS to assign orders. Once the status is set to PROCESSING the currentOrder field will be valid. The validity of the current order can be checked easily by seeing whether the manufacturer, serialNumber, orderId fields under the currentOrder object are not empty.

An example of the currentOrder JSON structure when transport order has the status PROCESSING as a vehicle is actively executing it is shown below. Some of the fields are omitted for brevity.

"currentOrder": {
  "headerId": 1,
  "timestamp": "2024-06-28T09:14:18.262041702Z",
  "version": "v2.0.0",
  "manufacturer": "ANSCER",
  "serialNumber": "AR002",
  "orderId": "ORD-0001",
  "orderUpdateId": 0,
  "nodes": [ 
    {
      "nodeId": "211",
      "sequenceId": 7,
      "nodePosition": {
        "x": 16.3721,
        "y": 15.2333,
        "theta": -1.5708,
      },
      "actions": []
    },
    {
      "nodeId": "10",
      "sequenceId": 8,
      "nodeDescription": "",
      "released": true,
      "nodePosition": {
        "x": 16.3721,
        "y": 15.483299999999998,
        "theta": -1.5708,
      },
      "actions": [
        {
          "actionType": "pick",
          "blockingType": "HARD",
          "actionParameters": [
            {
              "key": "lhd",
              "value": "stroke"
            },
            {
              "key": "loadType",
              "value": "BIN"
            }
          ]
        }
      ]
    }
  ],
  "edges": [
    {
      "edgeId": "211---10",
      "sequenceId": 7,
      "startNodeId": "211",
      "endNodeId": "10"
    }
  ]
}

The nodes array might contain the destination node that was specified in the transport order. If the node had an action associated with it, that will also be available under the actions. The actions that are specified under a node will be available in the vehicle state under the actionStates array field once the vehicle's current order contains the destination node with the actions to be executed there.

The currentOrderIndex can be considered as an index into the orders array field that basically contains the instruction for the transport order. In the below example, the transport order is to go to the nodeId 10 and do a pick action and then move on to 20 to execute a drop action.

The integer index of the currentOrderIndex field will change according to which part of the orders array is being executed by the vehicle. By default the value for it will be 0 which means the first order in the transport order.

For example, in the transport order message structure given below, if the currentOrderIndex is 0, the following element in the orders array is being executed.

{
  "nodes": [
    {
      "nodeId": "10",
      "actions": [
        {
          "actionType": "pick",
          "blockingType": "HARD",
          "actionParameters": [
            {
              "key": "lhd",
              "value": "stroke"
            },
            {
              "key": "loadType",
              "value": "BIN"
            }
          ]
        }
      ]
    }
  ]
}

When the currentOrderIndex field is set to 1, an update will be given for transport order through the transport order update event that will be discussed in dedicated section later. The following element in the orders array is being executed.

{
  "nodes": [
    {
      "nodeId": "20",
      "actions": [
        {
          "actionType": "drop",
          "blockingType": "HARD",
          "actionParameters": [
            {
              "key": "lhd",
              "value": "stroke"
            },
            {
              "key": "loadType",
              "value": "BIN"
            }
          ]
        }
      ]
    }
  ]
}

Constraints

The constraints object consists of the vehicle and loads. The vehicle field can be used to specify which vehicle should execute the transport order. While, the loads field can be used to tell the vehicle which load type the vehicle will need to handle. In this way, an appropriate vehicle can be selected to execute the orders specified in the transport order.

It is to be noted that it is recommended to either use the loads constraints or vehicle constraints. Do not use both constraints for a transport order.

The vehicle object contains the vehicle's manufacturer and serialNumber as fields that needs to be provided to set the vehicle constraint. While the loads constraint has the type field which is the load type and the count field is the number of specific load type the vehicle is expected to carry while executing the transport order. For example, if the loadType is BIN and each of this load type has a weight of 100Kg and the maximum payload of the vehicle is 250Kg then the maximum count that can be set is 2. For most use cases that involves load handling devices like lifter to interact with the load the count should always be set to 1.

If a vehicle is already loaded to the maximum payload capacity, any transport order with loads constraints that exceeds the payload capacity of the loaded vehicle can not be selected. It is recommended to use the vehicle constraints in such cases to select the loaded vehicle for transport order executions. In this way, loaded vehicles can be assigned transport orders to move the load to a different location or drop the load at a specified location.

Orders

Node

The orders array contains the instructions for the transport order to be executed. For each order element, the nodes array should contain only one node element. The nodeId field can be alpha numeric or numeric string, for example Station-1 or 10 can be used for pick location and Assembly-1 or 20 can be used for the drop location. In a later section, the graph which contains nodes or locations the vehicle can reach is discussed. The nodeId for the node object under the nodes array field can be set to any node that is available in the graph.

Action

For each node an action can be specified to be executed by the vehicle. This can be done by adding an action object under the actions array for the node object. The actionType field specifies the type of action to executed and the blockingType field specified whether the action requires the vehicle to stop and execute the action or not. In almost all use cases for transport order actions the blockingType is set to HARD which causes the vehicle to stop and execute the action. For more information regarding supported actions, please refer the action section.

In the above request, a pick and drop action needs to be executed at the specified node or location. The response returns the same structure as the request but with modified content. The currentOrderIndex specifies the index of the current order under the orders array that is being executed by the FMS. For example, if the currentOrderIndex is 0, the FMS will plan for the vehicle to reach the destination with ID 10 and will execute the action with type pick with action parameters for load handling device lhd set to stroke and loadType as BIN.

Updation of Transport Order

A transport order can be updated while the status for it is either QUEUED or PROCESSING. Updating a transport order might be required in some scenarios where the vehicle is actively executing the transport order but additional locations might be needed to be visited by the vehicle based on some process flow logic. There are a few points to note while updating a transport order.

1. Use the latest updated transport order using the get transport order MQTT topic. This topic is discussed in a later section.

2. The transport order to be updated should be retrieved using the transport order ID only. The transport order message data can then be modified and updated using the update MQTT topic that is explained below.

3. Only the orders array field and the status field in the status object can be updated. Updating other fields can lead to undefined behaviours.

4. Appending additional order to the orders array field is acceptable. In the orders array, additional order object with node and actions under it can be appended.

5. Updating current processing order which is indicated by the currentOrderIndex field is strictly prohibited and doing so can introduce undefined behaviours or the vehicle's plan might not update properly.

6. Updating the constraints while the transport order is in the PROCESSING status will have no affect as the vehicle that satisfied the constraint was already selected previously by the FMS.

7. While the external system is still updating the structure of the transport order, the FMS is executing the transport order. The state of the transport order might have changed while the update is being computed. To mitigate this, the external system should compute the update first, get the latest transport order structure, update the structure and execute the update request.

The request and response message structure for updating a transport order is show below. Some fields or objects that was previously discussed is omitted for brevity.

Request:

MQTT Topic: transport_orders/update/request

{
  "updateTransportOrdersRequest": [
    {
      "header": {
        "headerId": 1,
        "transportOrderType": "TRANSPORT",
        "transportOrderId": "TO-0001",
        "tranportOrderInterface": "task_manager_interface_mqtt"
      },
      "status": {
        "startTimestamp": "2024-12-11T11:12:05.983658708Z",
        "updateTimestamp": "2024-12-11T11:12:05.983664365Z",
        "status": "QUEUED",
        "transportOrderDescription": "Creating new TO"
      },
      "constraints": {
        "vehicle": {
          "serialNumber": "AR001",
          "manufacturer": "ANSCER"
        },
        "loads": [
          {
            "type": "BIN",
            "count": 1
          }
        ]
      },
      "orders": [
        {
          "nodes": [
            {
              "nodeId": "10",
              "actions": [
                {
                  "actionType": "pick",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "lhd",
                      "value": "stroke"
                    },
                    {
                      "key": "loadType",
                      "value": "BIN"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "nodes": [
            {
              "nodeId": "20",
              "actions": [
                {
                  "actionType": "drop",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "lhd",
                      "value": "stroke"
                    },
                    {
                      "key": "loadType",
                      "value": "BIN"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "nodes": [
            {
              "nodeId": "30",
              "actions": [
                {
                  "actionType": "waitForTrigger",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "triggerType",
                      "value": "remote"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Response:

MQTT Topic: transport_orders/update/response

{
  "updateTransportOrdersResponse": [
    {
      "transportOrder": {
        "header": {
          "headerId": 1,
          "transportOrderType": "TRANSPORT",
          "transportOrderId": "TO-0001",
          "tranportOrderInterface": "task_manager_interface_mqtt"
        },
        "status": {
          "startTimestamp": "2024-12-15T04:49:58.508133576Z",
          "updateTimestamp": "2024-12-15T04:50:50.514333411Z",
          "status": "QUEUED",
          "currentOrderIndex": 0,
          "transportOrderDescription": "Creating new TO"
        },
        "constraints": {
          "vehicle": {
            "manufacturer": "ANSCER",
            "serialNumber": "AR001"
          },
          "loads": [
            {
              "type": "BIN",
              "count": 1
            }
          ]
        },
        "orders": [
          {
            "nodes": [
              {
                "nodeId": "10",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "pick",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "nodes": [
              {
                "nodeId": "20",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "drop",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
          "nodes": [
            {
              "nodeId": "30",
              "actions": [
                {
                  "actionType": "waitForTrigger",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "triggerType",
                      "value": "remote"
                    }
                  ]
                }
              ]
            }
          ]
        }
        ],
        "properties": {}
      },
      "success": true,
      "message": "Successfully updated transport order"
    }
  ]
}

In update request structure, after the drop action at node with ID 20, another waitForTrigger action was added which is required to be executed at node with ID 30. If the update was successfully executed then the response will publish the same structure with a new update timestamp.

Cancelling a Transport Order

The following structure specifies the cancellation of a transport order. Once this is requested the vehicle that is associated with the transport order will be asked to cancel its order execution immediately. The following is the JSON request and response structure for cancellation. Some fields or objects that was previously discussed are omitted for brevity in the response message structure.

Request:

MQTT Topic: transport_orders/cancel/request

{
  "cancelTransportOrdersRequest": {
    "withIds": ["TO-0001"],
    "withStatuses": ["PROCESSING", "QUEUED"],
    "all": false
  }
}

Response:

MQTT Topic: transport_orders/cancel/response

{
  "cancelTransportOrdersResponse": {
    "transportOrders": [
      {
        "header": {
          "headerId": 1,
          "transportOrderType": "TRANSPORT",
          "transportOrderId": "TO-0001",
          "tranportOrderInterface": "task_manager_interface_mqtt"
        },
        "status": {
          "startTimestamp": "2024-12-15T04:49:58.508536408Z",
          "updateTimestamp": "2024-12-15T04:49:58.508536498Z",
          "status": "CANCELLED",
          "transportOrderDescription": "Creating new TO"
        },
        "constraints": {
          "vehicle": {
            "manufacturer": "ANSCER",
            "serialNumber": "AR001"
          },
          "loads": [
            {
              "type": "BIN",
              "count": 1
            }
          ]
        },
        "orders": [
          {
            "nodes": [
              {
                "nodeId": "10",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "pick",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "nodes": [
              {
                "nodeId": "20",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "drop",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ],
        "properties": {}
      }
    ],
    "success": true,
    "message": "Cancelled transport orders successfully"
  }
}

In the above request for cancelling, an array of transport order IDs in the withIds field or all currently PROCESSING and QUEUED transport orders by specifying it in withStatuses field can be used (Any valid status can be used). The response just contains the transport order structure at the time of cancelling and a message saying whether the cancellation was successful or not. It is important to note that even through the cancellation is communicated to the vehicle, the vehicle might not immediately cease all motion. For example, an action that might be running needs to be completed before the vehicle is ready to accept any new orders.

Normal status changes for QUEUED transport order will be from QUEUED to CANCELLED. For transport order with PROCESSING status, first the status will be set to CANCELLING. After this, an instant action will be sent to the vehicle that was processing the transport order to stop executing the current order. Once the vehicle has successfully stopped and is inactive (To determine whether the vehicle is active or inactive, please refer the vehicle state update event section), the status will be set to CANCELLED. The final cancelled status will only be set if the vehicle has finished the cancel order action successfully.

After the cancel instruction is successful the vehicle will be ready to accept new orders from the master control or FMS.

Getting Transport Orders

The following request and response structure is used to get the transport orders and their statuses from the FMS internal buffer.

Request:

MQTT Topic: transport_orders/get/request

{
  "retrieveTransportOrdersRequest": {
    "withIds": ["TO-0001"],
    "withStatuses": ["QUEUED"],
    "withOrderIds": ["ORD-0001"],
    "all": false
  }
}

Response:

MQTT Topic: transport_orders/get/response

{
  "retrieveTransportOrdersResponse": {
    "transportOrders": [
      {
        "header": {
          "headerId": 1,
          "transportOrderType": "TRANSPORT",
          "transportOrderId": "TO-0001",
          "tranportOrderInterface": "task_manager_interface_mqtt"
        },
        "status": {
          "startTimestamp": "2024-12-15T04:49:58.508536408Z",
          "updateTimestamp": "2024-12-15T04:49:58.508536498Z",
          "status": "QUEUED",
          "transportOrderDescription": "Creating new TO"
        },
        "constraints": {
          "vehicle": {
            "manufacturer": "ANSCER",
            "serialNumber": "AR001"
          },
          "loads": [
            {
              "type": "BIN",
              "count": 1
            }
          ]
        },
        "orders": [
          {
            "nodes": [
              {
                "nodeId": "STATION-1",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "pick",
                    "actionId": "ACT-0001",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "nodes": [
              {
                "nodeId": "STATION-2",
                "nodePosition": {},
                "actions": [
                  {
                    "actionType": "drop",
                    "actionId": "ACT-0002",
                    "blockingType": "HARD",
                    "actionParameters": [
                      {
                        "key": "lhd",
                        "value": "stroke"
                      },
                      {
                        "key": "loadType",
                        "value": "BIN"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ],
        "properties": {}
      }
    ],
    "success": true,
    "message": "Retrieved transport orders successfully"
  }
}

In the above get request for the transport orders, multiple transport order IDs in the withIds field can be provided or with specific statuses like QUEUED, PROCESSING or FINISHED in the field withStatuses. If a transport order needs to be retrieved using the orderId reported in the vehicle's state then it can be passed into the withOrderIds field. If all transport orders needs to be retrieved the all field can be set to true.

Providing transport order IDs, statuses or vehicle order ID together will retrieve all transport orders which satisfies the given query. On the other hand, to retrieve a specific transport order, any one of the fields (withIds, withStatuses or withOrderIds) can be used.

Vehicles

For the transport orders to be executed there should be vehicles that are be available to the FMS. Vehicles in the FMS are identified by using the manufacturer and serial number. This ensures that no name collisions will happen between the vehicles with respect to the manufacturer or serial number. For additional topics and data pertaining to individual vehicles in the system, please refer to the VDA5050 v2.0.0 document.

Pause Vehicles

The following topics can be used to pause vehicles. Vehicle IDs can be given to the request using the vehicleIds fields which contains the manufacturer and serialNumber field (Both of these fields are required to be set). If all vehicles in the system need to be paused, the all field can be set to true.

Request:

MQTT Topic: task_manager/vehicles/pause/request

{
  "pauseVehiclesRequest": {
    "vehicleIds": [
      {
        "manufacturer": "ANSCER",
        "serialNumber": "AR001"
      }
    ],
    "all": false
  }
}

Response:

MQTT Topic: task_manager/vehicles/pause/response

{
  "pauseVehiclesResponse": {
    "vehicleIds": [
      {
        "manufacturer": "ANSCER",
        "serialNumber": "AR001"
      }
    ],
    "success": true,
    "message": "Successfully paused specified vehicles"
  }
}

The response contains the list of vehicles that were paused. Please note that even though the command to pause the vehicle is received, the vehicle will continue to move or completed an action that was previously initiated. This might be because the action cannot be interrupted and is under the vehicle's discretion as to when it should stop all movement and actions. The transport order associated with the vehicle will reflect no changes with the status being set to PROCESSING.

The pause request topic can be used when an emergency situation arises in the plant were all machines and vehicles needs to be paused or stopped for safety reasons.

Resume Vehicle

The following topics can be used to resume vehicles that were previously paused. The fields are similar to the pause but is used to resume vehicles in the system.

Request:

MQTT Topic: task_manager/vehicles/resume/request

{
  "resumeVehiclesRequest": {
    "vehicleIds": [
      {
        "manufacturer": "ANSCER",
        "serialNumber": "AR001"
      }
    ],
    "all": false
  }
}

Response:

MQTT Topic: task_manager/vehicles/resume/response

{
  "resumeVehiclesResponse": {
    "vehicleIds": [
      {
        "manufacturer": "ANSCER",
        "serialNumber": "AR001"
      }
    ],
    "success": true,
    "message": "Successfully resumed specified vehicles"
  }
}

The response contains the list of vehicles that were resumed and has started to execute the orders that was assigned to it.

Instant Actions

Instant actions are sent to the vehicle to be executed instantly. The instant action needs to be specified for a vehicle and will be executed only by that vehicle. The actions provided in the instant actions are not associated with any transport orders. These actions are executed independently. For the header part the manufacturer, serialNumber and version field are mandatory. For the action object in the actions array field, the actionId which uniquely identifies an action needs to be unique and as such UUID can be used for it. The actionType can only be actions that can be executed as instant actions, other action types will be ignored by the vehicle. The blockingType as mentioned before determines whether the vehicles needs to stop and then execute the action or not. The allowed action and blocking types are provided in a table in the actions section.

Request:

MQTT Topic: task_manager/instant_actions_array/request

{
  "sendInstantActionsArrayRequest":[
    {
      "headerId": "0",
      "timestamp": "2025-05-01T12:00:00Z",
      "manufacturer": "ANSCER",
      "serialNumber": "AR001",
      "version": "v2.0.0",
      "actions": [
        {
          "actionId": "ACT-0003",
          "actionType": "remoteConfirmation",
          "blockingType": "HARD",
          "actionParameters": [
            {
              "key": "triggerType",
              "value": "remote"
            }
           ]
        }
      ]
    }
  ] 
}

Response:

MQTT Topic: task_manager/instant_actions_array/response

{
  "sendInstantActionsArrayResponse": {
    "instantActionsArray": [
      {
        "headerId": 0,
        "timestamp": "2025-05-01T12:00:00Z",
        "version": "v2.0.0",
        "manufacturer": "ANSCER",
        "serialNumber": "AR001",
        "actions": [
          {
            "actionType": "remoteConfirmation",
            "actionId": "ACT-0003",
            "actionDescription": "",
            "blockingType": "HARD",
            "actionParameters": [
              {
                "key": "triggerType",
                "value": "remote"
              }
            ]
          }
        ]
      }
    ],
    "success": true,
    "message": "Given instant actions array sent successfully"
  }
}

In the above example, a remote confirmation is send to the vehicle to confirm some operation being executed at the vehicle level. Other instant actions include stateRequest and factsheetRequest.

The vehicle state will reflect the instant action that was sent to it from the FMS. To know the current status of an action in the state, the actionStates array field can be checked. This is discussed in detail in the vehicle state event section later.

For more information on actions please refer the VDA5050 v2.0.0 document.

Actions

Actions can be executed at a specific node or it can be executed as an instant action by the vehicle.

The following actions can be executed only at specific node or location and can be used as part of the orders during the creation of transport orders.

Action Type	Action Parameters with Default Values	Blocking Type	Remarks
waitForTrigger	triggerType: remote or triggerType: user	HARD	Can be used for user as well as remote confirmation
pick	lhd: stroke and loadType: BIN	HARD	For picking a load using a particular load handling device and load type. The lhd and loadType values can vary for vehicles in different applications
drop	lhd: stroke and loadType: BIN	HARD	For dropping a load using a particular load handling device and load type. The lhd and loadType values can vary for vehicles in different applications
startCharging	No parameters	HARD	To command the vehicle to start charging (Automatically done by the FMS)

The following actions can be executed only as an instant actions. Please refer the instant actions section for how to structure the message.

Action Type	Action Parameters with Default Values	Blocking Type	Remarks
remoteConfirmation	triggerType: remote or triggerType: user	HARD	Can be used to confirm a waitForTrigger action being executed at the vehicle
trigger	triggerType: remote or triggerType: user	HARD	Can be used to confirm a waitForTrigger action being executed at the vehicle. This action type is the VDA5050 standardized version. The parameters are optional as this is used to confirm the currently RUNNING waitForTrigger action
stateRequest	No parameters	NONE	For requesting the current state for the vehicle
factsheetRequest	No parameters	NONE	For requesting the current factsheet for the vehicle
stopCharging	No parameters	HARD	To command the vehicle to stop charging (Automatically done by the FMS if automated charging is enabled)

Events

Transport Order Update Events

As the FMS processes the given transport orders to completion, updates on the transport order data are given over a separate topic. These update events can be generated because an order in the orders array was completed and the next order is going to be executed. Another reason could be the status of the transport order changed. For receiving the updates the following topic can be used.

The currentOrderIndex will provide the order in orders array that is being actively executed by the task manager. The currentOrder object constraints the order that is sent to the vehicle for execution. This is according to the VDA5050 order message structure.

MQTT Topic: transport_orders/events/updated

Message:

{
  "transportOrders": [
    {
      "header": {
        "headerId": 1,
        "transportOrderType": "TRANSPORT",
        "transportOrderId": "TO-0001",
        "tranportOrderInterface": "task_manager_interface_mqtt"
      },
      "status": {
        "startTimestamp": "2024-12-15T04:49:58.508536408Z",
        "updateTimestamp": "2024-12-15T04:51:43.508536498Z",
        "status": "PROCESSING",
        "currentOrderIndex": 0,
        "currentOrder": {
          "headerId": 398,
          "timestamp": "2025-06-04T10:43:27.849876950Z",
          "version": "v2.0.0",
          "manufacturer": "ANSCER",
          "serialNumber": "AR001",
          "orderId": "43dd0f67-18ca-484c-bdde-5c8c4a0d302c-39",
          "orderUpdateId": 2,
          "zoneSetId": "",
          "nodes": [
            {
              "nodeId": "7",
              "sequenceId": 1415,
              "nodeDescription": "",
              "released": true,
              "nodePosition": {
                "x": 51.2111,
                "y": 13.7395,
                "theta": 3.141592653589793,
                "allowedDeviationXY": 1,
                "allowedDeviationTheta": 3.141592653589793,
                "mapId": "map",
                "mapDescription": ""
              },
              "actions": []
            },
            {
              "nodeId": "10",
              "sequenceId": 1416,
              "nodeDescription": "",
              "released": true,
              "nodePosition": {
                "x": 51.2111,
                "y": 14.0395,
                "theta": 1.5707963267948963,
                "allowedDeviationXY": 1,
                "allowedDeviationTheta": 3.141592653589793,
                "mapId": "map",
                "mapDescription": ""
              },
              "actions": [
                 {
                  "actionType": "pick",
                  "actionId": "ACT-0001",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "lhd",
                      "value": "stroke"
                    },
                    {
                      "key": "loadType",
                      "value": "BIN"
                    }
                  ]
                }
              ]
            }
          ],
          "edges": [
            {
              "edgeId": "7---10",
              "sequenceId": 1,
              "edgeDescription": "",
              "released": true,
              "startNodeId": "7",
              "endNodeId": "10",
              "actions": []
            }
          ]
        },
        "transportOrderDescription": "Creating new TO"
      },
      "constraints": {
        "vehicle": {
          "manufacturer": "ANSCER",
          "serialNumber": "AR001"
        },
        "loads": [
          {
            "type": "BIN",
            "count": 1
          }
        ]
      },
      "orders": [
        {
          "nodes": [
            {
              "nodeId": "STATION-1",
              "nodePosition": {},
              "actions": [
                {
                  "actionType": "pick",
                  "actionId": "ACT-0001",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "lhd",
                      "value": "stroke"
                    },
                    {
                      "key": "loadType",
                      "value": "BIN"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "nodes": [
            {
              "nodeId": "STATION-2",
              "nodePosition": {},
              "actions": [
                {
                  "actionType": "drop",
                  "actionId": "ACT-0002",
                  "blockingType": "HARD",
                  "actionParameters": [
                    {
                      "key": "lhd",
                      "value": "stroke"
                    },
                    {
                      "key": "loadType",
                      "value": "BIN"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "properties": {}
    }
  ]
}

In the above example for an event topic, the status of the order changed from QUEUED to PROCESSING. Once all the orders in the orders array field is completed the status will be set to SUCCEEDED. If the vehicle reports a FATAL error the status will be set to FAILED from PROCESSING. If the FMS is unable to determine the current transport order being executed by the vehicle based on its state, the status might be set to LOST based on a timeout. All of these possible changes will generate a transport order update event.

Vehicle Update Events

The vehicle update events provides updates for all the vehicles that are registered with the FMS. If the vehicle is connected can be assigned orders by the FMS for transport order execution.

The message contains basic information regarding the vehicle that were provided at the time of registering the vehicle with the FMS. The interface field contains the name of the interface used by the FMS to communicate with the vehicle. This field is just for information and should be ignored. The version field is the protocol being used by the vehicle to communicate with the FMS. The manufacturer and serialNumber together forms a unique ID for the vehicle.

The usageLevel field determines how the FMS treats the vehicle. If the field is set to ACKNOWLEDGED the vehicle will be used to execute transport orders. The following table gives a description of all the usage levels.

Usage Level	Description
ACKNOWLEDGED	The vehicle can be used to execute transport orders and its position will be respected by other vehicles
POSITION_ACKNOWLEDGED	The vehicle's position is respected by other vehicles but is not used for transport order execution
IGNORED	The vehicles's position is not respected by other vehicles and cannot be used for transport order execution. State updates from the vehicle are also discarded

The usage level for vehicle is changed from the FMS only (No direct API control for usage level is provided). The usage level of the vehicle might be changed for a variety of reason. For example, if any of the vehicle is experiencing an issue and manual or human intervention is required, the vehicle can be set to POSITION_ACKNOWLEDGED. This is done so that other vehicles in the FMS can still respect the position of the vehicle for traffic and collision avoidance but the FMS will not sent it any orders during that period. The IGNORED usage level is used if the vehicle is kept aside for maintenance and state update from the vehicle is require to ignored.

The charge object contains the information regarding the battery charge percentage thresholds. The lowBatteryCharge threshold is the minimum charge percentage after which the FMS cannot use the vehicle for executing normal transport orders and will sent the vehicle for charging if automated charging is enabled in the FMS. Once the vehicle's charge has reached the sufficientBatteryCharge percentage, the vehicle can be used to execute normal transport orders again. The goodBatteryCharge percentage is considered as if the battery is fully charged.

It should be noted that, if opportunistic charging is enabled in the FMS, regardless of the charge percentage of the vehicle, it will be sent for charging if free charging locations are available.

Other fields that in the vehicle JSON structure that are not documented here should be ignored.

MQTT Topic: vehicle_array/events/updated

Message:

{
  "vehicles": [
    {
      "interface": "uagv",
      "version": "v2.0.0",
      "manufacturer": "ANSCER",
      "serialNumber": "AR001",
      "usageLevel": "ACKNOWLEDGED",
      "charge": {
        "lowBatteryCharge": 10,
        "sufficientBatteryCharge": 50,
        "goodBatteryCharge": 90,
      }
    },
    {
      "interface": "uagv",
      "version": "v2.0.0",
      "manufacturer": "ANSCER",
      "serialNumber": "AR002",
      "usageLevel": "POSITION_ACKNOWLEDGED",
      "charge": {
        "lowBatteryCharge": 10,
        "sufficientBatteryCharge": 50,
        "goodBatteryCharge": 90,
      }
    },
    {
      "interface": "uagv",
      "version": "v2.0.0",
      "manufacturer": "ANSCER",
      "serialNumber": "AR003",
      "usageLevel": "IGNORED",
      "charge": {
        "lowBatteryCharge": 10,
        "sufficientBatteryCharge": 50,
        "goodBatteryCharge": 90,
      }
    }
  ]
}

Connection Update Events

The connection update from individual vehicles are collected into a single array for ease of data access. This contains information about which all vehicles are connected to the FMS and ONLINE. This uses the same message structure as defined in VDA5050. Below is an example JSON payload for the connection array messages from different vehicles under the array field connectionArray.

The vehicle can identified using the manufacturer and serialNumber in the elements of the connectionArray array field. The connectionState field's value can be used to determine the current connection status. The connection states and the description is provided in the following table.

Connection State	Description
ONLINE	The vehicle is connected to the FMS and available to take orders
OFFLINE	The vehicle is going to disconnect itself from the FMS
CONNECTIONBROKEN	The vehicle has lost connection with the FMS

The connection state between the vehicle and the MQTT broker is set to CONNECTIONBROKEN if the communication is lost to the vehicle by the broker for more than 90 seconds. This is the default timeout. If communication was intermittently established this timeout is reset.

MQTT Topic: vehicle_connection_array/events/updated

Message:

{
  "connectionArray": [
    {
      "headerId": 1,
      "timestamp": "2025-06-04T11:09:55.719358306Z",
      "version": "v2.0.0",
      "manufacturer": "ANSCER",
      "serialNumber": "AR001",
      "connectionState": "ONLINE"
    },
    {
      "headerId": 1,
      "timestamp": "2025-06-04T11:09:55.719358306Z",
      "version": "v2.0.0",
      "manufacturer": "ANSCER",
      "serialNumber": "AR002",
      "connectionState": "OFFLINE"
    },
    {
      "headerId": 1,
      "timestamp": "2025-06-04T11:09:55.719358306Z",
      "version": "v2.0.0",
      "manufacturer": "ANSCER",
      "serialNumber": "AR003",
      "connectionState": "CONNECTIONBROKEN"
    }
  ]
}

State Update Events

The state updates from individual vehicle are collected into one array structure. This can also be utilized to make process flow control decisions based upon current state information coming from the vehicles. This adheres to the VDA5050 state message structure, but each vehicle's updates is appended to an array with field name stateArray. Please not that multiple state updates from the same vehicle can be present in a single message. For brevity some of the fields ignored and on one single message is shown below. The state of a particular vehicle can be identified by using the manufacturer and serialNumber field.

The message structure example given below contains a state update coming from a single vehicle. In this, a actionStates array field contains the action to be executed at node with ID 10. The status of the action is currently WAITING but once the vehicle has reached the node or when the lastNodeId field is 10 the action status field will change from WAITING to RUNNING while executing the pick operation and finally to FINISHED once the pick operation is completed. If for some reason the vehicle's pick action failed, the action status will be set to failed.

In order to check if the vehicle is ready to accept new orders from the FMS there are a few conditions that need to satisfied and are listed below. The following conditions can be used to derive vehicles statuses that might be required in process flow control and execution if required.

1. If the nodeStates and edgeStates array is not empty, then the robot is executing a planned movement.

2. If the actionStates array is not empty and if any of the action state in the array has an actionStatus other than FINISHED or FAILED the robot is executing a planned action.

3. If the operatingMode is set to any other value than AUTOMATIC, the vehicle is not under the control of the FMS and therefore orders cannot be sent by to it.

4. If the loads array field contains any elements then the vehicle is loaded and depending on the vehicle type more loads can be added but in most cases any transport order with a starting pick action cannot be executed. Any transport order than that just contains orders to move to another location or orders containing a drop action can be executed by the vehicle. An example of the load structure and explanation is provided below.

5. If the errors array field is not empty and if any of the error has errorLevel set to FATAL then the vehicle requires manual or human intervention to rectify the issue. But if the errorLevel is set to WARNING then it can be ignored as it is intended for the FMS and is not required to be processed by third party clients in their process flow that is consuming this data. An example of the error structure and explanation is provided below.

6. If the positionInitialized field is set to false, no transport orders can be assigned to that vehicle. The vehicle needs to be localized properly with in the map before the FMS can use it for order execution.

7. If the batteryCharge field in the batteryState object is less than the desired low charge threshold, then no transport orders will be assigned for the vehicle. The low battery threshold can be referred to in the vehicles array topic.

8. If the eStop field in the safetyState object is either set to AUTO_ACK which means the robot will resolve the safety state on it own or MANUAL if an E-Stop button was pressed, then no transport orders can be assigned to the vehicle.

9. If the paused field is set to true, the vehicle will not be considered for transport order assignments and as a consequence no orders will be generated for it unless the vehicle is resumed.

MQTT Topic: vehicle_state_array/events/updated

Message:

{
  "stateArray":[
    {
      "headerId": 233,
      "timestamp": "2025-06-04T11:10:08.419598408Z",
      "version": "v2.0.0",
      "manufacturer": "ANSCER",
      "serialNumber": "AR001",
      "orderId": "86bc7a1f-cf50-460d-8834-c9fdd1036e34-12",
      "orderUpdateId": 13,
      "lastNodeId": "738",
      "lastNodeSequenceId": 149,
      "nodeStates": [
        {
          "nodeId": "741",
          "sequenceId": 150,
          "nodePosition": {
            "x": 47.4451,
            "y": 17.5333,
            "allowedDeviationXY": 1,
            "allowedDeviationTheta": 3.141592653589793,
            "mapId": "map"
          },
          "released": true
        },
        {
          "nodeId": "126",
          "sequenceId": 151,
          "nodePosition": {
            "x": 47.6561,
            "y": 17.5333,
            "allowedDeviationXY": 1,
            "allowedDeviationTheta": 3.141592653589793,
            "mapId": "map"
          },
          "released": true
        },
        {
          "nodeId": "7",
          "sequenceId": 152,
          "nodePosition": {
            "x": 47.856100000000005,
            "y": 17.5333,
            "allowedDeviationXY": 1,
            "allowedDeviationTheta": 3.141592653589793,
            "mapId": "map"
          },
          "released": true
        },
        {
          "nodeId": "10",
          "sequenceId": 153,
          "nodePosition": {
            "x": 47.9561,
            "y": 17.5333,
            "allowedDeviationXY": 1,
            "allowedDeviationTheta": 3.141592653589793,
            "mapId": "map"
          },
          "released": true
        }
      ],
      "edgeStates": [
        {
          "edgeId": "738---741",
          "sequenceId": 6,
          "released": true,
          "trajectory": {}
        },
        {
          "edgeId": "741---126",
          "sequenceId": 7,
          "released": true,
          "trajectory": {}
        },
        {
          "edgeId": "126---2669",
          "sequenceId": 8,
          "released": true,
          "trajectory": {}
        },
        {
          "edgeId": "7---10",
          "sequenceId": 9,
          "released": true,
          "trajectory": {}
        }
      ],
       "actionStates": [
        {
          "actionId": "ACT-0001",
          "actionType": "pick",
          "actionDescription": "Pick up load from station with node ID 10",
          "actionStatus": "WAITING"
        }
      ],
      "agvPosition": {
        "positionInitialized": true,
        "localizationScore": 1,
        "x": 47.1451,
        "y": 17.5333,
        "theta": -1.5708,
        "mapId": "map"
      },
      "velocity": {
        "vx": 1.0,
        "vy": 0,
        "omega": 0.25
      },
      "loads": [],
      "paused": false,
      "driving": true,
      "newBaseRequest": true,
      "batteryState": {
        "batteryCharge": 100,
        "batteryVoltage": 48,
        "batteryHealth": 100,
        "reach": 10000
      },
      "operatingMode": "AUTOMATIC",
      "errors": [],
      "information": [],
      "safetyState": {
        "eStop": "NONE",
        "fieldBreach": false
      }
    }
  ]
}

Order ID

The orderId field is the ID of the current order that the vehicle is executing. For a single transport order, that specifies the vehicle to go to a location and then execute an action, multiple orders will be sent to the vehicle by the FMS in order to make it reach the location and execute the action. The orderId will change as the transport order's currentOrderIndex is shifted to new order in the array of orders.

The orderId can be used to retrieve the corresponding transport order associated with the vehicle. Please refer to the get transport orders sections on how this can be achieved.

Last Node ID

The lastNodeId field specified the current node that the vehicle has traversed. For example, once the last node in the nodeStates array in the above state message which is 10, is reached by the vehicle, the lastNodeId will be set to 10. This can be used to determine whether the vehicle has reached the nodeId specified in the transport order ID.

It should be noted that the last node ID might contain other node IDs that were planned by FMS which are not in the transport order.

Node states

The nodeStates array contains the set of nodes that are yet to be traversed by the vehicle. Only when the vehicle is close to the nodeId that was specified in the transport order will the nodeStates array contain it. If there are any actions to be executed at the nodeId it will appended to the actionStates and the actionStatus will be set to WAITING.

Edge states

The edgeStates array contains the set of edges that are yet to be traversed by the vehicle. It is not recommended to not use the elements in the array to implement an logic associated with the process flow. The edgeStates field can be used to check whether it is empty or not as mentioned above, on whether a vehicle is ready to accept orders from the FMS.

Action States

The following is the JSON structure for the actionStates array in the state message.

"actionStates": [
  {
    "actionId": "ACT-0001",
    "actionType": "pick",
    "actionDescription": "Pick up load from station with node ID 10",
    "actionStatus": "WAITING"
  }
],

For identifying each action there will be an actionId, the value for this will be an UUID. The actionType specifies the type of action. This will be the same as the actionType set for an action specified for a node in the transport order. The actionStatus will initially be WAITING as vehicle might not have reached the node where the actions are supposed to be executed. Then if there are some initialization steps for the action before it could be executed then it would change to INITIALIZING. If the action is being executed by the robot then the status will be RUNNING and finally it will be set to FINISHED once the vehicle has completed the action successfully.

The actionStatus can be set to be PAUSED if the vehicle is paused, but some actions cannot be paused by the vehicle. If the action execution failed the status will be set to FAILED. When a cancel order instant action is received all RUNNING actions are set to FAILED if possible by the vehicle.

In the case of multiple actions for a node. The actions will be executed sequentially if the blockingType for the action is set to HARD and the status of the actions will change as explained above. Some actions might be executed instantly as the blockingType is set to NONE as such the status of the action can be instantly set to FINISHED.

The following table gives a description of the different action statuses

Action Status	Description
WAITING	The action is waiting to be executed as the vehicle might not have reached the desired node for action execution
INITIALIZING	The action is setting itself for execution
RUNNING	The action is being actively executed by the vehicle
FINISHED	The action executed was completed successfully by the vehicle
FAILED	The action execution failed. A FATAL error might be generated depending on the action
PAUSED	The action execution is currently paused

AGV Position

The following JSON object is for the vehicle's position with respect to the map

"agvPosition": {
  "positionInitialized": true,
  "localizationScore": 1,
  "x": 47.1451,
  "y": 17.5333,
  "theta": -1.5708,
  "mapId": "map"
},

The positionInitialized field will be true if the vehicle is localized. If not, no transport orders will be assigned to the vehicle. The localizationScore field can be ignored and should not be used to implement any process flow logic. The x and y position of the vehicle are in meters and the theta is the yaw of the robot in radians. The mapId field can be used to determine on which map the vehicle is operating on and is only intended for the FMS and should be ignored in any process flow logic.

Velocity

The following JSON object is for the velocity of the vehicle in linear and angular components.

"velocity": {
  "vx": 1.0,
  "vy": 0,
  "omega": 0.25
},

The vx and vy are in meters per second while the omega is in radians per second. For a differential drive vehicle only the linear vx and angualar omega will be available. On the other hand for an omnidirectional vehicle all the fields will have valid values. The velocity object should only be used for visualization and should not be used in process flow logic. Some vehicles are not guaranteed to have this field published.

Battery State

The following JSON object is for the battery state of the vehicle.

"batteryState": {
  "batteryCharge": 100,
  "batteryVoltage": 48,
  "batteryHealth": 100,
  "reach": 10000
},

In the above structure only the batteryCharge can be used for any process flow decision making if required. In most cases vehicle battery charge management is handled by the FMS. The rest of the fields should be ignored.

Operating Mode

The operatingMode field determines whether orders can be assigned to the vehicle or not. If it is set to AUTOMATIC the vehicle can be controlled by the FMS.

Operating Mode	Desciption
AUTOMATIC	The vehicle can be controlled by the FMS
MANUAL	The vehicle cannot be controlled by the FMS. Can only be manually controlled
SERVICE	The vehicle is being serviced and cannot be operated manually or by the FMS

Loads

The following is the JSON structure for the loads array in the state message.

"loads": [
  {
    "loadId": "load-1",
    "loadType": "BIN",
    "loadPosition": "stroke",
    "weight": 100
  }
],

Some of the fields in the load structure is omitted for brevity sake. Each load is identified by the loadId field which is usually UUID generated by the vehicle. The loadType that was specified during the pick action under the actionParameters is reflected here. The loadPosition field can be considered another alias for the load handling device or lhd field used in the actionParameters. The loadType and loadPosition value will change according to the application.

The weight field specifies the approximate expected load weight. If the load weight exceeds the max load carrying capacity of the vehicle, the transport order will not be assigned to it. The FMS will only assign the transport order to the vehicle which can handle the expected weight. The unit of weight is in kilograms.

If the vehicle is loaded, the transport order containing actionType with pick for the first action under node will not be assigned to the vehicle. Transport orders with orders specifying the vehicle to move to a node or an action with actionType as drop in the first node can be assigned to the vehicle.

It should be noted that transport orders designated to be executed by loaded vehicles should be constrained to that vehicles using the vehicles manufacturers and serial number in the vehicles. This can be done by setting vehicle object under the constraints object of the transport order.

Driving

The driving field can be used to determine whether the vehicle is moving either by executing a planned motion or action. It can also be because the vehicle is being manually moved. If the vehicle is moving this field will be set to true.

Paused

The paused field will be set to true if the vehicle was paused using the MQTT topic to pause vehicles.

Errors

The following is the JSON structure for the errors array in the state message.

"errors": [
  {
    "errorType": "dockingFailure",
    "errorDescription": "Mission failure as docking has failed",
    "errorLevel": "FATAL"
  }
],

Some of the fields in the error structure is ommitted for brevity sake. Each error has an errorType field is used to identify the type of error. The errorDescription field provides a human understandable description of the error.

The errorLevel field provides the severity of the error. If it is set to FATAL manual or human intervention is required and robot will not be given any orders from the FMS until the error is cleared. If a transport order is associated to a vehicle that is reporting a FATAL error level transport order status will be set to FAILED. On the other hand, if it is set to WARNING then it can be ignored by third party interfaces that is using these APIs as it is intended for the FMS to do some corrective action.

Multiple errors can be reported by the vehicle and will be reflected in the errors array field. In such cases, each error's errorLevel should be check to see if it FATAL or WARNING. If any of the error is FATAL the assigned transport order will be set to failed.

It should be noted that it is under the vehicle's discretion on what is considered a FATAL or WARNING level error. If there are issues with the vehicle's software, hardware or network, it will decide how it should be treated.

Safety State

The following is the JSON structure for the safetyState object in the state message.

"safetyState": {
  "eStop": "NONE",
  "fieldBreach": false
}

The eStop field can be used to determine whether an emergency stop conditions are active for the vehicle. If there are no emergency stop conditions it will be NONE. If someone manually presses an emergency stop button in the vehicle then it will be set to MANUAL. If an emergency stop condition that is self resolvable by the vehicle is active, then it will set to AUTO_ACK meaning auto acknowledgable.

The fieldBreach field will be set to true if any of the vehicle's safety field is breached by an obstacle.

It should be noted that if the eStop field is set to any other value than NONE, no transport orders will be assigned to the vehicle.

Information

The information array should only be used visualization purposes and no logic to drive a process flow should be based on the data coming through this field. Also the structure of the data coming through this field will vary according to the vehicle. Therefore, the structure will not be discussed and should be ignored.

Configurations

Configuration topics contains data about how the FMS is configured. The configuration can included data about the nodes that the vehicles can reach as well as the paths or edges that connects the nodes together.

Graph

The graph contains data about the nodes that the vehicle can reach and the edges that connects it together. It can be used to identify the nodes that the vehicle can reach and also can be used to estimate the distance between nodes if required. The implementor of the process flow logic is expected to use the graph data accordingly.

The graph JSON structure is shown below. The metadata field contains information about the graph that can be utilized if required but in most cases can be ignored. The main part of the structure is the nodes and edges array.

MQTT Topic: task_manager/configuration/graph

{
  "metadata": {
    "graphName": "graph_demo",
    "graphType": "DIRECTED",
    "numberOfNodes": 4,
    "numberOfEdges": 7
  },
  "nodes": [
    {
      "id": "1",
      "alias": "",
      "type": "NORMAL",
      "ignoreOrientation": false,
      "pose": {
        "x": -4.00167,
        "y": 0.0,
        "theta": 0.0
      }
    },
    {
      "id": "2",
      "alias": "",
      "type": "NORMAL",
      "ignoreOrientation": false,
      "pose": {
        "x": 1.00042,
        "y": 4.01317,
        "theta": 0.0
      }
    },
    {
      "id": "3",
      "alias": "",
      "type": "NORMAL",
      "ignoreOrientation": false,
      "pose": {
        "x": 1.00042,
        "y": -4.01317,
        "theta": -0.745
      }
    },
    {
      "id": "4",
      "alias": "",
      "type": "NORMAL",
      "ignoreOrientation": true,
      "pose": {
        "x": 4.00167,
        "y": -0.0229979,
        "theta": -3.141
      }
    }
  ],
  "edges": [
    {
      "id": "4---1",
      "alias": "",
      "type": "STRAIGHT_LINE",
      "directionType": "FORWARD",
      "creationType": "CREATED",
      "sourceNode": "4",
      "destinationNode": "1",
      "length": 8.003369,
      "costFactor": 1,
      "controlPoints": []
    },
    {
      "id": "1---2",
      "alias": "",
      "type": "STRAIGHT_LINE",
      "directionType": "FORWARD",
      "creationType": "CREATED",
      "sourceNode": "1",
      "destinationNode": "2",
      "length": 6.412983,
      "costFactor": 1,
      "controlPoints": []
    },
    {
      "id": "4---3",
      "alias": "",
      "type": "CUBIC_BEZIER",
      "directionType": "BIDIRECTIONAL",
      "creationType": "GENERATED",
      "sourceNode": "4",
      "destinationNode": "3",
      "length": 5.767058,
      "costFactor": 1,
      "controlPoints": [
        {
          "x": 4.18628,
          "y": -1.35227
        },
        {
          "x": 3.56902,
          "y": -4.27945
        }
      ]
    },
    {
      "id": "4---2",
      "alias": "",
      "type": "STRAIGHT_LINE",
      "directionType": "BIDIRECTIONAL",
      "creationType": "GENERATED",
      "sourceNode": "4",
      "destinationNode": "2",
      "length": 5.029724,
      "costFactor": 1,
      "controlPoints": []
    },
    {
      "id": "3---4",
      "alias": "",
      "type": "CUBIC_BEZIER",
      "directionType": "BIDIRECTIONAL",
      "creationType": "CREATED",
      "sourceNode": "3",
      "destinationNode": "4",
      "length": 5.767058,
      "costFactor": 1,
      "controlPoints": [
        {
          "x": 3.56902,
          "y": -4.27945
        },
        {
          "x": 4.18628,
          "y": -1.35227
        }
      ]
    },
    {
      "id": "1---3",
      "alias": "",
      "type": "CUBIC_BEZIER",
      "directionType": "FORWARD",
      "creationType": "CREATED",
      "sourceNode": "1",
      "destinationNode": "3",
      "length": 7.138039,
      "costFactor": 1,
      "controlPoints": [
        {
          "x": -4.27153,
          "y": -2.17464
        },
        {
          "x": -1.2363,
          "y": -4.21205
        }
      ]
    },
    {
      "id": "2---4",
      "alias": "",
      "type": "STRAIGHT_LINE",
      "directionType": "BIDIRECTIONAL",
      "creationType": "CREATED",
      "sourceNode": "2",
      "destinationNode": "4",
      "length": 5.029724,
      "costFactor": 1,
      "controlPoints": []
    }
  ]
}

Node Data

Each node in the nodes array is identified by the id field and it will always be an integer string. This is passed to the nodeId field when creating a transport order for the vehicle to reach a node and then maybe some action to be executed at the node if actions are provided for the node as well. Please refer to the transport orders sections for any clarifications. The alias field can contain a human understandable name for node. The pose of the node x and y will always be in meters and the theta field should only be considered if the ignoreOrientation field is set to false. The type field specifies the type of the node which can ignored. Any other undocumented fields should be ignored.

Edge Data

Each edge in the edges array is also identified by an id field. The edge can can be considered as a path connecting the sourceNode to a destinationNode. If the edge's directionType is set to BIDIRECTIONAL, then there is a connection from the destinationNode to the sourceNode which will also be present in the edges array. On the other hand if it set to FORWARD, then there is only a connection from the sourceNode to the destintationNode. The length field contains the distance between the source and destination node in meters.

The costFactor field is used to determine how strongly an edge is preferred, for example, the value of 1 means the edge will considered according to the length. But if the cost factor is set to 0.5, the edge will be evaluated more favourably as the cost to traverse the edge is now lower. So the cost to traverse an edges is the length multiplied by the cost factor. This will eventually cause the vehicle to take the edge that has the lesser cost. In most applications the cost factor for all the edges will be 1 and is not recommended to be used.

The edge type field specifies whether the edges is a straight line or constructed using a Bezier curve and can be ignored. Any other undocumented fields should also be ignored.

Disclaimer

The above MQTT topics with its request and response JSON structure are subject to change and does not guarantee compatibility between releases of the API. Also for brevity sake some of the fields are ignored as they are reserved for future use cases or are not required by the client to be set or read. ANSCER Robotics reserves the right to modify these API without prior notice or compatibility gaurantees between version releases.