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.0RUNNING 후 약 1.5초 뒤 FINISHED, resultDescription: "map=floor2", agvPosition.mapId가 floor2로 바뀜통과
targetMap: map, speed: 5.0orderError: Expected a value not greater then 2, got 5선언의 범위
targetMap: floor9orderError: 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 orderorderUpdateError: Order ID does not match the current (unfinished) one
일시정지 중 cancelOrderchangeMap 액션 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를 함께 부르면 같은 오류가 두 번 올라가는지는 확인하지 않았습니다.