自訂訊息
上一篇傳送的是計數。這次改成自訂的 SensorReading:一筆訊息包含溫度 23.5 與感測器名稱 "room"。
沿用 open-vinc-examples 專案。本篇完整的 C++ 程式在 custom-message/;Python 程式在 python/modules/sensorPublisher/ 和 sensorSubscriber/。
1. 寫一份 .msg
Section titled “1. 寫一份 .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 重複定義。
2. 把訊息目錄加入建置
Section titled “2. 把訊息目錄加入建置”範例已設定好以下指令,同一個目錄只需加入一次。新增 .msg 時,不必每個檔案都寫一行 CMake:
專案根目錄的 CMakeLists.txt 在加入框架後呼叫:
add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/messages")python/CMakeLists.txt 加入同一個目錄,建置時也會產生 Python 訊息綁定:
add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/../messages")接下來修改的是 .msg 與模組程式,不必手寫或修改生成的 .hpp。
3. 填入欄位,再發送
Section titled “3. 填入欄位,再發送”發送端建立 SensorReading,填好兩個欄位,再呼叫 push():
custom-message/publisher.cpp 的 send_message():
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"。
sensorPublisher.py 的 send_message():
def send_message(self): # 填入兩個欄位,確認字串寫入成功後再發送。 try: message = vinc.make_message(vinc.messages.SensorReading) message.data().temperature = 23.5 message.data().sensor.assign("room") self.publisher.push(message) except vinc.VincError as error: print(error) return 1 return 0python/modules/sensorPublisher/sensorPublisher.py · e165aed · 中文註解
數值直接賦值,字串同樣使用 assign();Python 的文字會以 UTF-8 寫入。字串寫入或發送失敗時會拋出 vinc.VincError,範例捕捉後回傳 1。
完整範例的 Publisher 與 Subscriber 都使用 SensorReading 型別、"tutorial/sensor" topic。型別描述資料格式,topic 則是你選擇的收發名稱;兩端必須一致。
4. 接收並讀取欄位
Section titled “4. 接收並讀取欄位”收到訊息後,由具名的 on_message() 讀取內容:
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。
def on_message(self, message): # 訂閱 callback:讀取數值欄位,並取出感測器名稱的文字副本。 print( f"received sensor={message.data().sensor.decode()} " f"temperature={message.data().temperature} " f"publisher={message.publisher_name()}" )python/modules/sensorSubscriber/sensorSubscriber.py · e165aed · 中文註解
temperature 直接讀成 Python 數值;sensor.decode() 將 UTF-8 文字讀成 Python str。
訂閱的建立與清理方式和上一篇相同。C++ 的 lambda 只轉交給 on_message(),Python 則直接傳入 self.on_message。
5. 建置並試送一筆
Section titled “5. 建置並試送一筆”先在舊的 Vinc Shell 輸入 exit,關閉上一個範例。以下命令從 open-vinc-examples 根目錄執行;沿用前面已配置的建置目錄:
cmake --build build/debug新模組由 custom-message/CMakeLists.txt 的 add_module() 加入;根目錄已包含這個子目錄。
在 PowerShell 啟動:
.\build\debug\Vinc.exe先完成準備 Python 範例,再重新建置。新增訊息定義需要重建 SDK,即使模組是 Python 也一樣:
cmake --build build/python在 PowerShell 啟動:
.\build\python\Vinc.exe --python .\.venv\Scripts\python.exe接下來輸入在 Vinc Shell。先輸入 sensorSubscriber,等到 Started receiver;再輸入 sensorPublisher,等到 Started sender:
sensorSubscribersensorPublishersender send接收端會印出以下內容,實際輸出還會包含來源前綴:
received sensor=room temperature=23.5 publisher=sender這就是你在 .msg 自訂的兩個欄位。再輸入 sender send 會送出相同讀值;完成後用 exit 正常關閉。
6. 換成自己的資料
Section titled “6. 換成自己的資料”先選擇適合的欄位型別:
| 型別 | 常見用途 |
|---|---|
uint64_t |
非負的序號或計數 |
int32_t |
可正可負的整數 |
float/double |
小數,例如溫度與距離 |
bool |
開啟/關閉狀態 |
string |
名稱與文字 |
數值仍須放在型別可表示的範圍內。檔名與欄位名稱先使用英文字母開頭,後接字母、數字或底線;避開 C++ 關鍵字。
修改欄位後,先關閉中央,再重新建置所有使用這份訊息的模組;Python 也要重建 SDK。發送端與接收端應使用同一份更新後的定義。
接著回到計數範例,閱讀讓模組接收自己的指令。