Exacta Maestro™ StandardAgent Integration

Version: 0.0.2
Date: 2024/04/15

Overview

The Exacta Maestro™ StandardAgent integration relies on a handful of constants and conventions when interacting with agents over the StandardAgent API. By default, all communication flows in a single direction, where Exacta Maestro™ is the client to the server exposing the StandardAgent API. That server could be per vehicle, or there could be a single server managing multiple vehicles.

Polling for Agent Data

The main source of communication from Exacta Maestro™ to the server is polling for agent data over the get/agents endpoint. The Exacta Maestro™ StandardAgent agent service is responsible for polling for the latest agent data and reporting it to Exacta Maestro™ AgentHub. The agent data shown in the WebHmi, as well as used for all internal processing, is the data stored in AgentHub.

The delay between the requests is configurable, with a default value of 5 seconds.

AgentStatus Constants

Name	Value	Description
Unknown	0	The agent status is not known
Idle	1	The agent is idle and eligible for new work
Running	2	The agent is currently assigned to active work
Faulted	3	The agent is in an unhealthy state
DisabledByAgent	4	The agent requested a pause on tasks being dispatched to it

Task Execution

All standard task execution communication between Exacta Maestro™ and the agent is handled by Exacta Maestro™ invoking the endpoints NewTask, StartTaskAction, and GetTasks. Technically these endpoints may be on an individual agent or on a server that manages multiple agents, but for simplicity this document refers to the entity exposing the endpoint as the "agent". Exacta Maestro™ also supports force ending tasks, which invokes the StopTask endpoint on the agent.

When Exacta Maestro™ first dispatches a task to an agent, it invokes the NewTask endpoint as well as the StartTask endpoint. During NewTask processing, the agent should ensure that the task payload is valid and can be executed by the specified agent. When the agent receives a StartTaskAction command it should return success as soon as the agent begins executing the task actions. From there, Exacta Maestro™ monitors the task execution through the GetTasks endpoint, updating internal state based on the action index and task status.

In order for Exacta Maestro™ to detect that a task has ended, the agent must be able to return the details of a task after it has ended. The internal emulator caches the 3 latest tasks per agent, but that level of data retention is not required. Since Exacta Maestro™ only dispatches a single task at a time per agent, it is safe to assume the ended task was processed as soon as the next task is received.

TaskStatus Constants

Name	Value	Description
New	0	Default value for uninitialized agents
Assigned	100	The task was recently assigned to the agent, but is not being executed yet
Running	200	The task is actively being executed by the agent
Paused	300	The task execution is currently paused
Completed	400	The task has successfully completed execution
Cancelled	500	The task was cancelled before execution could complete
Faulted	600	The task failed to execute

Task Execution without Traffic Control

When the AgentType is configured within Exacta Maestro™ to NOT support TrafficControl, no MOVE actions are sent. Instead, the tasks only contain PICK and PLACE actions. That setting also prevents Exacta Maestro™ from sending map data to the agents.

Piecewise Task Execution

When the AgentType is configured within Exacta Maestro™ to support TrafficControl, MOVE actions are included. For TransferTask based movements, Exacta Maestro™ only sends a subset of actions in each StartTaskAction command based on the average velocity configured for the AgentType. This breakdown of MOVE actions allows Exacta Maestro™ to manage facility traffic by reserving a subset of the route at a time, moving agents as far as possible while waiting for future nodes to become available.

[NOTE] The action plan is only broken up into pieces when TrafficControl is enabled on the AgentType and the task derives from the TransferTask type. Missions will always be dispatched in two messages: a single NewTask and a near-identical single StartTaskActions

Piecewise Task Execution

Force Ending Tasks

Exacta Maestro™ supports users manually cancelling, completing, or faulting a task. When a user force completes or force faults a task, Exacta Maestro™ internally ends the task accordingly and then calls StopTask on the agent. For cancellation however, Exacta Maestro™ does NOT internally end the task. Instead, it only sends the StopTask command to the agent. From there the agent must cancel task execution itself before Exacta Maestro™ can detect the ended task through the normal GetTask processing.

Task Action Types

When Exacta Maestro™ dispatches a task to the agent, the task is broken it down into one or more TaskActions for the agent to execute. Without traffic control enabled, the action array will just contain the pick and place actions associated with the container transfer, as well as the final end action. When traffic control is enabled, the action array will contain one or more move actions to direct the agent to the container transfer locations. For some specific agent types, the multi-transfer start and stop actions are used to instruct the agent to concurrently execute the specified container transfers.

Move Action

Keyword: MOVE
Description: Instructs the agent to travel to the specified node. Notably, the MOVE action no longer contains multiple nodes, but instead only moves the agent a single node at a time. The first node specified should share an edge with the agent's current location, and each subsequent move should share an edge with the previous.
Argument Structure:

Keyword Data Type Description

waypoints string The id of the node to traverse to

Keyword	Data Type	Description
waypoints	`string`	The id of the node to traverse to

Example:

{
  "arguments": {
    "waypoints": "NodeB"
  },
  "name": "MOVE"
},
{
  "arguments": {
    "waypoints": "NodeC"
  },
  "name": "MOVE"
},
{
  "arguments": {
    "waypoints": "NodeD"
  },
  "name": "MOVE"
}

Pick and Place Actions

Keyword: PICK or PLACE
Description: Instructs the agent to pickup a container from an inventory location, or to place a container at an inventory location.

Argument Structure:

Keyword	Data Type	Meaning
locationId	`string`	The id of the inventory location to pick from or place to, according to the agent (`MAESTRO_STANDARDAGENT_LOCATION` alias)
maestroLocationName	`string`	The name of the inventory location to pick from or place to, according to Maestro (`MAESTRO_INVENTORY_LOCATION_NAME` alias)
maestroNodeId	`string`	The Map nodeId of the agent when accessing the inventory location (Map regex based config)
containerId	`string`	The id of the inventory container to pickup or place
payloadPositionId	`string`	Optional. The id of the position on the agent to pick to or place from. Used for agents that can carry more than 1 container at a time.

Example:

{
  "arguments": {
    "containerId": "Container 1",
    "locationId": "LA1R",
    "maestroLocationName": "maestro:LocationA1/R",
    "maestroNodeId": "LocationA1",
    "payloadPositionId": "1",
  },
  "name": "PICK"
}

Multi Transfer Action

Keyword: MultiTransferStart and MultiTransferStop
Description: Instructs the agent to concurrently execute all pick and place actions between the start and stop events. Used for agents capable of picking and dropping at the same time, and possibly even picking and dropping more than 1 container at the same time.
Argument Structure:

Keyword Data Type Meaning

NA

Keyword	Data Type	Meaning
NA

Example:

{
  "arguments": {
    "waypoints": "NodeB"
  },
  "name": "MOVE"
},
{
  "arguments": {
    "waypoints": "NodeA"
  },
  "name": "MOVE"
},
{
  "arguments": {},
  "name": "MultiTransferStart"
},
{
  "arguments": {
    "containerId": "Container 1",
    "locationId": "InboundA"
  },
  "name": "PICK"
},
{
  "arguments": {
    "containerId": "Container 2",
    "locationId": "InboundA"
  },
  "name": "PICK"
},
{
  "arguments": {
    "containerId": "Container 0",
    "locationId": "OutboundA",
  },
  "name": "PLACE"
},
{
  "arguments": {},
  "name": "MultiTransferStop"
},
{
  "arguments": {
    "waypoints": "NodeB"
  },
  "name": "MOVE"
},
{
  "arguments": {
    "waypoints": "NodeC"
  },
  "name": "MOVE"
},
{
  "arguments": {
    "containerId": "Container 1",
    "locationId": "LocationC",
  },
  "name": "PLACE"
},
{
  "arguments": {
    "waypoints": "NodeD"
  },
  "name": "MOVE"
},
{
  "arguments": {
    "containerId": "Container 2",
    "locationId": "LocationD",
  },
  "name": "PLACE"
},
{
  "arguments": {},
  "name": "END"
}

Scan Action

Keyword: SCAN
Description: Instructs the agent to scan a container at an inventory location.

Argument Structure:

Keyword	Data Type	Meaning
locationId	`string`	Optional. The id of the inventory location to scan, according to the agent (`MAESTRO_STANDARDAGENT_LOCATION` alias)
maestroLocationName	`string`	Optional. The name of the inventory location to scan, according to Maestro (`MAESTRO_INVENTORY_LOCATION_NAME` alias)
maestroNodeId	`string`	Optional. The Map nodeId of the agent when accessing the scan location (Map aliasing based config)
scannerPositionId	`string`	Optional. The id of the position on the agent to scan from. Used for agents that can scan more than 1 container at a time.
containerId	`string`	Optional. The id of the container expected to be scanned
expectedScan	`string`	Optional. The value expected to be at the scanner

Example:

{
  "arguments": {
    "locationId": "LA1R",
    "maestroLocationName": "maestro:LocationA1/R",
    "maestroNodeId": "LocationA1",
    "scannerPositionId": "1",
    "containerId": "Container 123",
    "expectedScan": "123",
  },
  "name": "SCAN"
}

End Action

Keyword: END
Description: Notifies the agent that the task does not contain any more task actions, and may be completed.
Argument Structure: NA
Example
```
{
  "arguments": {},
  "name": "END"
}
```