Your first cross-process message
Continue from Your first running module by exchanging a message between two modules: sender publishes a counter and receiver prints what it receives.
1. Reuse the example project
Section titled “1. Reuse the example project”Use the open-vinc-examples checkout from the previous lesson. You do not need to download it again. Run all commands below from the repository root, where you can see framework/, modules/ and messages/.
For Python, complete Prepare the Python examples first. For C++ tools, see the build guide.
2. Build the example
Section titled “2. Build the example”Use the repository root’s CMakeLists.txt this time to build the two counter modules:
cmake -S . -B build/debug -G Ninja -DCMAKE_BUILD_TYPE=Debugcmake --build build/debugOnce the build finishes, the next step runs build/debug/Vinc.exe.
The Python preparation page already built the SDK and counter message type. Reuse build/python/. If you edited Python code, copy the update with:
cmake --build build/python3. Start the two modules
Section titled “3. Start the two modules”Open the central application’s Vinc Shell from PowerShell:
.\build\debug\Vinc.exe.\build\python\Vinc.exe --python .\.venv\Scripts\python.exeThe central application has started its built-in Web UI and Recorder. The sender and receiver used in this lesson have not been created yet.
Enter the following in Vinc Shell, not PowerShell. Start the Subscriber first:
counterSubscriberWait for ready receiver and Started receiver, then start the Publisher:
counterPublisherWait for ready sender and Started sender. Enter a ModuleType to create an instance, then use the instance name for subsequent operations:
| Role | ModuleType | Instance name |
|---|---|---|
| Receive messages | counterSubscriber |
receiver |
| Send messages | counterPublisher |
sender |
4. Send your first message
Section titled “4. Send your first message”Enter in Vinc Shell:
sender sendWait for the receiver to print this line. Actual output also includes a source prefix:
received sequence=1 publisher=senderThis means receiver received sequence 1, published by sender.
Then query the received count:
receiver statusThe output includes:
received=1Wait for the receive output before querying. To send another message, enter sender send again and wait for the receiver to print the next sequence before querying.
Now read the code to see how the message gets from sender to receiver.
5. Define the message
Section titled “5. Define the message”messages/CounterSample.msg defines the data to send:
uint64_t sequence;messages/CounterSample.msg · e165aed
sequence is the counter value. Both languages use the same definition:
The build generates vinc::CounterSample and <vinc_messages/CounterSample.hpp>.
The build adds the type to the SDK as vinc.messages.CounterSample. Rebuild the SDK after changing a .msg definition.
6. Publisher: send a message
Section titled “6. Publisher: send a message”#include <vinc/vinc.hpp>#include <vinc_messages/CounterSample.hpp>
#include <cstdint>#include <iostream>#include <optional>#include <string>#include <utility>#include <vector>
class CounterPublisher final : public vinc::BaseModule<vinc::RunMode::FrameworkLoop> {public: CounterPublisher() : BaseModule("sender") { // Set the instance name used by Shell commands. }
vinc::Result<void> on_start(const std::vector<std::string>&) override { // Startup hook: the framework calls this after the instance name is approved. // Set up this module here; returning {} means initialization succeeded. 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 {}; }
vinc::Result<std::int32_t> module_interface(std::vector<std::string> args) override { // Command hook: called when Shell addresses this instance. // Return 0 for success or 1 to report a command error. // Native Shell includes the target. Direct Manager callers may omit it. if (!args.empty() && args.front() == get_module_name()) { args.erase(args.begin()); }
if (args.size() != 1 || args.front() != "send") { std::cout << "Usage: sender send" << std::endl; return 1; }
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; }
++next_sequence_; return 0; }
vinc::Result<void> on_stop() override { // Shutdown hook: called during normal shutdown to clean up this module. publisher_.reset(); std::cout << "stopped sender" << std::endl; return {}; }
private: std::optional<vinc::message_bus::Publisher<vinc::CounterSample>> publisher_; std::uint64_t next_sequence_ = 1;};
// Register the type name Shell uses to create this module.REGISTER_MODULE(CounterPublisher, "counterPublisher")modules/publisher.cpp · e165aed
Follow these steps:
on_start()creates a Publisher withcontext.advertise()and stores it in memberpublisher_, keeping it alive while the module runs.sender sendentersmodule_interface(), which creates a message withmake_message()and setssequence.publisher_->push(*message)sends the message. The next sequence increases only after success.on_stop()releases the Publisher.
The code checks each Result so registration and send failures can be reported.
import vinc
class Module(vinc.BaseModule, mode=vinc.RunMode.FrameworkLoop): def on_name(self, args): # Naming hook: return the instance name used to address this module in Shell. # Create publishers and subscriptions later, in on_start. return "sender"
def on_start(self, args): # Startup hook: the framework calls this after the instance name is approved. # Set up this module here; returning None means initialization succeeded. self.publisher = self.context.advertise( vinc.messages.CounterSample, "tutorial/counter" ) self.next_sequence = 1 print("ready sender")
def module_interface(self, args): # Command hook: called when Shell addresses this instance. # Return 0 for success or 1 to report a command error. # args contains command arguments; the instance name is already removed. if args != ["send"]: print("Usage: sender send") return 1
try: message = vinc.make_message(vinc.messages.CounterSample) message.data().sequence = self.next_sequence self.publisher.push(message) except vinc.VincError as error: print(error) return 1
self.next_sequence += 1 return 0
def on_stop(self): # Shutdown hook: called during normal shutdown to clean up this module. self.publisher.close() print("stopped sender")python/modules/counterPublisher/counterPublisher.py · e165aed
on_start()creates a Publisher withself.context.advertise()and stores it inself.publisher.sender sendentersmodule_interface(), creates a message withvinc.make_message(), and setsmessage.data().sequence.self.publisher.push(message)sends it. The next sequence increases only after success.on_stop()releases the Publisher withclose().
For a send failure, the example catches vinc.VincError and returns 1. This fails the command while keeping the Module available for further commands.
Both versions use the framework’s default capacity for now; a slow reader can still miss data.
7. Subscriber: receive a message
Section titled “7. Subscriber: receive a message”#include <vinc/vinc.hpp>#include <vinc_messages/CounterSample.hpp>
#include <cstdint>#include <iostream>#include <memory>#include <optional>#include <string>#include <utility>#include <vector>
class CounterSubscriber final : public vinc::BaseModule<vinc::RunMode::FrameworkLoop> {public: CounterSubscriber() : BaseModule("receiver") { // Set the instance name used by Shell commands. }
vinc::Result<void> on_start(const std::vector<std::string>&) override { // Startup hook: the framework calls this after the instance name is approved. // Set up this module here; returning {} means initialization succeeded. auto subscriber = context.subscribe<vinc::CounterSample>( "tutorial/counter", [this](std::unique_ptr<vinc::CounterSample> message) { on_message(std::move(message)); }); if (!subscriber) { return std::unexpected(subscriber.error()); }
subscriber_.emplace(std::move(*subscriber)); std::cout << "ready receiver" << std::endl; return {}; }
vinc::Result<std::int32_t> module_interface(std::vector<std::string> args) override { // Command hook: called when Shell addresses this instance. // Return 0 for success or 1 to report a command error. if (!args.empty() && args.front() == get_module_name()) { args.erase(args.begin()); }
if (args.empty()) { args.push_back("status"); }
if (args.size() == 1 && args.front() == "status") { std::cout << "received=" << received_ << std::endl; return 0; }
if (args.size() == 1 && args.front() == "reset") { received_ = 0; std::cout << "counter reset" << std::endl; return 0; }
std::cout << "Usage: receiver [status|reset]" << std::endl; return 1; }
vinc::Result<void> on_stop() override { // Shutdown hook: called during normal shutdown to clean up this module. subscriber_.reset(); std::cout << "stopped receiver" << std::endl; return {}; }
private: void on_message(std::unique_ptr<vinc::CounterSample> message) { // Subscription callback: called when a counter message is delivered. ++received_;
// Flush this small interactive example so captured output is visible promptly. std::cout << "received sequence=" << message->data().sequence.get() << " publisher=" << message->publisher_name() << std::endl; }
std::optional<vinc::message_bus::Subscriber<vinc::CounterSample>> subscriber_; std::uint64_t received_ = 0;};
// Register the type name Shell uses to create this module.REGISTER_MODULE(CounterSubscriber, "counterSubscriber")modules/subscriber.cpp · e165aed
The receiver has two parts:
on_start()subscribes to"tutorial/counter"withcontext.subscribe()and stores the subscription in membersubscriber_.- When a message arrives, the lambda only calls
on_message(). That named function contains the counting and output logic.
Capturing [this] lets the lambda call a member function on this object. std::move(message) transfers ownership of the message to on_message(). Inside that function, publisher_name() reads the publisher’s name.
Storing the subscription as a member keeps it receiving after on_start() returns. on_stop() releases it.
import vinc
class Module(vinc.BaseModule, mode=vinc.RunMode.FrameworkLoop): def on_name(self, args): # Naming hook: return the instance name used to address this module in Shell. # Create publishers and subscriptions later, in on_start. return "receiver"
def on_start(self, args): # Startup hook: the framework calls this after the instance name is approved. # Set up this module here; returning None means initialization succeeded. self.received = 0 self.subscriber = self.context.subscribe( vinc.messages.CounterSample, "tutorial/counter", self.on_message ) print("ready receiver")
def module_interface(self, args): # Command hook: called when Shell addresses this instance. # Return 0 for success or 1 to report a command error. # args contains command arguments; the instance name is already removed. if not args: args = ["status"]
if args == ["status"]: print(f"received={self.received}") return 0
if args == ["reset"]: self.received = 0 print("counter reset") return 0
print("Usage: receiver [status|reset]") return 1
def on_message(self, message): # Subscription callback: called when a counter message is delivered. self.received += 1 print( f"received sequence={message.data().sequence} " f"publisher={message.publisher_name()}" )
def on_stop(self): # Shutdown hook: called during normal shutdown to clean up this module. self.subscriber.close() print("stopped receiver")python/modules/counterSubscriber/counterSubscriber.py · e165aed
on_start() subscribes with self.context.subscribe(), passing self.on_message as the callback. The framework calls this named function to count and print incoming messages.
message.data().sequence reads the counter, and message.publisher_name() reads the publisher name.
Storing the subscription in self.subscriber keeps it receiving after on_start() returns. on_stop() releases it with close().
The sender and receiver must use the same topic name, "tutorial/counter".
8. Assemble with CMake
Section titled “8. Assemble with CMake”cmake_minimum_required(VERSION 3.20)project(open_vinc_counter_example LANGUAGES C CXX)
if(MSVC) add_compile_options("$<$<COMPILE_LANGUAGE:CXX>:/utf-8>")endif()
set(VINC_NAME "counter-example" CACHE STRING "Central instance identity")set(VINC_BUILD_APPS OFF CACHE BOOL "Build the framework's demonstration app")set(BUILD_TESTING OFF CACHE BOOL "Build the framework's internal tests")
add_subdirectory(framework/open-vinc/src open-vinc)add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/messages")
add_module(counter_publisher MODULE_TYPE_NAME counterPublisher SOURCES modules/publisher.cpp)add_module(counter_subscriber MODULE_TYPE_NAME counterSubscriber SOURCES modules/subscriber.cpp)
add_subdirectory(parameters)add_subdirectory(rpc)add_subdirectory(logging)add_subdirectory(custom-message)
vinc_add_app(Vinc INSTANCE_NAME "${VINC_NAME}" VINC_BUILD_CONFIG vinc.conf)
# Keep the tutorial's executable path stable. Tcl deployment follows this target.set_target_properties(Vinc PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}")
include(tests/CMakeLists.txt)This lesson adds a message definition and a second module to the previous lesson’s structure. Focus on these four commands:
add_subdirectory(): add the framework.add_message_dir(): add the message definitions inmessages/.add_module(): build the Publisher and Subscriber.vinc_add_app(): compose this App usingvinc.conf.
set_target_properties() places the executable in build/debug/. You can skip the final test include() for now.
cmake_minimum_required(VERSION 3.20)project(open_vinc_python_tutorials LANGUAGES C CXX)
set(VINC_NAME "python-tutorials" CACHE STRING "Central instance identity")set(VINC_BUILD_APPS OFF CACHE BOOL "Build the framework's demonstration app")set(BUILD_TESTING OFF CACHE BOOL "Build the framework's internal tests")
add_subdirectory(../framework/open-vinc/src open-vinc)add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/../messages")
if(WIN32) set(default_python "${CMAKE_CURRENT_SOURCE_DIR}/../.venv/Scripts/python.exe")else() set(default_python "${CMAKE_CURRENT_SOURCE_DIR}/../.venv/bin/python")endif()set(TUTORIAL_PYTHON_EXECUTABLE "${default_python}" CACHE FILEPATH "Python used by tutorial modules")configure_file(vinc.conf.in "${CMAKE_CURRENT_BINARY_DIR}/vinc.conf" @ONLY)vinc_add_app(Vinc INSTANCE_NAME "${VINC_NAME}" VINC_BUILD_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/vinc.conf")
set_target_properties(Vinc PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}" RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}")
include(cmake/DeployModules.cmake)include(tests/CMakeLists.txt)python/CMakeLists.txt · e165aed
The Python project enables bindings with CONFIG_VINC_APP_PYTHON=y in vinc.conf.in and adds the shared message definition with add_message_dir(). CMake fills in the path to the project’s Python environment.
DeployModules.cmake copies python/modules/ to data/module/ beside the executable. The central application scans Python modules, so they do not need individual add_module() calls. You can skip the final test include() for now.
9. Shut down cleanly
Section titled “9. Shut down cleanly”When you have finished reading, enter in Vinc Shell:
exitLook for stopped sender and stopped receiver; they may appear in either order. The central application waits for both processes to exit, then returns to PowerShell.
You have now started two modules, exchanged a message and shut down cleanly. Continue with Define your own message to define your own numeric and string fields.