Skip to content

Define your own message

Documented releasev0.2.0/Stable main branch

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/.

Create SensorReading.msg in the project’s messages/ directory:

messages/SensorReading.msg
// 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.

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:

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

CMakeLists.txt · e165aed

Edit your .msg and module source files. You do not need to write or edit the generated .hpp files.

The publisher creates a SensorReading, fills both fields, then calls push():

The send_message() function in custom-message/publisher.cpp:

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.

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.

The named on_message() function reads the delivered message:

custom-message/subscriber.cpp
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.

Subscription setup and cleanup follow the previous lesson. The C++ lambda only forwards to on_message(); Python passes self.on_message directly.

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:

Terminal window
cmake --build build/debug

custom-message/CMakeLists.txt registers the new modules with add_module(). The root build already includes that directory.

Start the central executable in PowerShell:

Terminal window
.\build\debug\Vinc.exe

Enter the following in Vinc Shell. Run sensorSubscriber and wait for Started receiver; then run sensorPublisher and wait for Started sender:

sensorSubscriber
sensorPublisher
sender send

The receiver prints the following content, with an additional source prefix in the actual output:

received sensor=room temperature=23.5 publisher=sender

These are the two fields you defined in .msg. Another sender send sends the same reading. Enter exit to shut down normally when finished.

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.