設定與儲存模組參數
這篇接續讓模組接收自己的指令,替發送端加入 step 參數,決定每次序號增加多少。預設增加 1,運行中可以改成 5,不必重新啟動 Module。
這次啟動帶參數的 parameterPublisher,接收端沿用 counterSubscriber。實例名稱仍是 sender 和 receiver。
1. 建置並啟動範例
Section titled “1. 建置並啟動範例”若前一次的 Vinc Shell 還開著,先輸入 exit。在 open-vinc-examples 根目錄重新建置,再從 PowerShell 開啟 Shell:
cmake --build build/debug.\build\debug\Vinc.execmake --build build/python.\build\python\Vinc.exe --python .\.venv\Scripts\python.exe若還沒準備建置目錄,請先完成跨程序訊息或 Python 環境準備。
看到 VINC ready 後,在 Vinc Shell 啟動接收端:
counterSubscriber等到 ready receiver 和 Started receiver,再啟動本篇的發送端:
parameterPublisher等到 ready sender 和 Started sender。第一次執行時也會看到 step=1,這幾行的顯示順序可能不同。
若先前已保存其他步進,先輸入 param set sender.step 1,等到 step=1,就能從相同起點重做本篇操作。
2. 查看預設值並送一筆訊息
Section titled “2. 查看預設值並送一筆訊息”param get sender.step輸出包含:
sender.step [uint64] = 1sender.step 由實例名稱 sender 和參數名稱 step 組成;uint64 表示非負整數型別。
接著發送第一筆:
sender send等待接收端印出:
received sequence=1 publisher=sender3. 運行中把步進改成 5
Section titled “3. 運行中把步進改成 5”param set sender.step 5中央會回報 Parameter committed (not saved)。等到發送端也印出下列訊息,才繼續操作:
step=5這表示模組已經套用新設定。可以再查一次中央目前的值:
param get sender.step輸出中的值會變成 5。再發送一筆:
sender send等到接收端印出:
received sequence=6 publisher=sender因為上一筆是 1,加上新的步進 5,所以這筆是 6。再輸入一次 sender send,等待:
received sequence=11 publisher=senderModule 一直保持運行,只改變每次發送時使用的設定。sender send 是執行動作的指令,sender.step 則是調整行為的參數。
4. 儲存設定,重啟後沿用
Section titled “4. 儲存設定,重啟後沿用”剛才的 param set 只修改執行中的值。要讓下次啟動仍使用 5,在 Vinc Shell 輸入:
param save等待 Parameters saved。這會保存目前所有參數的設定;單獨輸入 exit 不會自動保存剛才的調整。
接著關閉中央與兩個 Module:
exit回到 PowerShell 後,重新啟動同一個 Vinc,不需要重新建置:
.\build\debug\Vinc.exe.\build\python\Vinc.exe --python .\.venv\Scripts\python.exe看到 VINC ready 後,在 Vinc Shell 啟動接收端:
counterSubscriber等到 ready receiver 和 Started receiver,再啟動發送端:
parameterPublisher這次等到 ready sender、Started sender 和 step=5。再查一次:
param get sender.step輸出包含:
sender.step [uint64] = 5原始碼的預設值仍是 1,這次啟動會套用先前保存的 5。送出一筆:
sender send等待接收端印出:
received sequence=5 publisher=sender再輸入一次 sender send,等待:
received sequence=10 publisher=sender參數設定保留了,模組的計數狀態則重新開始。 上一筆序號從 0 開始,套用步進 5,所以依序是 5、10。
5. 在程式中登記參數
Section titled “5. 在程式中登記參數”在 on_start() 登記 step,再設定參數變更時要呼叫的函式:
vinc::Result<void> on_start(const std::vector<std::string>&) override { // 啟動 hook:實例名稱核准後,由框架呼叫。 // 在這裡初始化模組;回傳 {} 代表初始化成功。 auto registered = context.param.register_param<std::uint64_t>("step", 1); if (!registered) { return std::unexpected(registered.error()); }
auto watching = context.param.on_change([this](const vinc::param::ParamMap&) { on_parameters_changed(); }); if (!watching) { return std::unexpected(watching.error()); }
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 {};}parameters/publisher.cpp · e165aed · 中文註解
register_param<std::uint64_t>("step", 1) 指定名稱、型別和預設值。成功後會自動監聽這個參數。
on_change() 的 lambda 只轉交給具名的 on_parameters_changed()。每個 Result 都保留錯誤檢查。
def on_start(self, args): # 啟動 hook:實例名稱核准後,由框架呼叫。 # 在這裡初始化模組;回傳 None 代表初始化成功。 self.sequence = 0 self.step = 1 self.context.param.register_param("step", vinc.param.Type.UInt64, 1) self.context.param.on_change(self.on_parameters_changed) self.publisher = self.context.advertise( vinc.messages.CounterSample, "tutorial/counter" ) print("ready sender")python/modules/parameterPublisher/parameterPublisher.py · e165aed · 中文註解
register_param("step", vinc.param.Type.UInt64, 1) 指定名稱、型別和預設值。成功後會自動監聽這個參數。
on_change(self.on_parameters_changed) 直接指定具名函式作為 callback。
Module 內使用自己的簡稱 step,Shell 則使用完整名稱 sender.step。本例沿用預設權限,透過中央的 param set 修改。
6. 套用設定並繼續發送
Section titled “6. 套用設定並繼續發送”參數更新後,框架會呼叫 on_parameters_changed()。從本地快取讀取最新值,再印出確認:
void on_parameters_changed() { // 參數 callback:從框架的本地快取讀取最新的 step。 auto updated = context.param.update("step", step_); if (!updated) { std::cerr << vinc::error_to_string(updated.error()) << std::endl; return; }
std::cout << "step=" << step_ << std::endl;}parameters/publisher.cpp · e165aed · 中文註解
update("step", step_) 把快取值寫進成員 step_。若讀取失敗,程式保留先前的值並回報錯誤。
def on_parameters_changed(self, values): # 參數 callback:從框架的本地快取讀取最新的 step。 try: self.step = self.context.param.update("step", vinc.param.Type.UInt64) except vinc.VincError as error: print(error) return
print(f"step={self.step}")python/modules/parameterPublisher/parameterPublisher.py · e165aed · 中文註解
update("step", vinc.param.Type.UInt64) 回傳快取值,存到 self.step。若讀取失敗,範例捕捉 VincError,保留先前的值。
中央接受 param set 與 Module 套用更新是兩件事,因此操作時要等到 step=5。使用 FrameworkLoop 時,框架會負責派送更新,不需要自己輪詢。
每次發送時,用「上一筆序號 + 目前步進」計算新序號,成功送出後才記錄它:
const auto next_sequence = sequence_ + step_; 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; }
sequence_ = next_sequence;def module_interface(self, args): # 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。 # 回傳 0 表示成功,回傳 1 表示指令執行失敗。 # args 只包含指令參數,實例名稱已經移除。 if args != ["send"]: print("Usage: sender send") return 1
next_sequence = self.sequence + self.step if next_sequence > 2**64 - 1: print("sequence limit reached") return 1
try: message = vinc.make_message(vinc.messages.CounterSample) message.data().sequence = next_sequence self.publisher.push(message) except vinc.VincError as error: print(error) return 1
self.sequence = next_sequence return 0python/modules/parameterPublisher/parameterPublisher.py · e165aed · 中文註解
每次啟動時,上一筆序號都從 0 開始。步進預設為 1,有已保存設定時會套用該值;運行中修改步進則不會清除目前的序號。
7. 正常關閉
Section titled “7. 正常關閉”exit等到兩個 Module 停止並回到 PowerShell。
之後若再用 param set 調整設定,記得執行 param save,才會在下次啟動時沿用。
接著閱讀第一個 RPC:讓模組互相詢問,由 sender 詢問 receiver 的接收數量。