Skip to content

Configure and save module parameters

Documented releasev0.2.0/Stable main branch

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.

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:

Terminal window
cmake --build build/debug
.\build\debug\Vinc.exe

If 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:

counterSubscriber

Wait for ready receiver and Started receiver, then start this lesson’s sender:

parameterPublisher

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

param get sender.step

The output includes:

sender.step [uint64] = 1

sender.step combines the instance name sender and parameter name step. uint64 is a non-negative integer type.

Send the first message:

sender send

Wait for the receiver to print:

received sequence=1 publisher=sender
param set sender.step 5

The central application reports Parameter committed (not saved). Wait for the sender to also print this confirmation before continuing:

step=5

This confirms the Module has applied the new setting. You can also check the current value in the central application:

param get sender.step

The value is now 5. Send another message:

sender send

Wait for the receiver to print:

received sequence=6 publisher=sender

The previous sequence was 1; adding the new increment of 5 gives 6. Enter sender send once more and wait for:

received sequence=11 publisher=sender

The Module has kept running throughout. sender send is a command that performs an action; sender.step is a parameter that adjusts its behavior.

The earlier param set changed the running value only. To keep 5 for the next launch, enter in Vinc Shell:

param save

Wait 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:

exit

Back in PowerShell, launch the same Vinc executable again. No rebuild is needed:

Terminal window
.\build\debug\Vinc.exe

Once you see VINC ready, start the receiver in Vinc Shell:

counterSubscriber

Wait for ready receiver and Started receiver, then start the sender:

parameterPublisher

This time, wait for ready sender, Started sender, and step=5. Check again:

param get sender.step

The output includes:

sender.step [uint64] = 5

The default in the source is still 1, but this launch applies the saved value of 5. Send a message:

sender send

Wait for the receiver to print:

received sequence=5 publisher=sender

Enter sender send once more and wait for:

received sequence=10 publisher=sender

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

Register step in on_start(), then set the function to call when parameters change:

parameters/publisher.cpp
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.

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.

When parameters update, the framework calls on_parameters_changed(). Read the current value from the local cache, then print confirmation:

parameters/publisher.cpp
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.

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:

parameters/publisher.cpp
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;

parameters/publisher.cpp · 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.

exit

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