libVDA5050++ 커스텀 액션 만들기: changeMap 예제로 보는 validate 재정의, 시간 제한, pause·cancel 처리
이 글의 핵심
새 액션을 만들 때 할 일은 네 가지입니다. ActionDeclaration으로 이름·파라미터(타입·범위)·blockingType·사용 위치를 선언하고, 런타임 정보가 필요한 검사는 validate()를 재정의해 기본 검사 뒤에 덧붙이고, prepare()에서 on_start·on_pause·on_resume·on_cancel을 모두 채우고, 시간 제한과 실패 보고를 직접 구현합니다. 2.11.3은 setFailed(errors)의 오류를 State에 싣지 않으므로 StatusSink().addError()를 함께 불러야 하고, 콜백을 비워 두면 해당 instantAction이 RUNNING에 머뭅니다.
앞 글에서 선언과 핸들러의 경계를 정리했습니다. 이 글은 그 경계 위에서 실제로 새 액션을 하나 만들어 봅니다. 맵을 바꾸는 changeMap 액션을 선언하고, 불러 두지 않은 맵은 order 단계에서 거절하고, 장비가 응답하지 않으면 4초 뒤 실패로 끝내고, 일시정지와 취소에 반응하게 만든 다음, 직접 빌드해 mosquitto 브로커에 붙여 order를 보낸 결과를 봅니다. initPosition 핸들러도 같이 만듭니다.
환경은 라이브러리 v2.11.3, 우분투 24.04 aarch64 컨테이너(g++ 13, C++17), eclipse-mosquitto:2입니다. 아래 코드는 실제로 컴파일해 실행한 것이고, 내비게이션 핸들러는 어댑터 만들기의 1 m/s 직선 이동 예제와 같은 구조라 생략했습니다. ToyNavigation은 위치를 바꾸는 placeAt(x, y, map)과 현재 맵을 바꾸는 setMap(map)을 추가로 가진 클래스입니다.
1. 선언: 이름, 파라미터, 범위, 위치
static vda5050pp::agv_description::ActionDeclaration changeMapDecl() {
using namespace vda5050pp::agv_description;
ActionDeclaration d;
d.action_type = "changeMap";
d.description = "Switch the active map";
d.parameter = {ParameterRange{"targetMap", ParameterValueType::k_string, "id of the target map",
std::nullopt, std::nullopt, std::nullopt}};
d.optional_parameter = {ParameterRange{"speed", ParameterValueType::k_float, "m/s while switching",
ConstraintValue(0.1), ConstraintValue(2.0), std::nullopt}};
d.blocking_types = {vda5050::BlockingType::HARD};
d.node = true; // instant, edge는 기본값 false
return d;
}
ParameterRange의 마지막 세 인자는 최솟값, 최댓값, 허용 값 집합입니다. 이 선언만으로 factsheet의 agvActions에 아래처럼 올라갔고, 범위가 설명에 자동으로 붙었습니다.
{"actionType": "changeMap", "actionScopes": ["NODE"],
"actionDescription": "Switch the active map",
"actionParameters": [
{"key": "targetMap", "valueDataType": "STRING", "isOptional": false,
"description": "Parameter targetMap:\nid of the target map"},
{"key": "speed", "valueDataType": "FLOAT", "isOptional": true,
"description": "Parameter speed:\nm/s while switching\n Must be in [0.100000, 2.000000]"}]}
2. validate() 재정의: 기본 검사 뒤에 런타임 검사 덧붙이기
선언이 모르는 정보는 “지금 이 차량에 어떤 맵이 올라와 있는가”입니다. SimpleActionHandler::validate를 먼저 부르고, 기본 검사를 통과했을 때만 맵 목록을 확인합니다.
class ChangeMapHandler : public vda5050pp::handler::SimpleActionHandler {
public:
ChangeMapHandler(std::shared_ptr<ToyNavigation> nav)
: SimpleActionHandler(changeMapDecl()), nav_(std::move(nav)) {}
ValidationResult validate(const vda5050::Action &action,
vda5050pp::misc::ActionContext ctx) noexcept(true) override {
auto result = SimpleActionHandler::validate(action, ctx); // 기본 검사 먼저
if (result.errors.empty()) {
const auto &target = std::get<std::string>(result.parameters.at("targetMap"));
if (loaded_.count(target) == 0) {
vda5050::Error e;
e.errorType = "orderError";
e.errorLevel = vda5050::ErrorLevel::WARNING;
e.errorDescription = "Map \"" + target + "\" is not loaded on this vehicle";
e.errorReferences = {{"action.actionId", action.actionId},
{"action.parameter.key", "targetMap"}};
result.errors.push_back(e);
}
}
return result;
}
// prepare(), reset() ...
private:
std::set<std::string> loaded_{"map", "floor2"};
};
validate가 돌려준 result.parameters는 이미 선언한 타입으로 변환돼 있어서(std::get<std::string>) 다시 JSON을 파싱할 필요가 없습니다. 이 맵은 prepare에도 같은 ParametersMap으로 전달됩니다.
order에 changeMap을 넣어 보낸 결과입니다.
| 보낸 값 | 결과 | 어디서 거른 것 |
|---|---|---|
targetMap: floor2, speed: 1.0 | RUNNING 후 약 1.5초 뒤 FINISHED, resultDescription: "map=floor2", agvPosition.mapId가 floor2로 바뀜 | 통과 |
targetMap: map, speed: 5.0 | orderError: Expected a value not greater then 2, got 5 | 선언의 범위 |
targetMap: floor9 | orderError: Map "floor9" is not loaded on this vehicle | 재정의한 validate() |
targetMap 없음 | orderError: Missing action parameters: ["targetMap"] | 선언의 필수 파라미터 |
거절된 order는 state의 현재 order(앞서 성공한 M1)를 건드리지 않았고 errors에만 쌓였습니다.
3. prepare(): 콜백 네 개와 시간 제한
ActionCallbacks prepare(std::shared_ptr<ActionState> st,
std::shared_ptr<ParametersMap> params) noexcept(false) override {
const std::string target = std::get<std::string>(params->at("targetMap"));
auto cancelled = std::make_shared<std::atomic<bool>>(false);
auto paused = std::make_shared<std::atomic<bool>>(false);
ActionCallbacks cbs;
cbs.on_start = [this, st, target, cancelled, paused](ActionState &) {
st->setRunning();
std::thread([this, st, target, cancelled, paused] {
auto t0 = std::chrono::steady_clock::now();
std::chrono::milliseconds waited{0};
const auto need = hang_ ? 3600s : 1500ms; // 장비 응답을 흉내 (hang_이면 무응답)
while (waited < need) {
std::this_thread::sleep_for(100ms);
if (cancelled->load()) { st->setFailed(); return; }
if (paused->load()) continue;
waited += 100ms;
if (std::chrono::steady_clock::now() - t0 > 4s) { // 직접 만든 시간 제한
vda5050::Error e;
e.errorType = "mapChangeTimeout";
e.errorLevel = vda5050::ErrorLevel::WARNING;
e.errorDescription = "map server did not answer within 4 s";
vda5050pp::sinks::StatusSink().addError(e); // 2.11.3: 이게 있어야 State errors에 올라온다
st->setFailed({e});
return;
}
}
nav_->setMap(target);
st->setFinished("map=" + target);
}).detach();
};
cbs.on_cancel = [cancelled](ActionState &) { cancelled->store(true); };
cbs.on_pause = [paused, st](ActionState &) { paused->store(true); st->setPaused(); };
cbs.on_resume = [paused, st](ActionState &) { paused->store(false); st->setRunning(); };
return cbs;
}
설계에서 지킨 점이 세 가지입니다.
- 콜백은 바로 돌아옵니다. 오래 걸리는 일은 별도 스레드에서 하고, 콜백에는
ActionState의shared_ptr복사본(st)을 쥐어 줍니다. 콜백 인자로 받는 참조 대신 이 복사본을 쓰는 이유는 스레드가 콜백보다 오래 살기 때문입니다. - 끝내는 호출(
setFinished/setFailed)은 작업 스레드 한 곳에서만 합니다.on_cancel은 플래그만 세우고, 스레드가 그 플래그를 보고setFailed()를 부릅니다. 두 곳에서 부르면 상태 전이 예외가 날 수 있습니다. - 시간 제한은 라이브러리에 없으므로 직접 넣었습니다.
실행 결과
| 상황 | 관찰한 State |
|---|---|
장비 무응답(hang_) | RUNNING → 약 4.1초 뒤 FAILED, errors에 mapChangeTimeout |
같은 상황에서 addError 없이 setFailed({e})만 | FAILED는 되지만 errors는 비어 있음 |
실행 중 startPause | 액션 PAUSED, paused: true, startPause 액션은 FINISHED |
이어서 stopPause | 액션 RUNNING으로 복귀, 이어서 FINISHED(map=floor2). 일시정지한 시간은 이 예제가 작업 시간에 넣지 않음 |
일시정지 중 새 orderId order | orderUpdateError: Order ID does not match the current (unfinished) one |
일시정지 중 cancelOrder | changeMap 액션 FAILED, cancelOrder 액션 FINISHED |
일시정지 중인 order는 끝나지 않은 order로 취급됩니다. 새 작업을 보내기 전에 stopPause나 cancelOrder가 필요합니다.
콜백을 비워 두면
on_pause, on_resume만 채우지 않은 빌드(TOY_NO_PAUSE)로 같은 order를 보내고 startPause를 보냈습니다. 라이브러리 로그에 아래 예외가 남았습니다.
[events] [error] ActionEventManager caught an exception, while processing events:
VDA5050PPCallbackNotSet @ ...ActionEventHandler...: on_pause is null
프로세스는 죽지 않았지만, startPause 액션이 RUNNING에 머물렀고 changeMap은 일시정지도 되지 않은 채 6초 관찰 동안 RUNNING에 남아 끝나지 않았습니다(정상이라면 1.5초에 끝납니다). 의미 없는 콜백이라도 빈 함수로 채워야 하는 이유입니다. 일시정지를 지원하지 않는 장비라면 on_pause에서 setPaused()를 부르지 않고 setFailed로 거절하는 설계도 가능하지만, 어느 쪽이든 아무것도 안 하는 상태는 피합니다.
4. initPosition: 상속해서 handleInitPosition만 구현
initPosition은 라이브러리가 선언과 prepare까지 이미 제공하고, 실제로 위치를 바꾸는 부분만 비워 둔 클래스를 줍니다.
class ToyInitPosition : public vda5050pp::handler::InitPositionHandler {
public:
explicit ToyInitPosition(std::shared_ptr<ToyNavigation> nav) : nav_(std::move(nav)) {}
void handleInitPosition(double x, double y, double, std::string_view map_id,
std::string_view last_node_id, ActionState &st) override {
nav_->placeAt(x, y, std::string(map_id));
setLastNodeId(last_node_id); // 베이스 클래스 제공: lastNodeId를 State에 반영
st.setFinished();
}
void reset() override {}
private:
std::shared_ptr<ToyNavigation> nav_;
};
handle.registerActionHandler(std::make_shared<ToyInitPosition>(nav))로 등록합니다. 깨끗한 차량에 initPosition(x 5.0, y 2.0, mapId floor2, lastNodeId n9, HARD)을 instantAction으로 보내자 액션이 FINISHED가 되고 agvPosition이 (5.0, 2.0, floor2), lastNodeId가 n9가 됐습니다. 이 선언은 HARD만 허용해서, 같은 액션을 NONE으로 보내면 instantActionError로 거절되고 액션이 FAILED로 남았습니다(BlockingType "NONE" is not allowed, expected one of {HARD}). 한편 order가 일시정지된 상태에서 보낸 initPosition은 바로 실행되지 않고, stopPause로 재개한 뒤에야 actionStates에 WAITING으로 나타났습니다. 일시정지한 스케줄러는 끼어드는 instantAction을 받지 않기 때문입니다(blockingType 실험에서 자세히 다룹니다). 위 결과는 재시작한 깨끗한 차량에서 얻은 것입니다.
5. 등록과 main
vda5050pp::Handle handle;
handle.initialize(cfg); // 핸들러 등록은 initialize 뒤에만 가능
auto nav = std::make_shared<ToyNavigation>();
handle.registerNavigationHandler(nav);
handle.registerActionHandler(std::make_shared<ToyInitPosition>(nav));
handle.registerActionHandler(std::make_shared<ChangeMapHandler>(nav));
nav->placeAt(0.0, 0.0, "map");
Config의 MQTT 서버, interface(코드로 만든 Config는 빈 문자열이므로 "uagv"를 직접 지정), 노드 허용 오차 기본값은 어댑터 만들기와 같습니다.
만들면서 부딪힌 것
addError는vda5050++/sinks/status_sink.h에 있습니다. 이 헤더를 포함하지 않으면StatusSink를 찾지 못합니다.1500ms,4s같은 시간 리터럴을 쓰려면using namespace std::chrono_literals;가 필요합니다.- 오류 메시지의 숫자는
Expected a value not greater then 2, got 5처럼 정리된 형태로 나옵니다(then은 라이브러리 철자 그대로). - 거절된 order는 State의
errors에 계속 남으므로, 새 오류를 찾으려면 이전 State와 비교합니다.
한계
라이브러리 동작은 v2.11.3과 이 장난감 어댑터의 실행 결과입니다. 장비와의 통신은 sleep으로 흉내 냈고, 취소·일시정지 중 장비를 안전하게 멈추는 일은 실제 하드웨어마다 다릅니다. 일시정지 중 initPosition이 대기하는 이유는 소스의 스케줄러 상태 규칙으로 설명했지만, 그 예외가 로그에 남는지는 확인하지 않았습니다. 다른 버전에서는 setFailed(errors)가 State에 오류를 싣도록 고쳐졌을 수 있으며, 그 경우 addError를 함께 부르면 같은 오류가 두 번 올라가는지는 확인하지 않았습니다.