RobotRaconteurCompanion.Util.DeviceConnector

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.

The DeviceConnector can use device metadata, URLs, or service discovery filters to connect to devices. The DeviceConnectorDetails structure is used to specify the connection details. The DeviceConnector uses the Robot Raconteur ServiceSubscriptionManager class to manage subscriptions to services based on the information provided in the DeviceConnectorDetails structure. Each device uses a unique nickname to identify the device locally.

The list of DeviceConnectorDetails can also be specified using YAML files to simplify the configuration of the DeviceConnector when connecting to multiple devices. The file can easily be specified on the command line using the Python argparse module.

The DeviceConnector is used by applications like the PyRI Open Source Teaching Pendant to simplify the connection to multiple devices. It is recommended to use the PyRI Device Manager capability to manage complex systems with multiple devices when practical to do so.

An example of using the DeviceConnector to connect to a device using the device name is shown below:

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

# Create a DeviceConnector
connector = DeviceConnector()

# Create a DeviceConnectorDetails using the device name "abb_robot"
# For this example, we do not use other metadata like tags, serial number, UUIDs, etc
device_details = DeviceConnectorDetails(device_nickname="robot", device="abb_robot")

# Add to the device
device = connector.AddDevice(device_details)

# Get the device subscription
device_sub = connector.GetDevice("robot")

# Get the device client
device_client = device_sub.GetDefaultClientWait(5)

# Read and print the device info
device_info = device_client.device_info
print(device_info)

# The device client can be used to connect to other services on the device. The subscription
# can be used to subscribe the wires and pipes on the device.

# Close the connector
connector.Close()

An example of using the DeviceConnector to connect to a device using a URL is shown below:

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

# Create a DeviceConnector
connector = DeviceConnector()

# Create a DeviceConnectorDetails using the URL "rr+tcp://localhost:58653?service=device"
# For this example, we do not use other metadata like tags, serial number, UUIDs, etc
device_url = "rr+tcp://localhost:52512/?service=robot"
device_details = DeviceConnectorDetails(device_nickname="robot", urls=[device_url])

# Add to the device
device = connector.AddDevice(device_details)

# Get the device subscription
device_sub = connector.GetDevice("robot")

# Get the device client
device_client = device_sub.GetDefaultClientWait(5)

# Read and print the device info
device_info = device_client.device_info
print(device_info)

# The device client can be used to connect to other services on the device. The subscription
# can be used to subscribe the wires and pipes on the device.

# Close the connector
connector.Close()

An example using a YAML file to specify the connection details is shown below:

YAML file:

devices:
  robot:
    device: abb_robot
  robot2:
    urls:
      - rr+tcp://localhost:52512/?service=robot

Python code using argparse to specify the YAML file:

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

# Use argparse to specify the YAML file
parser = argparse.ArgumentParser(description="Device Connector Example")
parser.add_argument("--client-config-file", type=argparse.FileType('r'), required=True, help="Client connection configuration file")

args, _ = parser.parse_known_args()

# Create a DeviceConnector and load the device details from the YAML file
connector = DeviceConnector(devices_yaml_f=args.client_config_file)

# Get robot default client
robot = connector.GetDevice("robot").GetDefaultClientWait(5)
robot2 = connector.GetDevice("robot2").GetDefaultClientWait(5)

print(robot.device_info)
print(robot2.device_info)

# The devices are now connected and can be used

# Close the connector
connector.Close()

DeviceConnector

class RobotRaconteurCompanion.Util.DeviceConnector.DeviceConnector(device_list=None, devices_yaml_f=None, autoconnect=True, node=None)

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:

device: The device identifier (name and/or uuid) of the device.

serial_number: The serial number of the device.

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:

Discovery devices using device identifier (name, uuid) in combination with optional serial number and/or device tags

Connection using a list of URLs. Using URLs is the most direct way to connect to a device.

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:

device, serial_number, tags, tag_match_operation, service_nodes, transport_schemes, max_connections

urls, url_auth

root_object_type, subscription_filter

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 using the devices_yaml_f parameter, or using the utility functions load_device_details_from_yaml, load_device_details_from_yaml_path, and load_device_details_from_yaml_dict.

The YAML file should match the following example format:

devices:
    device1:
        # Connect to device using URLs
        urls: rr+intra:///?nodename=server_node&service=robot1
    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

Use io.StringIO to load the YAML from a string.

Parameters:

device_list (list[DeviceConnectorDetails]) – (optional) A list of DeviceConnectorDetails to connect to devices
devices_yaml_f (file) – (optional) A file object containing YAML formatted device details
autoconnect (bool) – (optional) If True, the DeviceConnector will automatically connect to devices
node (RobotRaconteur.RobotRaconteurNode) – (optional) The Robot Raconteur node to use for parsing. Defaults to RobotRaconteurNode.s

AddDevice(device_details, force_connect=False)

Add a device to the DeviceConnector

Parameters:: device_details (DeviceConnectorDetails) – The device details to add

Close(): Close the DeviceConnector and all subscriptions

ConnectDevice(device_nickname)

Connect to a device previously added to the DeviceConnector but not connected

Parameters:: device_nickname (str) – The nickname of the device to connect

property DeviceNicknames

Get a list of device nicknames

Returns:: A list of device nicknames
Return type:: list[str]

DisconnectDevice(device_nickname, close=True)

Disconnect from a device previously connected to the DeviceConnector

Parameters:

device_nickname (str) – The nickname of the device to disconnect
close (bool) – (optional) If True, close the device subscription

GetDevice(device_nickname, force_create=False)

Get a the subscription to a device previously added to the DeviceConnector

Parameters:

device_nickname (str) – The nickname of the device to get
force_create (bool) – (optional) If True, create the subscription if it does not exist

Returns:

The subscription to the device

Return type:

RobotRaconteur.ServiceSubscription

RemoveDevice(device_nickname, close=True)

Remove a device from the DeviceConnector

Parameters:

device_nickname (str) – The nickname of the device to remove
close (bool) – (optional) If True, close the device connection

TryGetDevice(device_nickname)

Try to get a the subscription to a device previously added to the DeviceConnector

Parameters:: device_nickname (str) – The nickname of the device to get
Returns:: A tuple containing a boolean indicating if the device was found and the subscription
Return type:: (bool, RobotRaconteur.ServiceSubscription)

DeviceConnectorDetails

class RobotRaconteurCompanion.Util.DeviceConnector.DeviceConnectorDetails(device_nickname, device=None, serial_number=None, tags=None, tag_match_operation='and', service_nodes=None, transport_schemes=None, urls=None, url_auth=None, root_object_type=None, subscription_filter=None, max_connections=10)

Device connection information for use with DeviceConnector class.

The DeviceConnectorDetails contains information that is used by the DeviceConnector class to connect to devices. The DeviceConnector can connect to devicues using three different methods:

Discovery devices using device identifier (name, uuid) in combination with optional serial number and/or device tags

Connection using a list of URLs. Using URLs is the most direct way to connect to a device.

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. See the DeviceConnector documentation for more information on how to use the DeviceConnectorDetails class.

Variables:

device_nickname (str) – The nickname of the device
device (str | dict | com.robotraconteur.identifier.Identifier) – The device identifier (name, uuid) of the device. This can be either a string, a dictionary with “name” and “uuid” keys, or a com.robotraconteur.identifier.Identifier structure
serial_number (str) – The serial number of the device
tags (list[str | dict | com.robotraconteur.identifier.Identifier]) – The tags of the device. This a list of strings, a list of a dictionaries with “name” and “uuid” keys, or a list com.robotraconteur.identifier.Identifier structure in any combination
tag_match_operation (str) – The operation to use when matching tags. Can be “and”, “or”, “nand”, or “nor”
service_nodes (list[RobotRaconteur.SubscriptionFilterNode]) – A list of RobotRaconteur.SubscriptionFilterNode to use for service discovery. This is intended for advanced users needing to provide authentication or other advanced options.
transport_schemes (list[str]) – A list of transport schemes to use for service discovery. This is intended for advanced users needing to provide authentication or other advanced options.
urls (str | list[str]) – A list of URLs to use for direct connection to the device
url_auth (RobotRaconteur.SubscriptionFilterNode) – The username and password to use for authentication when connecting using URLs
root_object_type (str | list[str]) – The root object type to use for service discovery. This is a list of strings
subscription_filter (RobotRaconteur.ServiceSubscriptionFilter) – The subscription filter to use for service discovery.
max_connections (int) – The maximum number of connections to the device. Defaults to 10. Should be set to 1 for connecting to a single device

Parameters:

device_nickname (str) – The nickname of the device
device (str | dict | com.robotraconteur.identifier.Identifier) – The device identifier (name, uuid) of the device. This can be either a string, a dictionary with “name” and “uuid” keys, or a com.robotraconteur.identifier.Identifier structure
serial_number (str) – The serial number of the device
tags (list[str | dict | com.robotraconteur.identifier.Identifier]) – The tags of the device. This a list of strings, a list of a dictionaries with “name” and “uuid” keys, or a list com.robotraconteur.identifier.Identifier structure in any combination
tag_match_operation (str) – The operation to use when matching tags. Can be “and”, “or”, “nand”, or “nor”
service_nodes (list[RobotRaconteur.SubscriptionFilterNode]) – A list of RobotRaconteur.SubscriptionFilterNode to use for service discovery. This is intended for advanced users needing to provide authentication or other advanced options.
transport_schemes (list[str]) – A list of transport schemes to use for service discovery. This is intended for advanced users needing to provide authentication or other advanced options.
urls (str | list[str]) – A list of URLs to use for direct connection to the device
url_auth (RobotRaconteur.SubscriptionFilterNode) – The username and password to use for authentication when connecting using URLs
root_object_type (str | list[str]) – The root object type to use for service discovery. This is a list of strings
subscription_filter (RobotRaconteur.ServiceSubscriptionFilter) – The subscription filter to use for service discovery.
max_connections (int) – The maximum number of connections to the device. Defaults to 10. Should be set to 1 for connecting to a single device

YAML Functions

RobotRaconteurCompanion.Util.DeviceConnector.load_device_details_from_yaml_path(yaml_filename)

Load device details from a YAML file specified by the file path

Parameters:: yaml_filename (str | pathlib.Path) – The path to the YAML file

RobotRaconteurCompanion.Util.DeviceConnector.load_device_details_from_yaml(yaml_file)

Load device details from a YAML file object

Parameters:: yaml_file (file) – The file object containing the YAML file

RobotRaconteurCompanion.Util.DeviceConnector.load_device_details_from_yaml_dict(yaml_dict)

Load device details from a YAML dictionary

Parameters:: yaml_dict (dict) – The dictionary containing the YAML file contents