Configure and save module parameters
Continue from Give your module its own commands by adding a step parameter to the sender. It controls how much the sequence increases with each message. Start at 1, then change it to 5 while the Module keeps running.
This lesson starts parameterPublisher, a sender with parameter support, and reuses counterSubscriber. The instance names remain sender and receiver.
1. Build and start the example
Section titled “1. Build and start the example”If the previous Vinc Shell is still open, enter exit first. Rebuild from the open-vinc-examples repository root, then open the Shell from PowerShell:
cmake --build build/debug.\build\debug\Vinc.execmake --build build/python.\build\python\Vinc.exe --python .\.venv\Scripts\python.exeIf you have not prepared the build directory, follow Your first cross-process message or Prepare the Python examples first.
Once you see VINC ready, start the receiver in Vinc Shell:
counterSubscriberWait for ready receiver and Started receiver, then start this lesson’s sender:
parameterPublisherWait for ready sender and Started sender. On the first run, you will also see step=1. These lines may appear in a different order.
If you previously saved a different increment, enter param set sender.step 1 and wait for step=1 to repeat this lesson from the same starting point.
2. Check the default and send a message
Section titled “2. Check the default and send a message”param get sender.stepThe output includes:
sender.step [uint64] = 1sender.step combines the instance name sender and parameter name step. uint64 is a non-negative integer type.
Send the first message:
sender sendWait for the receiver to print:
received sequence=1 publisher=sender3. Change the increment to 5
Section titled “3. Change the increment to 5”param set sender.step 5The central application reports Parameter committed (not saved). Wait for the sender to also print this confirmation before continuing:
step=5This confirms the Module has applied the new setting. You can also check the current value in the central application:
param get sender.stepThe value is now 5. Send another message:
sender sendWait for the receiver to print:
received sequence=6 publisher=senderThe previous sequence was 1; adding the new increment of 5 gives 6. Enter sender send once more and wait for:
received sequence=11 publisher=senderThe Module has kept running throughout. sender send is a command that performs an action; sender.step is a parameter that adjusts its behavior.
4. Save the setting and restart
Section titled “4. Save the setting and restart”The earlier param set changed the running value only. To keep 5 for the next launch, enter in Vinc Shell:
param saveWait for Parameters saved. This saves the current settings for all parameters. Entering exit alone does not automatically save your changes.
Close the central application and both modules:
exitBack in PowerShell, launch the same Vinc executable again. No rebuild is needed:
.\build\debug\Vinc.exe.\build\python\Vinc.exe --python .\.venv\Scripts\python.exeOnce you see VINC ready, start the receiver in Vinc Shell:
counterSubscriberWait for ready receiver and Started receiver, then start the sender:
parameterPublisherThis time, wait for ready sender, Started sender, and step=5. Check again:
param get sender.stepThe output includes:
sender.step [uint64] = 5The default in the source is still 1, but this launch applies the saved value of 5. Send a message:
sender sendWait for the receiver to print:
received sequence=5 publisher=senderEnter sender send once more and wait for:
received sequence=10 publisher=senderThe parameter setting is preserved, while the Module’s counter starts over. The previous sequence starts at 0; adding 5 on each send gives 5, 10.
5. Register the parameter in code
Section titled “5. Register the parameter in code”Register step in on_start(), then set the function to call when parameters change:
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 registered = context.param.register_param<std::uint64_t>("step", 1); if (!registered) { return std::unexpected(registered.error()); }
auto watching = context.param.on_change([this](const vinc::param::ParamMap&) { on_parameters_changed(); }); if (!watching) { return std::unexpected(watching.error()); }
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 {};}parameters/publisher.cpp · e165aed
register_param<std::uint64_t>("step", 1) specifies the name, type, and default value. Successful registration also watches this parameter.
The lambda in on_change() only forwards to the named on_parameters_changed() function. Each Result is checked for failure.
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.sequence = 0 self.step = 1 self.context.param.register_param("step", vinc.param.Type.UInt64, 1) self.context.param.on_change(self.on_parameters_changed) self.publisher = self.context.advertise( vinc.messages.CounterSample, "tutorial/counter" ) print("ready sender")python/modules/parameterPublisher/parameterPublisher.py · e165aed
register_param("step", vinc.param.Type.UInt64, 1) specifies the name, type, and default value. Successful registration also watches this parameter.
on_change(self.on_parameters_changed) passes the named function directly as the callback.
Inside the Module, use the local name step. In Shell, use the full name sender.step. The example uses the default permissions and changes the value through the central application’s param set command.
6. Apply the setting and keep sending
Section titled “6. Apply the setting and keep sending”When parameters update, the framework calls on_parameters_changed(). Read the current value from the local cache, then print confirmation:
void on_parameters_changed() { // Parameter callback: read the latest step from the framework's local cache. auto updated = context.param.update("step", step_); if (!updated) { std::cerr << vinc::error_to_string(updated.error()) << std::endl; return; }
std::cout << "step=" << step_ << std::endl;}parameters/publisher.cpp · e165aed
update("step", step_) copies the cached value into member step_. If reading fails, the code keeps the previous value and reports the error.
def on_parameters_changed(self, values): # Parameter callback: read the latest step from the framework's local cache. try: self.step = self.context.param.update("step", vinc.param.Type.UInt64) except vinc.VincError as error: print(error) return
print(f"step={self.step}")python/modules/parameterPublisher/parameterPublisher.py · e165aed
update("step", vinc.param.Type.UInt64) returns the cached value to store in self.step. If reading fails, the example catches VincError and keeps the previous value.
The central application accepting param set and the Module applying the update are separate events. That is why you wait for step=5. With FrameworkLoop, the framework dispatches updates for you; you do not need to poll.
Each send computes the new sequence as the previous sequence plus the current increment. Record it only after the send succeeds:
const auto next_sequence = sequence_ + step_; 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; }
sequence_ = next_sequence;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
next_sequence = self.sequence + self.step if next_sequence > 2**64 - 1: print("sequence limit reached") return 1
try: message = vinc.make_message(vinc.messages.CounterSample) message.data().sequence = next_sequence self.publisher.push(message) except vinc.VincError as error: print(error) return 1
self.sequence = next_sequence return 0python/modules/parameterPublisher/parameterPublisher.py · e165aed
The previous sequence starts at 0 each time the Module starts. The increment defaults to 1, or uses a saved setting when one exists. Changing the increment while running does not reset the current sequence.
7. Shut down cleanly
Section titled “7. Shut down cleanly”exitWait for both modules to stop and return to PowerShell.
If you change settings again with param set, remember to run param save to keep them for the next launch.
Continue with Your first RPC: ask another module to have sender query the received count from receiver.