Define your own message
The previous lesson sent a counter. This time, define a SensorReading with two fields: a temperature of 23.5 and the sensor name "room".
Keep using open-vinc-examples. The complete C++ modules are in custom-message/; the Python modules are in python/modules/sensorPublisher/ and sensorSubscriber/.
1. Write a .msg file
Section titled “1. Write a .msg file”Create SensorReading.msg in the project’s messages/ directory:
// Temperature in degrees Celsius.double temperature;// Name of the sensor that produced the reading.string sensor;messages/SensorReading.msg · e165aed
Each line declares a type and a field name, followed by a semicolon. Here, double stores the temperature and string stores the sensor name. Text after // is a comment.
The filename determines the message type name. Building generates both language interfaces from this definition:
| Language | How to use it |
|---|---|
| C++ | vinc::SensorReading, included with <vinc_messages/SensorReading.hpp> |
| Python | vinc.messages.SensorReading |
Define your application data here. The framework supplies the publisher name and message timestamps; you do not need to duplicate them in .msg.
2. Add the message directory to the build
Section titled “2. Add the message directory to the build”The example already includes the following configuration. Register each directory once; you do not need a separate CMake line for every new .msg file:
The root CMakeLists.txt calls this after adding the framework:
add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/messages")python/CMakeLists.txt adds the same directory. Building also generates its Python message bindings:
add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/../messages")Edit your .msg and module source files. You do not need to write or edit the generated .hpp files.
3. Fill the fields and send
Section titled “3. Fill the fields and send”The publisher creates a SensorReading, fills both fields, then calls push():
The send_message() function in custom-message/publisher.cpp:
std::int32_t send_message() { // Fill both fields, then publish only if the string assignment succeeded. 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
- Assign numeric fields directly:
temperature = 23.5. - Use
sensor.assign("room")for the string and check its result. Do not publish if assignment fails. - Call
push(*message)to send the completed message.
The sensor field is the framework’s string type, not std::string; do not write sensor = "room" directly.
The send_message() function in sensorPublisher.py:
def send_message(self): # Fill both fields, then publish only if the string assignment succeeded. 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 numbers directly and use assign() for strings. Python text is encoded as UTF-8. String assignment or publishing can raise vinc.VincError; the example catches it and returns 1.
Both modules in the complete example use the SensorReading type and the "tutorial/sensor" topic. The type defines the data format; the topic is the name you choose for delivery. Both ends must agree on both.
4. Receive and read the fields
Section titled “4. Receive and read the fields”The named on_message() function reads the delivered message:
void on_message(std::unique_ptr<vinc::SensorReading> message) { // Subscription callback: read the numeric field and copy the sensor text. 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() returns a double; sensor.str() returns a local std::string copy.
def on_message(self, message): # Subscription callback: read the numeric field and copy the sensor text. print( f"received sensor={message.data().sensor.decode()} " f"temperature={message.data().temperature} " f"publisher={message.publisher_name()}" )python/modules/sensorSubscriber/sensorSubscriber.py · e165aed
Read temperature as a Python number. sensor.decode() reads the UTF-8 text as a Python str.
Subscription setup and cleanup follow the previous lesson. The C++ lambda only forwards to on_message(); Python passes self.on_message directly.
5. Build and try a message
Section titled “5. Build and try a message”Enter exit in the previous Vinc Shell first. Run these commands from the open-vinc-examples root, using the build directory configured in the earlier lessons:
cmake --build build/debugcustom-message/CMakeLists.txt registers the new modules with add_module(). The root build already includes that directory.
Start the central executable in PowerShell:
.\build\debug\Vinc.exeComplete Prepare the Python examples first, then rebuild. A new message definition requires rebuilding the SDK, even when your modules are written in Python:
cmake --build build/pythonStart the central executable in PowerShell:
.\build\python\Vinc.exe --python .\.venv\Scripts\python.exeEnter the following in Vinc Shell. Run sensorSubscriber and wait for Started receiver; then run sensorPublisher and wait for Started sender:
sensorSubscribersensorPublishersender sendThe receiver prints the following content, with an additional source prefix in the actual output:
received sensor=room temperature=23.5 publisher=senderThese are the two fields you defined in .msg. Another sender send sends the same reading. Enter exit to shut down normally when finished.
6. Use your own data
Section titled “6. Use your own data”Choose field types to match your data:
| Type | Typical use |
|---|---|
uint64_t |
Nonnegative sequence numbers or counts |
int32_t |
Signed integers |
float / double |
Fractional values, such as temperature or distance |
bool |
On/off state |
string |
Names and text |
Values must fit the selected numeric type. Start filenames and field names with an ASCII letter, followed by letters, digits or underscores; avoid C++ keywords.
After changing fields, close the central process and rebuild every module using the message. Python also needs an SDK rebuild. Both sender and receiver should use the same updated definition.
Next, return to the counter example in Give your module its own commands.