RobotRaconteurNode

class RobotRaconteur.RobotRaconteurNode

The central node implementation

RobotRaconteurNode implements the current Robot Raconteur instance and acts as the central switchpoint for the instance. The user registers types, connects clients, registers services, and registers transports through this class.

If the current program only needs one instance of RobotRaconteurNode, the singleton can be used. The singleton is accessed using:

RobotRaconteurNode.s

The singleton node is typically aliased to RRN for shorthand.

If

from RobotRaconteur.Client import *

is used, then RRN is automatically imported. If not used, the following is typically used:

import RobotRaconteur as RR
RRN = RobotRaconteur.s

Singleton accessor

The RobotRaconteurNode singleton can be used when only one instance of Robot Raconteur is required in a program.

ArrayToNamedArray(a, named_array_dt)

Converts a numeric array into a namedarray. The type of the namedarray is specified using dt, which is returned from GetNamedArrayDType(). The input numeric array must have the correct numeric type, and the first dimension must match the element count of the namedarray. The output array will have one fewer dimensions than the input array.

Parameters:

a (numpy.ndarray) – The numeric array to convert
dt (numpy.dtype) – The data type of the desired namedarray type

Returns:

The converted namedarray

Return type:

numpy.ndarray

AsyncConnectService(url, username, credentials, listener, handler, timeout=-1)

Asynchronously create a client connection to a remote service using a URL

Same as ConnectService but returns asynchronously. See ConnectService() for more details on client connections.

handler is called after the client connection succeeds are fails. On success, the object reference is returned and the exception is None. On failure, the returned object is None and the exception contains a subclass of Exception.

If handler is None, returns an awaitable future.

Parameters:

url (Union[str,List[str]]) – The URL of the service to connect
username (str) – A username for authentication, None for no authentication
credentials (Dict[str,Any]) – credentials for authentication, None for no authentication
listener (Callable[[object,int,Any],None]) – A listener callback function, None for no listener
handler (Callable[[object,Exception],None]) – A handler function to receive the object reference or an exception
timeout (float) – Timeout in seconds, or -1 for no timeout

AsyncDisconnectService(stub, handler)

Asynchronously disconnects a client connection to a service

Same as DisconnectService() but returns asynchronously.

If handler is None, returns an awaitable future.

Parameters:

obj – The root object of the client to disconnect
handler (Callable[[],None]) – The handler to call when complete

AsyncFindNodeByID(id, transportschemes, handler, timeout=5)

Asynchronously finds nodes on the network with the specified NodeID

Same as FindNodeByID() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

id (RobotRaconteur.NodeID) – The NodeID to find
transportschemes (List[str]) – A list of transport types to search, ie “rr+tcp”, “rr+local”, “rrs+tcp”, etc
handler (Callable[List[NodeInfo2],None]) – Handler to call on completion
timeout (float) – Timeout in seconds. Using a timeout greater than 5 seconds is not recommended.

AsyncFindNodeByName(name, transportschemes, handler, timeout=5)

Asynchronously finds nodes on the network with the specified NodeName

Same as FindNodeByName() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

name (str) – The NodeName to find
transportschemes (List[str]) – A list of transport types to search, ie “rr+tcp”, “rr+local”, “rrs+tcp”, etc
handler (Callable[List[NodeInfo2],None]) – Handler to call on completion
timeout (float) – Timeout in seconds. Using a timeout greater than 5 seconds is not recommended.

AsyncFindObjectType(obj, member, handler, timeout=-1)

Asynchronously returns an objref as a specific type

Same as FindObjectType() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

obj – The object with the desired “objref”
objref (str) – The name of the “objref” member
handler (Callable[[str,Exception],None]) – A handler function to receive the object type or an exception
timeout (float) – Timeout is milliseconds, or -1 for infinite

AsyncFindObjectTypeInd(obj, member, ind, handler, timeout=-1)

Asynchronously returns an objref as a specific type

Same as FindObjectType() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

obj – The object with the desired “objref”
objref (str) – The name of the “objref” member
ind (Union[int,str]) – The index for the “objref”
handler (Callable[[str,Exception],None]) – A handler function to receive the object type or an exception
timeout (float) – Timeout is milliseconds, or -1 for infinite

AsyncFindServiceByType(servicetype, transportschemes, handler, timeout=5)

Asynchronously use discovery to find availabe services by service type

Same as FindServiceByType() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

servicetype (str) – The service type to find, ie “com.robotraconteur.robotics.robot.Robot”
transportschemes (List[str]) – A list of transport types to search, ie “rr+tcp”, “rr+local”, “rrs+tcp”, etc
handler (Callable[[List[ServiceInfo2]],None]) – Handler to call on completion
timeout (float) – Timeout in seconds. Using a timeout greater than 5 seconds is not recommended.

AsyncReleaseObjectLock(obj, handler, timeout=-1)

Asynchronously release an excluse access lock previously locked with RequestObjectLock() or AsyncRequestObjectLock()

Same as ReleaseObjectLock() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

obj – The object previously locked
handler (Callable[[str,Exception],None]) – Handler to call on completion
timeout – Timeout in seconds, or -1 for infinite

AsyncRequestObjectLock(obj, flags, handler, timeout=-1)

Asynchronously request an exclusive access lock to a service object

Same as RequestObjectLock() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

obj – The object to lock. Must be returned by ConnectService or returned by an “objref”
flags – Select either a “User” lock with RobotRaconteur.RobotRaconteurObjectLockFlags_USER_LOCK or “Session” lock with RobotRaconteur.RobotRaconteurObjectLockFlags_CLIENT_LOCK
handler (Callable[[str,Exception],None]) – Handler to call on completion
timeout (float) – Timeout in seconds, or -1 for infinite

AsyncUpdateDetectedNodes(schemes, handler, timeout=5)

Asynchronously update the detected nodes cache

Same as UpdateDetectedNodes() but returns asynchronously

If handler is None, returns an awaitable future.

Parameters:

schemes (List[str]) – A list of transport schemes, ie “rr+tcp”, “rr+local”, etc. to update.
handler (Callable[[],None]) – The handler to call on completion
timeout (float) – The timeout for the operation in seconds. This function will often run for the full timeout, so values less than 5 seconds are recommended.

CheckConnection(client)

Check that the TransportConnection associated with an endpoint is connected

Raises RobotRaconteur.ConnectionException or other exception if connection is invalid.

Parameters:: endpoint (int) – The LocalEndpoint identifier to check

CloseService(sname)

Closes a previously registered service

Services are automatically closed by Shutdown, so this function is rarely used.

Parameters:: sname (str) – The name of the service to close

CompareLogLevel(log_level)

Test if the specified log level would be accepted

Parameters:: log_level (int) – Log level to test
Returns:: True if the log would be accepted, False if it would be ignored
Return type:: bool

ConnectService(url, username=None, credentials=None, listener=None)

Create a client connection to a remote service using a URL

Synchronously creates a connection to a remote service using a URL. URLs are either provided by the service, or are determined using discovery functions such as FindServiceByType(). This function is the primary way to create client connections.

username and credentials can be used to specify authentication information. Credentials will often contain a “password” or token entry.

The listener is a function that is called during various events. See ClientServiceListenerEventType constants for a description of the possible events.

ConnectService will attempt to instantiate a client object reference (proxy) based on the type information provided by the service. The type information will contain the type of the object, and all the implemented types.

Parameters:

url (Union[str,List[str]]) – The URL of the service to connect
username (str) – An optional username for authentication, None for no authentication
credentials (Dict[str,Any]) – Optional credentials for authentication, None for no authentication
listener (Callable[[object,int,Any],None]) – Optional listener callback function

Returns:

The client object reference (proxy).

CreateAutoResetEvent()

Create an AutoResetEvent object

Normally the AutoResetEvent will use the system clock for timeouts, but in certain circumstances will use simulation time

Returns:: The new AutoResetEvent object
Return type:: RobotRaconteur.AutoResetEvent

CreateRate(frequency)

Create a Rate object

Rate is used to stabilize periodic loops to a specified frequency

This function will normally return a WallRate instance

Parameters:: frequency (float) – Frequency of loop in Hz
Returns:: The new Rate object
Return type:: RobotRaconteur.Rate

CreateTimer(period, handler, oneshot=False)

Create a Timer object

This function will normally return a WallTimer instance

Start() must be called after timer creation

Parameters:

period (float) – The period of the timer in seconds
handler (Callable[[TimerEvent],None]) – The handler function to call when timer times out
oneshot (bool) – True if timer is a one-shot timer, False for repeated timer

Returns:

The new Timer object. Must call Start()

Return type:

RobotRaconteur.Timer

DisconnectService(stub)

Disconnects a client connection to a service

Synchronously disconnects a client connection. Client connections are automatically closed by Shutdown(), so this function is optional.

Parameters:: obj – The root object of the service to disconnect

property EndpointInactivityTimeout

(float) The timeout for endpoint activity in seconds

Sets a timeout for endpoint inactivity. If no message is sent or received by the endpoint for the specified time, the endpoint is closed. Default timeout is 10 minutes.

FindNodeByID(id, transportschemes)

Finds nodes on the network with a specified NodeID

Updates the discovery cache and find nodes with the specified NodeID. This function returns unverified cache information.

Parameters:

id (RobotRaconteur.NodeID) – The NodeID to find
transportschemes – A list of transport types to search, ie “rr+tcp”, “rr+local”, “rrs+tcp”, etc

Returns:

The discovered nodes

Return type:

List[NodeInfo2]

FindNodeByName(name, transportschemes)

Finds nodes on the network with a specified NodeName

Updates the discovery cache and find nodes with the specified NodeName. This function returns unverified cache information.

Parameters:

name (str) – The NodeName to find
transportschemes – A list of transport types to search, ie “rr+tcp”, “rr+local”, “rrs+tcp”, etc

Returns:

The discovered nodes

Return type:

List[NodeInfo2]

FindObjectType(obj, member, ind=None)

Returns the fully qualified object type that would be returned by an “objref” member

Parameters:

obj – The object with the desired “objref”
objref (str) – The name of the “objref” member
ind (Union[int,str]) – The index for the “objref”

Returns:

The fully qualified object type

Return type:

str

FindServiceByType(servicetype, transportschemes)

Use discovery to find available services by service type

Uses discovery to find available services based on a service type. This service type is the type of the root object, ie “com.robotraconteur.robotics.robot.Robot”. This process will update the detected node cache.

Parameters:

servicetype (str) – The service type to find, ie “com.robotraconteur.robotics.robot.Robot”
transportschemes (List[str]) – A list of transport types to search, ie “rr+tcp”, “rr+local”, “rrs+tcp”, etc

Returns:

The discovered services

Return type:

List[RobotRaconteur.ServiceInfo2]

GetConstants(servicetype, obj=None)

Returns a structure that contains the constants of the specified service type

Parameters:

servicetype (str) – The name of the service definition
obj – The client connection object reference to be used with to retrive service types. This is necessary because each client maintains type information. A client must be provided from which type information can be queried. For services this parameter is unnecessary.

Return type:

Dict[str,Any]

GetDetectedNodeCacheInfo(nodeid)

Get cached node discovery information

Return current node information from the discovery cache. This information is unverified and is used for the first step in the discovery process.

Parameters:: nodeid (RobotRaconteur.NodeID) – The NodeID of the requested node
Returns:: The node info
Return type:: RobotRaconteur.NodeInfo2

GetDetectedNodes()

Get the nodes currently detected by Transports

Transports configured to listen for node discovery send detected node information to the parent node, where it is stored. Normally this information will expire after one minute, and needs to be constantly refreshed.

This node information is not verified. It is the raw discovery information received by the transports. Verification is done when the node is interrogated for service information.

Returns:: List of detected NodeID
Return type:: List[RobotRaconteur.NodeID]

GetExceptionType(exceptionname, obj=None)

Returns a reference to the exception class of fully qualified type exceptiontype. Note that this is a class reference, not an instance.

Parameters:

exceptionname (str) – The fully qualified name of the exception type
obj – The client connection object reference to be used with to retrive service types. This is necessary because each client maintains type information. A client must be provided from which type information can be queried. For services this parameter is unnecessary.

Returns:

Exception type

GetLogLevel()

Get the current log level for the node

Default level is “info”

Returns:: The current log level
Return type:: int

GetLogRecordHandler()

Get the currently configured log record handler

If None, records are sent to stdout

Returns:: The log record handler
Return type:: LogRecordHandler

GetNamedArrayDType(namedarraytype, obj=None)

Returns the numpy dtype for namedarraytype

Use with numpy.array() or numpy.zeros() to create new namedarray arrays.

Parameters:

type (str) – The fully qualified type of the namedarray
obj – The client connection object reference to be used with this namedarray type. This is necessary because each client maintains type information. A client must be provided from which type information can be queried. For services this parameter is unnecessary.

Returns:

The dtype for the specified namedarray

Return type:

numpy.dtype

GetObjectServicePath(obj)

Get the service path of a client object

Parameters:: obj – The object to get the service path for
Returns:: The object’s service path
Return type:: str

GetObjectType(obj)

Get the Robot Raconteur type of a connected service object obj have been returned by ConnectService(), AsyncConnectService(), or an objref

Parameters:: obj – The object to query
Returns:: The Robot Raconteur type of the object
Return type:: str

GetPodDType(podtype, obj=None)

Returns the numpy dtype for podtype

Use with numpy.array() or numpy.zeros() to create new pod arrays.

Parameters:

type (str) – The fully qualified type of the pod
obj – The client connection object reference to be used with this pod type. This is necessary because each client maintains type information. A client must be provided from which type information can be queried. For services this parameter is unnecessary.

Returns:

The dtype for the specified podtype

Return type:

numpy.dtype

GetPulledServiceType(obj, servicetype)

Get a ServiceFactory created from a service type pulled by a client

Clients pull service definitions from services and create instances of ServiceFactory if a DynamicServiceFactory has been configured. GetPulledServiceType() returns a generated ServiceFactory. Use GetPulledServiceTypes() to return a list of available service types.

Parameters:

obj – Client object referenece returned by ConnectService() or AsyncConnectService()
servicetype (str) – The name of the service type

Returns:

The pulled service factory

Return type:

RobotRaconteur.ServiceDefinition

GetPulledServiceTypes(obj)

Get the names of service types pulled by a client

Clients pull service definitions from services and create instances of ServiceFactory if a DynamicServiceFactory has been configured. GetPulledServiceTypes returns a list of the names of these pulled service types. Use GetPulledServiceType() to retrieve the ServiceFactory for a specific type.

Parameters:: obj – Client object referenece returned by ConnectService() or AsyncConnectService()
Returns:: The names of the pulled service types
Return type:: List[str]

GetRegisteredServiceTypes()

Return names of registered service types

Return type:: List[str]

GetServiceAttributes(obj)

Get the service attributes of a client connection

Returns the service attributes of a client connected using ConnectService()

Parameters:: obj – The root object of the client to use to retrieve service attributes
Returns:: The service attributes
Return type:: Dict[str,Any]

GetServiceName(obj)

Get the name of a service from a client connection

Returns the service name of the remote service that a client is connected

Param:: obj The root object of the client to use to retrieve service attributes
Returns:: The service name
Return type:: str

GetServiceNodeID(obj)

Get the service NodeID of the remote node from a client connection

Returns the NodeID of the remote node that a client is connected

Parameters:: obj – The root object of the client to use to retrieve service attributes
Returns:: The NodeID
Return type:: NodeID

GetServiceNodeName(obj)

Get the service NodeName of the remote node from a client connection

Returns the NodeName of the remote node that a client is connected

Parameters:: obj – The root object of the client to use to retrieve service attributes
Returns:: The NodeName
Return type:: str

GetServiceType(name)

Returns a previously registered service type

Parameters:: name (str) – The name of the service type to retrieve
Return type:: ServiceDefinition

GetStructureType(structtype, obj=None)

Returns a constructor for Robot Raconteur structure with type structtype

Parameters:

structtype (str) – The fully qualified type of the structure
obj – The client connection object reference to be used with this structure. This is necessary because each client maintains type information. A client must be provided from which type information can be queried. For services this parameter is unnecessary.

Returns:

The constructer for the structure type

Return type:

Callable[[],<structtype>]

Init(thread_count=20)

Initialize the node. Called automatically for RRN

This function must be called to initialize background tasks before using the node. It is called automatically by the singleton accesors, so the user only needs to call this function when not using the singleton. If a custom thread pool is being used, the thread pool factory must be specified before calling init.

Parameters:: thread_count (int) – The initial number of threads in the thread pool (default 20)

IsServiceTypeRegistered(servicename)

Test if a service type has been registered

Parameters:: type (str) – The name of the service type to check
Return type:: bool

LogMessage(level, message)

Log a simple message using the current node

The record will be sent to the configured log handler, or sent to std::cerr if none is configured

If the level of the message is below the current log level for the node, the record will be ignored

LogRecord(record)

Log a record to the node.

The record will be sent to the configured log handler, or sent to std::cerr if none is configured

If the level of the message is below the current log level for the node, it will be ignored

Parameters:: record (RRLogRecord) – The record to log

property MemoryMaxTransferSize

(int) The maximum chunk size for memory transfers in bytes

“memory” members break up large transfers into chunks to avoid sending messages larger than the transport maximum, which is normally approximately 10 MB. The memory max transfer size is the largest data chunk the memory will send, in bytes. Default is 100 kB.

MonitorEnter(obj, timeout=-1)

Creates a monitor lock on a specified object

Monitor locks are intendended for short operations that require guarding to prevent races, corruption, or other concurrency problems. Monitors emulate a single thread locking the service object.

Use of ScopedMonitorLock instead of this function is highly recommended

Monitor locks do not lock any sub-objects (objref)

Param:: obj The object to lock
Parameters:: timeout – The timeout in seconds to acquire the monitor lock, or -1 for infinite

MonitorExit(obj)

Releases a monitor lock

Use of ScopedMonitorLock instead of this function is highly recommended

Parameters:: obj – The object previously locked by MonitorEnter()

NamedArrayToArray(named_array)

Converts a namedarray type into a primitive array with the namedarray numeric type. This function will return an array with one more dimension than the input array, with the first dimension set to the element count of the named array.

Parameters:: namedarray (numpy.ndarray) – The namedarray to convert stored in a numpy.ndarray
Returns:: The converted numeric array
Return type:: numpy.ndarray

NewStructure(structtype, obj=None)

Returns a new Robot Raconteur structure with type structtype

Parameters:

structtype (str) – The fully qualified type of the structure
obj – The client connection object reference to be used with this structure. This is necessary because each client maintains type information. A client must be provided from which type information can be queried. For services this parameter is unnecessary.

Returns:

The new structure instance

property NodeDiscoveryMaxCacheCount

the maximum number of detected nodes that will be cached

The node keeps a cache of detected nodes. The NodeDiscoveryMaxCacheCount sets an upper limit to how many detected nodes are cached. By default set to 4096

property NodeID: (RobotRaconteur.NodeID) The current NodeID. If one has not been set, one will be automatically generated when read. NodeID cannot be set after it has been configured.

property NodeName: (str) The current NodeName. If one has not been set, it will be the empty string. Cannot be set after it has been configured.

NodeSyncTimeSpec()

The sync time of the node as a TimeSpec

See NowTimeSpec()

Returns:: The node sync time as a TimeSpec
Return type:: RobotRaconteur.TimeSpec

NodeSyncTimeUTC()

The sync time of the node as a TimeSpec

See NowNodeTime()

Returns:: The node sync time as a TimeSpec
Return type:: datetime.DateTime

NowNodeTime()

The current node time

UTC time is not monotonic, due to the introduction of leap-seconds, and the possibility of the system clock being updated by the user. For a real-time systems, this is unaccetpable and can lead to system instability. The “node time” used by Robot Raconteur is synchronized to UTC at startup, and is then steadily increasing from that initial time. It will ignore changes to the system clock, and will also ignore corrections like leap seconds.

Returns:: The current node time
Return type:: datetime.DateTime

NowTimeSpec()

The current time node time as a TimeSpec

The current node time as a TimeSpec. See NowNodeTime()

Returns:: The current node time as a TimeSpec
Return type:: RobotRaconteur.TimeSpec

NowUTC()

The current time in UTC time zone

Uses the internal node clock to get the current time in UTC. While this will normally use the system clock, this may use simulation time in certain circumstances

Returns:: The current time in UTC
Return type:: datetime.DateTime

PostToThreadPool(handler)

Posts a function to be called by the node’s native thread pool.

Parameters:: handler (Callable[[],None]) – The function to call

RegisterService(name, objecttype, obj, securitypolicy=None)

Registers a service for clients to connect

The supplied object becomes the root object in the service. Other objects may be accessed by clients using “objref” members. The name of the service must conform to the naming rules of Robot Raconteur member names. A service is closed using either CloseService() or when Shutdown() is called.

Multiple services can be registered within the same node. Service names within a single node must be unique.

Parameters:

name (str) – The name of the service, must follow member naming rules
objecttype – The fully qualified Robot Raconteur type of the object
obj – The root object of the service
securitypolicy (ServiceSecurityPolicy) – An optional security policy for the service to control authentication and other security functions

Returns:

The instantiated ServerContext. This object is owned by the node and the return can be safely ignored.

Return type:

RegisterServiceType(d)

Register a service type

If passed a string, the string will be parsed as a service definition file

The service type will be verified. All imported types must already have been registered for verification to succeed. It is recommended that RegisterServiceTypes() be used for lists of service types.

Parameters:: d (Union[RobotRaconteur.ServiceDefinition,str]) – The service definition implementing the type to register

RegisterServiceTypeFromFile(file_name)

Register a service type from a file

The file_name must point to a plain text “robdef” file. The file_name may leave off the “.robdef” extension.

The path in the environmental variable ROBOTRACONTEUR_ROBDEF_PATH will be searched if the file is not found in the working directory.

The service type will be verified. All imported types must already have been registered for verification to succeed. It is recommended that RegisterServiceTypesFromFiles() be used for lists of service types.

Parameters:: d (str) – The filename of the service type to load

RegisterServiceTypes(d)

Register a list of service types

If passed a string, the string will be parsed as a service definition file

The service types will be verified. All imported types must be included in the list or already have been registered for verification to succeed.

Parameters:: d (Union[List[RobotRaconteur.ServiceDefinition],List[str]]) – The service types implementing the types to register

RegisterServiceTypesFromFiles(file_names, auto_import=False)

Register a list of service type from files

The file names in file_names must point to plain text “robdef” files. The file names may leave off the “.robdef” extension.

The path in the environmental variable ROBOTRACONTEUR_ROBDEF_PATH will be searched if a file is not found in the working directory.

The service types will be verified. All imported types must already have been registered or included in the file_names list for verification to succeed.

If auto_import is True, missing service type files will be loaded automatically from the filesystem.

Parameters:

file_names (List[str]) – The filenames of the service types to load
auto_import (bool) – If True, attempt to import missing service types

RegisterTransport(transport)

Register a transport for use by the node

Parameters:: transport (RobotRaconteur.Transport) – The transport to register
Returns:: The transport internal id
Return type:: int

ReleaseObjectLock(obj)

Release an excluse access lock previously locked with RequestObjectLock() or AsyncRequestObjectLock()

Object must have previously been locked using RequestObjectLock() or AsyncRequestObjectLock()

Parameters:: obj – The object previously locked
Returns:: “OK” on success
Return type:: str

RequestObjectLock(obj, flags)

Request an exclusive access lock to a service object

Called by clients to request an exclusive lock on a service object and all subobjects (“objrefs”) in the service. The exclusive access lock will prevent other users (“User” lock) or client connections (“Session” lock) from interacting with the objects.

Parameters:

obj – The object to lock. Must be returned by ConnectService or returned by an “objref”
flags – Select either a “User” lock with RobotRaconteur.RobotRaconteurObjectLockFlags_USER_LOCK or “Session” lock with RobotRaconteur.RobotRaconteurObjectLockFlags_CLIENT_LOCK

Returns:

“OK” on success

Return type:

str

property RequestTimeout

(float) The timeout for requests in seconds

Requests are calls to a remote node that expect a response. “function”, “property”, “callback”, “memory”, and setup calls in “pipe” and “wire” are all requests. All other Robot Raconteur functions that call the remote node and expect a response are requests. Default timeout is 15 seconds.

property RobotRaconteurVersion: (str) Returns the Robot Raconteur library version

class ScopedMonitorLock(obj, timeout=-1)

Wrapper for RobotRaconteurNode.MonitorEnter() and RobotRaconteurNode.MonitorExit() supporting with statement scoping

lock(timeout)

Relock the object after calling unlock()

:param timeou:t The timeout in seconds to acquire the monitor lock,: or -1 for infinite

release()

Release the monitor lock from the class

The monitor lock is released from the ScopedMonitorLock instance. The monitor lock will not be released when the with block exits.

unlock()

Releases the monitor lock

The ScopedMonitorLock destructor will release the lock automatically, so in most cases it is not necessary to call this function

static SelectRemoteNodeURL(urls)

Select the “best” URL from a std::vector of candidates

Service discovery will often return a list of candidate URLs to use to connect to a node. This function uses hueristics to select the “best” URL to use. The selection criteria ranks URLs in roughly the following order, lower number being better:

“rr+intra” for IntraTransport
“rr+local” for LocalTransport
“rr+pci” or “rr+usb” for HardwareTransport
“rrs+tcp://127.0.0.1” for secure TcpTransport loopback
“rrs+tcp://[::1]” for secure TcpTransport IPv6 loopback
“rrs+tcp://localhost” for secure TcpTransport loopback
“rrs+tcp://[fe80” for secure TcpTransport link-local IPv6
“rrs+tcp://” for any secure TcpTransport
“rr+tcp://127.0.0.1” for TcpTransport loopback
“rr+tcp://[::1]” for TcpTransport IPv6 loopback
“rr+tcp://localhost” for TcpTransport loopback
“rr+tcp://[fe80” for TcpTransport link-local IPv6
“rr+tcp://” for any TcpTransport

Parameters:: urls (List[str]) – The candidate URLs
Returns:: The “best” URL out of the candidates
Return type:: str

SetExceptionHandler(handler)

Set an exception handler function

The ThreadPool will catch exceptions that are uncaught by other logic and pass the exception to the specified exception handler. User handler functions that throw exceptions will also be caught and passed to the specified handler function

Parameters:: handler (Callable[[Exception],None]) – The handler function for uncaught exceptions

SetLogLevel(level)

Set the log level for the node

Set RobotRaconteur.RobotRaconteur_LogLevel_Disable to disable logging

Parameters:: level (int) – The desired log level

SetLogLevelFromEnvVariable(*args)

Set the log level for the node from specified environmental variable

Retrieves the specified environmental variable and sets the log level based on one of the following values: DISABLE, FATAL, ERROR, WARNING, INFO, DEBUG, TRACE

If an invalid value or the variable does not exist, the log level is left unchanged.

Parameters:: env_variable_name (str) – The environmental variable to use. Defaults to ROBOTRACONTEUR_LOG_LEVEL
Returns:: The log level
Return type:: int

SetLogLevelFromString(level)

Set the log level for the node from a string

Must be one of the following values: DISABLE, FATAL, ERROR, WARNING, INFO, DEBUG, TRACE

Defaults to WARNING

Parameters:: level (str) – The desired log level
Returns:: The log level
Return type:: int

SetLogRecordHandler(handler)

Set the handler for log records

If handler is NULL, records are sent to std::cerr

Parameters:: handler (RobotRaconteur.LogRecordHandler) – The log record handler function

SetNodeID(nodeid)

Set the NodeID

The NodeID must be set before NodeID is called. If an attempt to set the NodeID after NodeID has been called, an InvalidOperationException will be thrown.

The NodeID must not be all zeros.

Parameters:: nodeid (RobotRaconteur.NodeID) – The NodeID

SetNodeName(nodename)

Set the NodeName

The NodeName must be set before calling NodeName If an attempt to set the NodeName after NodeName has been called, an InvalidOperationException will be thrown.

The NodeName must not be empty, and must conform to the following regex:

^[a-zA-Z][a-zA-Z0-9_.-]*$

Parameters:: nodename (str) – The NodeName

Shutdown()

Shuts down the node. Called automatically by ClientNodeSetup and ServerNodeSetup

Shutdown must be called before program exit to avoid segfaults and other undefined behavior. The singleton node is automatically shut down in Python. The use of ClientNodeSetup and ServerNodeSetup is recommended to automate the node lifecycle. Calling this function does the following: 1. Closes all services and releases all service objects 2. Closes all client connections 3. Shuts down discovery 4. Shuts down all transports 5. Notifies all shutdown listeners 6. Releases all periodic cleanup task listeners 7. Shuts down and releases the thread pool

Sleep(duration)

Sleeps for a specified duration

Normally will sleep based on the system clock, but in certain circumstances will use simulation time

Parameters:: duration (float) – Duration to sleep in seconds

SubscribeService(url, username=None, credentials=None)

Subscribe to a service using one or more URL. Used to create robust connections to services

Creates a ServiceSubscription assigned to a service with one or more candidate connection URLs. The subscription will attempt to maintain a peristent connection, reconnecting if the connection is lost.

Parameters:

url (Union[str,List[str]]) – One or more candidate connection urls
username (str) – An optional username for authentication
credentials (Dict[str,Any]) – Optional credentials for authentication

Returns:

The subscription object

Return type:

RobotRaconteur.ServiceSubscription

SubscribeServiceByType(service_types, filter_=None)

Subscribe to listen for available services and automatically connect

A ServiceSubscription will track the availability of service types and create connections when available.

Parameters:

service_types (List[str]) – A list of service types to listen for, ie “com.robotraconteur.robotics.robot.Robot”
filter (RobotRaconteur.ServiceSubscriptionFilter) – A filter to select individual services based on specified criteria

Returns:

The active subscription

Return type:

ServiceSubscription

SubscribeServiceInfo2(service_types, filter_=None)

Subscribe to listen for available services information

A ServiceInfo2Subscription will track the availability of service types and inform when services become available or are lost. If connections to available services are also required, ServiceSubscription should be used.

Parameters:

service_types (List[str]) – A list of service types to listen for, ie “com.robotraconteur.robotics.robot.Robot”
filter (RobotRaconteur.ServiceSubscriptionFilter) – A filter to select individual services based on specified criteria

Returns:

The active subscription

Return type:

ServiceInfo2Subscription

property ThreadPoolCount: (int) The size of the native thread pool. May be configured dynamically.

property TransportInactivityTimeout

(float) The timeout for transport activity in seconds

Sets a timeout for transport inactivity. If no message is sent or received on the transport for the specified time, the transport is closed. Default timeout is 10 minutes.

TryGetDetectedNodeCacheInfo(nodeid)

Try get cached node discovery information

Same as GetDetectedNodeCacheInfo, but returns bool for success or failure instead of throwing an exception

UnregisterServiceType(type)

Unregister a previously registered service type

This function is not recommended as the results can be unpredictable

Parameters:: type (str) – The service type to unregister

UpdateDetectedNodes(schemes)

Update the detected nodes cache

The node keeps a cache of detected nodes, but this may become stale if nodes are rapidly added and removed from the network. Call this function to update the detected nodes.

Parameters:: schemes (List[str]) – A list of transport schemes, ie “rr+tcp”, “rr+local”, etc. to update.