--DEPRECATED-- msgconnector, HATP's middleware --DEPRECATED--

This module is now deprecated ! HATP relies on ROS to transport messages.

This page presents msgconnector's usage. msgconnector is responsible to carry messages form a module to another.

It is also responsible to the connection to other middlewares: OPRS, ORO, YARP.

<<TableOfContents: execution failed [list index out of range] (see also the log)>>

/!\ The way to install msgconnector is described in HATP/install.

Principle

msgconnector is composed of a server (MsgSever) that once started allows the different clients to connect. When a client connects it gives its name. This name is then used to carry a message from a client to another.

It is possible to declare several clients with the same name, then all the message are repeated to all the clients with the same name.

The message passed are usually using the JSON format (see JSON) but it is not mandatory.

Finally msgconnector can be connected to other middleware to extend the reach of HATP's messages. To do so bridges need to be started. So far the implemented bridge are:

If you need an additional bridge put the request on the tracker, see the troubleshooting section at the bottom of this page.

Start the server

The default usage for the server is simply: 

MsgServer

It starts the server on localhost and on the port 5500.

The help gives: 

MsgServer --help
Usage:  Default:        MsgServer
        Compact:        MsgServer address:port [max_time]
        Standard:       MsgServer address port [max_time]
        Complete:       MsgServer [-a address] [-p port] [-t max_time] [-m max_connections]

Allowed options:
  --help                   Produce help message
  -a [ --address ] arg     The address of the server (default : localhost)
  -p [ --port ] arg        The port number of the server (default : 5500)
  -t [ --time ] arg        The maximum inactivity time in second before the 
                           automatic-shutdown of the server (default : 3600)
  -n [ --noLimit ]         Deactivate the time limit, the server runs until 
                           shutdown by hand (opposite of time)
  -m [ --max-clients ] arg Maximum number of clients that can connect at the 
                           same time (default : 10)

It is indeed possible to change the following parameters:

To connect the MsgServer over the network the address should be ":<port>" or nothing to connect over the network, not localhost.

Use a bridge

1. Use OPRS bridge

msgconnector-OPRS-bridge <NAME_OF_HATP> <NAME_OF_MSG_CLIENT> <MSGC_SERV> <NAME_OF_OPRS> <OPRS_SERV> <VERBOSE_MODE>

The parameters are:

*: The address can be a hostname like localhost.

2. Use ORO bridge

msgconnector-ORO-bridge <NAME_OF_BRIDGE> <MSGC_SERV> <ORO_SERV> <VERBOSE_MODE>

The parameters are:

3. Use YARP bridge

msgconnector-YARP-bridge <NAME_OF_MSGC> <MSGC_SERV> <NAME_OF_YARPIN> <NAME_OF_YARPOUT> <VERBOSE_MODE>

The parameters are:

4. Use the print bridge

msgconnector-PRINT-bridge <NAME_OF_BRIDGE> <MSGC_SERV>

The parameters are:

Introduction to the API

This section shows some basic usages to send and receive messages using msgconnector.

1. Create a client

The msgconnector API is client based, the server is responsible of transferring the messages. If several clients have the same name they will all receive the messages sent to one, the message transfer is based on the name of the agents.

1.1. Add msgconnector to a project

There are two ways to integrate msgconnector to a project: (1) using CMake and find_package, or (2) using pkgconfig. In this section we only show the CMake fashion.

Here is the extract of the CMakeLists.txt: 

find_package(msgconnector REQUIRED)

include_directories(${msgconnector_INCLUDE_DIRS})

target_link_libraries(<target> ${msgconnector_LIBRARIES})

However if msgconnector was not installed system wide, for instance if it was installed using robotpkg you will have to specifiy the path to the Findmsgconnector.cmake.

To do so, invoke the CMake executable as follow: 

cmake [<OTHER_OPTIONS>] -DCMAKE_MODULES_PATH=<path/to/directory/containing/Findmsgconnector>

If msgconnetor has been installed using robotpkg (as advised) then the path is -DCMAKE_MODULES_PATH=${ROBOTPKG_BASE}/share/cmake/Modules.

1.2. Connect a new client

Here is the minimum code to connect to msgconnector with a new client: 

#include <iostream>

#include <msgClient.hh>

int main(int argc, char ** argv){
        msgClient client;
        client.connect(<name>, <server>, <server_port>);
}

When calling connect, the name corresponds to the name of this client, the server can be: an IP address or a hostname (by default use "localhsot") finally the server_port is 5500 by default but can be any port the server listens to.

1.3. Send messages and broadcast messages

To send a message there are two options: send a message to a recipient or send a broadcast message. When the message is sent to a recipient, the message is transferred by the server to ALL client with the target name. The broadcast is simply sent to all the clients.

If a message is sent to a recipient not connected, it does not trigger an error, it is supposed a normal behaviour.

Reminder: the message are usually using the JSON format.

To send a message to a recipient: 

client.sendMessage(<recipient>, <message>);

To send a broadcast message: 

client.sendBroadcastMessage(<message>);

The parameters for both send functions are std::string.

1.4. Receive messages

Now that message can be sent, it is time to receive messages. There are three ways to retrieve messages: it is possible to wait for the message (blocking), or wait for the message for a given time (blocking with a timeout) and finally it is possible to directly get a message if present.

1.4.1. Wait for a message

Using this solution the code will wait indefinitely for a message to arrive, the only things that can stop it are: a message or the server exiting. 

while(client.isConnected()){
        std::pair<std::string, std::string> result = client.getBlockingMessage();
        std::cout<<"#### Message from "<<result.first<<": "<<result.second<<std::endl;
}

The pair is composed as follow: <sender, message>. However if the sender is the empty string it means an error occurred, then the message will contain "NOT_CONNECTED" (defined as #define STATUS_DISCONNECTED "NOT_CONNECTED".

1.4.2. Wait for a message (with a timeout)

This solution allows to wait for a message for a given time, if the time is exceeded a timeout is returned. 

while(client.isConnected()){
        std::pair<std::string, std::string> result = client.getMessageTimeout(<time>);
        if(result.second==STATUS_TIMEOUT){
                std::cout<<"#### Wait timeouted"<<std::endl;
        }else{
                std::cout<<"#### Message from "<<result.first<<": "<<result.second<<std::endl;
        }
}

The time parameter is expressed in ms. The pair is formed as in blocking message, and again an empty first field means an error: STATUS_DISCONNECTED or STATUS_TIMEOUT.

1.4.3. Non-blocking message retrieving

This last solution allows to directly retrieve a message 

while(client.isConnected()){
        if(client.isMessageWaiting()){
                std::pair<std::string, std::string> result = client.getMessage();
                std::cout<<"#### Message from "<<result.first<<": "<<result.second<<std::endl;
        }
        
        //Something else
}

2. Run the example

Once compiled, to execute the code you first need to start the server: see here.

Changelog

1. Version 2.0.0

2. Version 2.1.0

3. Version 2.2.0

4. Version 2.3.0

5. Version 2.4.0

6. Version 2.5.0

7. Version 2.6.0

8. Version 2.7.0

9. Version 2.8.0

10. Version 2.8.1

11. Version 2.8.2

12. Version 2.8.3

13. Version 2.8.4

14. Version 2.9.0

15. Version 2.9.1

16. Version 2.10.0

17. Version 2.11.0

18. Version 2.11.1

19. Version 2.12.0

20. Version 2.13.0

License, Troubleshooting and Maintainer

HATP is distributed under 2-clause BSD license. (See here for details.)

The page to report problems or for pull request: Openrobots/msgconnector.

Current maintainer(s):