Give your module its own commands
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.
1. Build and start the example
Section titled “1. Build and start the example”If the previous Vinc Shell is still running, enter exit first. Return to the open-vinc-examples repository root and rebuild:
cmake --build build/debugcmake --build build/pythonOpen Vinc Shell from PowerShell:
.\build\debug\Vinc.exe.\build\python\Vinc.exe --python .\.venv\Scripts\python.exeEnter all subsequent commands in Vinc Shell. Start the receiver first:
counterSubscriberWait for ready receiver and Started receiver, then start the sender:
counterPublisherWait for ready sender and Started sender before continuing. For the earlier build steps, see Your first cross-process message.
2. Check the count with status
Section titled “2. Check the count with status”Send one message:
sender sendWait for the receiver to print:
received sequence=1 publisher=senderThen query the count:
receiver statusThe output includes:
received=1Here, receiver selects the Module to operate on, and status is the command passed to it.
3. Clear the count with reset
Section titled “3. Clear the count with reset”Enter the new command:
receiver resetWait for:
counter resetThen enter:
receiver statusThis time, the output includes:
received=0reset only clears the received count stored by receiver. It does not change the message sequence in sender. Receiving more messages starts the count again.
4. Try an unsupported command
Section titled “4. Try an unsupported command”Enter:
receiver unknownThe output includes a usage hint:
Usage: receiver [status|reset]receiver returned 1This means the example accepts status or reset. The Module keeps running after the command fails. Entering receiver status again still reports received=0.
5. Handle commands in code
Section titled “5. Handle commands in code”The implementation lives in module_interface() in modules/subscriber.cpp. Focus on this function:
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.
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 1python/modules/counterSubscriber/counterSubscriber.py · e165aed
The implementation lives in python/modules/counterSubscriber/counterSubscriber.py. For receiver status, Python receives args as ["status"]: the instance name has already been removed, so you can compare the list directly.
For example, receiver reset extra becomes ["reset", "extra"]. It does not match ["reset"], so the example rejects it.
It then checks these cases:
- With no subcommand, use
statusby default. - For
status, print the current received count. - For
reset, set the received count to0, 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.
6. Shut down cleanly
Section titled “6. Shut down cleanly”When finished, enter:
exitAfter 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.