C++ - How to write a qimessaging client

On this page


This guide will teach you how to write a qimessaging client in C++, to interact with the various services offered by the robot.


  • An installed NAOqi SDK for your operating system.
  • A C++ project setup in your favorite C++ development environment, ready to use the headers and libraries provided by the NAOqi SDK.

Write your function

First you need to write the function that does the work you want.

You can use the qi::Session::service method to get access to a service (local or remote). This method will return a qi::AnyObject . In this example, the danceManager object works as any other qi::AnyObject , please refer to its documentation for more details.

             #include <qi/session.hpp>

void dance(qi::SessionPtr session)
  qi::AnyObject danceManager = session->service("DanceManager");
  // this function blocks here, it should return a future
  // we keep the function like this for the sake of the simplicity of this example


Then you must register your function in the module. If you don’t want to use modules, you can skip directly to the Manual way section.

             #include <qi/anymodule.hpp>

void registerDance(qi::ModuleBuilder* mb)
  mb->advertiseMethod("dance", &dance);
QI_REGISTER_MODULE("dancemodule", &registerDance);


Finally, create your module through CMake.

             cmake_minimum_required(VERSION 2.8)





The name you give to QI_REGISTER_MODULE in the C++ file must be the same as the one you give to qi_create_module in the CMake file.

Running your client

Fully automated way

qilaunch can be used to call a function in a module. So, with the module you just created, qilaunch can take care of all the boiler plate of parsing arguments, connecting a session, forwarding logs, etc, and just run that function.

To run your function, just do:

              qilaunch -n dancedanceman --function dancemodule.dance


Troubleshooting :

If you have “qilaunch: no module found: ‘dancemodule’” error message, then try:

              qilaunch -n dancedanceman --function dancemodule.dance --qi-sdk-prefix /path/to/build-<config>/sdk


where /path/to/build-<config>/sdk is the build-<config>/sdk directory containing the lib of your module.

Semi-automated way

If you don’t want to use qilaunch, you can write your own main function.

The first step to interact with qi services is to connect a qi::Session to the Service Directory of the robot. The Service Directory address is represented by a standard URL.

One simple way to achieve this is to use the helper class ApplicationSession , which will fetch the URL from the command line (using the –qi-url option), or use a default value of localhost .

Finally, you call qi::Session::callModule to call the function and give the session as the first parameter automatically.

              #include <qi/applicationsession.hpp>

int main(int argc, char** argv)
  qi::ApplicationSession app(argc, argv);
  app.startSession(); // connect the session
  qi::SessionPtr session = app.session();

  qi::Future<void> future = session->callModule<void>("dancedance.dance");
  future.value(); // wait for the end

  return 0;


Manual way

If you don’t want to use module, you can of course call your function directly. The code is very similar to the semi-automated way.

              #include <qi/applicationsession.hpp>
#include "dance.hpp"

int main(int argc, char** argv)
  qi::ApplicationSession app(argc, argv);
  app.startSession(); // connect the session
  qi::SessionPtr session = app.session();


  return 0;