VDA5050 액션 선언과 핸들러: 라이브러리가 해 주는 일, 직접 구현할 일, 자주 막히는 지점
이 글의 핵심
libVDA5050++에서는 액션 선언(ActionDeclaration)이 핸들러에 들어 있고, 선언이 있으면 타입 일치, 사용 위치(instant·node·edge), blockingType, 파라미터 이름·타입·범위를 라이브러리가 검사해 어긋나면 order 전체를 거절합니다. 핸들러를 등록하면 라이브러리가 액션을 WAITING으로 올리고, 노드 도착 뒤 시작 시점을 정하고, blockingType에 따라 주행을 멈추고, 콜백을 부르고, 상태를 State로 내보냅니다. 직접 구현하는 것은 prepare가 돌려주는 콜백 네 개, 실제 장비 동작, 결과 보고(setFinished·setFailed), 시간 제한, 선언으로 표현할 수 없는 검사입니다.
VDA5050 차량 쪽을 직접 개발하다 보면 “액션 선언을 하고 핸들러를 등록하면 라이브러리가 어디까지 해 주고, 내가 직접 짜야 하는 건 어디부터인가”가 가장 먼저 헷갈립니다. 이 글은 그 경계를 libVDA5050++ v2.11.3 소스를 읽고, 같은 라이브러리로 만든 시뮬레이터(Ubuntu 24.04 aarch64 컨테이너, eclipse-mosquitto:2)에 order를 직접 보내 확인한 결과로 정리합니다. 먼저 order와 액션이 어떻게 생겼는지 짧게 짚고, 이어서 자동 처리와 직접 구현의 경계, 실제 거절 메시지, 자주 부딪히는 문제와 해결책 순서로 갑니다.
소스를 읽어서 안 내용과 실행해서 본 내용은 구분해서 적었습니다. 이 글의 동작은 VDA5050 표준이 아니라 libVDA5050++ v2.11.3과 이 시뮬레이터의 동작이므로, 다른 구현체나 다른 버전에서는 오류 이름과 세부 동작이 다를 수 있습니다.
order는 어떻게 생겼나
order는 관제가 차량에 보내는 “이 경로를 따라 이 일을 하라”는 메시지입니다. 뼈대는 이렇습니다.
{
"orderId": "T1",
"orderUpdateId": 0,
"nodes": [
{"nodeId": "n0", "sequenceId": 0, "released": true,
"nodePosition": {"x": 0.0, "y": 0.0, "mapId": "map", "allowedDeviationXY": 0.5},
"actions": []},
{"nodeId": "n1", "sequenceId": 2, "released": true,
"nodePosition": {"x": 3.0, "y": 0.0, "mapId": "map", "allowedDeviationXY": 0.5},
"actions": [
{"actionId": "p1", "actionType": "pick", "blockingType": "HARD",
"actionParameters": [
{"key": "stationType", "value": "floor"},
{"key": "loadType", "value": "EPAL"}]}]}
],
"edges": [
{"edgeId": "e0", "sequenceId": 1, "released": true,
"startNodeId": "n0", "endNodeId": "n1", "actions": []}
]
}
orderId와orderUpdateId: 같은 작업을 이어서 갱신할 때는orderId를 유지하고orderUpdateId를 올립니다. 새 작업은 새orderId입니다.nodes와edges: 노드와 엣지가 번갈아 이어지는 경로입니다. 이 글의 실험은 노드를 0, 2, 4, 엣지를 1, 3으로 번호 매겼습니다.released: true인 구간은 차량이 실제로 갈 수 있는 확정 구간(base), false는 앞으로 바뀔 수 있는 예고 구간(horizon)입니다.actions: 노드와 엣지마다 붙는 액션 목록입니다.
order의 구조 규칙과 갱신 방식은 order 수명주기에서 자세히 다룹니다.
액션의 종류
액션 객체는 actionId, actionType, blockingType, actionParameters로 이뤄집니다. 어디에 붙는지에 따라 세 가지로 나눕니다.
| 위치 | 어디서 보내나 | 언제 실행되나 |
|---|---|---|
| node | order의 노드 | 그 노드에 도착한 뒤 |
| edge | order의 엣지 | 그 엣지를 달리는 동안 |
| instant | instantActions 토픽 | 받는 즉시 (order와 무관) |
actionType에는 표준이 정한 이름(startPause, stopPause, cancelOrder, initPosition, stateRequest, pick, drop, startCharging, stopCharging 등)과 제조사가 정의하는 이름이 있습니다. 표준 액션 표와 각 액션의 상태 필드는 instantActions와 표준 액션 총정리에 정리해 두었습니다.
blockingType은 “이 액션이 도는 동안 다른 일을 해도 되는가”입니다.
NONE: 주행이나 다른 액션과 같이 해도 됩니다.SOFT: 다른 액션은 같이 할 수 있지만 주행은 멈춰야 합니다.HARD: 주행도, 다른 액션도 할 수 없습니다. 혼자 실행됩니다.
이 라이브러리에서 이 규칙이 구현된 곳은 스케줄러입니다. 소스를 보면 HARD가 끼면 활성 액션이 있는 동안 다음 액션 그룹을 시작하지 않고, NONE이 아닌 액션이 시작될 차례가 되면 주행 중에는 시작하지 않도록 막습니다.
라이브러리가 기본으로 제공하는 선언은 startCharging, stopCharging, logReport, pick, drop, detectObject, finePositioning, waitForTrigger, initPosition입니다. 표준 이름이라도 차량이 지원할지는 어댑터가 선언하기 나름입니다.
선언과 핸들러, 어디까지가 자동인가
여기가 이 글의 핵심입니다. 먼저 구조를 바로잡으면, libVDA5050++에서 선언은 핸들러와 따로 등록하는 것이 아닙니다. SimpleActionHandler와 SimpleMultiActionHandler는 생성자에서 ActionDeclaration을 받아, 그것으로 매칭·검증·factsheet 설명을 만듭니다.
// 선언을 핸들러 생성자에 넘긴다. 선언 없는 핸들러, 핸들러 없는 선언은 없다.
class MyHandler : public vda5050pp::handler::SimpleMultiActionHandler {
public:
MyHandler()
: SimpleMultiActionHandler({vda5050pp::misc::action_declarations::k_pick,
vda5050pp::misc::action_declarations::k_drop}) {}
// prepare(), reset()만 구현하면 된다.
};
선언의 필드는 이렇습니다(agv_description/action_declaration.h).
| 필드 | 뜻 |
|---|---|
action_type | 액션 이름. 핸들러를 고르는 키이기도 함 |
description, result_description | factsheet에 나가는 설명 |
parameter | 필수 파라미터 (키, 타입, 최소·최대, 허용 값 집합) |
optional_parameter | 선택 파라미터 |
blocking_types | 허용하는 blockingType 집합 |
instant, node, edge | 사용할 수 있는 위치 (기본값 모두 false) |
선언이 있으면 라이브러리가 하는 일
order를 받으면 라이브러리는 order 안의 모든 액션을 핸들러에 보내 검증하고, 오류가 하나라도 있으면 order 자체를 받지 않습니다(소스: validation_event_handler.cpp의 actionChecks). 핸들러의 검증은 checks/action.cpp의 validateActionWithDeclaration이 하며, 선언과 비교해 다음을 봅니다.
- 핸들러 매칭:
actionType이 선언과 같은 핸들러를 찾습니다. 맞는 핸들러가 없으면unknownActionType오류가 됩니다. - 위치: instant, node, edge 중 선언이 허용하지 않은 곳에 붙었으면 거절합니다.
- blockingType: 선언의
blocking_types에 없으면 거절합니다. - 파라미터: 선언에 없는 키는 거절, 필수 키가 빠지면 거절, 값은 선언한 타입(정수·실수·불리언·문자열)으로 변환하고 최소·최대·허용 값 집합을 검사합니다.
- 검사를 통과한 값은
ParametersMap으로 만들어prepare의 두 번째 인자로 넘깁니다. 핸들러가 JSON을 다시 파싱할 필요가 없습니다. - 선언 목록은 factsheet의
agvActions로 나갑니다. 시뮬레이터의 factsheet에는pick이EDGE·NODE범위, 필수 파라미터loadType·stationType, 선택 파라미터stationName·loadId등과 함께 올라갔습니다.
타입이 배열이나 객체인 파라미터는 기본 검증이 지원하지 않습니다(소스에서 설정 오류 예외를 던집니다). 그런 파라미터가 필요하면 validate를 직접 재정의해야 합니다.
핸들러가 등록되면 라이브러리가 하는 일
- WAITING 등록: 확정된(released) 구간의 액션을
actionStates에 WAITING으로 올립니다. - 실행 시점: 노드 액션은 노드 도착 뒤에 시작하고, 위에서 본 blockingType 규칙대로 주행을 멈추거나 다른 액션을 기다리게 합니다.
- 콜백 호출: 알맞은 때에
on_start,on_pause,on_resume,on_cancel을 부릅니다.ActionCallbacks구조체의 네 필드입니다. - 상태 전이와 State 발행: 콜백 안에서
setRunning(),setPaused(),setFinished(),setFailed()를 부르면 라이브러리가actionStatus를 바꾸고 State를 내보냅니다. 전이 순서가 맞지 않으면 예외를 던집니다. 예를 들어 WAITING에서는 시작 신호와 취소만 받을 수 있습니다. - 내장 instantAction 처리:
cancelOrder,startPause,stopPause,stateRequest,factsheetRequest는 핸들러 없이도 라이브러리가 직접 처리하고 factsheet에도 올립니다(control_instant_actions.cpp). 시뮬레이터의 factsheet에서도 이 다섯 개가 INSTANT 범위로 나왔습니다.initPosition은 내장이 아니라InitPositionHandler를 상속해handleInitPosition을 구현하고 등록해야 합니다.
직접 구현해야 하는 것
| 구현 | 설명 |
|---|---|
prepare() | 액션마다 콜백 네 개를 담은 ActionCallbacks를 돌려줍니다 |
on_start | 실제 동작을 시작하고 setRunning()을 부릅니다. 오래 걸리는 일은 별도 스레드나 이벤트로 넘깁니다 |
| 결과 보고 | 끝나면 setFinished()(결과 코드를 줄 수도 있음), 실패하면 setFailed()를 부릅니다. 2.11.3은 setFailed(errors)에 넘긴 오류 목록을 State에 싣지 않으므로 StatusSink().addError(err)를 따로 불러야 합니다 |
on_cancel | 진행 중인 동작을 멈추고 setFailed() 또는 setFinished()를 부릅니다 |
on_pause, on_resume | 의미 있는 액션이면 구현하고, 아니면 아무것도 하지 않는 함수라도 반드시 채웁니다 |
| 시간 제한 | 액션 실행 시간 제한은 라이브러리에 없습니다(스케줄러·액션 태스크·핸들러 소스에서 액션용 타임아웃을 찾지 못했고 내비게이션 쪽에만 있음). 응답이 없는 장비를 기다리다 영원히 RUNNING으로 남지 않게 직접 만듭니다 |
| 선언으로 못 하는 검사 | 예를 들어 targetMap이 실제 맵 목록에 있는지처럼 런타임 정보가 필요한 검사는 validate()를 재정의해 기본 검사를 부른 뒤 오류를 더합니다 |
reset() | 수동 모드로 바뀔 때 호출됩니다. 진행 중인 액션 상태를 비웁니다 |
콜백을 채우는 일은 형식이 아니라 필수입니다. 소스를 보면 on_pause가 비어 있을 때 라이브러리가 VDA5050PPCallbackNotSet 예외를 던집니다(action_event_handler.cpp의 handlePauseEvent, 취소·재개·시작도 같은 구조). 직접 일으켜 보면 라이브러리 로그에 ActionEventManager caught an exception ... on_pause is null이 남고 프로세스는 살아 있지만, 보낸 startPause 액션이 RUNNING에 머물고 일시정지도 되지 않았습니다. 라이브러리 자체의 InitPositionHandler도 일시정지·재개·취소가 의미 없다는 주석과 함께 빈 함수를 채워 반환합니다.
실행해서 확인한 결과
시뮬레이터 차량(노드 n0 (0,0) → n1 (3,0) → n2 (3,2), 충전소 n0, pick 역 n1, drop 역 n2)에 order를 보내고 state를 관찰했습니다. 아래 errorType의 이름과 메시지는 이 라이브러리가 붙인 것입니다.
| 보낸 것 | 결과 |
|---|---|
알 수 없는 doBackflip | unknownActionType (WARNING): “Unknown action Type doBackflip encountered” |
pick에서 필수 loadType 빠짐 | orderError: Missing action parameters: ["loadType"] |
pick에 선언에 없는 키 bogus | orderError: ActionParameter "bogus" with value "x" is unknown. |
pick의 height(실수)에 문자열 “abc” | validationError: [json.exception.type_error.302] type must be number, but is string |
pick을 blockingType NONE으로 | orderError: BlockingType "NONE" is not allowed, expected one of {HARD} |
엣지에 startCharging | orderError: The action is not allowed to run at "Edge" |
instantActions로 pick | instantActionError: The action is not allowed to run at "Instant", 액션이 FAILED로 actionStates에 나타남 |
startCharging과 doBackflip을 한 order에 | unknownActionType만 올라오고 orderId가 비어 있음. order 전체 거절 |
예고(released=false) 노드에 필수 파라미터가 빠진 pick | orderError: 거절됨 |
몇 가지 눈에 띄는 점이 있습니다.
- 타입이 맞지 않는 값의 오류는
validationError로 올라오고, 설명은 JSON 라이브러리의 예외 메시지 그대로입니다. 반면 키·범위·blockingType·위치 오류는orderError입니다. 오류 분류로 원인을 가르려면 이 차이를 알아 둬야 합니다. - 이 시뮬레이터에서는 거절 오류가 다음 order에도
errors배열에 계속 남아 있었습니다. 새 오류를 찾으려면 이전 state와의 차이를 봐야 합니다. - order 액션의 거절은
actionStates에 아무것도 남기지 않지만, instantAction의 거절은 FAILED 상태의 액션으로 나타났습니다.
정상 실행 타임라인
pick(n1)과 drop(n2)이 붙은 정상 order의 state 변화입니다.
| 시각 | driving | 위치 | 액션 상태 | loads |
|---|---|---|---|---|
| 접수 직후 | true | (0.1, 0.0) | p1·d1 WAITING | 없음 |
| 약 3초 뒤 n1 도착 | false | (3.0, 0.0) | p1 RUNNING | 없음 |
| 2초 뒤 | false | (3.0, 0.0) | p1 FINISHED | L1 |
| 이어서 | true | (3.0, 0.2) | d1 WAITING | L1 |
| n2 도착 | false | (3.0, 2.0) | d1 RUNNING | L1 |
| 2초 뒤 | false | (3.0, 2.0) | d1 FINISHED | 없음 |
HARD 액션이 도는 동안 driving이 false였고, 노드 도착 보고와 액션 시작이 거의 같은 시점에 일어났습니다. 액션 실행 시간 2초는 시뮬레이터가 정한 값입니다.
액션이 실패하는 경우
핸들러가 실패를 알릴 때 State의 errors에 오류를 싣는 방법은 주의가 필요합니다. 이 라이브러리 2.11.3은 setFailed(errors)로 넘긴 오류 목록을 버리므로, vda5050pp::sinks::StatusSink().addError(err)를 따로 불러야 errors에 올라옵니다(이 시뮬레이터도 그렇게 합니다). 직접 만든 어댑터로 addError 없이 setFailed({err})만 부르면 액션은 FAILED가 되는데 errors는 비어 있었고, addError를 같이 부르자 올라왔습니다. 역이 없는 n0에서 pick을 하면 actionStatus가 FAILED가 되고 noPickStation(“no station to pick from at the current position”, WARNING) 오류가 나왔습니다. 다른 역(D1)에서 stationName을 P1로 주면 stationMismatch였습니다. 이 오류 이름은 시뮬레이터 핸들러가 정한 것이고 라이브러리가 만든 것이 아닙니다. 즉 “실행 중 실패의 이름과 설명”은 직접 구현하는 영역입니다.
예고 노드의 액션
예고 구간의 노드에 액션을 붙여 보내면 검증은 통과하지만 actionStates는 비어 있었고(nodeStates에만 노드가 나타남), 4초 뒤 같은 orderId에 orderUpdateId 1로 그 노드를 확정(released)하자 비로소 액션이 WAITING으로 나타나고 차량이 주행을 시작했습니다. 소스에서 keep = node.released로 액션 저장 여부를 정하는 것과 맞는 동작입니다.
자주 부딪히는 문제와 해결
1. 액션 하나 때문에 order 전체가 거절된다.
오류가 하나라도 있으면 order가 통째로 반려됩니다. 정상 액션까지 같이 사라지므로, 관제는 order를 보내기 전에 factsheet의 agvActions로 같은 검사(위치, blockingType, 필수 파라미터, 타입)를 해 두는 편이 낫습니다. 거절 오류 중 상당수는 errorReferences에 action.actionId나 action.actionType이 들어 있어(알 수 없는 액션, 알 수 없는 파라미터, 필수 파라미터 누락, 위치 위반) 어떤 액션인지 바로 찾을 수 있습니다. blockingType 오류는 action.blockingType과 허용 목록만 담으므로 errorDescription도 함께 봅니다.
2. 예고 노드의 액션도 검증된다.
지금 실행하지 않을 액션도 등록 시점에 검증됩니다. 예고 구간에 아직 정해지지 않은 파라미터를 넣으면 거절되므로, 파라미터를 알 수 없는 액션은 확정할 때 orderUpdateId를 올려 보내는 방식이 안전합니다.
3. 선언에 HARD만 열어 두었는데 관제가 NONE을 보낸다.
기본 선언(pick, drop, startCharging 등)은 HARD만 허용합니다. 관제 쪽 기본값이 NONE이면 첫 시도에서 모두 거절됩니다. 필요하면 선언을 복사해 blocking_types를 넓히되, NONE을 허용한다는 것은 주행 중에 시작될 수 있다는 뜻이므로 핸들러가 그 상황을 감당할 수 있어야 합니다.
4. 파라미터 타입이 안 맞는다.
height는 실수, loadId는 문자열처럼 선언한 타입대로 JSON 값이 와야 합니다. 실수 자리에 문자열 “1.0”을 보내면 validationError입니다. 숫자 필드를 문자열로 보내는 관제 구현이 흔하니, 첫 연동에서 이 오류를 보면 JSON 타입부터 확인합니다.
5. 콜백을 비워 두었다.
on_pause 등을 비우면 pause 때 예외가 납니다. 의미 없는 콜백은 빈 함수라도 채우고, 의미가 있다면 setPaused()/setRunning()을 반드시 부릅니다. 부르지 않으면 상태가 전이하지 않습니다.
6. 장비 응답이 없는데 액션이 영원히 RUNNING이다.
라이브러리에 액션 시간 제한이 없습니다. on_start에서 타이머를 같이 시작해 시간이 지나면 addError로 오류를 싣고 setFailed()로 끝내십시오.
7. on_start에서 오래 블로킹한다.
콜백은 라이브러리 이벤트 처리 흐름에서 불립니다. 장비 응답을 그 자리에서 기다리면 다른 이벤트 처리가 막힙니다. 별도 스레드나 비동기 이벤트로 넘기고, 넘길 때 ActionState를 shared_ptr로 복사해 수명을 보장해야 합니다. 같은 문제를 어댑터 만들기에서도 다뤘습니다.
8. 선언만으로 표현할 수 없는 조건이 있다.
“현재 위치가 역과 맞는가”, “맵 목록에 있는가” 같은 조건은 선언이 모릅니다. 두 곳에서 처리할 수 있습니다. 실행 전에 알 수 있는 것은 validate() 재정의로 order 단계에서 거절하고, 실행 중에야 알 수 있는 것은 on_start에서 확인해 addError와 setFailed로 보고합니다. 이 글의 시뮬레이터가 stationMismatch와 noPickStation을 실행 시점에 보고하는 것이 후자의 예입니다.
9. 관제가 예고 노드 액션의 WAITING을 기다린다.
예고 노드의 액션은 확정 전까지 actionStates에 없습니다. 관제가 “보낸 액션이 모두 state에 보인다”고 가정하면 오작동하므로, 확정 여부에 따라 기대 상태를 달리 계산해야 합니다.
실무 팁
- 새 액션은 먼저
on_start에서setRunning()뒤 바로setFinished()를 부르는 빈 구현으로 등록하고, 관제와 order 왕복만 확인한 다음 실제 동작을 붙입니다. - 액션 하나당 핸들러가 하나일 필요는 없습니다.
SimpleMultiActionHandler에 선언 목록을 주고,prepare안에서action_state->getAction().actionType으로 갈라서 처리하면 장비 접근 코드를 한곳에 모을 수 있습니다. - 오류 이름은 구현체마다 다르므로(
unknownActionType,instantActionError는 표준 목록에 없고 이 라이브러리가 붙인 이름), 관제는 이름 문자열만 보지 말고errorDescription과errorReferences를 함께 로그에 남깁니다. - 실패 오류는
addError로 싣고(setFailed의 인자만으로는 State에 안 올라옵니다), 무엇이 안 맞았는지(stationMismatch처럼 이름과 사람이 읽을 설명)를 담습니다. 관제 운영자가 State만 보고 원인을 알 수 있습니다. - 개발 중에는 시뮬레이터나 mosquitto 위에서 거절 케이스를 먼저 만들어 보십시오. 위 표의 아홉 가지 입력은 그대로 회귀 테스트로 쓸 수 있습니다.
한계
라이브러리 동작은 v2.11.3 소스와 이 라이브러리 위에 만든 시뮬레이터의 실행 결과이며, 다른 버전이나 다른 VDA5050 구현체에서는 다를 수 있습니다. 실행은 로컬 컨테이너의 가상 차량에서 한 것이라 실제 장비의 응답 시간이나 안전 장치와의 상호작용은 다루지 않았습니다. 표준의 세부 규칙은 VDA5050 2.0.0 문서를 기준으로 하며 이후 버전에서 바뀌었는지는 확인하지 않았습니다.