跳到內容

自訂訊息

文件對應版本v0.2.0/main 穩定版

上一篇傳送的是計數。這次改成自訂的 SensorReading:一筆訊息包含溫度 23.5 與感測器名稱 "room"。

沿用 open-vinc-examples 專案。本篇完整的 C++ 程式在 custom-message/;Python 程式在 python/modules/sensorPublisher/ 和 sensorSubscriber/。

在專案的 messages/ 建立 SensorReading.msg:

messages/SensorReading.msg
// 攝氏溫度。
double temperature;
// 產生這筆讀值的感測器名稱。
string sensor;

messages/SensorReading.msg · e165aed · 中文註解

每行是「型別 欄位名稱」,以分號結尾。這裡的 double 存溫度,string 存感測器名稱,// 後面是註解。

檔名決定訊息型別名稱。 建置後,同一份定義會產生:

語言 使用方式
C++ vinc::SensorReading,標頭為 <vinc_messages/SensorReading.hpp>
Python vinc.messages.SensorReading

欄位只寫你的應用資料。發布者名稱與訊息時間由框架提供,不必在 .msg 重複定義。

範例已設定好以下指令,同一個目錄只需加入一次。新增 .msg 時,不必每個檔案都寫一行 CMake:

專案根目錄的 CMakeLists.txt 在加入框架後呼叫:

CMakeLists.txt
add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/messages")

CMakeLists.txt · e165aed

接下來修改的是 .msg 與模組程式,不必手寫或修改生成的 .hpp。

發送端建立 SensorReading,填好兩個欄位,再呼叫 push():

custom-message/publisher.cpp 的 send_message():

custom-message/publisher.cpp
std::int32_t send_message() {
// 填入兩個欄位,確認字串寫入成功後再發送。
auto message = vinc::make_message<vinc::SensorReading>();
message->data().temperature = 23.5;
auto assigned = message->data().sensor.assign("room");
if (!assigned) {
std::cerr << vinc::error_to_string(assigned.error()) << std::endl;
return 1;
}
auto published = publisher_->push(*message);
if (!published) {
std::cerr << vinc::error_to_string(published.error()) << std::endl;
return 1;
}
return 0;
}

custom-message/publisher.cpp · e165aed · 中文註解

  • 數值欄位直接賦值:temperature = 23.5。
  • 字串欄位使用 sensor.assign("room"),並檢查回傳結果;失敗時不發送。
  • push(*message) 發送填好的訊息。

這裡的 sensor 是框架的字串欄位,不是 std::string,不要直接寫 sensor = "room"。

完整範例的 Publisher 與 Subscriber 都使用 SensorReading 型別、"tutorial/sensor" topic。型別描述資料格式,topic 則是你選擇的收發名稱;兩端必須一致。

收到訊息後,由具名的 on_message() 讀取內容:

custom-message/subscriber.cpp
void on_message(std::unique_ptr<vinc::SensorReading> message) {
// 訂閱 callback:讀取數值欄位,並取出感測器名稱的文字副本。
std::cout
<< "received sensor=" << message->data().sensor.str()
<< " temperature=" << message->data().temperature.get()
<< " publisher=" << message->publisher_name()
<< std::endl;
}

custom-message/subscriber.cpp · e165aed · 中文註解

temperature.get() 取出 double,sensor.str() 取出一份本機 std::string。

訂閱的建立與清理方式和上一篇相同。C++ 的 lambda 只轉交給 on_message(),Python 則直接傳入 self.on_message。

先在舊的 Vinc Shell 輸入 exit,關閉上一個範例。以下命令從 open-vinc-examples 根目錄執行;沿用前面已配置的建置目錄:

終端機視窗
cmake --build build/debug

新模組由 custom-message/CMakeLists.txt 的 add_module() 加入;根目錄已包含這個子目錄。

在 PowerShell 啟動:

終端機視窗
.\build\debug\Vinc.exe

接下來輸入在 Vinc Shell。先輸入 sensorSubscriber,等到 Started receiver;再輸入 sensorPublisher,等到 Started sender:

sensorSubscriber
sensorPublisher
sender send

接收端會印出以下內容,實際輸出還會包含來源前綴:

received sensor=room temperature=23.5 publisher=sender

這就是你在 .msg 自訂的兩個欄位。再輸入 sender send 會送出相同讀值;完成後用 exit 正常關閉。

先選擇適合的欄位型別:

型別 常見用途
uint64_t 非負的序號或計數
int32_t 可正可負的整數
float/double 小數,例如溫度與距離
bool 開啟/關閉狀態
string 名稱與文字

數值仍須放在型別可表示的範圍內。檔名與欄位名稱先使用英文字母開頭,後接字母、數字或底線;避開 C++ 關鍵字。

修改欄位後,先關閉中央,再重新建置所有使用這份訊息的模組;Python 也要重建 SDK。發送端與接收端應使用同一份更新後的定義。

接著回到計數範例,閱讀讓模組接收自己的指令。