Connecting to Services

Introduction

Clients form “connections” to services to access the resources provided by the service, as discussed in Client-Service Object-Oriented Model. The connection consists of three pieces: the transport connection between the nodes, the client references/proxies, and the service endpoint. These pieces are all created automatically when the connection is created.

Connections can be created using several different methods. These methods include:

Connect using a URL
Create a subscription using a URL
Create a subscription based on service criteria
Connect using the Device Connector
Connect using the PyRI Device Manager
Use discovery to find available devices

The best method to use will depend on the exact use case. For most simple use cases, such as a laboratory environment, using a URL or a subscription with a URL is the simplest. For production environments, using the Device Connector or the PyRI Device Manager is probably more appropriate.

Note that firewalls and networking configurations can cause problems with connections between computers. See the “Networking and Firewalls” section below for more information.

This page is only an introduction to creating connections. See the more in-depth documentation for more details.

Connect using a URL

The simplest and most direct method to connect to a service is by using a URL and the ConnectService() function.

# connect_url.py - Connect to a service using a URL

from RobotRaconteur.Client import *

url = 'rr+tcp://localhost:29200?service=reynard'
c = RRN.ConnectService(url)
c.say("Hello from connect_url!")

% connect_url.m - Connect to a service using a URL

url = 'rr+tcp://localhost:29200?service=reynard';
c = RobotRaconteur.ConnectService(url);
c.say('Hello from connect_url!');
RobotRaconteur.DisconnectService(c);

// connect_url.cs - Connect to a service using a URL

using System;
using RobotRaconteur;
using System.Threading;
using System.Threading.Tasks;
using System.Linq;

// Initialize the client node
using (var node_setup = new ClientNodeSetup(args))
{
    // Connect to the Reynard service using a URL
    var c = (experimental.reynard_the_robot.Reynard)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:29200?service=reynard");

    // Say hello
    c.say("Hello from connect_url!");
}

// connect_url.cpp - Connect to a service using a URL

#include <stdio.h>
#include <iostream>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;

int main(int argc, char* argv[])
{
    // Use RobotRaconteur::NodeSetup to initialize Robot Raconteur
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    // Connect to the service
    std::string url = "rr+tcp://localhost:29200/?service=reynard";
    auto reynard =
        RR::rr_cast<experimental::reynard_the_robot::Reynard>(RR::RobotRaconteurNode::s()->ConnectService(url));

    // Say hello
    reynard->say("Hello from connect_url!");

    return 0;
}

Finding the URL for a service can be tricky. There are multiple “transports” to connect to the service, and the exact contents of the URL are very specific to the network topology between the client and the service. In the examples above, the rr+tcp “scheme” at the beginning of the URL means the connection is using TCP/IP, a networking transport that is common on the Internet and local networks. localhost means that the service is on the same computer as the client. This would be replaced with the IP address of the computer running the service if it was not running on the same machine. For example, 192.168.11.14 is an IPv4 address for a computer on a local network. The ?service=reynard means that we are attempting to connect to a service named reynard on the node. The rr+local transport scheme for the “local” transport is also frequently used. This transport uses local sockets and has higher performance since it is only used for services running on the same computer.

The README, documentation, and examples for services will often contain information about how to find the URL for the service.

The Robot Raconteur Service Browser can be used to find service URLs using discovery.

It is advised to always run the service browser on the same computer as the client. This will return a URL that is valid for that exact scenario. For example, when searching for Reynard the Robot on a different computer, the following URL is returned:

rr+tcp://[fe80::6a23:fb1a:23b3:db79]:29200/?nodeid=54cb0389-163d-4ce0-8237-154fd8b83deb&service=reynard

Note the IP address in this URL is an IPv6 link-local address rather than IPv4. By default, Robot Raconteur will use IPv6 addresses since they automatically configure and can be configured to be permanently static without the headache of IPv4 address assignment. The fe80:: prefix means that this address is only valid within a local network. Note that this example address is only valid for the example network and will be different for every setup. The nodeid and nodename are optional for TCP in some scenarios, but one or both are required for other transports like rr+local.

Example rr+local URLs:

rr+local:///?nodeid=e513887c-4512-4ce5-a7e7-1396cfc718f2&service=reynard

rr+local:///?nodename=experimental.reynard_the_robot&service=reynard

Note

If discovery does not work, there is probably a firewall configuration error. See the “Firewall” section below.

Note

The following sections on subscriptions and discovery describe how to create connections automatically based on criteria for selecting services without the need for a manually configured URL.

The URL has a special form:

<scheme>://<host>:<port>/?nodename=<nodename>&nodeid=<nodeid>&service=<servicename>

See the Framework Nodes and Communication documentation for more details on URLs.

Services opened using the ConnectService() function should be closed using the DisconnectService() function, or be closed automatically when the node is shut down.

Subscription using a URL

Robot Raconteur subscriptions are designed to create a robust connection to services and to manage the lifecycle of connections. They also allow for connectionless-like interaction with pipe and wire members. See subscriptions for more information.

Subscriptions can be created using a URL or through criteria. See the rest of this document for information on criteria-based connections.

Creating a subscription using a URL is similar to connecting to a service using ConnectService(), except instead of returning a client connection, a ServiceSubscription is returned.

# subscribe_url.py - Subscribe to a service using a URL

from RobotRaconteur.Client import *

url = 'rr+tcp://localhost:29200?service=reynard'
sub = RRN.SubscribeService(url)
c = sub.GetDefaultClientWait(10)
c.say("Hello from URL subscription!")

% subscribe_url.m - Connect to a service using a URL

url = 'rr+tcp://localhost:29200?service=reynard';
sub = RobotRaconteur.SubscribeService(url);
c = sub.GetDefaultClientWait(10);
c.say('Hello from URL subscription!');
sub.Close();

// subscribe_url.cs - Subscribe to a service using a URL

using System;
using RobotRaconteur;
using System.Threading;
using System.Threading.Tasks;
using System.Linq;

// Initialize the client node
using (var node_setup = new ClientNodeSetup(args))
{
    // Subscribe to the service using a URL
    string url = "rr+tcp://localhost:29200?service=reynard";
    var sub = RobotRaconteurNode.s.SubscribeService(url);

    // Get the default client
    var c = (experimental.reynard_the_robot.Reynard)sub.GetDefaultClientWait(10000);

    // Say hello
    c.say("Hello from subscribe_url!");
}

// subscribe_url.cpp - Subscribe to a service using a URL

#include <stdio.h>
#include <iostream>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;

int main(int argc, char* argv[])
{
    // Use RobotRaconteur::NodeSetup to initialize Robot Raconteur
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    // Subscribe to the service
    std::string url = "rr+tcp://localhost:29200/?service=reynard";
    RR::ServiceSubscriptionPtr sub = RR::RobotRaconteurNode::s()->SubscribeService(url);

    // Get the default client
    auto reynard = sub->GetDefaultClientWait<experimental::reynard_the_robot::Reynard>(10000);

    // Say hello
    reynard->say("Hello from subscribe_url!");

    return 0;
}

In these examples, the SubscribeService() and GetDefaultClientWait() functions are used to create the connection. The GetDefaultClient() and GetDefaultClientWait() functions will return the “default” connected client. Since SubscribeService() only connects one client, this is the recommended way to retrieve the connection.

Note

In most cases, it is recommended to use SubscribeService() and GetDefaultClientWait() since it will not return an error if the client starts before the service is ready.

See subscriptions for more information about the capabilities of ServiceSubscription.

Subscription Based on Service Criteria

The SubscribeServiceByType() function returns a ServiceSubscription that uses discovery to connect to services rather than using a URL. It decides which services to connect to based on “criteria”, essentially filtering to select services to connect to.

The available criteria are:

The service type of the root object, for example, com.robotraconteur.robotics.robot.Robot
The name of the service
The node name or node ID of the node containing the service
The type of transport used to connect to the service
The attributes of the service
A user-defined predicate function

Note

In most cases, it is preferred to use the Device Connector described in the next section rather than directly using SubscribeServiceByType().

Note

SubscribeServiceByType() will match services where the root object extends/implements the required type along with direct implementations. This allows for new types to extend existing types and still be matched, allowing for forward compatibility.

Simple examples connecting all services of a specific type, in this case, experimental.reynard_the_robot.Reynard:

# subscribe_type.py - Subscribe to services by type

from RobotRaconteur.Client import *
import time

# Subscribe to a service by type
root_object_type = "experimental.reynard_the_robot.Reynard"
sub = RRN.SubscribeServiceByType(root_object_type)
# Give a few seconds for the service to be connected
time.sleep(6)

# Run a function on all connected services. Could also use GetDefaultClientWait() to
# get the first connected client and run functions on that client
# without waiting for all clients to connect
connected_clients = sub.GetConnectedClients()
for k, c in connected_clients.items():
    print(f"Saying hello on client {k}")
    c.say("Hello from type subscription!")

% subscribe_type.py - Subscribe to services by type

root_object_type = 'experimental.reynard_the_robot.Reynard';
sub = RobotRaconteur.SubscribeServiceByType(root_object_type);

% Give a few seconds for the service to be connected
pause(6);

% Run a function on all connected services. Could also use
% GetDefaultClientWait() to get the first connected client and
% run functions on that client without waiting for all clients to connect
connected_clients = sub.GetConnectedClients();

% Loop connected clients and call say method
client_keys = keys(connected_clients);
for i = 1:length(client_keys)
    key = client_keys{i};
    c = connected_clients(key);
    c.say('Hello from type subscription!');
end

sub.Close();

// subscribe_type.cs - Subscribe to a service by type

using System;
using RobotRaconteur;
using System.Threading;
using System.Threading.Tasks;
using System.Linq;

// Initialize the client node
using (var node_setup = new ClientNodeSetup(args))
{
    // Subscribe to a service by type
    string[] root_object_type = new string[] { "experimental.reynard_the_robot.Reynard" };
    var sub = RobotRaconteurNode.s.SubscribeServiceByType(root_object_type);

    // Give a few seconds for the service to be connected
    Thread.Sleep(6000);

    // Run a function on all connected services. Could also use GetDefaultClientWait() to
    // get the first connected client and run functions on that client
    // without waiting for all clients to connect
    var connected_clients = sub.GetConnectedClients();
    foreach (var c1 in connected_clients)
    {
        var c = (experimental.reynard_the_robot.Reynard)c1.Value;
        c.say("Hello from subscribe_type!");
    }
}

// subscribe_type.cpp - Subscribe to a service by type

#include <stdio.h>
#include <iostream>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;

int main(int argc, char* argv[])
{
    // Use RobotRaconteur::NodeSetup to initialize Robot Raconteur
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    // Subscribe to a service by type
    std::vector<std::string> root_object_type = {"experimental.reynard_the_robot.Reynard"};
    RR::ServiceSubscriptionPtr sub = RR::RobotRaconteurNode::s()->SubscribeServiceByType(root_object_type);

    // Give a few seconds for the service to be connected
    boost::this_thread::sleep(boost::posix_time::seconds(6));

    // Run a function on all connected services. Could also use GetDefaultClientWait() to
    // get the first connected client and run functions on that client
    // without waiting for all clients to connect
    auto connected_clients = sub->GetConnectedClients();
    for (auto client : connected_clients)
    {
        auto reynard = RR::rr_cast<experimental::reynard_the_robot::Reynard>(client.second);
        reynard->say("Hello from subscribe_type!");
    }

    return 0;
}

The following examples show how to use filters with SubscribeServiceByType().

SubscribeServiceByType() Filter Examples (click to expand)

# subscribe_filter.py - Subscribe to services by type using a filter

from RobotRaconteur.Client import *
import time


def subscription_predicate(service_info2):
    # This function is called for each discovered service
    # Return True to connect to the service, False to ignore
    # The service_info2 parameter is a ServiceInfo2 object
    # containing information about the discovered service
    return True


# Populate a subscription filter. Note that all empty fields are considered "wildcards" that match any value
f = RR.ServiceSubscriptionFilter()
# Only connect to services named "reynard"
f.ServiceNames = ['reynard']
# Only use rr+tcp transport
f.TransportSchemes = ['rr+tcp', 'rr+local']
# The ServiceSubscriptionFilter has powerful attribute matching capabilities
# The use is intended for advanced use cases
# f.Attributes = <Advanced attribute matching>
# f.AttributesMatchOperation = ServiceSubscriptionFilterAttributeGroupOperation_AND
# Set a "predicate" function that is called for each discovered service
f.Predicate = subscription_predicate
# Set the maximum number of clients to connect. Default is -1 (no limit)
f.MaxConnections = 5

# Create a ServiceSubscriptionFilterNode for node matching
n = RR.ServiceSubscriptionFilterNode()
# Only connect to nodes named "experimental.reynard_the_robot"
n.NodeName = "experimental.reynard_the_robot"
# Only connect to nodes with NodeID as listed. This will be different for every instance of the node
# n.NodeID = RR.NodeID('12345678-1234-1234-1234-123456789abc')
# Username and credentials can also be set for services that require authentication.
# This should only be used when NodeID is also specified so the credentials are not sent to the wrong node
# n.Username = "username"
# n.Credentials = {"password", RR.VarValue("my_password", "string")}
f.Nodes.append(n)

# Subscribe to a service by type using the filter
root_object_type = "experimental.reynard_the_robot.Reynard"
sub = RRN.SubscribeServiceByType(root_object_type, f)
# Give a few seconds for the service to be connected
time.sleep(6)

# Run a function on all connected services. Could also use GetDefaultClientWait() to
# get the first connected client and run functions on that client
# without waiting for all clients to connect
connected_clients = sub.GetConnectedClients()
for k, c in connected_clients.items():
    c.say("Hello from subscribe_filter!")

% subscribe_filter.py - Subscribe to services by type using a filter

function subscribe_filter()

% Populate a subscription filter. Note that all missing fields are
% considered "wildcards" that match any value
f = struct;
% Only connect to services named "reynard"
f.ServiceNames = {'reynard'};
% Only use rr+tcp transport
f.TransportSchemes = {'rr+tcp'};
% The ServiceSubscriptionFilter has powerful attribute matching capabilities
% The use is intended for advanced use cases
% f.Attributes = <Advanced attribute matching>
% f.AttributesMatchOperation = 'and';
% "Predicate" not supported in matlab
% Set the maximum number of clients to connect. Default is -1 (no limit)
f.MaxConnections = -1;

% Create a ServiceSubscriptionFilterNode for node matching
n = struct;
% Only connect to nodes named "experimental.reynard_the_robot"
n.NodeName = 'experimental.reynard_the_robot';
% Only connect to nodes with NodeID as listed. This will be different for every instance of the node
% n.NodeID = '12345678-1234-1234-1234-123456789abc';
%Username and credentials can also be set for services that require authentication.
%This should only be used when NodeID is also specified so the credentials are not sent to the wrong node
%n.Username = 'username';
%n.Credentials = containers.Map({'password'}, {RobotRaconteurVarValue('my_password', 'string')});
f.Nodes = {n};

% Subscribe to a service by type using the filter
root_object_type = 'experimental.reynard_the_robot.Reynard';
sub = RobotRaconteur.SubscribeServiceByType(root_object_type, f);

% Give a few seconds for the service to be connected
pause(6);

% Run a function on all connected services. Could also use
% GetDefaultClientWait() to get the first connected client and
% run functions on that client without waiting for all clients to connect
connected_clients = sub.GetConnectedClients();

% Loop connected clients and call say method
client_keys = keys(connected_clients);
for i = 1:length(client_keys)
    key = client_keys{i};
    c = connected_clients(key);
    c.say('Hello from subscribe_filter!');
end

sub.Close();

end

// subscribe_filter.cs - Subscribe to a service by type using a filter

using System;
using RobotRaconteur;
using System.Threading;
using System.Threading.Tasks;
using System.Linq;

bool subscription_predicate(ServiceInfo2 service_info)
{
    // This function is called for each discovered service
    // Return true to connect to the service, false to ignore
    // The service_info2 parameter is a ServiceInfo2 object
    // containing information about the discovered service
    return true;
}

// Initialize the client node
using (var node_setup = new ClientNodeSetup(args))
{

    // Populate a subscription filter. Note that all empty fields are considered "wildcards" that match any value
    var f = new ServiceSubscriptionFilter();
    // Only connect to services named "reynard"
    f.ServiceNames = new string[] { "reynard" };
    // Only use rr+tcp and rr+local transport
    f.TransportSchemes = new string[] { "rr+tcp", "rr+local" };
    // The ServiceSubscriptionFilter has powerful attribute matching capabilities
    // The use is intended for advanced use cases
    // f.Attributes = <Advanced attribute matching>
    // f.AttributesMatchOperation = ServiceSubscriptionFilterAttributeGroupOperation.AND;
    // Set a "predicate" function that is called for each discovered service
    f.Predicate = subscription_predicate;
    // Set the maximum number of clients to connect. Default is -1 (no limit)
    f.MaxConnections = 5;

    // Create a ServiceSubscriptionFilterNode for node matching
    var n = new ServiceSubscriptionFilterNode();
    // Only connect to nodes named "experimental.reynard_the_robot"
    n.NodeName = "experimental.reynard_the_robot";
    // Only connect to nodes with NodeID as listed. This will be different for every instance of the node
    // n.NodeID = new NodeID('12345678-1234-1234-1234-123456789abc');
    // Username and credentials can also be set for services that require authentication.
    // This should only be used when NodeID is also specified so the credentials are not sent to the wrong node
    // n.Username = "username"
    // auto credentials = RR::AllocateEmptyRRMap<std::string, RR::RRValue>();
    // credentials->insert({"password", RR::VarValue("my_password", "string")});
    // n.Credentials = credentials;
    f.Nodes = new ServiceSubscriptionFilterNode[] { n };

    // Subscribe to a service by type
    string[] root_object_type = new string[] { "experimental.reynard_the_robot.Reynard" };
    var sub = RobotRaconteurNode.s.SubscribeServiceByType(root_object_type, f);

    // Give a few seconds for the service to be connected
    Thread.Sleep(6000);

    // Run a function on all connected services. Could also use GetDefaultClientWait() to
    // get the first connected client and run functions on that client
    // without waiting for all clients to connect
    var connected_clients = sub.GetConnectedClients();
    foreach (var c1 in connected_clients)
    {
        var c = (experimental.reynard_the_robot.Reynard)c1.Value;
        c.say("Hello from subscribe_filter!");
    }
}

// subscribe_filter.cpp - Subscribe to a service by type using a filter

#include <stdio.h>
#include <iostream>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;

bool subscription_predicate(const RR::ServiceInfo2& service_info2)
{
    // This function is called for each discovered service
    // Return true to connect to the service, false to ignore
    // The service_info2 parameter is a ServiceInfo2 object
    // containing information about the discovered service
    return true;
}

int main(int argc, char* argv[])
{
    // Use RobotRaconteur::NodeSetup to initialize Robot Raconteur
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    // Populate a subscription filter. Note that all empty fields are considered "wildcards" that match any value
    auto f = RR_MAKE_SHARED<RR::ServiceSubscriptionFilter>();
    // Only connect to services named "reynard"
    f->ServiceNames.push_back("reynard");
    // Only use rr+tcp and rr+local transport
    f->TransportSchemes.push_back("rr+tcp");
    f->TransportSchemes.push_back("rr+local");
    // The ServiceSubscriptionFilter has powerful attribute matching capabilities
    // The use is intended for advanced use cases
    // f->Attributes = <Advanced attribute matching>
    // f->AttributesMatchOperation = RR::ServiceSubscriptionFilterAttributeGroupOperation_AND;
    // Set a "predicate" function that is called for each discovered service
    f->Predicate = subscription_predicate;
    // Set the maximum number of clients to connect. Default is -1 (no limit)
    f->MaxConnections = 5;

    // Create a ServiceSubscriptionFilterNode for node matching
    auto n = RR_MAKE_SHARED<RR::ServiceSubscriptionFilterNode>();
    // Only connect to nodes named "experimental.reynard_the_robot"
    n->NodeName = "experimental.reynard_the_robot";
    // Only connect to nodes with NodeID as listed. This will be different for every instance of the node
    // n->NodeID = RR::NodeID('12345678-1234-1234-1234-123456789abc');
    // Username and credentials can also be set for services that require authentication.
    // This should only be used when NodeID is also specified so the credentials are not sent to the wrong node
    // n->Username = "username";
    // auto credentials = RR::AllocateEmptyRRMap<std::string, RR::RRValue>();
    // credentials->insert({"password", RR::VarValue("my_password", "string")});
    // n->Credentials = credentials;
    f->Nodes.push_back(n);

    // Subscribe to a service by type using the filter
    std::vector<std::string> root_object_type = {"experimental.reynard_the_robot.Reynard"};
    RR::ServiceSubscriptionPtr sub = RR::RobotRaconteurNode::s()->SubscribeServiceByType(root_object_type, f);

    // Give a few seconds for the service to be connected
    boost::this_thread::sleep(boost::posix_time::seconds(6));

    // Run a function on all connected services. Could also use GetDefaultClientWait() to
    // get the first connected client and run functions on that client
    // without waiting for all clients to connect
    auto connected_clients = sub->GetConnectedClients();
    for (auto client : connected_clients)
    {
        auto reynard = RR::rr_cast<experimental::reynard_the_robot::Reynard>(client.second);
        reynard->say("Hello from subscribe_filter!");
    }

    return 0;
}

The SubscribeServiceByType function and ServiceSubscription provide sophisticated capabilities. See subscriptions and the documentation specific to each programming language for more information.

Device Connector

The Device Connector is a utility provided as part of the Robot Raconteur Companion for Python and C++. The Device Connector uses the “Device” concept discussed in device-concept that is introduced by the Robot Raconteur Standard Types. All “Devices” provide a DeviceInfo structure that contains metadata about the device, including a unique identifier (name and UUID), model and manufacturer information, device class information, serial number, description, tags, and more. The Device Connector uses this metadata to connect to devices. The Device Connector can also use URLs and subscription filters to connect to services. This capability is built on top of the Robot Raconteur subscription system.

The Device Connector uses the DeviceConnectorDetails structure to specify which devices to connect to. The DeviceConnectorDetails can use the following methods to select devices:

Device name, along with additional information like tags, manufacturer, model, and serial number. The device must provide a DeviceInfo structure to use this method.
A list of candidate URLs
A service type and filter

The following example uses a DeviceConnector to connect to the camera found in the Training Simulator robot scenes:

# device_connector.py - Example of using the DeviceConnector class to connect to a device

from RobotRaconteur.Client import *
from RobotRaconteurCompanion.Util.DeviceConnector import DeviceConnector, DeviceConnectorDetails
from RobotRaconteurCompanion.Util.ImageUtil import ImageUtil
import cv2

# Create a DeviceConnector object
con = DeviceConnector()

# Add a device to the connector
d1 = DeviceConnectorDetails(device_nickname="camera", device="gazebo_camera")
con.AddDevice(d1)

# Get the ServiceSubscription to the camera
sub = con.GetDevice("camera")

# Get the default client and capture and image
c = sub.GetDefaultClientWait(10)
raw_img = c.capture_frame()
image_util = ImageUtil(client_obj=c)

# Display the image
img = image_util.image_to_array(raw_img)
cv2.namedWindow("Image")
cv2.imshow("Image", img)
cv2.waitKey()
cv2.destroyAllWindows()

// device_connector.cpp - Example of using the DeviceConnector class to connect to a device

#include <stdio.h>
#include <iostream>
#include <RobotRaconteur.h>
#include <RobotRaconteurCompanion/Util/DeviceConnector.h>
#include <RobotRaconteurCompanion/StdRobDef/StdRobDefAll.h>
#include <RobotRaconteurCompanion/Util/ImageUtil.h>
#include <RobotRaconteurCompanion/Util/IdentifierUtil.h>
#include <opencv2/highgui/highgui.hpp>

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace RRC = RobotRaconteur::Companion;
namespace RR_Util = RobotRaconteur::Companion::Util;
namespace cam = com::robotraconteur::imaging;
namespace img = com::robotraconteur::image;

int main(int argc, char* argv[])
{
    // Register the standard Robot Raconteur types
    RRC::RegisterStdRobDefServiceTypes();

    // Use RobotRaconteur::NodeSetup to initialize Robot Raconteur
    RR::ClientNodeSetup node_setup(std::vector<RR_SHARED_PTR<RR::ServiceFactory> >(), argc, argv);

    // Create a DeviceConnector
    RR_Util::DeviceConnector con;
    con.Init();

    // Create a DeviceConnectorDetails to connect to the camera
    RR_Util::DeviceConnectorDetails d1("camera", RR_Util::CreateIdentifierFromName("gazebo_camera"),
                                       {"com.robotraconteur.imaging.Camera"});

    // Add the camera to the DeviceConnector
    con.AddDevice(d1);

    // Get the subscription to the camera
    auto sub = con.GetDevice("camera");

    // Get the camera client
    auto c = sub->GetDefaultClientWait<cam::Camera>(5000);

    // Capture an image and convert to OpenCV image type
    cv::Mat frame1 = RR_Util::ImageToMat(c->capture_frame());

    // Show image
    cv::imshow("Image", frame1);
    cv::waitKey();
    cv::destroyAllWindows();

    return 0;
}

The following example uses a YAML file to specify the camera details.

# devices.yml - Yaml file containing device information

devices:
  camera:
    device: gazebo_camera
    root_object_type: com.robotraconteur.imaging.Camera

# device_connector_yaml.py - Example of using the DeviceConnector class to connect to a device

# To run this example:
#    python device_connector_yml.py --devices devices.yaml

from RobotRaconteur.Client import *
from RobotRaconteurCompanion.Util.DeviceConnector import DeviceConnector, DeviceConnectorDetails
from RobotRaconteurCompanion.Util.ImageUtil import ImageUtil
import cv2
import argparse

# Parse command line arguments to get the devices yaml file object
parser = argparse.ArgumentParser(description="Device connector example")
parser.add_argument("--devices", type=argparse.FileType("r"), required=True, help="The devices yaml file")
args, _ = parser.parse_known_args()

# Create a DeviceConnector object and load the devices yaml file
con = DeviceConnector(devices_yaml_f=args.devices)

# Get the ServiceSubscription to the camera
sub = con.GetDevice("camera")

# Get the default client and capture and image
c = sub.GetDefaultClientWait(10)
raw_img = c.capture_frame()
image_util = ImageUtil(client_obj=c)

# Display the image
img = image_util.image_to_array(raw_img)
cv2.namedWindow("Image")
cv2.imshow("Image", img)
cv2.waitKey()
cv2.destroyAllWindows()

// device_connector_yaml.cpp - Example of using the DeviceConnector class to connect to a device using a YAML file

// To run the example:
//    device_connector_yaml --devices devices.yml

#include <stdio.h>
#include <iostream>
#include <RobotRaconteur.h>
#include <RobotRaconteurCompanion/Util/DeviceConnector.h>
#include <RobotRaconteurCompanion/StdRobDef/StdRobDefAll.h>
#include <RobotRaconteurCompanion/Util/ImageUtil.h>
#include <RobotRaconteurCompanion/Util/IdentifierUtil.h>
#include <opencv2/highgui/highgui.hpp>
#include <boost/program_options.hpp>
#include <fstream>

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace RRC = RobotRaconteur::Companion;
namespace RR_Util = RobotRaconteur::Companion::Util;
namespace cam = com::robotraconteur::imaging;
namespace img = com::robotraconteur::image;

int main(int argc, char* argv[])
{

    boost::program_options::options_description desc("Allowed options");
    desc.add_options()("devices", boost::program_options::value<std::string>(),
                       "YAML file containing device definitions");

    // Parse known options. Use allow_unregistered() to allow unknown options due to
    // possible --robotraconteur-* options being passed to the node
    boost::program_options::variables_map vm;
    boost::program_options::store(
        boost::program_options::command_line_parser(argc, argv).options(desc).allow_unregistered().run(), vm);

    // Open the YAML file
    std::ifstream file(vm["devices"].as<std::string>());
    if (!file.is_open())
    {
        std::cerr << "Error opening devices file" << std::endl;
        return 1;
    }

    // Register the standard Robot Raconteur types
    RRC::RegisterStdRobDefServiceTypes();

    // Use RobotRaconteur::NodeSetup to initialize Robot Raconteur
    RR::ClientNodeSetup node_setup(std::vector<RR_SHARED_PTR<RR::ServiceFactory> >(), argc, argv);

    // Create a DeviceConnector and initialize from the YAML file
    RR_Util::DeviceConnector con;
    con.InitFromYamlFile(file);

    // Get the subscription to the camera
    auto sub = con.GetDevice("camera");

    // Get the camera client
    auto c = sub->GetDefaultClientWait<cam::Camera>(5000);

    // Capture an image and convert to OpenCV image type
    cv::Mat frame1 = RR_Util::ImageToMat(c->capture_frame());

    // Show image
    cv::imshow("Image", frame1);
    cv::waitKey();
    cv::destroyAllWindows();

    return 0;
}

PyRI Device Manager

The PyRI Open Source Teach Pendant uses a built-in “Device Manager” to add and remove devices from the system. The Device Manager can be accessed using a user interface or a Robot Raconteur service. The Device Manager is typically used with Robot Raconteur services that provide a DeviceInfo structure.

Third-party nodes can connect to the PyRI Device Manager and use it to connect to devices. In fact, almost all of the functionality provided by the PyRI Teach Pendant can be used through Robot Raconteur services. This is a powerful development option since it allows the developer to utilize all the features of PyRI while developing their projects.

The following example shows how to connect to the PyRI Device Manager and use it to connect to a camera:

# pyri_device_manager_client.py - Example of using the PyriDeviceManagerClient class to connect to a device

# The package pyri-common must be installed to use this example. See https://github.com/pyri-project/pyri-core
# for more information.

from pyri.device_manager_client import DeviceManagerClient
from RobotRaconteur.Client import *
from RobotRaconteurCompanion.Util.ImageUtil import ImageUtil
import cv2

# Create the DeviceManagerClient object
d = DeviceManagerClient()

# Refresh the available devices from the service
d.refresh_devices(1)

# Get the default client and capture and image
c = d.get_device_client("camera", timeout=10)
raw_img = c.capture_frame()
image_util = ImageUtil(client_obj=c)

# Display the image
img = image_util.image_to_array(raw_img)
cv2.namedWindow("Image")
cv2.imshow("Image", img)
cv2.waitKey()
cv2.destroyAllWindows()

Networking and Firewalls

Robot Raconteur uses standard IPv4 and IPv6 networking protocols to communicate between nodes when they are on different computers, or using localhost (127.0.0.1) when they are on the same computer. Currently, Robot Raconteur uses TCP/IP for communication; however, UDP/IP communication using QUIC is planned. Networking can be an extremely complex topic and has many pitfalls that can cause connections to fail. Robot Raconteur is primarily concerned with local connections between devices on the same local Ethernet network, which reduces the complexity somewhat. This section provides a brief overview of the relevant networking concepts to create connections. See also the Networking and Firewall Configuration Application Note for up-to-date information on networking and firewall configuration, along with tooling to help configure networks correctly.

Note

See the Networking and Firewall Configuration Application Note for a more in-depth discussion of networking and firewall configuration.

Note

Robot Raconteur has the official TCP and UDP port number 48653 assigned by the IANA! The Robot Raconteur Port Sharer uses TCP port 48653. Server nodes that are not using the port sharer should use a different port number. UDP port 48653 is used for discovery.

Networking Fundamentals

Devices on an IP network have an “IP Address,” which allows for packets to be routed to the correct device.

IPv4 addresses are 32-bits and are typically written as four decimal numbers separated by periods, for example, 192.168.12.14. IPv4 addresses only have around 4 billion possible addresses, which means that it is not possible to assign a unique address to every device in existence. Configuration is required to guarantee a static IPv4 address, which causes significant complications.

IPv6 addresses use a 128-bit address space, which allows for more than 340 trillion, trillion, trillion possible addresses. IPv6 addresses have the concept of “link-local” addresses, which are only valid on a single local network. They start with fe80::, and are followed by a 64-bit hexadecimal number, for example, fe80::6a23:fb1a:23b3:db79. This number can be based on the MAC address of the adapter or randomly generated. Crucially for Robot Raconteur, this is an automatically configured address that is statistically guaranteed to be unique on the local network. Robot Raconteur can use both IPv4 and IPv6 addresses, but IPv6 is preferred since it is easier to configure and more robust. The discovery and subscription system will return IPv6 addresses by default.

Note

By default, Linux uses a randomly generated IPv6 link-local address for privacy reasons. This random address may change occasionally, which is highly undesirable for Robot Raconteur services. To disable, run the following command in a terminal:

cat >> /etc/sysctl.conf <<EOT
net.ipv6.conf.all.use_tempaddr=0
net.ipv6.conf.default.use_tempaddr=0
EOT

sysctl -p

Source

To determine the IP address of a device:

Use ipconfig on Windows in a command prompt
Use ip a on Linux in a terminal
Use ifconfig on MacOS in a terminal

These will typically return many addresses, some with a physical adapter attached to a network, but many more with virtual adapters that are not relevant. It is recommended that the Service Browser be used on the same computer as the client to determine the correct address to use since it can be very difficult to determine the correct address manually unless you are familiar with networking concepts.

Firewall Configuration

Most modern operating systems have a firewall that blocks incoming connections by default. This is an important security feature, but it will by default block Robot Raconteur connections. The firewall must be configured to allow full access for the program running the Robot Raconteur node. The following subsections discuss how to configure the firewall for different operating systems.

Note

Robot Raconteur uses IPv6 UDP multicast port 48653 for discovery. This port must be open for discovery, or the program must have an exception in the firewall!

Windows Firewall

By default, Windows will block Robot Raconteur. It is necessary to either add an exception or disable the firewall completely. Disabling the firewall is useful for a development environment, but in general, it is recommended to add an exception for the program running the Robot Raconteur node.

Instructions to disable the Windows Firewall: Windows Firewall
Instructions to add an exception to the Windows Firewall for a specific program: How to Allow or Block a Program Through Firewall Windows 10

When a program first starts and attempts to open a port, Windows will typically prompt the user to allow or block the connection. This is the easiest way to configure the firewall.

Linux Firewall

Ubuntu and Debian do not by default have a firewall enabled. If a firewall is enabled, it is typically UFW or iptables. Configuring these firewalls is more complex than Windows, and it is recommended to consult the documentation.

MacOS Firewall

MacOS does not typically have a firewall enabled that blocks Robot Raconteur connections.