第一個跨程序訊息
這篇接續第一個運行模組,讓兩個 Module 交換訊息:sender 負責發送計數,receiver 收到後印出內容。
1. 沿用範例專案
Section titled “1. 沿用範例專案”使用上一篇的 open-vinc-examples,不需要重新下載。以下命令都從專案根目錄執行,也就是看得到 framework/、modules/ 與 messages/ 的位置。
選擇 Python 時,請先完成準備 Python 範例。C++ 工具準備見建置指南。
2. 建置範例
Section titled “2. 建置範例”這次使用專案根目錄的 CMakeLists.txt,建置兩個計數 Module:
cmake -S . -B build/debug -G Ninja -DCMAKE_BUILD_TYPE=Debugcmake --build build/debug建置完成後,下一步會執行 build/debug/Vinc.exe。
Python 準備頁已建置 SDK 和計數訊息型別,沿用 build/python/ 即可。若修改過 Python 程式,執行以下命令複製更新:
cmake --build build/python3. 啟動兩個 Module
Section titled “3. 啟動兩個 Module”在 PowerShell 開啟中央的 Vinc Shell:
.\build\debug\Vinc.exe.\build\python\Vinc.exe --python .\.venv\Scripts\python.exe中央已啟動內建 Web UI 與 Recorder;這篇要操作的 sender、receiver 還沒建立。
接下來的命令輸入在 Vinc Shell,不是 PowerShell。先啟動 Subscriber:
counterSubscriber等待看見 ready receiver 與 Started receiver,再啟動 Publisher:
counterPublisher等待看見 ready sender 與 Started sender。啟動時輸入 ModuleType,之後操作使用實例名稱:
| 用途 | ModuleType | 實例名稱 |
|---|---|---|
| 接收訊息 | counterSubscriber |
receiver |
| 發送訊息 | counterPublisher |
sender |
4. 傳送第一筆訊息
Section titled “4. 傳送第一筆訊息”在 Vinc Shell 輸入:
sender send等待接收端印出這行內容;實際輸出還會包含來源前綴:
received sequence=1 publisher=sender這表示 receiver 收到序號為 1 的訊息,發布者是 sender。
接著查詢接收數量:
receiver status輸出會包含:
received=1請等到接收輸出出現後再查詢。若要再送一筆,重複輸入 sender send,等待接收端印出下一個序號後再查詢。
接下來閱讀程式,看看這筆訊息如何從 sender 到達 receiver。
5. 定義訊息
Section titled “5. 定義訊息”messages/CounterSample.msg 定義要傳送的資料:
uint64_t sequence;messages/CounterSample.msg · e165aed
sequence 是計數值。同一份定義可供兩種語言使用:
建置時產生 vinc::CounterSample 型別與 <vinc_messages/CounterSample.hpp>。
建置時把型別加入 SDK,程式透過 vinc.messages.CounterSample 使用。修改 .msg 後需要重新建置 SDK。
6. Publisher:發送訊息
Section titled “6. Publisher:發送訊息”#include <vinc/vinc.hpp>#include <vinc_messages/CounterSample.hpp>
#include <cstdint>#include <iostream>#include <optional>#include <string>#include <utility>#include <vector>
class CounterPublisher final : public vinc::BaseModule<vinc::RunMode::FrameworkLoop> {public: CounterPublisher() : BaseModule("sender") { // 設定 Shell 指令使用的實例名稱。 }
vinc::Result<void> on_start(const std::vector<std::string>&) override { // 啟動 hook:實例名稱核准後,由框架呼叫。 // 在這裡初始化模組;回傳 {} 代表初始化成功。 auto publisher = context.advertise<vinc::CounterSample>( "tutorial/counter"); if (!publisher) { return std::unexpected(publisher.error()); }
publisher_.emplace(std::move(*publisher)); std::cout << "ready sender" << std::endl; return {}; }
vinc::Result<std::int32_t> module_interface(std::vector<std::string> args) override { // 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。 // 回傳 0 表示成功,回傳 1 表示指令執行失敗。 // 原生 Shell 會附上目標名稱;直接透過 Manager 呼叫時可以省略。 if (!args.empty() && args.front() == get_module_name()) { args.erase(args.begin()); }
if (args.size() != 1 || args.front() != "send") { std::cout << "Usage: sender send" << std::endl; return 1; }
auto message = vinc::make_message<vinc::CounterSample>(); message->data().sequence = next_sequence_;
auto published = publisher_->push(*message); if (!published) { std::cerr << vinc::error_to_string(published.error()) << std::endl; return 1; }
++next_sequence_; return 0; }
vinc::Result<void> on_stop() override { // 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。 publisher_.reset(); std::cout << "stopped sender" << std::endl; return {}; }
private: std::optional<vinc::message_bus::Publisher<vinc::CounterSample>> publisher_; std::uint64_t next_sequence_ = 1;};
// 登記 Shell 用來建立此模組的種類名稱。REGISTER_MODULE(CounterPublisher, "counterPublisher")modules/publisher.cpp · e165aed · 中文註解
先看這幾個步驟:
on_start()用context.advertise()建立 Publisher,並存到成員publisher_,讓它在 Module 運行期間持續存在。sender send進入module_interface(),用make_message()建立訊息,填入sequence。publisher_->push(*message)發送訊息,成功後才增加下一筆序號。on_stop()釋放 Publisher。
程式保留每個 Result 的錯誤檢查,讓註冊或發送失敗時可以回報錯誤。
import vinc
class Module(vinc.BaseModule, mode=vinc.RunMode.FrameworkLoop): def on_name(self, args): # 命名 hook:回傳 Shell 用來識別此模組的實例名稱。 # 發布與訂閱請稍後在 on_start 裡建立。 return "sender"
def on_start(self, args): # 啟動 hook:實例名稱核准後,由框架呼叫。 # 在這裡初始化模組;回傳 None 代表初始化成功。 self.publisher = self.context.advertise( vinc.messages.CounterSample, "tutorial/counter" ) self.next_sequence = 1 print("ready sender")
def module_interface(self, args): # 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。 # 回傳 0 表示成功,回傳 1 表示指令執行失敗。 # args 只包含指令參數,實例名稱已經移除。 if args != ["send"]: print("Usage: sender send") return 1
try: message = vinc.make_message(vinc.messages.CounterSample) message.data().sequence = self.next_sequence self.publisher.push(message) except vinc.VincError as error: print(error) return 1
self.next_sequence += 1 return 0
def on_stop(self): # 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。 self.publisher.close() print("stopped sender")python/modules/counterPublisher/counterPublisher.py · e165aed · 中文註解
on_start()用self.context.advertise()建立 Publisher,存到self.publisher。sender send進入module_interface(),用vinc.make_message()建立訊息,填入message.data().sequence。self.publisher.push(message)發送訊息,成功後才增加下一筆序號。on_stop()用close()釋放 Publisher。
發送失敗時,範例捕捉 vinc.VincError 並回傳 1,讓這次指令失敗,Module 仍可繼續接收指令。
兩種版本都先使用框架預設容量;接收太慢仍可能漏資料。
7. Subscriber:接收訊息
Section titled “7. Subscriber:接收訊息”#include <vinc/vinc.hpp>#include <vinc_messages/CounterSample.hpp>
#include <cstdint>#include <iostream>#include <memory>#include <optional>#include <string>#include <utility>#include <vector>
class CounterSubscriber final : public vinc::BaseModule<vinc::RunMode::FrameworkLoop> {public: CounterSubscriber() : BaseModule("receiver") { // 設定 Shell 指令使用的實例名稱。 }
vinc::Result<void> on_start(const std::vector<std::string>&) override { // 啟動 hook:實例名稱核准後,由框架呼叫。 // 在這裡初始化模組;回傳 {} 代表初始化成功。 auto subscriber = context.subscribe<vinc::CounterSample>( "tutorial/counter", [this](std::unique_ptr<vinc::CounterSample> message) { on_message(std::move(message)); }); if (!subscriber) { return std::unexpected(subscriber.error()); }
subscriber_.emplace(std::move(*subscriber)); std::cout << "ready receiver" << std::endl; return {}; }
vinc::Result<std::int32_t> module_interface(std::vector<std::string> args) override { // 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。 // 回傳 0 表示成功,回傳 1 表示指令執行失敗。 if (!args.empty() && args.front() == get_module_name()) { args.erase(args.begin()); }
if (args.empty()) { args.push_back("status"); }
if (args.size() == 1 && args.front() == "status") { std::cout << "received=" << received_ << std::endl; return 0; }
if (args.size() == 1 && args.front() == "reset") { received_ = 0; std::cout << "counter reset" << std::endl; return 0; }
std::cout << "Usage: receiver [status|reset]" << std::endl; return 1; }
vinc::Result<void> on_stop() override { // 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。 subscriber_.reset(); std::cout << "stopped receiver" << std::endl; return {}; }
private: void on_message(std::unique_ptr<vinc::CounterSample> message) { // 訂閱 callback:計數訊息送達時,由框架呼叫。 ++received_;
// 立即送出輸出緩衝區的內容,讓互動範例及時顯示接收結果。 std::cout << "received sequence=" << message->data().sequence.get() << " publisher=" << message->publisher_name() << std::endl; }
std::optional<vinc::message_bus::Subscriber<vinc::CounterSample>> subscriber_; std::uint64_t received_ = 0;};
// 登記 Shell 用來建立此模組的種類名稱。REGISTER_MODULE(CounterSubscriber, "counterSubscriber")modules/subscriber.cpp · e165aed · 中文註解
接收端分成兩個部分:
on_start()用context.subscribe()訂閱"tutorial/counter",並把訂閱存到成員subscriber_。- 收到訊息時,lambda 只負責呼叫
on_message();計數與輸出都寫在這個具名函式裡。
[this] 讓 lambda 可以呼叫目前物件的成員函式。std::move(message) 把這筆訊息的所有權交給 on_message()。函式內的 publisher_name() 可讀出發布者名稱。
訂閱要存成成員,才能在 on_start() 返回後繼續接收;on_stop() 再釋放它。
import vinc
class Module(vinc.BaseModule, mode=vinc.RunMode.FrameworkLoop): def on_name(self, args): # 命名 hook:回傳 Shell 用來識別此模組的實例名稱。 # 發布與訂閱請稍後在 on_start 裡建立。 return "receiver"
def on_start(self, args): # 啟動 hook:實例名稱核准後,由框架呼叫。 # 在這裡初始化模組;回傳 None 代表初始化成功。 self.received = 0 self.subscriber = self.context.subscribe( vinc.messages.CounterSample, "tutorial/counter", self.on_message ) print("ready receiver")
def module_interface(self, args): # 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。 # 回傳 0 表示成功,回傳 1 表示指令執行失敗。 # args 只包含指令參數,實例名稱已經移除。 if not args: args = ["status"]
if args == ["status"]: print(f"received={self.received}") return 0
if args == ["reset"]: self.received = 0 print("counter reset") return 0
print("Usage: receiver [status|reset]") return 1
def on_message(self, message): # 訂閱 callback:計數訊息送達時,由框架呼叫。 self.received += 1 print( f"received sequence={message.data().sequence} " f"publisher={message.publisher_name()}" )
def on_stop(self): # 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。 self.subscriber.close() print("stopped receiver")python/modules/counterSubscriber/counterSubscriber.py · e165aed · 中文註解
on_start() 用 self.context.subscribe() 訂閱 topic,把 self.on_message 當作接收函式。收到訊息時,框架會呼叫這個具名函式,完成計數與輸出。
message.data().sequence 讀取計數值,message.publisher_name() 讀取發布者名稱。
訂閱存到 self.subscriber,才能在 on_start() 返回後繼續接收;on_stop() 用 close() 釋放它。
發送端與接收端必須使用相同的 topic 名稱 "tutorial/counter"。
8. 用 CMake 組裝
Section titled “8. 用 CMake 組裝”cmake_minimum_required(VERSION 3.20)project(open_vinc_counter_example LANGUAGES C CXX)
if(MSVC) add_compile_options("$<$<COMPILE_LANGUAGE:CXX>:/utf-8>")endif()
set(VINC_NAME "counter-example" CACHE STRING "Central instance identity")set(VINC_BUILD_APPS OFF CACHE BOOL "Build the framework's demonstration app")set(BUILD_TESTING OFF CACHE BOOL "Build the framework's internal tests")
add_subdirectory(framework/open-vinc/src open-vinc)add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/messages")
add_module(counter_publisher MODULE_TYPE_NAME counterPublisher SOURCES modules/publisher.cpp)add_module(counter_subscriber MODULE_TYPE_NAME counterSubscriber SOURCES modules/subscriber.cpp)
add_subdirectory(parameters)add_subdirectory(rpc)add_subdirectory(logging)add_subdirectory(custom-message)
vinc_add_app(Vinc INSTANCE_NAME "${VINC_NAME}" VINC_BUILD_CONFIG vinc.conf)
# 固定教學使用的執行檔路徑,Tcl 也會部署到相同位置。set_target_properties(Vinc PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}")
include(tests/CMakeLists.txt)CMakeLists.txt · e165aed · 中文註解
本篇在上一篇的基礎上加入訊息定義與第二個 Module,先掌握這四個指令:
add_subdirectory():加入框架。add_message_dir():加入messages/的訊息定義。add_module():分別建立 Publisher 與 Subscriber。vinc_add_app():依vinc.conf組裝這個 App。
set_target_properties() 讓執行檔放在 build/debug/。最後的測試 include() 可以先略過。
cmake_minimum_required(VERSION 3.20)project(open_vinc_python_tutorials LANGUAGES C CXX)
set(VINC_NAME "python-tutorials" CACHE STRING "Central instance identity")set(VINC_BUILD_APPS OFF CACHE BOOL "Build the framework's demonstration app")set(BUILD_TESTING OFF CACHE BOOL "Build the framework's internal tests")
add_subdirectory(../framework/open-vinc/src open-vinc)add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/../messages")
if(WIN32) set(default_python "${CMAKE_CURRENT_SOURCE_DIR}/../.venv/Scripts/python.exe")else() set(default_python "${CMAKE_CURRENT_SOURCE_DIR}/../.venv/bin/python")endif()set(TUTORIAL_PYTHON_EXECUTABLE "${default_python}" CACHE FILEPATH "Python used by tutorial modules")configure_file(vinc.conf.in "${CMAKE_CURRENT_BINARY_DIR}/vinc.conf" @ONLY)vinc_add_app(Vinc INSTANCE_NAME "${VINC_NAME}" VINC_BUILD_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/vinc.conf")
set_target_properties(Vinc PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}")
include(cmake/DeployModules.cmake)include(tests/CMakeLists.txt)python/CMakeLists.txt · e165aed
Python 入口透過 vinc.conf.in 的 CONFIG_VINC_APP_PYTHON=y 啟用綁定,並用 add_message_dir() 加入同一份訊息定義。CMake 會將專案的 Python 環境路徑填入設定檔。
DeployModules.cmake 把 python/modules/ 複製到執行檔旁的 data/module/。Python 模組由中央掃描,不需要逐一呼叫 add_module()。最後的測試 include() 可以先略過。
9. 正常關閉
Section titled “9. 正常關閉”閱讀完成後,在 Vinc Shell 輸入:
exit你會看見 stopped sender、stopped receiver;兩者的輸出順序可能不同。中央等待兩個程序退出後,會返回 PowerShell。
你已經完成兩個 Module 的啟動、訊息收發與正常關閉。接下來閱讀自訂訊息,練習定義自己的數值與字串欄位。