Skip to content

Give your module its own commands

Documented releasev0.2.0/Stable main branch

The previous lesson used sender send. Reuse the same counter example to give receiver two commands: status displays the received count, and reset clears it.

If the previous Vinc Shell is still running, enter exit first. Return to the open-vinc-examples repository root and rebuild:

Terminal window
cmake --build build/debug

Open Vinc Shell from PowerShell:

Terminal window
.\build\debug\Vinc.exe

Enter all subsequent commands in Vinc Shell. Start the receiver first:

counterSubscriber

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

counterPublisher

Wait for ready sender and Started sender before continuing. For the earlier build steps, see Your first cross-process message.

Send one message:

sender send

Wait for the receiver to print:

received sequence=1 publisher=sender

Then query the count:

receiver status

The output includes:

received=1

Here, receiver selects the Module to operate on, and status is the command passed to it.

Enter the new command:

receiver reset

Wait for:

counter reset

Then enter:

receiver status

This time, the output includes:

received=0

reset only clears the received count stored by receiver. It does not change the message sequence in sender. Receiving more messages starts the count again.

Enter:

receiver unknown

The output includes a usage hint:

Usage: receiver [status|reset]
receiver returned 1

This means the example accepts status or reset. The Module keeps running after the command fails. Entering receiver status again still reports received=0.

The implementation lives in module_interface() in modules/subscriber.cpp. Focus on this function:

modules/subscriber.cpp
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;
}

modules/subscriber.cpp · e165aed

For receiver status, Shell passes receiver and status in args, in that order. The function first removes the instance name, leaving the command to handle.

It then checks these cases:

  • With no subcommand, use status by default.
  • For status, print the current received count.
  • For reset, set the received count to 0, then print confirmation.
  • For other commands or extra arguments, print the usage hint.

This example returns 0 for a successful command and 1 for incorrect usage. The return value describes this command’s result; it does not request module shutdown.

When finished, enter:

exit

After both modules stop normally, you return to PowerShell.

You can now use the same checks to add your own commands in module_interface(). Next, follow Configure and save module parameters to adjust the sender’s counter increment and keep the setting after restarting.