Device connection manager for connecting to devices using Robot Raconteur. More...

#include <DeviceConnector.h>

Public Member Functions
	DeviceConnector (RobotRaconteur::RobotRaconteurNodePtr node=nullptr, bool autoconnect=true)
	Construct a new DeviceConnector.
void	Init ()
	Initialize the DeviceConnector.
void	Init (const std::vector< DeviceConnectorDetails > &devices)
	Initialize the DeviceConnector with a list of devices.
void	InitFromYamlStr (const std::string &yaml)
	Initialize the DeviceConnector from a YAML string.
void	InitFromYamlFile (std::istream &file)
	Initialize the DeviceConnector from a YAML stream.
void	InitFromYamlFile (const boost::filesystem::path &filename)
	Initialize the DeviceConnector from a YAML file.
void	AddDevice (const DeviceConnectorDetails &device_details, bool force_connect=false)
	Add a device to the DeviceConnector.
void	RemoveDevice (const std::string &device_nickname, bool close=true)
	Remove a device from the DeviceConnector.
void	ConnectDevice (const std::string &device_nickname)
	Connect to a device if not already connected.
void	DisconnectDevice (const std::string &device_nickname, bool close=true)
	Disconnect a device.
RobotRaconteur::ServiceSubscriptionPtr	GetDevice (const std::string &device_nickname, bool force_create=false)
	Get the Device object.
bool	TryGetDevice (const std::string &device_nickname, RobotRaconteur::ServiceSubscriptionPtr &device)
	Try to get the Device object. Returns false if the device does not exist instead of throwing an exception.
void	Close ()
	Close the DeviceConnector.
std::vector< std::string >	GetDeviceNicknames ()
	Get all nicknames of the devices.
boost::shared_ptr< RobotRaconteur::ServiceSubscriptionManager >	GetServiceSubscriptionManager ()
	Get the underlying ServiceSubscriptionManager used by the DeviceConnector.

Detailed Description

Device connection manager for connecting to devices using Robot Raconteur.

The DeviceConnector class is designed to simplify connecting to devices using Robot Raconteur. Finding and connecting to multiple services can be complex, especially when using advanced features such as service discovery filters. The DeviceConnector takes advantage of the "device" concept introduced by the Robot Raconteur standard types. The "device" concept introduces the com.robotraconteur.device.Device interface, which provides the structure com.robotraconteur.device.DeviceInfo containing metadata about the device. The "device" concept provides a more descriptive way to identify, connect, and interrogate devices.

Three fields in the com.robotraconteur.device.DeviceInfo structure are used to identify devices by the DeviceConnector:

1. `device`: The device identifier (name and/or uuid) of the device.
2. `serial_number`: The serial number of the device.
3. `tags`: A list of tags associated with the device. These tags are typically strings or identifiers.

For the "device" concept, an identifier is a combination of a human readable name and a UUID. The name is not guaranteed to be unique, but the combination of the name and UUID is expected unique. The UUID should be used in a production environment, but the simple name can be used for testing and development.

The combination of device, serial_number, and tags is used to generate a ServiceSubscriptionFilter that is used to create a subscription to the device.

The DeviceConnector is used by software like the PyRI Open Source Teaching Pendant to connect to devices. The DeviceConnector should be used by production level software that provides the option to users to select and connect to devices.

The DeviceConnectorDetails structure is used to provide information to the DeviceConnector about how to connect to a device. See the DeviceConnectorDetails documentation for more information on each field. DeviceConnectorDetails contains information that is used by the DeviceConnector class to connect to devices. The DeviceConnector can connect to devicues using three different methods:

1. Discovery devices using device identifier (name, uuid) in combination with optional serial
   number and/or device tags
2. Connection using a list of URLs. Using URLs is the most direct way to connect to a device.
3. Connection using specified list of service root object types and optional subscription filter.

Different combinations of fields are valid depending on the connection method used.

The following fields are used to connect to devices with the methods described above:

 1. `Device`, `RootObjectType`, `SerialNumber`, `Tags`, `TagMatchOperation`, `ServiceNodes`, `TransportSchemes`,

MaxConnections

Urls, UrlAuth
RootObjectType, SubscriptionFilter

For all methods, the device_nickname field is used to identify the device in the DeviceConnector and must be unique.

The device details can also be loaded from a YAML file.

The YAML file should match the following example format:

devices:
    device1:
        # Connect to device using URLs
        urls: rr+intra:
    device2:
        # Connect to device using device identifier, serial number, and tags
        device: robot2
        serial_number: "1234"
        tags:
        - tag1
        - tag2
    device3:
        # Connect to device using device identifier and tags
        device:
            name: robot3
            uuid: "b92fda92-c74e-4fd1-8174-0163b4dc182a"
        tags:
        - name: tag1
          uuid: "a9d4e339-f248-49c7-9443-e2f3ebba9c02"
        - tag2
    device4:
        # Match any tags or serial number
        device: robot3

Constructor & Destructor Documentation

◆ DeviceConnector()

RobotRaconteur::Companion::Util::DeviceConnector::DeviceConnector	(	RobotRaconteur::RobotRaconteurNodePtr	node = nullptr,
		bool	autoconnect = true )

Construct a new DeviceConnector.

Parameters

node	The Robot Raconteur node to use. If null, the default node is used.
autoconnect	If true, the DeviceConnector will automatically connect to devices when they are added. Default is true.

Must call one of the Init methods to initialize the DeviceConnector.

Member Function Documentation

◆ AddDevice()

void RobotRaconteur::Companion::Util::DeviceConnector::AddDevice	(	const DeviceConnectorDetails &	device_details,
		bool	force_connect = false )

Add a device to the DeviceConnector.

Also used to update a device. If the device already exists, it will be updated with the new details.

Parameters

device_details	The device details to add
force_connect	If true, the device will be connected immediately. Default is false. Ignored if autoconnect is true.

◆ Close()

void RobotRaconteur::Companion::Util::DeviceConnector::Close ( )

Close the DeviceConnector.

All subscriptions to devices will be closed.

◆ ConnectDevice()

void RobotRaconteur::Companion::Util::DeviceConnector::ConnectDevice ( const std::string & device_nickname )

Connect to a device if not already connected.

If a device is disconnected or autoconnect is false, the device will be connected.

Parameters

device_nickname The nickname of the device to connect

◆ DisconnectDevice()

void RobotRaconteur::Companion::Util::DeviceConnector::DisconnectDevice	(	const std::string &	device_nickname,
		bool	close = true )

Disconnect a device.

Parameters

device_nickname	The nickname of the device to disconnect
close	If true, the device will be closed. Default is true.

◆ GetDevice()

RobotRaconteur::ServiceSubscriptionPtr RobotRaconteur::Companion::Util::DeviceConnector::GetDevice	(	const std::string &	device_nickname,
		bool	force_create = false )

Get the Device object.

Parameters

device_nickname	The nickname of the device
force_create	If true, the device will be created if it does not exist. Default is false.

Returns: RobotRaconteur::ServiceSubscriptionPtr The subscription to the device

◆ GetDeviceNicknames()

std::vector< std::string > RobotRaconteur::Companion::Util::DeviceConnector::GetDeviceNicknames ( )

Get all nicknames of the devices.

Returns: std::vector<std::string> The nicknames of the devices

◆ GetServiceSubscriptionManager()

boost::shared_ptr< RobotRaconteur::ServiceSubscriptionManager > RobotRaconteur::Companion::Util::DeviceConnector::GetServiceSubscriptionManager ( )

Get the underlying ServiceSubscriptionManager used by the DeviceConnector.

Returns: RR_SHARED_PTR<RobotRaconteur::ServiceSubscriptionManager>

◆ Init() [1/2]

void RobotRaconteur::Companion::Util::DeviceConnector::Init ( )

Initialize the DeviceConnector.

Initializes the DeviceConnector with no devices. Must call AddDevice to add devices.

◆ Init() [2/2]

void RobotRaconteur::Companion::Util::DeviceConnector::Init ( const std::vector< DeviceConnectorDetails > & devices )

Initialize the DeviceConnector with a list of devices.

Parameters

devices The list of devices to add

◆ InitFromYamlFile() [1/2]

void RobotRaconteur::Companion::Util::DeviceConnector::InitFromYamlFile ( const boost::filesystem::path & filename )

Initialize the DeviceConnector from a YAML file.

See the DeviceConnector documentation for the YAML format

Parameters

filename The path to the YAML file

◆ InitFromYamlFile() [2/2]

void RobotRaconteur::Companion::Util::DeviceConnector::InitFromYamlFile ( std::istream & file )

Initialize the DeviceConnector from a YAML stream.

See the DeviceConnector documentation for the YAML format

Parameters

file	The YAML formatted stream

◆ InitFromYamlStr()

void RobotRaconteur::Companion::Util::DeviceConnector::InitFromYamlStr ( const std::string & yaml )

Initialize the DeviceConnector from a YAML string.

See the DeviceConnector documentation for the YAML format

Parameters

yaml	The YAML formatted string

◆ RemoveDevice()

void RobotRaconteur::Companion::Util::DeviceConnector::RemoveDevice	(	const std::string &	device_nickname,
		bool	close = true )

Remove a device from the DeviceConnector.

Parameters

device_nickname	The nickname of the device to remove
close	If true, the device will be disconnected before removing. Default is true.

◆ TryGetDevice()

bool RobotRaconteur::Companion::Util::DeviceConnector::TryGetDevice	(	const std::string &	device_nickname,
		RobotRaconteur::ServiceSubscriptionPtr &	device )

Try to get the Device object. Returns false if the device does not exist instead of throwing an exception.

Parameters

device_nickname	The nickname of the device
device	[out] The subscription to the device

Returns: true The device was found; false No device with the given nickname was found

The documentation for this class was generated from the following file:

include/RobotRaconteurCompanion/Util/DeviceConnector.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DeviceConnector()

Member Function Documentation

◆ AddDevice()

◆ Close()

◆ ConnectDevice()

◆ DisconnectDevice()

◆ GetDevice()

◆ GetDeviceNicknames()

◆ GetServiceSubscriptionManager()

◆ Init() [1/2]

◆ Init() [2/2]

◆ InitFromYamlFile() [1/2]

◆ InitFromYamlFile() [2/2]

◆ InitFromYamlStr()

◆ RemoveDevice()

◆ TryGetDevice()