VDA5050 Core v3.0 (NexOS Robotics) 2.0.0+bot.0 documentation

NexOS Robotics 對 VDA5050 v3.0（2024 年發表，main 分支版本）的核心 MQTT 通訊規格。

與 v2.0（asyncapi-core.yaml）雙版本並行：v2 機器人沿用 /uagv/v2/ topic 樹，v3 機器人改走 /vda5050/v3/ topic 樹。Backend（雙 prefix 訂閱 + per-robot 版本鎖定）與 IoT Gateway（雙 Listener

version-pinned Responder）皆已支援雙軌——細節見 docs/vda5050/v3-upgrade-strategy.html。

目前狀態（Phase 4 完成）：v3 leaf schema（common + enums）已由 bot codegen 從 packages/shared-types/src/vda5050.ts 的 Vda5050V3* 介面產出於 schemas/v3/， v3 message wrapper（order / instant-actions / state / connection / visualization / factsheet）由人類維護於 schemas/v3/messages/，組合 v3 common 與 enums 的 $ref。 Example payload 暫沿用 v2 examples（向後相容；待 v3 範例補完後切換）。

與 v2.0 的關鍵差異（彙整）

Topic 前綴：/uagv/v2/{mfr}/{sn}/{channel} → /vda5050/v3/{mfr}/{sn}/{channel}
Header 版本字串："version": "2.0.0" → "version": "3.0.0"
AGV 重命名 → MobileRobot：agvPosition → mobileRobotPosition、agvActionScopes → mobileRobotActionScopes 等（state 訊息變動最多）
BatteryState → PowerSupply：欄位重組以支援多種能源源類型
ConnectionState 列舉：CONNECTIONBROKEN → CONNECTION_BROKEN，新增 HIBERNATING
OperatingMode 列舉：新增 STARTUP / INTERVENED；TEACHIN 改為 TEACH_IN
BlockingType 列舉：新增 SINGLE（但 instantAction 強制只能用 NONE）
ActionStatus 列舉：新增 RETRIABLE
allowedDeviationXY：v2 的數字半徑改為 v3 的橢圓（thetaX / thetaY）。 Stage 3 task-order task-order.service.ts 已依 robot capability 在派工層動態切換寫法。
新增標準 instantAction：clearInstantActions、clearAllErrors（共 8 種標準動作）

詳細對照表見 docs/vda5050/v3-upgrade-strategy.html §3。

2.0.0+bot.0 — 2026-06-11 (human:phase-4-schema)

拆分 v3 common / enums leaf schema 到 schemas/v3/（29 份，由 bot codegen 產出）
新增 6 份 v3 message wrapper（schemas/v3/messages/）： order / instant-actions / state / connection / visualization / factsheet
所有 v3 message $ref 切換到 v3 schema；example payload 暫沿用 v2

2.0.0+v3-draft — 2026-06-11 (human:phase-4-init)

建立 v3.0 雙版本並行 AsyncAPI spec 草案
6 個 channel 路徑全面切換到 /vda5050/v3/ 前綴
Message payload schema 暫沿用 v2（向後相容）；完整 v3 schema 拆分留待後續 bot codegen 升級

Operations

SEND /vda5050/v3/{manufacturer}/{serialNumber}/order

Master Control 下達任務給 Mobile Robot（v3 — version 欄位需為 "3.0.0"）

Master Control 發送 Order 給 Mobile Robot（v3）

Operation IDsendOrder

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Order

application/json

Message IDOrder

object allOf

Master Control → AGV 的任務訊息（VDA5050 v3.0）。 v3 變更：新增 orderDescription 頂層欄位；nodes/edges 使用 v3 common 結構。

Examples

#1 Example - delivery

送餐任務（payload `version` 應填 `"3.0.0"`）

{
  "headerId": 1712995200000,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "orderId": "task_0f3a8b9c-0000-0000-0000-000000000001",
  "orderUpdateId": 0,
  "taskType": "delivery",
  "nodes": [
    {
      "nodeId": "node_origin_task_0f3a8b9c",
      "sequenceId": 0,
      "released": true,
      "nodePosition": {
        "x": 12.345,
        "y": 6.789,
        "theta": 0,
        "mapId": "map-lobby-v3",
        "allowedDeviationXY": 0.3,
        "allowedDeviationTheta": 0.1
      },
      "actions": []
    },
    {
      "nodeId": "node_target_task_0f3a8b9c",
      "sequenceId": 2,
      "released": true,
      "nodePosition": {
        "x": 20,
        "y": 8.5,
        "mapId": "map-lobby-v3"
      },
      "actions": [
        {
          "actionId": "action_task_0f3a8b9c_drop",
          "actionType": "drop",
          "blockingType": "HARD",
          "actionParameters": []
        }
      ]
    }
  ],
  "edges": [
    {
      "edgeId": "edge_task_0f3a8b9c_0",
      "sequenceId": 1,
      "released": true,
      "startNodeId": "node_origin_task_0f3a8b9c",
      "endNodeId": "node_target_task_0f3a8b9c",
      "actions": []
    }
  ]
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/order

Master Control 下達任務給 Mobile Robot（v3 — version 欄位需為 "3.0.0"）

Mobile Robot 接收 Order（v3）

Operation IDreceiveOrder

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Order

application/json

Message IDOrder

object allOf

Master Control → AGV 的任務訊息（VDA5050 v3.0）。 v3 變更：新增 orderDescription 頂層欄位；nodes/edges 使用 v3 common 結構。

Examples

#1 Example - delivery

送餐任務（payload `version` 應填 `"3.0.0"`）

{
  "headerId": 1712995200000,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "orderId": "task_0f3a8b9c-0000-0000-0000-000000000001",
  "orderUpdateId": 0,
  "taskType": "delivery",
  "nodes": [
    {
      "nodeId": "node_origin_task_0f3a8b9c",
      "sequenceId": 0,
      "released": true,
      "nodePosition": {
        "x": 12.345,
        "y": 6.789,
        "theta": 0,
        "mapId": "map-lobby-v3",
        "allowedDeviationXY": 0.3,
        "allowedDeviationTheta": 0.1
      },
      "actions": []
    },
    {
      "nodeId": "node_target_task_0f3a8b9c",
      "sequenceId": 2,
      "released": true,
      "nodePosition": {
        "x": 20,
        "y": 8.5,
        "mapId": "map-lobby-v3"
      },
      "actions": [
        {
          "actionId": "action_task_0f3a8b9c_drop",
          "actionType": "drop",
          "blockingType": "HARD",
          "actionParameters": []
        }
      ]
    }
  ],
  "edges": [
    {
      "edgeId": "edge_task_0f3a8b9c_0",
      "sequenceId": 1,
      "released": true,
      "startNodeId": "node_origin_task_0f3a8b9c",
      "endNodeId": "node_target_task_0f3a8b9c",
      "actions": []
    }
  ]
}

SEND /vda5050/v3/{manufacturer}/{serialNumber}/instantActions

雙向 channel：Master → Mobile Robot 下達即時動作；Mobile Robot / Dispatcher → Master 回應。

v3 標準 instantAction 共 8 種：cancelOrder startPause stopPause stateRequest factsheetRequest initPosition 加上 v3 新增的 clearInstantActions clearAllErrors。

專案自訂 instantAction（補足 spec 未涵蓋的場域維運場景，blockingType 統一 NONE）：

retry：AMR 回報 error（NO_ROUTE_TO_TARGET / AISLE_BLOCKED 等）後，中控指示重試。參數：orderId errorType targetNodeId? targetEdgeId? retryMode（same_route / replan / clear_costmap_then_retry）
skipRetry：取消正在進行中的重試流程。參數：orderId errorType? targetNodeId? targetEdgeId? reason
skipNode：跳過目前 node 前進到下一個 node。參數：orderId currentNodeId currentNodeSequenceId nextNodeId nextNodeSequenceId reason

blockingType 在 instantAction 上強制只能用 NONE。

Master Control 發送 InstantActions（v3）

Operation IDsendInstantActions

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 InstantActions

application/json

Message IDInstantActions

object allOf

雙向 instant actions 訊息（VDA5050 v3.0）。 v3 變更：欄位從 instantActions 改名為 actions；blockingType 限定為 NONE。

Examples

#1 Example - cancel

取消訂單

{
  "headerId": 1712995202000,
  "timestamp": "2026-04-13T18:00:02.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "instantActions": [
    {
      "actionId": "cancel_task_0f3a8b9c_1712995202000",
      "actionType": "cancelOrder",
      "blockingType": "HARD",
      "actionParameters": []
    }
  ]
}

#2 Example - initPosition

初始化位置

{
  "headerId": 1712995203000,
  "timestamp": "2026-04-13T18:00:03.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "instantActions": [
    {
      "actionId": "initPos_1712995203000",
      "actionType": "initPosition",
      "blockingType": "HARD",
      "actionParameters": [
        {
          "key": "x",
          "value": 12
        },
        {
          "key": "y",
          "value": 7.5
        },
        {
          "key": "theta",
          "value": 1.5708
        },
        {
          "key": "mapId",
          "value": "map-lobby-v3"
        }
      ]
    }
  ]
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/instantActions

雙向 channel：Master → Mobile Robot 下達即時動作；Mobile Robot / Dispatcher → Master 回應。

v3 標準 instantAction 共 8 種：cancelOrder startPause stopPause stateRequest factsheetRequest initPosition 加上 v3 新增的 clearInstantActions clearAllErrors。

專案自訂 instantAction（補足 spec 未涵蓋的場域維運場景，blockingType 統一 NONE）：

retry：AMR 回報 error（NO_ROUTE_TO_TARGET / AISLE_BLOCKED 等）後，中控指示重試。參數：orderId errorType targetNodeId? targetEdgeId? retryMode（same_route / replan / clear_costmap_then_retry）
skipRetry：取消正在進行中的重試流程。參數：orderId errorType? targetNodeId? targetEdgeId? reason
skipNode：跳過目前 node 前進到下一個 node。參數：orderId currentNodeId currentNodeSequenceId nextNodeId nextNodeSequenceId reason

blockingType 在 instantAction 上強制只能用 NONE。

Mobile Robot 接收 InstantActions（v3）

Operation IDreceiveInstantActions

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 InstantActions

application/json

Message IDInstantActions

object allOf

雙向 instant actions 訊息（VDA5050 v3.0）。 v3 變更：欄位從 instantActions 改名為 actions；blockingType 限定為 NONE。

Examples

#1 Example - cancel

取消訂單

{
  "headerId": 1712995202000,
  "timestamp": "2026-04-13T18:00:02.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "instantActions": [
    {
      "actionId": "cancel_task_0f3a8b9c_1712995202000",
      "actionType": "cancelOrder",
      "blockingType": "HARD",
      "actionParameters": []
    }
  ]
}

#2 Example - initPosition

初始化位置

{
  "headerId": 1712995203000,
  "timestamp": "2026-04-13T18:00:03.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "instantActions": [
    {
      "actionId": "initPos_1712995203000",
      "actionType": "initPosition",
      "blockingType": "HARD",
      "actionParameters": [
        {
          "key": "x",
          "value": 12
        },
        {
          "key": "y",
          "value": 7.5
        },
        {
          "key": "theta",
          "value": 1.5708
        },
        {
          "key": "mapId",
          "value": "map-lobby-v3"
        }
      ]
    }
  ]
}

SEND /vda5050/v3/{manufacturer}/{serialNumber}/state

Mobile Robot → Master 狀態回報（1–10 Hz）。v3 將 agvPosition 改為 mobileRobotPosition、 batteryState 改為 powerSupply，並新增 instantActionStates / maps / zoneSets / plannedPath / intermediatePath 等欄位。payload 採用 schemas/v3/messages/state.yaml。

Mobile Robot 發布狀態（v3）

Operation IDpublishState

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 State

application/json

Message IDState

object allOf

AGV → Master 狀態訊息（VDA5050 v3.0）。 v3 變更：agvPosition→mobileRobotPosition、batteryState→powerSupply、informations→information；新增 instantActionStates、zoneActionStates、maps、zoneSets、plannedPath、intermediatePath、 zoneRequests、edgeRequests。

Examples

#1 Example - driving

執行任務中

{
  "headerId": 1712995200100,
  "timestamp": "2026-04-13T18:00:00.100Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "orderId": "task_0f3a8b9c-0000-0000-0000-000000000001",
  "orderUpdateId": 0,
  "lastNodeId": "node_origin_task_0f3a8b9c",
  "lastNodeSequenceId": 0,
  "driving": true,
  "paused": false,
  "operatingMode": "AUTOMATIC",
  "nodeStates": [
    {
      "nodeId": "node_target_task_0f3a8b9c",
      "sequenceId": 2,
      "released": true,
      "nodePosition": {
        "x": 20,
        "y": 8.5,
        "mapId": "map-lobby-v3"
      }
    }
  ],
  "edgeStates": [
    {
      "edgeId": "edge_task_0f3a8b9c_0",
      "sequenceId": 1,
      "released": true
    }
  ],
  "actionStates": [
    {
      "actionId": "action_task_0f3a8b9c_drop",
      "actionType": "drop",
      "actionStatus": "WAITING"
    }
  ],
  "batteryState": {
    "batteryCharge": 72.5,
    "batteryVoltage": 24.1,
    "batteryHealth": 98,
    "charging": false,
    "reach": 5200
  },
  "errors": [],
  "informations": [
    {
      "infoType": "agvIp",
      "infoLevel": "INFO",
      "infoDescription": "192.168.10.42"
    }
  ],
  "safetyState": {
    "eStop": "NONE",
    "fieldViolation": false
  },
  "agvPosition": {
    "x": 13.579,
    "y": 7.111,
    "theta": 1.5708,
    "mapId": "map-lobby-v3",
    "positionInitialized": true,
    "localizationScore": 0.98
  },
  "velocity": {
    "vx": 0.45,
    "vy": 0,
    "omega": 0
  },
  "loads": []
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/state

Master Control 接收狀態（v3）

Operation IDreceiveState

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 State

application/json

Message IDState

object allOf

Examples

#1 Example - driving

執行任務中

{
  "headerId": 1712995200100,
  "timestamp": "2026-04-13T18:00:00.100Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "orderId": "task_0f3a8b9c-0000-0000-0000-000000000001",
  "orderUpdateId": 0,
  "lastNodeId": "node_origin_task_0f3a8b9c",
  "lastNodeSequenceId": 0,
  "driving": true,
  "paused": false,
  "operatingMode": "AUTOMATIC",
  "nodeStates": [
    {
      "nodeId": "node_target_task_0f3a8b9c",
      "sequenceId": 2,
      "released": true,
      "nodePosition": {
        "x": 20,
        "y": 8.5,
        "mapId": "map-lobby-v3"
      }
    }
  ],
  "edgeStates": [
    {
      "edgeId": "edge_task_0f3a8b9c_0",
      "sequenceId": 1,
      "released": true
    }
  ],
  "actionStates": [
    {
      "actionId": "action_task_0f3a8b9c_drop",
      "actionType": "drop",
      "actionStatus": "WAITING"
    }
  ],
  "batteryState": {
    "batteryCharge": 72.5,
    "batteryVoltage": 24.1,
    "batteryHealth": 98,
    "charging": false,
    "reach": 5200
  },
  "errors": [],
  "informations": [
    {
      "infoType": "agvIp",
      "infoLevel": "INFO",
      "infoDescription": "192.168.10.42"
    }
  ],
  "safetyState": {
    "eStop": "NONE",
    "fieldViolation": false
  },
  "agvPosition": {
    "x": 13.579,
    "y": 7.111,
    "theta": 1.5708,
    "mapId": "map-lobby-v3",
    "positionInitialized": true,
    "localizationScore": 0.98
  },
  "velocity": {
    "vx": 0.45,
    "vy": 0,
    "omega": 0
  },
  "loads": []
}

SEND /vda5050/v3/{manufacturer}/{serialNumber}/connection

Mobile Robot → Master 連線狀態（建議設 MQTT LWT）。v3 列舉變更： CONNECTIONBROKEN → CONNECTION_BROKEN，並新增 HIBERNATING。

Mobile Robot 發布連線狀態（v3，建議搭配 LWT）

Operation IDpublishConnection

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Connection

application/json

Message IDConnection

object allOf

AGV → Master 連線狀態訊息（VDA5050 v3.0）。建議設 MQTT LWT。 v3 變更：connectionState enum 與 v2 結構相同，但走 v3 topic prefix（/vda5050/v3/…）。

Examples

#1 Example - online

{
  "headerId": 1,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "connectionState": "ONLINE"
}

#2 Example - lwt

LWT CONNECTION_BROKEN

{
  "headerId": 0,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "connectionState": "CONNECTIONBROKEN"
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/connection

Mobile Robot → Master 連線狀態（建議設 MQTT LWT）。v3 列舉變更： CONNECTIONBROKEN → CONNECTION_BROKEN，並新增 HIBERNATING。

Master Control 接收連線狀態（v3）

Operation IDreceiveConnection

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Connection

application/json

Message IDConnection

object allOf

AGV → Master 連線狀態訊息（VDA5050 v3.0）。建議設 MQTT LWT。 v3 變更：connectionState enum 與 v2 結構相同，但走 v3 topic prefix（/vda5050/v3/…）。

Examples

#1 Example - online

{
  "headerId": 1,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "connectionState": "ONLINE"
}

#2 Example - lwt

LWT CONNECTION_BROKEN

{
  "headerId": 0,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "connectionState": "CONNECTIONBROKEN"
}

SEND /vda5050/v3/{manufacturer}/{serialNumber}/visualization

Mobile Robot → Master 高頻位置更新（10–30 Hz）

Operation IDpublishVisualization

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Visualization

application/json

Message IDVisualization

object allOf

AGV → Master 高頻位置更新（VDA5050 v3.0，10–30 Hz）。 v3 變更：新增必需欄位 referenceStateHeaderId；agvPosition→mobileRobotPosition；新增 plannedPath / intermediatePath。

Examples

#1 Example - position

{
  "headerId": 1234567,
  "timestamp": "2026-04-13T18:00:00.050Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "agvPosition": {
    "x": 13.6,
    "y": 7.1,
    "theta": 1.57,
    "mapId": "map-lobby-v3",
    "positionInitialized": true
  },
  "velocity": {
    "vx": 0.45,
    "vy": 0,
    "omega": 0
  }
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/visualization

Mobile Robot → Master 高頻位置更新（10–30 Hz）

Operation IDreceiveVisualization

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Visualization

application/json

Message IDVisualization

object allOf

Examples

#1 Example - position

{
  "headerId": 1234567,
  "timestamp": "2026-04-13T18:00:00.050Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "agvPosition": {
    "x": 13.6,
    "y": 7.1,
    "theta": 1.57,
    "mapId": "map-lobby-v3",
    "positionInitialized": true
  },
  "velocity": {
    "vx": 0.45,
    "vy": 0,
    "omega": 0
  }
}

SEND /vda5050/v3/{manufacturer}/{serialNumber}/factsheet

Mobile Robot → Master 規格表（v3 新增 protocolVersion / supportedV3Capabilities 等欄位）

Operation IDpublishFactsheet

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Factsheet

application/json

Message IDFactsheet

object allOf

AGV → Master 功能規格表（VDA5050 v3.0）。 v3 變更：agvKinematic/agvClass→mobileRobotKinematic/mobileRobotClass； physicalParameters 多欄位改名（speedMin→minimumSpeed 等）；agvActions→mobileRobotActions； agvGeometry→mobileRobotGeometry；新增 mobileRobotConfiguration 頂層欄位。

Examples

#1 Example - puduBot

{
  "headerId": 1,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "typeSpecification": {
    "seriesName": "PuduBot 2",
    "seriesDescription": "Delivery robot series",
    "agvKinematic": "DIFF",
    "agvClass": "CARRIER",
    "maxLoadMass": 40,
    "localizationTypes": [
      "NATURAL"
    ],
    "navigationTypes": [
      "VIRTUAL_LINE_GUIDED"
    ]
  },
  "physicalParameters": {
    "speedMin": 0.1,
    "speedMax": 1.2,
    "accelerationMax": 0.5,
    "decelerationMax": 0.8,
    "heightMin": 1,
    "heightMax": 1.3,
    "width": 0.52,
    "length": 0.58
  },
  "protocolLimits": {
    "maxStringLens": {
      "msgLen": 65535
    },
    "maxArrayLens": {
      "order.nodes": 100
    },
    "timing": {
      "minOrderInterval": 1,
      "minStateInterval": 0.1,
      "defaultStateInterval": 1,
      "visualizationInterval": 0.1
    }
  },
  "protocolFeatures": {
    "optionalParameters": [
      {
        "parameter": "trajectory",
        "support": "SUPPORTED"
      }
    ],
    "agvActions": [
      {
        "actionType": "drop",
        "actionScopes": [
          "NODE"
        ],
        "actionParameters": []
      },
      {
        "actionType": "wait",
        "actionScopes": [
          "NODE"
        ],
        "actionParameters": [
          {
            "key": "duration",
            "valueDataType": "STRING"
          }
        ]
      },
      {
        "actionType": "cancelOrder",
        "actionDescription": "取消當下執行中的 order。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "startPause",
        "actionDescription": "AMR 立即停止等待。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "stopPause",
        "actionDescription": "AMR 繼續依照 order 前進。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "factsheetRequest",
        "actionDescription": "AMR 回報目前能力。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": []
      },
      {
        "actionType": "retry",
        "actionDescription": "AMR 回報 error 時，例如目的地無法抵達或幹道無法通行，收到此命令後重試。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "errorType",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetNodeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetEdgeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "retryMode",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "skipRetry",
        "actionDescription": "取消重試。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "errorType",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetNodeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetEdgeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "skipNode",
        "actionDescription": "跳過當下 order 要前往的 node，到下一個 node。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "currentNodeId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "currentNodeSequenceId",
            "valueDataType": "INTEGER",
            "isOptional": false
          },
          {
            "key": "nextNodeId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "nextNodeSequenceId",
            "valueDataType": "INTEGER",
            "isOptional": false
          },
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      }
    ]
  }
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/factsheet

Mobile Robot → Master 規格表（v3 新增 protocolVersion / supportedV3Capabilities 等欄位）

Operation IDreceiveFactsheet

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Factsheet

application/json

Message IDFactsheet

object allOf

Examples

#1 Example - puduBot

{
  "headerId": 1,
  "timestamp": "2026-04-13T18:00:00.000Z",
  "version": "2.0.0",
  "manufacturer": "pudu",
  "serialNumber": "ROBOT-001",
  "typeSpecification": {
    "seriesName": "PuduBot 2",
    "seriesDescription": "Delivery robot series",
    "agvKinematic": "DIFF",
    "agvClass": "CARRIER",
    "maxLoadMass": 40,
    "localizationTypes": [
      "NATURAL"
    ],
    "navigationTypes": [
      "VIRTUAL_LINE_GUIDED"
    ]
  },
  "physicalParameters": {
    "speedMin": 0.1,
    "speedMax": 1.2,
    "accelerationMax": 0.5,
    "decelerationMax": 0.8,
    "heightMin": 1,
    "heightMax": 1.3,
    "width": 0.52,
    "length": 0.58
  },
  "protocolLimits": {
    "maxStringLens": {
      "msgLen": 65535
    },
    "maxArrayLens": {
      "order.nodes": 100
    },
    "timing": {
      "minOrderInterval": 1,
      "minStateInterval": 0.1,
      "defaultStateInterval": 1,
      "visualizationInterval": 0.1
    }
  },
  "protocolFeatures": {
    "optionalParameters": [
      {
        "parameter": "trajectory",
        "support": "SUPPORTED"
      }
    ],
    "agvActions": [
      {
        "actionType": "drop",
        "actionScopes": [
          "NODE"
        ],
        "actionParameters": []
      },
      {
        "actionType": "wait",
        "actionScopes": [
          "NODE"
        ],
        "actionParameters": [
          {
            "key": "duration",
            "valueDataType": "STRING"
          }
        ]
      },
      {
        "actionType": "cancelOrder",
        "actionDescription": "取消當下執行中的 order。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "startPause",
        "actionDescription": "AMR 立即停止等待。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "stopPause",
        "actionDescription": "AMR 繼續依照 order 前進。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "factsheetRequest",
        "actionDescription": "AMR 回報目前能力。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": []
      },
      {
        "actionType": "retry",
        "actionDescription": "AMR 回報 error 時，例如目的地無法抵達或幹道無法通行，收到此命令後重試。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "errorType",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetNodeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetEdgeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "retryMode",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "skipRetry",
        "actionDescription": "取消重試。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "errorType",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetNodeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "targetEdgeId",
            "valueDataType": "STRING",
            "isOptional": true
          },
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      },
      {
        "actionType": "skipNode",
        "actionDescription": "跳過當下 order 要前往的 node，到下一個 node。",
        "actionScopes": [
          "INSTANT"
        ],
        "blockingTypes": [
          "NONE"
        ],
        "actionParameters": [
          {
            "key": "orderId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "currentNodeId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "currentNodeSequenceId",
            "valueDataType": "INTEGER",
            "isOptional": false
          },
          {
            "key": "nextNodeId",
            "valueDataType": "STRING",
            "isOptional": false
          },
          {
            "key": "nextNodeSequenceId",
            "valueDataType": "INTEGER",
            "isOptional": false
          },
          {
            "key": "reason",
            "valueDataType": "STRING",
            "isOptional": true
          }
        ]
      }
    ]
  }
}

SEND /vda5050/v3/{manufacturer}/{serialNumber}/zoneSet

Fleet Control → Mobile Robot 區域規則集分發（v3.0 新增 topic）。內含 10 種 zoneType（BLOCKED / SPEED_LIMIT / ACTION / RELEASE / PRIORITY / PENALTY / DIRECTED / BIDIRECTED / LINE_GUIDED / COORDINATED_REPLANNING），每種觸發不同條件欄位。 QoS 0（無需保留）；AMR 比對 state.zoneSets[].zoneSetId 更新本地快取。

Fleet Control 發送 ZoneSet 區域規則給 Mobile Robot（v3 新增）

Operation IDsendZoneSet

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 ZoneSet (新增)

application/json

Message IDZoneSet

object allOf

Fleet Control → AMR 的區域規則集訊息（VDA5050 v3.0 新增）。分發 Zone 規則（BLOCKED / SPEED_LIMIT / ACTION / RELEASE 等）給 AMR 用於規劃與行為調整。 QoS 0（無需保留），AMR 收到後比對 state.zoneSets[].zoneSetId 更新本地快取。

Examples

#1 Example - factoryFloor

工廠 1F 區域規則集（含 BLOCKED + SPEED_LIMIT + RELEASE 三種 zone）

{
  "headerId": 8,
  "timestamp": "2026-06-09T08:25:00.000Z",
  "version": "3.0.0",
  "manufacturer": "nexos",
  "serialNumber": "AMR-0001",
  "zoneSet": {
    "mapId": "factory-1f",
    "zoneSetId": "zs-factory-1f-v2",
    "zoneSetDescriptor": "Factory 1F operational zones",
    "zones": [
      {
        "zoneId": "zone-blocked-server-room",
        "zoneType": "BLOCKED",
        "zoneDescriptor": "機房入口禁止進入",
        "vertices": [
          {
            "x": 12,
            "y": 4
          },
          {
            "x": 16,
            "y": 4
          },
          {
            "x": 16,
            "y": 8
          },
          {
            "x": 12,
            "y": 8
          }
        ]
      },
      {
        "zoneId": "zone-slow-corridor",
        "zoneType": "SPEED_LIMIT",
        "zoneDescriptor": "走廊限速",
        "vertices": [
          {
            "x": 0,
            "y": 10
          },
          {
            "x": 20,
            "y": 10
          },
          {
            "x": 20,
            "y": 12
          },
          {
            "x": 0,
            "y": 12
          }
        ],
        "maximumSpeed": 0.5
      },
      {
        "zoneId": "zone-charging-bay",
        "zoneType": "RELEASE",
        "zoneDescriptor": "充電區（資源型）",
        "vertices": [
          {
            "x": 25,
            "y": 0
          },
          {
            "x": 30,
            "y": 0
          },
          {
            "x": 30,
            "y": 3
          },
          {
            "x": 25,
            "y": 3
          }
        ],
        "releaseLossBehavior": "EVACUATE"
      }
    ]
  }
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/zoneSet

Mobile Robot 接收 ZoneSet（v3 新增）

Operation IDreceiveZoneSet

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 ZoneSet (新增)

application/json

Message IDZoneSet

object allOf

Examples

#1 Example - factoryFloor

工廠 1F 區域規則集（含 BLOCKED + SPEED_LIMIT + RELEASE 三種 zone）

{
  "headerId": 8,
  "timestamp": "2026-06-09T08:25:00.000Z",
  "version": "3.0.0",
  "manufacturer": "nexos",
  "serialNumber": "AMR-0001",
  "zoneSet": {
    "mapId": "factory-1f",
    "zoneSetId": "zs-factory-1f-v2",
    "zoneSetDescriptor": "Factory 1F operational zones",
    "zones": [
      {
        "zoneId": "zone-blocked-server-room",
        "zoneType": "BLOCKED",
        "zoneDescriptor": "機房入口禁止進入",
        "vertices": [
          {
            "x": 12,
            "y": 4
          },
          {
            "x": 16,
            "y": 4
          },
          {
            "x": 16,
            "y": 8
          },
          {
            "x": 12,
            "y": 8
          }
        ]
      },
      {
        "zoneId": "zone-slow-corridor",
        "zoneType": "SPEED_LIMIT",
        "zoneDescriptor": "走廊限速",
        "vertices": [
          {
            "x": 0,
            "y": 10
          },
          {
            "x": 20,
            "y": 10
          },
          {
            "x": 20,
            "y": 12
          },
          {
            "x": 0,
            "y": 12
          }
        ],
        "maximumSpeed": 0.5
      },
      {
        "zoneId": "zone-charging-bay",
        "zoneType": "RELEASE",
        "zoneDescriptor": "充電區（資源型）",
        "vertices": [
          {
            "x": 25,
            "y": 0
          },
          {
            "x": 30,
            "y": 0
          },
          {
            "x": 30,
            "y": 3
          },
          {
            "x": 25,
            "y": 3
          }
        ],
        "releaseLossBehavior": "EVACUATE"
      }
    ]
  }
}

SEND /vda5050/v3/{manufacturer}/{serialNumber}/responses

Fleet Control → Mobile Robot 對 state.zoneRequests / edgeRequests 的回應（v3.0 新增 topic）。 grantType 4 種：GRANTED（須帶 leaseExpiry）/ QUEUED / REVOKED / REJECTED。支援單包多筆 response。QoS 0。

Fleet Control 回應 Mobile Robot 的 zone/edge requests（v3 新增）

Operation IDsendResponses

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Responses (新增)

application/json

Message IDResponses

object allOf

Fleet Control → AMR 對 state.zoneRequests[] / state.edgeRequests[] 的回應訊息（VDA5050 v3.0 新增）。 AMR 透過 state 提出資源請求（access / replanning / corridor），Fleet 透過此 topic 回覆授權結果。 GRANTED 時必帶 leaseExpiry（租約失效時間，AMR 過期前須續租或釋放）。 QoS 0；可一次回覆多個 request。

Examples

#1 Example - grantedAndQueued

一筆 GRANTED（含 leaseExpiry）+ 一筆 QUEUED

{
  "headerId": 31,
  "timestamp": "2026-06-09T08:30:00.600Z",
  "version": "3.0.0",
  "manufacturer": "nexos",
  "serialNumber": "AMR-0001",
  "responses": [
    {
      "requestId": "ZR-001",
      "grantType": "GRANTED",
      "leaseExpiry": "2026-06-09T08:31:00.000Z"
    },
    {
      "requestId": "ER-002",
      "grantType": "QUEUED"
    }
  ]
}

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/responses

Mobile Robot 接收 Responses 並更新 zone/edge request 授權狀態（v3 新增）

Operation IDreceiveResponses

Available only on servers:

production
development

object

manufacturerstring

required

廠商代碼

serialNumberstring

required

機器人序號

object

Accepts the following message:

VDA5050 v3 Responses (新增)

application/json

Message IDResponses

object allOf

Examples

#1 Example - grantedAndQueued

一筆 GRANTED（含 leaseExpiry）+ 一筆 QUEUED

{
  "headerId": 31,
  "timestamp": "2026-06-09T08:30:00.600Z",
  "version": "3.0.0",
  "manufacturer": "nexos",
  "serialNumber": "AMR-0001",
  "responses": [
    {
      "requestId": "ZR-001",
      "grantType": "GRANTED",
      "leaseExpiry": "2026-06-09T08:31:00.000Z"
    },
    {
      "requestId": "ER-002",
      "grantType": "QUEUED"
    }
  ]
}

Messages

#1VDA5050 v3 Order

application/json

Message IDOrder

object allOf

Master Control → AGV 的任務訊息（VDA5050 v3.0）。 v3 變更：新增 orderDescription 頂層欄位；nodes/edges 使用 v3 common 結構。

#2VDA5050 v3 InstantActions

application/json

Message IDInstantActions

object allOf

雙向 instant actions 訊息（VDA5050 v3.0）。 v3 變更：欄位從 instantActions 改名為 actions；blockingType 限定為 NONE。

#3VDA5050 v3 State

application/json

Message IDState

object allOf

#4VDA5050 v3 Connection

application/json

Message IDConnection

object allOf

AGV → Master 連線狀態訊息（VDA5050 v3.0）。建議設 MQTT LWT。 v3 變更：connectionState enum 與 v2 結構相同，但走 v3 topic prefix（/vda5050/v3/…）。

#5VDA5050 v3 Visualization

application/json

Message IDVisualization

object allOf

#6VDA5050 v3 Factsheet

application/json

Message IDFactsheet

object allOf

#7VDA5050 v3 ZoneSet (新增)

application/json

Message IDZoneSet

object allOf

#8VDA5050 v3 Responses (新增)

application/json

Message IDResponses

object allOf

VDA5050 Core v3.0 (NexOS Robotics) 2.0.0+bot.0

與 v2.0 的關鍵差異（彙整）

2.0.0+bot.0 — 2026-06-11 (human:phase-4-schema)

2.0.0+v3-draft — 2026-06-11 (human:phase-4-init)

Servers

Security:

Operations

SEND /vda5050/v3/{manufacturer}/{serialNumber}/order

Examples

#1 Example - delivery

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/order

Examples

#1 Example - delivery

SEND /vda5050/v3/{manufacturer}/{serialNumber}/instantActions

Examples

#1 Example - cancel

#2 Example - initPosition

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/instantActions

Examples

#1 Example - cancel

#2 Example - initPosition

SEND /vda5050/v3/{manufacturer}/{serialNumber}/state

Examples

#1 Example - driving

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/state

Examples

#1 Example - driving

SEND /vda5050/v3/{manufacturer}/{serialNumber}/connection

Examples

#1 Example - online

#2 Example - lwt

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/connection

Examples

#1 Example - online

#2 Example - lwt

SEND /vda5050/v3/{manufacturer}/{serialNumber}/visualization

Examples

#1 Example - position

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/visualization

Examples

#1 Example - position

SEND /vda5050/v3/{manufacturer}/{serialNumber}/factsheet

Examples

#1 Example - puduBot

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/factsheet

Examples

#1 Example - puduBot

SEND /vda5050/v3/{manufacturer}/{serialNumber}/zoneSet

Examples

#1 Example - factoryFloor

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/zoneSet

Examples

#1 Example - factoryFloor

SEND /vda5050/v3/{manufacturer}/{serialNumber}/responses

Examples

#1 Example - grantedAndQueued

RECEIVE /vda5050/v3/{manufacturer}/{serialNumber}/responses

Examples

#1 Example - grantedAndQueued

Messages