Node Setup

RobotRaconteurNodeSetup Class

class RobotRaconteur.RobotRaconteurNodeSetup(node_name=None, tcp_port=None, flags=None, allowed_overrides=None, node=None, argv=None, config=None)

Setup a node using specified options and manage node lifecycle

RobotRaconteurNodeSetup and its subclasses ClientNodeSetup, ServerNodeSetup, and SecureServerNodeSetup are designed to help configure nodes and manage node lifecycles. The node setup classes use the “with” statement to configure the node on construction, and call RobotRaconteurNode.Shutdown() when the instance is destroyed.

The node setup classes execute the following operations to configure the node:

1. Set log level and tap options from flags, command line options, or environmental variables

2. Register specified service factory types

3. Initialize transports using flags specified in flags or from command line options

4. Configure timeouts

See Command Line Options for more information on available command line options.

Logging level is configured using the environmental variable ROBOTRACONTEUR_LOG_LEVEL or the command line option --robotraconteur-log-level. See Logging for more information.

See Taps for more information on using taps.

The node setup classes optionally initialize LocalTransport, TcpTransport, HardwareTransport, and/or IntraTransport. Transports for more information.

The LocalTransport.StartServerAsNodeName() or LocalTransport.StartClientAsNodeName() are used to load the NodeID. See LocalTransport for more information on this procedure.

Parameters:

• node_name (str) – (optional) The NodeName

• tcp_port (int) – (optional) The port to listen for incoming TCP clients

• flags (int) – (optional) The configuration flags

• allowed_overrides (int) – (optional) The allowed override flags

• node (RobotRaconteur.RobotRaconteurNode) – (optional) The node to configure and manage lifecycle

• argv – (optional) The command line argument vector. Default is sys.argv

ReleaseNode()

Release the node from lifecycle management

If called, RobotRaconteurNode.Shutdown() will not be called when the node setup instance is destroyed

close()

Shutdown the node and release the node from lifecycle management

property command_line_config

The command line config parser object used to configure node

property hardware_transport

The HardwareTransport, will be None if HardwareTransport is not specified in flags, Note: Hardware transport is not enabled by default

property intra_transport

The IntraTransport, will be None if IntraTransport is not specified in flags

property local_transport

The LocalTransport, will be None if LocalTransport is not specified in flags

property tcp_transport

The TcpTransport, will be None if TcpTransport is not specified in flags

ClientNodeSetup Class

class RobotRaconteur.ClientNodeSetup(node_name=None, node=None, argv=None)

Initializes a RobotRaconteurNode instance to default configuration for a client only node

ClientNodeSetup is a subclass of RobotRaconteurNodeSetup providing default configuration for a RobotRaconteurNode instance that is used only to create outgoing client connections.

See CommandLineOptions for more information on available command line options.

Note: String table and HardwareTransport are disabled by default. They can be enabled using command line options.

By default, the configuration will do the following:

1. Configure logging level from environmental variable or command line options. Defaults to INFO if not specified

2. Configure tap if specified in command line options

3. Register service types passed to service_types

4. Start LocalTransport (default enabled)

   1. If RobotRaconteurNodeSetupFlags_LOCAL_TRANSPORT_START_CLIENT flag is specified, call LocalTransport.StartServerAsNodeName() with the specified node_name

   2. Start LocalTransport discovery listening if specified in flags or on command line (default enabled)

   3. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified on command line

5. Start TcpTransport (default enabled)

   1. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

   2. Start TcpTranport discovery listening (default enabled)

   3. Load TLS certificate and set if TLS is specified on command line (default disabled)

   4. Process WebSocket origin command line options

6. Start HardwareTransport (default disabled)

   1. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

7. Start IntraTransport (default enabled)

   1. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

8. Disable timeouts if specified in flags or command line (default timeouts normal)

Most users will not need to be concerned with these details, and can simply use the default configuration.

Parameters:

• node_name (str) – (optional) The NodeName

• node (RobotRaconteur.RobotRaconteurNode) – (optional) The node to configure and manage lifecycle

• argv – (optional) The command line argument vector. Default is sys.argv

ServerNodeSetup Class

class RobotRaconteur.ServerNodeSetup(node_name, tcp_port, node=None, argv=None)

Initializes a RobotRaconteurNode instance to default configuration for a server and client node

ServerNodeSetup is a subclass of RobotRaconteurNodeSetup providing default configuration for a RobotRaconteurNode instance that is used as a server to accept incoming client connections and to initiate client connections.

ServerNodeSetup requires a NodeName, and a TCP port if LocalTransport and TcpTransport are enabled (default behavior).

See Command Line Options for more information on available command line options.

Note: String table and HardwareTransport are disabled by default. They can be enabled using command line options.

By default, the configuration will do the following:

1. Configure logging level from environmental variable or command line options. Defaults to INFO if not specified 2. Configure tap if specified in command line options 3. Register service types passed to service_types 4. Start LocalTransport (default enabled)

1. Configure the node to use the specified NodeName, and load the NodeID from the filesystem based based on the NodeName. NodeID will be automatically generated if not previously used.

   1. If “public” option is set, the transport will listen for all local users (default disabled)

2. Start the LocalTransport server to listen for incoming connections with the specified NodeName and NodeID

3. Start LocalTransport discovery announce and listening (default enabled)

4. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified on command line

5. Start TcpTransport (default enabled)

   1. Start the TcpTransport server to listen for incoming connections on specified port or using the port sharer (default enabled using specified port)

   2. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

   3. Start TcpTranport discovery announce and listening (default enabled)

   4. Load TLS certificate and set if TLS is specified on command line (default disabled)

   5. Process WebSocket origin command line options

6. Start HardwareTransport (default disabled)

   1. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

7. Start IntraTransport (default enabled)

   1. Enable IntraTransport server to listen for incoming clients (default enabled)

   2. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

8. Disable timeouts if specified in flags or command line (default timeouts normal)

Most users will not need to be concerned with these details, and can simply use the default configuration.

Parameters:

• node_name (str) – The NodeName

• tcp_port (int) – The port to listen for incoming TCP clients

• node (RobotRaconteur.RobotRaconteurNode) – (optional) The node to configure and manage lifecycle

• argv – (optional) The command line argument vector. Default is sys.argv

ReleaseNode()

Release the node from lifecycle management

If called, RobotRaconteurNode.Shutdown() will not be called when the node setup instance is destroyed

close()

Shutdown the node and release the node from lifecycle management

property command_line_config

The command line config parser object used to configure node

property hardware_transport

The HardwareTransport, will be None if HardwareTransport is not specified in flags, Note: Hardware transport is not enabled by default

property intra_transport

The IntraTransport, will be None if IntraTransport is not specified in flags

property local_transport

The LocalTransport, will be None if LocalTransport is not specified in flags

property tcp_transport

The TcpTransport, will be None if TcpTransport is not specified in flags

SecureServerNodeSetup Class

class RobotRaconteur.SecureServerNodeSetup(node_name, tcp_port, node=None, argv=None)

Initializes a RobotRaconteurNode instance to default configuration for a secure server and client node

SecureServerNodeSetup is a subclass of RobotRaconteurNodeSetup providing default configuration for a secure RobotRaconteurNode instance that is used as a server to accept incoming client connections and to initiate client connections. SecureServerNodeSetup is identical to ServerNodeSetup, except that it requires TLS for all network communication.

ServerNodeSetup requires a NodeName, and a TCP port if LocalTransport and TcpTransport are enabled (default behavior).

See Command Line Options for more information on available command line options.

Note: String table and HardwareTransport are disabled by default. They can be enabled using command line options.

By default, the configuration will do the following:

1. Configure logging level from environmental variable or command line options. Defaults to INFO if not specified 2. Configure tap if specified in command line options 3. Register service types passed to service_types 4. Start LocalTransport (default enabled)

1. Configure the node to use the specified NodeName, and load the NodeID from the filesystem based based on the NodeName. NodeID will be automatically generated if not previously used.

   1. If “public” option is set, the transport will listen for all local users (default disabled)

2. Start the LocalTransport server to listen for incoming connections with the specified NodeName and NodeID

3. Start LocalTransport discovery announce and listening (default enabled)

4. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified on command line

5. Start TcpTransport (default enabled)

   1. Start the TcpTransport server to listen for incoming connections on specified port or using the port sharer (default enabled using specified port)

   2. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

   3. Start TcpTranport discovery announce and listening (default enabled)

   4. Load TLS certificate and set if TLS is specified on command line (default enabled, required)

   5. Process WebSocket origin command line options

6. Start HardwareTransport (default disabled)

   1. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

7. Start IntraTransport (default enabled)

   1. Enable IntraTransport server to listen for incoming clients (default enabled)

   2. Disable Message Format Version 4 (default enabled) and/or String Table (default disabled) if specified in flags or command line

8. Disable timeouts if specified in flags or command line (default timeouts normal)

Most users will not need to be concerned with these details, and can simply use the default configuration.

Parameters:

• node_name (str) – The NodeName

• tcp_port (int) – The port to listen for incoming TCP clients

• node (RobotRaconteur.RobotRaconteurNode) – (optional) The node to configure and manage lifecycle

• argv – (optional) The command line argument vector. Default is sys.argv

ReleaseNode()

Release the node from lifecycle management

If called, RobotRaconteurNode.Shutdown() will not be called when the node setup instance is destroyed

close()

Shutdown the node and release the node from lifecycle management

property command_line_config

The command line config parser object used to configure node

property hardware_transport

The HardwareTransport, will be None if HardwareTransport is not specified in flags, Note: Hardware transport is not enabled by default

property intra_transport

The IntraTransport, will be None if IntraTransport is not specified in flags

property local_transport

The LocalTransport, will be None if LocalTransport is not specified in flags

property tcp_transport

The TcpTransport, will be None if TcpTransport is not specified in flags

CommandLineConfigParser Class

class RobotRaconteur.CommandLineConfigParser(*args)

Command line parser for node setup classes

The CommandLineConfigParser is used to parse command line options specified when a program is launched. These options allow for the node configuration to be changed without recompiling the software. See ref command_line_options for a table of the standard command line options.

ClientNodeSetup, ServerNodeSetup, and SecureServerNodeSetup use this class to parse the sys.argv parameters. The RobotRaconteurNodeSetup constructors will accept either sys.argv, or will accept an initialize CommandLineConfigParser.

The CommandLineConfig() constructor takes the “allowed override” flags, and the option prefix. The “allowed override” specifies which options can be overridden using the command line. The prefix option allows the command line flag prefix to be changed. By default it expects all options to begin with –robotraconteur- followed by the name of the option. If there are multiple nodes, it is necessary to change the prefix to be unique for each node. For instance, “robotraconteur1-” for the first node and “robotraconteur2-” for the second node.

Users may add additional options to the parser. Use AddStringOption(), AddBoolOption(), or AddIntOption() to add additional options.

AddBoolOption(name, descr)

Add a new bool option

Parameters:

• name (str) – The name of the option

• descr (str) – Description of the option

AddIntOption(name, descr)

Add a new int32_t option

Parameters:

• name (str) – The name of the option

• descr (str) – Description of the option

AddStringOption(name, descr)

Add a new string option

Parameters:

• name (str) – The name of the option

• descr (str) – Description of the option

GetOptionOrDefaultAsBool(*args)

Get the option value as a bool

Returns default_value if option not specified on command line

Parameters:

• option (bool) – The name of the option

• default_value (bool) – The default option value

Returns:

The option value, or default_value if not specified on command line

Return type:

bool

GetOptionOrDefaultAsInt(*args)

Get the option value as an int

Returns default_value if option not specified on command line

Parameters:

• option (str) – The name of the option

• default_value (int) – The default option value

Returns:

The option value, or default_value if not specified on command line

Return type:

int

GetOptionOrDefaultAsString(*args)

Get the option value as a string

Returns default_value if option not specified on command line

Parameters:

• option (str) – The name of the option

• default_value (str) – The default option value

Returns:

The option value, or default_value if not specified on command line

Return type:

str

ParseCommandLine(args)

Parse a specified string vector containing the options

Results are stored in the instance

Parameters:

args (List[str]) – The options as a string list

SetDefaults(node_name, tcp_port, default_flags)

Set the default NodeName, TCP port, and flags

The command line options will be allowed to override the options specified in allowed_overrides passed to CommandLineConfigParser().

Parameters:

node_name – The default NodeName

:type node_name str :param tcp_port: The default TCP port :type tcp_port: int :param default_flags: The default flags :type default_flags: int

Node Setup Flags

Setup option flags

Setup option flags passed to node setup classes to select options to enable and disable. Flags are used to configure the following types of options:

1. Enable and disable transport types

2. Modify transport options including discovery, security requirements, and connection listening

3. Configure TLS behavior

4. Enable local tap for logging

Node setup classes also allow options and flags to be “overridden” using command line options. Use the *_ALLOW_OVERRIDE options to configure when these overrides are allowed.

The ClientNodeSetup, ServerNodeSetup, and SecureServerNodeSetup are convenience classes for the most commonly used options.

RobotRaconteur.RobotRaconteurNodeSetupFlags_NONE = 0x0

No options enabled

RobotRaconteur.RobotRaconteurNodeSetupFlags_ENABLE_NODE_DISCOVERY_LISTENING = 0x1

Enable node discovery listening on all transports

RobotRaconteur.RobotRaconteurNodeSetupFlags_ENABLE_NODE_ANNOUNCE = 0x2

Enable node announce on all transports

RobotRaconteur.RobotRaconteurNodeSetupFlags_ENABLE_LOCAL_TRANSPORT = 0x4

Enable LocalTransport

RobotRaconteur.RobotRaconteurNodeSetupFlags_ENABLE_TCP_TRANSPORT = 0x8

Enable TcpTransport

RobotRaconteur.RobotRaconteurNodeSetupFlags_ENABLE_HARDWARE_TRANSPORT = 0x10

Enable HardwareTransport

RobotRaconteur.RobotRaconteurNodeSetupFlags_LOCAL_TRANSPORT_START_SERVER = 0x20

Start the LocalTransport server to listen for incoming clients

RobotRaconteur.RobotRaconteurNodeSetupFlags_LOCAL_TRANSPORT_START_CLIENT = 0x40

Start the LocalTransport client with specified node name

RobotRaconteur.RobotRaconteurNodeSetupFlags_TCP_TRANSPORT_START_SERVER = 0x80

Start the TcpTransport server to listen for incoming clients on the specified port

RobotRaconteur.RobotRaconteurNodeSetupFlags_TCP_TRANSPORT_START_SERVER_PORT_SHARER = 0x100

Start the TcpTransport server to incoming for incoming clients using the port sharer

RobotRaconteur.RobotRaconteurNodeSetupFlags_DISABLE_MESSAGE4 = 0x200

Disable Message Format Version 4 on all transports

RobotRaconteur.RobotRaconteurNodeSetupFlags_DISABLE_STRINGTABLE = 0x400

Disable Message Format Version 4 string table on all transports

RobotRaconteur.RobotRaconteurNodeSetupFlags_DISABLE_TIMEOUTS = 0x800

Disable all timeouts (useful for debugging)

RobotRaconteur.RobotRaconteurNodeSetupFlags_LOAD_TLS_CERT = 0x1000

Load the TLS certificate for TcpTransport

RobotRaconteur.RobotRaconteurNodeSetupFlags_REQUIRE_TLS = 0x2000

Require TLS for all clients on TcpTransport

RobotRaconteur.RobotRaconteurNodeSetupFlags_LOCAL_TRANSPORT_SERVER_PUBLIC = 0x4000

Make LocalTransport server listen for incoming clients from all users

RobotRaconteur.RobotRaconteurNodeSetupFlags_NODENAME_OVERRIDE = 0x10000

Allow NodeName to be configured using command line options

RobotRaconteur.RobotRaconteurNodeSetupFlags_NODEID_OVERRIDE = 0x20000

Allow NodeID to be configured using command line options

RobotRaconteur.RobotRaconteurNodeSetupFlags_TCP_PORT_OVERRIDE = 0x40000

Allow TCP port to be configured using command line options

RobotRaconteur.RobotRaconteurNodeSetupFlags_TCP_WEBSOCKET_ORIGIN_OVERRIDE = 0x80000

Allow TCP WebSocket origin control to be configured using command line options

RobotRaconteur.RobotRaconteurNodeSetupFlags_ENABLE_INTRA_TRANSPORT = 0x100000

Enable IntraTransport

RobotRaconteur.RobotRaconteurNodeSetupFlags_INTRA_TRANSPORT_START_SERVER = 0x200000

Start the IntraTransport server to listen for incoming clients

RobotRaconteur.RobotRaconteurNodeSetupFlags_LOCAL_TAP_ENABLE = 0x1000000

Enable the LocalTap debug logging system

RobotRaconteur.RobotRaconteurNodeSetupFlags_LOCAL_TAP_NAME = 0x2000000

Allow the user to set the LocalTap name

RobotRaconteur.RobotRaconteurNodeSetupFlags_ENABLE_ALL_TRANSPORTS = 0x10001c

Convenience flag to enable all transports

RobotRaconteur.RobotRaconteurNodeSetupFlags_CLIENT_DEFAULT = 0x10004d

Default configuration for client nodes (See ClientNodeSetup)

RobotRaconteur.RobotRaconteurNodeSetupFlags_CLIENT_DEFAULT_ALLOWED_OVERRIDE = 0x3133e5d

Default allowed overrides for client nodes (See ClientNodeSetup)

RobotRaconteur.RobotRaconteurNodeSetupFlags_SERVER_DEFAULT = 0x3004af

Default configuration for server nodes

RobotRaconteur.RobotRaconteurNodeSetupFlags_SERVER_DEFAULT_ALLOWED_OVERRIDE = 0x33f7fff

Default allowed overrides for server nodes

RobotRaconteur.RobotRaconteurNodeSetupFlags_SECURE_SERVER_DEFAULT = 0x3034af

Default configuration for server nodes requiring TLS network transports

RobotRaconteur.RobotRaconteurNodeSetupFlags_SECURE_SERVER_DEFAULT_ALLOWED_OVERRIDE = 0x33f4fff

Default allowed overrides for server nodes requiring TLS network transports