Transports

TcpTransport Class

class RobotRaconteur.TcpTransport(Node=none)

Transport for Transport Control Protocol Internet Protocol (TCP/IP) networks

It is recommended that ClientNodeSetup, ServerNodeSetup, or SecureServerNodeSetup be used to construct this class.

See ref robotraconteur_url for more information on URLs.

The TcpTransport implements transport connections over TCP/IP networks. TCP/IP is the most common protocol used for Internet and Local Area Network (LAN) communication, including Ethernet and WiFi connections. The Transport Control Protocol (TCP) is a reliable stream protocol that establishes connections between devices using IP address and port pairs. Each adapter has an assigned address, and applications create connections on different ports. TcpTransport listens to the port specified in StartServer(), and the client uses a URL containing the IP address and port of the listening transport. The TcpTransport uses the established connection to pass messages between nodes.

The IP protocol is available in two major versions, IPv4 and IPv6. The most common is IPv4, and its 32 bit address is typically written as four numbers, ie 172.17.12.174. IPv4 has a number of critical limitations, the greatest being its 2^32 address limit (approximately 4 billion). This is a problem when there are tens of billions of internet connected devices already present. IPv6 introduces a 128 bit address space, which allows for approximately 3.4x10^38 possible addresses. The major advantage for Robot Raconteur is the introduction of “link-local” addresses. These addresses begin with “FE80::” and finish with an “EUI-64” address, which is tied to the MAC address of the adaptor. IPv4 addresses need to be assigned to devices locally, and have a tendency to change. IPv6 addresses are permanently assigned to the adapter itself, meaning that network configuration for LAN communication is essentially automatic. Robot Raconteur will prefer IPv6 connections when possible for this reason.

The TcpTransport is capable of using “raw” streams that implement the Robot Raconteur message protocols, or to use HTTP WebSockets. HTTP WebSockets allow Robot Raconteur to communicate seamlessly with browsers and HTTP servers without requiring additional plugins. WebSockets provide additional security using “origins”. See AddWebSocketAllowedOrigin() for more information.

The TcpTransport supports TLS encryption using certificates. See ref tls_security for more information on TLS. The TcpTransport supports four modes of TLS encryption:

Scheme

Description

Direction

rrs+tcp

“Raw” protocol with TLS

Both

rr+wss

Websocket over HTTPS

Client Only

rrs+ws

Websocket with RobotRaconteur TLS over HTTP

Both

rrs+wss

Websocket with RobotRaconteur TLS over HTTPS

Client Only

The different combinations of TLS and HTTPS for websockets are used for different scenarios. Robot Raconteur Core can initiate HTTPS connections, but cannot accept them. Accepting HTTPS connections requires a certificate issued by an authority like GoDaddy or Digicert, and is typically used with an HTTP server running RobotRaconteurWeb.

TLS certificates for Robot Raconteur nodes are issued by Wason Technology, LLC using a root certificate that is “burned in” to Robot Raconteur Core. All devices running Robot Raconteur will support this certificate chain.

Discovery for the TcpTransport is accomplished using User Defined Protocol (UDP) multicast and/or broadcast packets. Broadcast packets are sent to all connected devices, while multicast is sent to devices that have registered to receive them. Unlike TCP, the packets sent to broadcast or multicast are sent to the entire network. This allows for devices to find each other on the network.

For IPv4, the broadcast address 255.255.255.255 on port 48653 is used for discovery. By default, IPv4 is disabled in favor of IPv6. IPv6 uses the multicast following multicast addresses:

Address

Scope

Port

Default?

FF01::BA86

Node-Local

48653

Disabled

FF02::BA86

Link-Local

48653

Enabled

FF05::BA86

Site-Local

48653

Disabled

By default, discovery will only occur on the link-local IPv6 scope. This will find nodes on the local subnet, but will not attempt to pass through any routers.

The use of RobotRaconteurNodeSetup and subclasses is recommended to construct transports.

The transport must be registered with the node using RobotRaconteurNode.RegisterTransport() after construction if node setup is not used.

Parameters:

node (RobotRaconteur.RobotRaconteurNode) – (optional) The node that will use the transport. Default is the singleton node

property AcceptWebSockets

Set if the transport will accept incoming HTTP websocket connections

Default: true

Return type:

bool

Close()

Close the transport. Done automatically by node shutdown.

property DefaultConnectTimeout

Set the default connect timeout in seconds

If the connection is not completed within the timeout, the connection attempt will be aborted.

Default: 5 seconds

Return type:

float

property DefaultHeartbeatPeriod

Set the default heartbeat period in seconds

The heartbeat is used to keep the connection alive if no communication is occuring between nodes.

Default: 5 seconds

Return type:

float

property DefaultReceiveTimeout

Set the default receive timeout in seconds

If no messages are received within the timeout, the connection is assumed to be lost.

Default: 15 seconds

Return type:

float

property DisableAsyncMessageIO

Set if async message io is disabled

Async message io has better memory handling, at the expense of slightly higher latency.

Default: Async io enabled

Return type:

bool

property DisableMessage4

Set disable Message Format Version 4

Message Format Version 2 will be used

Default: Message V4 is enabled

Return type:

bool

DisableNodeAnnounce()

Disable node discovery announce

DisableNodeDiscoveryListening()

Disable node discovery listening

property DisableStringTable

Set disable string table

Default: false

RobotRaconteurNodeSetup and its subclasses will disable the string table by default

Return type:

bool

EnableNodeAnnounce(*args)

Enable node discovery announce

By default enables announce on IPv6 link-local scope

See IPNodeDiscoveryFlags constants

Parameters:

flags (int) – The flags specifying the scope

EnableNodeDiscoveryListening(*args)

Enable node discovery listening

By default enables listining on IPv6 link-local scope

See IPNodeDiscoveryFlags constants

Parameters:

flags (int) – The flags specifying the scope

GetSecurePeerIdentity(obj)

Get the identity of the peer if secured using TLS

Get the identity of a peer verified using TLS certificates. Returns a NodeID in string format. Will throw AuthenticationException if the peer has not been verified.

Parameters:

obj – The client or endpoint to check

Returns:

The verified peer NodeID as a string

Return type:

str

IsSecurePeerIdentityVerified(obj)

Check if specified peer is using TLS and has been verified using a certificate

Checks if the peer server node has a valid certificate, or if the peer client has been verified using mutual authentication.

Throws ConnectionException if the endpoint is invalid or the connection is not using TcpTransport

Parameters:

obj – The client or endpoint to check

Returns:

True The connection is using TLS, otherwise False

Return type:

bool

property IsTlsNodeCertificateLoaded

Check if TLS certificate is loaded

Return type:

bool

IsTransportConnectionSecure(obj)

Check if specified client or endpoint is using TLS for its transport

Throws ConnectionException if the client or endpoint is invalid or the connection is not using TcpTransport

Parameters:

obj – The client or endpoint to check

Returns:

True The connection is using TLS, otherwise False

Return type:

bool

property MaxConnectionCount

Set the maximum number of concurrent connections

Default: 0 for unlimited

Return type:

int

property MaxMessageSize

Set the maximum serialized message size

Default: 10 MB

Return type:

int

property NodeAnnouncePeriod

Set the period between node announce in seconds

Default 55 seconds

Return type:

float

property RequireTls

Set if all connections require TLS

If true, all connections require TLS

Return type:

bool

LocalTransport Class

class RobotRaconteur.LocalTransport(Node=none)

Transport for communication between processes using UNIX domain sockets

It is recommended that ClientNodeSetup, ServerNodeSetup, or SecureServerNodeSetup be used to construct this class.

See ref robotraconteur_url for more information on URLs.

The LocalTransport implements transport connections between processes running on the same host operating system using UNIX domain sockets. UNIX domain sockets are similar to standard networking sockets, but are used when both peers are on the same machine instead of connected through a network. This provides faster operation and greater security, since the kernel simply passes data between the processes. UNIX domain sockets work using Information Node (inode) files, which are special files on the standard filesystem. Servers “listen” on a specified inode, and clients use the inode as the address to connect. The LocalTransport uses UNIX sockets in SOCK_STREAM mode. This provides a reliable stream transport connection similar to TCP, but with significantly improved performance due the lower overhead.

UNIX domain sockets were added to Windows 10 with the 1803 update. Robot Raconteur switch to UNIX domain sockets for the LocalTransport on Windows in version 0.9.2. Previous versions used Named Pipes, but these were inferior to UNIX sockets. The LocalTransport will not function on versions of Windows prior to Windows 10 1803 update due to the lack of support for UNIX sockets. A warning will be issued to the log if the transport is not available, and all connection attempts will fail. All other transports will continue to operate normally.

The LocalTransport stores inode and node information files in the filesystem at various operator system dependent locations. See the Robot Raconteur Standards documents for details on where these files are stored.

Discovery is implemented using file watchers. The file watchens must be activated using the node setup flags, or by calling EnableNodeDiscoveryListening(). After being initialized the file watchers operate automatically.

The LocalTransport can be used to dynamically assign NodeIDs to nodes based on a NodeName. StartServerAsNodeName() and StartClientAsNodeName() take a NodeName that will identify the node to clients, and manage a system-local NodeID corresponding to that NodeName. The generated NodeIDs are stored on the local filesystem. If LocalTransport finds a corresponding NodeID on the filesystem, it will load and use that NodeID. If it does not, a new random NodeID is automatically generated.

The server can be started in “public” or “private” mode. Private servers store their inode and information in a location only the account owner can access, while “public” servers are placed in a location that all users with the appropriate permissions can access. By default, public LocalTransport servers are assigned to the “robotraconteur” group. Clients that belong to the “robotraconteur” group will be able to connect to these public servers.

The use of RobotRaconteurNodeSetup and subclasses is recommended to construct transports.

The transport must be registered with the node using RobotRaconteurNode.RegisterTransport() after construction if node setup is not used.

Parameters:

node (RobotRaconteur.RobotRaconteurNode) – (optional) The node that will use the transport. Default is the singleton node

Close()

Close the transport. Done automatically by node shutdown.

property DisableAsyncMessageIO

Set if async message io is disabled

Async message io has better memory handling, at the expense of slightly higher latency.

Default: Async io enabled

Return type:

bool

property DisableMessage4

Set disable Message Format Version 4

Message Format Version 2 will be used

Default: Message V4 is enabled

Return type:

bool

property DisableStringTable

Set disable string table

Default: false

RobotRaconteurNodeSetup and its subclasses will disable the string table by default

Return type:

bool

static IsLocalTransportSupported()

Check if the LocalTransport is supported on the current operating system.

Windows versions before Windows 10 1803 do not support the LocalTransport due to lack of UNIX sockets. All other transports will continue to operate normally.

All versions of Linux and Mac OSX support the LocalTransport

LocalTransport on Android and iOS is not officially supported

Returns:

True LocalTransport is supported, otherwise False

Return type:

bool

property MaxMessageSize

Set the maximum serialized message size

Default: 10 MB

Return type:

int

StartClientAsNodeName(name)

Initialize the LocalTransport by assigning a NodeID based on NodeName

Assigns the specified name to be the NodeName of the node, and manages a corresponding NodeID. See LocalTransport for more information.

Throws NodeNameAlreadyInUse if another node is using name

Parameters:

name (str) – The node name

StartServerAsNodeID(nodeid, public_=False)

StartServerAsNodeId(name, public_ = False)

The LocalTransport will listen on a UNIX domain socket for incoming clients, using information files and inodes on the local filesystem. This function leaves the NodeName blank, so clients must use NodeID to identify the node.

Throws NodeIDAlreadyInUse if another node is using nodeid

Parameters:

  • nodeid (RobotRaconteur.NodeID) – The NodeID

  • public (bool) – If True, other users can access the server. If False, only the account owner can access the server.

StartServerAsNodeName(name, public_=False)

Start the server using the specified NodeName and assigns a NodeID

The LocalTransport will listen on a UNIX domain socket for incoming clients, using information files and inodes on the local filesystem. Clients can locate the node using the NodeID and/or NodeName. The NodeName is assigned to the node, and the transport manages a corresponding NodeID. See LocalTransport for more information.

Throws NodeNameAlreadyInUse if another node is using name

Throws NodeIDAlreadyInUse if another node is using the managed NodeID

Parameters:

  • name (str) – The NodeName

  • public (bool) – If True, other users can access the server. If False, only the account owner can access the server.

IntraTransport Class

class RobotRaconteur.IntraTransport(Node=none)

Transport for intra-process communication

It is recommended that ClientNodeSetup, ServerNodeSetup, or SecureServerNodeSetup be used to construct this class.

See ref robotraconteur_url for more information on URLs.

The IntraTransport implements transport connections between nodes running within the same process. This is often true for simulation environments, where there may be multiple simulated devices running within the simulation. The IntraTransport uses a singleton to keep track of the different nodes running in the same process, and to form connections. The singleton also implements discovery updates.

The use of RobotRaconteurNodeSetup and subclasses is recommended to construct transports.

The transport must be registered with the node using RobotRaconteurNode.RegisterTransport() after construction if node setup is not used.

Parameters:

node (RobotRaconteur.RobotRaconteurNode) – (optional) The node that will use the transport. Default is the singleton node

Close()

Close the transport. Done automatically by node shutdown.

StartClient()

Start the transport as a client

StartServer()

Start the server to listen for incoming client connections

HardwareTransport Class

class RobotRaconteur.HardwareTransport(Node=none)

Transport for USB, Bluetooth, and PCIe hardware devices

WARNING: THE HARDWARE TRANSPORT IS EXPERIMENTAL!

The HardwareTransport is disabled by default by the node setup classes. Use --robotraconteur-hardware-enable=true option to enable.

It is recommended that ClientNodeSetup, ServerNodeSetup, or SecureServerNodeSetup be used to construct this class.

See ref robotraconteur_url for more information on URLs.

Contact Wason Technology, LLC for more information on the hardware transport.

The use of RobotRaconteurNodeSetup and subclasses is recommended to construct transports.

The transport must be registered with the node using RobotRaconteurNode.RegisterTransport() after construction if node setup is not used.

Parameters:

node (RobotRaconteur.RobotRaconteurNode) – (optional) The node that will use the transport. Default is the singleton node

Close()

Close the transport. Done automatically by node shutdown.

property DisableAsyncMessageIO

Set if async message io is disabled

Async message io has better memory handling, at the expense of slightly higher latency.

Default: Async io enabled

Return type:

bool

property DisableMessage4

Set disable Message Format Version 4

Message Format Version 2 will be used

Default: Message V4 is enabled

Return type:

bool

property DisableStringTable

Set disable string table

Default: false

RobotRaconteurNodeSetup and its subclasses will disable the string table by default

Return type:

bool

property MaxMessageSize

Set the maximum serialized message size

Default: 10 MB

Return type:

int

BrowserWebSocketTransport Class

class RobotRaconteur.BrowserWebSocketTransport(Node=none)

Transport for creating client connections inside a web browser using WebSockets

Robot Raconteur can be compiled to run inside a web browser using Emscripten and WebAssembly (WASM). While inside a web browser, the only connection method currently available to connection to a Robot Raconteur service is using WebSockets. The BrowserWebSocketTransport class implements the WebSocket transport for the web browser. Currently only the client side is implemented.

See \ref robotraconteur_url for more information on URLs.

Currently the url connections schemes rr+ws, rr+wss and rr+tcp are supported. rr+tcp are treated as rr+ws connections.

The BrowserWebSocketTransport is automatically registered when the RobotRaconteur.Client module is used. If the RobotRaconteur.Client module is not used, the BrowserWebSocketTransport must be manually registered with the node using RobotRaconteurNode.RegisterTransport(). NodeSetup is not currently available in the web browser.

Note that for services to accept a WebSocket connection, the service must have the WebSocket "origin" configured correctly. The origin is the base URL of the web page that is hosting the web page that is connecting to the service. For example, if the web page is hosted at https://example.com/application/index.html, the origin would be https://example.com. For localhost, the origin is http://localhost:8080, where 8080 is the port the web page is hosted on. The origin can be configured using the function TcpTransport.AddWebSocketAllowedOrigin(), or using the --robotraconteur-tcp-ws-add-origin command line option if a node setup class is used. If a local file is used to host the web page, the origin is null and no origin checking is performed.

See TcpTransport.AddWebSocketAllowedOrigin() for more information on configuring the WebSocket origin and the default origins that are automatically configured.

Parameters:

node (RobotRaconteur.RobotRaconteurNode) – (optional) The node that will use the transport. Default is the singleton node

property DefaultReceiveTimeout

Set the default receive timeout in seconds

If no messages are received within the timeout, the connection is assumed to be lost.

Default: 15 seconds

rtype:

float

property DefaultConnectTimeout

Set the default connect timeout in seconds

If the connection is not completed within the timeout, the connection attempt will be aborted.

Default: 5 seconds

rtype:

float

property DefaultHeartbeatPeriod

Set the default heartbeat period in seconds

The heartbeat is used to keep the connection alive if no communication is occuring between nodes.

Default: 5 seconds

rtype:

float

property MaxMessageSize

Set the maximum serialized message size

Default: 10 MB

rtype:

int

property DisableMessage4

Set disable Message Format Version 4

Message Format Version 2 will be used

Default: Message V4 is enabled

rtype:

bool

property DisableStringTable

Set disable string table

Default: false

RobotRaconteurNodeSetup and its subclasses will disable the string table by default

rtype:

bool

property DisableAsyncMessageIO

Set if async message io is disabled

Async message io has better memory handling, at the expense of slightly higher latency.

Async message io is not well supported by this transport. Enabling async message io is not recommended.

Default: Async io disabled

rtype:

bool