Subscription

ServiceInfo2Subscription Class

class RobotRaconteur.ServiceInfo2Subscription

Subscription for information about detected services

Created using RobotRaconteurNode.SubscribeServiceInfo2()

The ServiceInfo2Subscription class is used to track services with a specific service type as they are detected on the local network and when they are lost. The currently detected services can also be retrieved. The service information is returned using the ServiceInfo2 structure.

Close()

Close the subscription

Closes the subscription. Subscriptions are automatically closed when the node is shut down.

GetDetectedServiceInfo2()

Returns a dict of detected services.

The returned dict contains the detected nodes as ServiceInfo2. The dict is keyed with ServiceSubscriptionClientID.

This function does not block.

Returns:

The detected services.

Return type:

Dict[RobotRaconteur.ServiceSubscriptionClientID,ServiceInfo2]

property ServiceDetected

Event hook for service detected events. Use to add handlers to be called when a service is detected.

def my_handler(sub, subscription_id, service_info2):
   # Process detected service
   pass

my_serviceinfo2_sub.ServiceDetected += my_handler

Handler must have signature Callable[[RobotRaconteur.ServiceInfo2Subscription,RobotRaconteur.ServiceSubscriptionClientID,RobotRaconteur.ServiceInfo2],None]

Return type:

RobotRaconteur.EventHook

property ServiceLost

Event hook for service lost events. Use to add handlers to be called when a service is lost.

def my_handler(sub, subscription_id, service_info2):
   # Process lost service
   pass

my_serviceinfo2_sub.ServiceLost += my_handler

Handler must have signature Callable[[RobotRaconteur.ServiceInfo2Subscription,RobotRaconteur.ServiceSubscriptionClientID,RobotRaconteur.ServiceInfo2],None]

Return type:

RobotRaconteur.EventHook

ServiceSubscription Class

class RobotRaconteur.ServiceSubscription

Subscription that automatically connects services and manages lifecycle of connected services

Created using RobotRaconteurNode.SubscribeService() or RobotRaconteurNode.SubscribeServiceByType(). The ServiceSubscription class is used to automatically create and manage connections based on connection criteria. RobotRaconteur.SubscribeService() is used to create a robust connection to a service with a specific URL. RobotRaconteurNode.SubscribeServiceByType() is used to connect to services with a specified type, filtered with a ServiceSubscriptionFilter. Subscriptions will create connections to matching services, and will retry the connection if it fails or the connection is lost. This behavior allows subscriptions to be used to create robust connections. The retry delay for connections can be modified using the ConnectRetryDelay property.

The currently connected clients can be retrieved using the GetConnectedClients() function. A single “default client” can be retrieved using the GetDefaultClient() function or TryGetDefaultClient() functions. Listeners for client connect and disconnect events can be added using the ClientConnectListener and ClientDisconnectListener properties. If the user wants to claim a client, the ClaimClient() and ReleaseClient() functions will be used. Claimed clients will no longer have their lifecycle managed by the subscription.

Subscriptions can be used to create “pipe” and “wire” subscriptions. These member subscriptions aggregate the packets and values being received from all services. They can also act as a “reverse broadcaster” to send packets and values to all services that are actively connected. See PipeSubscription and WireSubscription.

AsyncGetDefaultClient(handler, timeout=-1)

Asynchronously get the default client, with optional timeout

Same as GetDefaultClientWait(), but returns asynchronously.

If handler is None, returns an awaitable future.

Parameters:

• handler (Callable[[bool,object],None]) – The handler to call when default client is available, or times out

• timeout (float) – Timeout in seconds, or -1 for infinite

property ClientConnectFailed

Event hook for client client connect failed events. Used to receive notification of when a client connection was not successful, including the urls and resulting exceptions.

def my_handler(sub, subscription_id, candidate_urls, exceptions):
   # Process lost service
   pass

my_service_sub.ClientDisconnected += my_handler

Handler must have signature Callable[[RobotRaconteur.ServiceInfo2Subscription,RobotRaconteur.ServiceSubscriptionClientID,List[str],List[Exception]],None]

Return type:

RobotRaconteur.EventHook

property ClientConnected

Event hook for client connected events. Use to add handlers to be called when a client is connected.

def my_handler(sub, subscription_id, connected_service):
   # Process lost service
   pass

my_service_sub.ClientConnected += my_handler

Handler must have signature Callable[[RobotRaconteur.ServiceInfo2Subscription,RobotRaconteur.ServiceSubscriptionClientID,T],None]

Return type:

RobotRaconteur.EventHook

property ClientDisconnected

Event hook for client disconnected events. Use to add handlers to be called when a client is disconnected.

def my_handler(sub, subscription_id, connected_service):
   # Process lost service
   pass

my_service_sub.ClientDisconnected += my_handler

Handler must have signature Callable[[RobotRaconteur.ServiceInfo2Subscription,RobotRaconteur.ServiceSubscriptionClientID,T],None]

Return type:

RobotRaconteur.EventHook

Close()

Close the subscription

Closes the subscription. Subscriptions are automatically closed when the node is shut down.

property ConnectRetryDelay

Set the connect retry delay in seconds

Default is 2.5 seconds

Return type:

float

GetConnectedClients()

Returns a dict of connected clients

The returned dict contains the connect clients. The dict is keyed with ServiceSubscriptionClientID.

Clients must be cast to a type, similar to the client returned by RobotRaconteurNode.ConnectService().

Clients can be “claimed” using ClaimClient(). Once claimed, the subscription will stop managing the lifecycle of the client.

This function does not block.

Return type:

Dict[RobotRaconteur.ServiceSubscriptionClientID,Any]

GetDefaultClient()

Get the “default client” connection

The “default client” is the “first” client returned from the connected clients map. This is effectively default, and is only useful if only a single client connection is expected. This is normally true for RobotRaconteurNode.SubscribeService()

Clients using GetDefaultClient() should not store a reference to the client. It should instead call GetDefaultClient() right before using the client to make sure the most recenty connection is being used. If possible, SubscribePipe() or SubscribeWire() should be used so the lifecycle of pipes and wires can be managed automatically.

Returns:

The client connection

GetDefaultClientWait(timeout=-1)

Get the “default client” connection, waiting with timeout if not connected

The “default client” is the “first” client returned from the connected clients map. This is effectively default, and is only useful if only a single client connection is expected. This is normally true for RobotRaconteurNode.SubscribeService()

Clients using GetDefaultClient() should not store a reference to the client. It should instead call GetDefaultClient() right before using the client to make sure the most recenty connection is being used. If possible, SubscribePipe() or SubscribeWire() should be used so the lifecycle of pipes and wires can be managed automatically.

Parameters:

timeout (float) – Timeout in seconds, or -1 for infinite

Returns:

The client connection

property ServiceURL

Get the service connection URL

Returns the service connection URL. Only valid when subscription was created using RobotRaconteurNode.SubscribeService(). Will throw an exception if subscription was opened using RobotRaconteurNode.SubscribeServiceByType()

SubscribePipe(pipe_name, service_path=None)

Creates a pipe subscription

Pipe subscriptions aggregate the packets received from the connected services. It can also act as a “reverse broadcaster” to send packets to clients. See PipeSubscription.

The optional service path may be an empty string to use the root object in the service. The first level of the service path may be “*” to match any service name. For instance, the service path “*.sub_obj” will match any service name, and use the “sub_obj” objref.

Parameters:

• membername (str) – The member name of the pipe

• servicepath (str) – The service path of the object owning the pipe member

Returns:

The pipe subscription

Return type:

RobotRaconteur.PipeSubscription

SubscribeSubObject(service_path)

Creates a sub object subscription.

Sub objects are objects within a service that are not the root object. Sub objects are typically referenced using objref members, however they can also be referenced using a service path. The SubObjectSubscription class is used to automatically access sub objects of the default client.

The service path is broken up into segments using periods. See the Robot Raconter documentation for more information. The BuildServicePath() function can be used to assist building service paths. The first level of the* service path may be “*” to match any service name. For instance, the service path “*.sub_obj” will match any service name, and use the “sub_obj” objref

Parameters:

service_path (str) – The service path of the object

Returns:

The sub object subscription

Return type:

SubObjectSubscription

SubscribeWire(wire_name, service_path=None)

Creates a wire subscription

Wire subscriptions aggregate the value received from the connected services. It can also act as a “reverse broadcaster” to send values to clients. See WireSubscription.

The optional service path may be an empty string to use the root object in the service. The first level of the service path may be “*” to match any service name. For instance, the service path “*.sub_obj” will match any service name, and use the “sub_obj” objref.

Parameters:

• membername (str) – The member name of the wire

• servicepath (str) – The service path of the object owning the wire member

Returns:

The wire subscription

Return type:

RobotRaconteur.WireSubscription

TryGetDefaultClient()

Try getting the “default client” connection

Same as GetDefaultClient(), but returns a bool success instead of throwing exceptions on failure.

Returns:

Success and client (if successful) as a tuple

Return type:

Tuple[bool,T]

TryGetDefaultClientWait(timeout=-1)

Try getting the “default client” connection, waiting with timeout if not connected

Same as GetDefaultClientWait(), but returns a bool success instead of throwing exceptions on failure.

Returns:

Success and client (if successful) as a tuple

Return type:

Tuple[bool,T]

UpdateServiceByType(service_types, filter_=None)

Update the service types and filter

Parameters:

• service_types (Union[str,List[str]]) – The new service types to use to connect to service

• filter (Union[str,RobotRaconteurPython.ServiceSubscriptionFilter]) – Optional filter to use to connect to service

UpdateServiceURL(url, username=None, credentials=None, close_connected=False)

Update the service connection URL

Updates the URL used to connect to the service. If close_connected is True, existing connections will be closed. If False, existing connections will not be closed.

Parameters:

• url (Union[str,List[str]]) – The new URL to use to connect to service

• username (str) – An optional username for authentication

• credentials (Dict[str,Any]) – Optional credentials for authentication

• close_connected – Optional, (default False) Close existing connections

ServiceSubscriptionClientID Class

class RobotRaconteur.ServiceSubscriptionClientID

ClientID for use with ServiceSubscription

The ServiceSubscriptionClientID stores the NodeID and ServiceName of a connected service.

NodeID

(RobotRaconteur.NodeID) The NodeID of the connected service

ServiceName

(str) The ServiceName of the connected service

ServiceSubscriptionFilter Class

class RobotRaconteur.ServiceSubscriptionFilter

Subscription filter

The subscription filter is used with RobotRaconteurNode.SubscribeServiceByType() and RobotRaconteurNode.SubscribeServiceInfo2() to decide which services should be connected. Detected services that match the service type are checked against the filter before connecting.

Attributes

(Dict[str,RobotRaconteur.ServiceSubscriptionFilterAttributeGroup] Attributes to match)

AttributesMatchOperation

(RobotRaconteur.ServiceSubscriptionFilterAttributeGroupOperation) The operation to use when matching attributes. Default is AND. Can be OR, AND, NOR, and NAND.

MaxConnections

(int) The maximum number of connections the subscription will create. Zero means unlimited connections.

Nodes

(List[RobotRaconteurServiceSubscriptionFilterNode]) List of nodes that should be connected. Empty means match any node.

Predicate

(Callable[[RobotRaconteur.ServiceInfo2],bool]) A user specified predicate function. If nullptr, the predicate is not checked.

ServiceNames

(List[str]) List of service names that should be connected. Empty means match any service name.

TransportSchemes

(List[str]) List of transport schemes. Empty means match any transport scheme.

ServiceSubscriptionFilterNode Class

class RobotRaconteur.ServiceSubscriptionFilterNode

Subscription filter node information

Specify a node by NodeID and/or NodeName. Also allows specifying username and password.

When using username and credentials, secure transports and specified NodeID should be used. Using username and credentials without a transport that verifies the NodeID could result in credentials being leaked.

Credentials

(Dict[str,Any]) The credentials to use for authentication. Should only be used with secure transports and verified NodeID

NodeID

(RobotRaconteur.NodeID) The NodeID to match. All zero NodeID will match any NodeID.

NodeName

(str) The NodeName to match. Emtpy NodeName will match any NodeName.

Username

(str) The username to use for authentication. Should only be used with secure transports and verified NodeID

WireSubscription Class

class RobotRaconteur.WireSubscription

Subscription for wire members that aggregates the values from client wire connections

Wire subscriptions are created using the ServiceSubscription.SubscribeWire() function. This function takes the type of the wire value, the name of the wire member, and an optional service path of the service object that owns the wire member.

Wire subscriptions aggregate the InValue from all active wire connections. When a client connects, the wire subscriptions will automatically create wire connections to the wire member specified when the WireSubscription was created using ServiceSubscription.SubscribeWire(). The InValue of all the active wire connections are collected, and the most recent one is used as the current InValue of the wire subscription. The current value, the timespec, and the wire connection can be accessed using GetInValue() or TryGetInValue().

The lifespan of the InValue can be configured using the InValueLifeSpan property. It is recommended that the lifespan be configured, so that the value will expire if the subscription stops receiving fresh in values.

The wire subscription can also be used to set the OutValue of all active wire connections. This behaves similar to a “reverse broadcaster”, sending the same value to all connected services.

property ActiveWireConnectionCount

Get the number of wire connections currently connected

Return type:

int

Close()

Closes the wire subscription

Wire subscriptions are automatically closed when the parent ServiceSubscription is closed or when the node is shut down.

property IgnoreInValue

Set if InValue should be ignored

See WireConnection.IgnoreInValue

If true, InValue will be ignored for all wire connections

Return type:

bool

property InValue

Get the current InValue

Throws ValueNotSetException if no valid value is available

Returns:

The current InValue

property InValueLifespan

Set the InValue lifespan in seconds

Set the lifespan of InValue in seconds. The value will expire after the specified lifespan, becoming invalid. Use -1 for infinite lifespan.

See also WireConnection.InValueLifespan

Return type:

float

property InValueWithTimeSpec

Get the current InValue and TimeSpec

Throws ValueNotSetException if no valid value is available

Returns:

The current InValue and TimeSpec

Return type:

Tuple[T,RobotRaconteur.TimeSpec]

SetOutValueAll(value)

Set the OutValue for all active wire connections

Behaves like a “reverse broadcaster”. Calls WireConnection.OutValue for all connected wire connections.

Parameters:

value – The value to send

TryGetInValue()

Try getting the current InValue and metadata

Same as GetInValue(), but returns a bool for success or failure instead of throwing an exception.

Returns:

Success and value (if successful)

Return type:

Tuple[bool,T,RobotRaconteur.TimeSpec]

WaitInValueValid(timeout=-1)

Wait for a valid InValue to be received from a client

Blocks the current thread until value is received or timeout

Parameters:

timeout (float) – The timeout in seconds

Returns:

True if value was received, otherwise False

Return type:

bool

property WireValueChanged

Event hook for wire value change. Use to add handlers to be called when the InValue changes.

def my_handler(sub, value, ts):
   # Handle new value
   pass

my_wire_csub.WireValueChanged += my_handler

Handler must have signature Callable[[RobotRaconteur.WireSubscription,T,RobotRaconteur.TimeSpec],None]

Return type:

RobotRaconteur.EventHook

PipeSubscription Class

class RobotRaconteur.PipeSubscription

Subscription for pipe members that aggregates incoming packets from client pipe endpoints

Pipe subscriptions are created using the ServiceSubscription.SubscribePipe() function. This function takes the the type of the pipe packets, the name of the pipe member, and an optional service path of the service object that owns the pipe member.

Pipe subscriptions collect all incoming packets from connect pipe endpoints. When a client connects, the pipe subscription will automatically connect a pipe endpoint the pipe endpoint specified when the PipeSubscription was created using ServiceSubscription.SubscribePipe(). The packets received from each of the collected pipes are collected and placed into a common receive queue. This queue is read using ReceivePacket(), TryReceivePacket(), or TryReceivePacketWait(). The number of packets available to receive can be checked using Available().

Pipe subscriptions can also be used to send packets to all connected pipe endpoints. This is done with the AsyncSendPacketAll() function. This function behaves somewhat like a “reverse broadcaster”, sending the packets to all connected services.

If the pipe subscription is being used to send packets but not receive them, IgnoreInValue should be set to true to prevent packets from queueing.

property ActivePipeEndpointCount

Get the number of pipe endpoints currently connected

Return type:

int

AsyncSendPacketAll(packet)

Sends a packet to all connected pipe endpoints

Calls AsyncSendPacket() on all connected pipe endpoints with the specified value. Returns immediately, not waiting for transmission to complete.

Parameters:

packet – The packet to send

property Available

Get the number of packets available to receive

Use ReceivePacket(), TryReceivePacket(), or TryReceivePacketWait() to receive the packet

Return type:

int

Close()

Closes the pipe subscription

Pipe subscriptions are automatically closed when the parent ServiceSubscription is closed or when the node is shut down.

property PipePacketReceived

Event hook for packet received. Use to add handlers to be called when the subscription receives a new packet.

def my_handler(pipe_sub):
   while pipe_sub.Available > 0:
       packet = pipe_sub.ReceivePacket()
       # Handle new packet
       pass

my_pipe_sub.PipePacketReceived+= my_handler

Handler must have signature Callable[[RobotRaconteur.PipeSubscription],None]

Return type:

RobotRaconteur.EventHook

ReceivePacket()

Dequeue a packet from the receive queue

If the receive queue is empty, an InvalidOperationException() is thrown

Returns:

The dequeued packet

TryReceivePacket()

Try dequeuing a packet from the receive queue

Same as ReceivePacket(), but returns a bool for success or failure instead of throwing an exception

Returns:

Success and packet (if successful)

Return type:

Tuple[bool,T]

TryReceivePacketWait(timeout=-1, peek=False)

Try dequeuing a packet from the receive queue, optionally waiting or peeking the packet

Parameters:

• timeout (float) – The time to wait for a packet to be received in seconds if the queue is empty, or -1 to wait forever

• peek (bool) – If True, the packet is returned, but not dequeued. If False, the packet is dequeued

Returns:

Success and packet (if successful)

Return type:

Tuple[bool,T]

SubObjectSubscription Class

class RobotRaconteur.SubObjectSubscription(parent, subscription)

Subscription for sub objects of the default client.

SubObjectSubscription is used to access sub objects of the default client. Sub objects are objects within a service that are not the root object. Sub objects are typically referenced using objref members, however they can also be referenced using a service path. The SubObjectSubscription class is used to automatically access sub objects of the default client.

Use ServiceSubscription.SubscribeSubObject() to create a SubObjectSubscription.

This class should not be used to access Pipe or Wire members. Use the ServiceSubscription.SubscribePipe() and ServiceSubscription.SubscribeWire() functions to access Pipe and Wire members.

AsyncGetDefaultClient(handler, timeout=-1)

Asynchronously get the default client, with optional timeout

Same as GetDefaultClientWait(), but returns asynchronously.

If handler is None, returns an awaitable future.

Parameters:

• handler (Callable[[bool,object],None]) – The handler to call when default client is available, or times out

• timeout (float) – Timeout in seconds, or -1 for infinite

GetDefaultClient()

Get the “default client” sub object.

The sub object is retrieved from the default client. The default client is the first client that connected to the service. If no clients are currently connected, an exception is thrown.

Clients using GetDefaultClient() should not store a reference to the client. Call GetDefaultClient() each time the client is needed.

Returns:

The sub object

Return type:

T

GetDefaultClientWait(timeout=-1)

Get the “default client” sub object, waiting with timeout if not connected

The sub object is retrieved from the default client. The default client is the first client that connected to the service. If no clients are currently connected, an exception is thrown.

Clients using GetDefaultClient() should not store a reference to the client. Call GetDefaultClient() each time the client is needed.

Parameters:

timeout (float) – Timeout in seconds, or -1 for infinite

Returns:

The sub object

TryGetDefaultClient()

Try getting the “default client” sub object.

Same as GetDefaultClient(), but returns a bool success instead of throwing exceptions on failure.

Returns:

Success and client (if successful) as a tuple

Return type:

Tuple[bool,T]

TryGetDefaultClientWait(timeout=-1)

Try getting the “default client” sub object, waiting with timeout if not connected

Same as GetDefaultClientWait(), but returns a bool success instead of throwing exceptions on failure.

Returns:

Success and client (if successful) as a tuple

Return type:

Tuple[bool,T]

ServiceSubscriptionManager Class

class RobotRaconteur.ServiceSubscriptionManager(details=None, node=None)

Class to manage multiple subscriptions to services

ServiceSubscriptionManager is used to manage multiple subscriptions to services. Subscriptions are created using information contained in ServiceSubscriptionManagerDetails structures. The subscriptions can connect using URLs or service types. The subscriptions can be enabled or disabled, and can be closed.

Parameters:

• details (List[ServiceSubscriptionManagerDetails]) – (optional) A list of ServiceSubscriptionManagerDetails structures

• node (RobotRaconteur.RobotRaconteurNode) – (optional) The RobotRaconteurNode to use

AddSubscription(details)

Add a subscription to the manager

Parameters:

details (ServiceSubscriptionManagerDetails) – The subscription to add

Close(close_subscriptions=True)

Close the subscription manager

Parameters:

close_subscriptions (bool) – (default True) Close all subscriptions

DisableSubscription(name, close=True)

Disable a subscription

Parameters:

name (str) – The name of the subscription to disable

EnableSubscription(name)

Enable a subscription

Parameters:

name (str) – The name of the subscription to enable

GetSubscription(name, force_create=False)

Get a subscription by name

Parameters:

• name (str) – The name of the subscription to get

• force_create (bool) – (default False) Create the subscription if it does not exist

Returns:

The subscription

Return type:

ServiceSubscription

IsConnected(name)

Check if a subscription is connected

Parameters:

name (str) – The name of the subscription to check

Returns:

True if the subscription is connected

Return type:

bool

IsEnabled(name)

Get if a subscription is enabled

Parameters:

name (str) – The name of the subscription to check

Returns:

True if the subscription is enabled

Return type:

bool

RemoveSubscription(name, close=True)

Remove a subscription from the manager

Parameters:

• name (str) – The name of the subscription to remove

• close (bool) – (default True) Close the subscription

property SubscriptionDetails

Get the details of all subscriptions

Return type:

List[ServiceSubscriptionManagerDetails]

property SubscriptionNames

Get the names of all subscriptions

Return type:

List[str]

ServiceSubscriptionManagerDetails Class

class RobotRaconteur.ServiceSubscriptionManagerDetails(Name=None, ConnectionMethod=None, Urls=None, UrlUsername=None, UrlCredentials=None, ServiceTypes=None, Filter=None, Enabled=True)

ServiceSubscriptionManager subscription connection information

Contains the connection information for a ServiceSubscriptionManager subscription and the local name of the subscription

ConnectionMethod

(ServiceSubscriptionManager_CONNECTION_METHOD) The connection method used to connect to the service

Enabled

(bool) True if the subscription is enabled

Filter

(ServiceSubscriptionFilter) The filter used to connect to the service

Name

(str) The local name of the subscription

ServiceTypes

(List[str]) The service types used to connect to the service

UrlCredentials

(Dict[str,Any]) The credentials used to connect to the service

UrlUsername

(str) The username used to connect to the service

Urls

(List[str]) The URLs used to connect to the service