Module API

rocon_interactions

This is the top-level namespace of the rocon_interactions ROS package. It provides python utilities for working with the console.

rocon_interactions.exceptions

This module defines exceptions raised by the rocon_interactions package. These exception names are all included in the main rocon_interactions namespace. To catch one, import it this way:

from rocon_interactions import InvalidInteraction

exception rocon_interactions.exceptions.FailedToStartRappError[source]

Bases: exceptions.Exception

Failed to start rapp.

exception rocon_interactions.exceptions.FailedToStopRappError[source]

Bases: exceptions.Exception

Failed to stop rapp.

exception rocon_interactions.exceptions.InvalidInteraction[source]

Bases: exceptions.Exception

Whenever an interaction has been specified incorrectly.

exception rocon_interactions.exceptions.MalformedInteractionsYaml[source]

Bases: exceptions.Exception

Whenever malformed yaml is used in loading a set of interactions.

exception rocon_interactions.exceptions.YamlResourceNotFoundException[source]

Bases: exceptions.IOError

The requested yaml resource could not be found.

rocon_interactions.interactions

This module defines a class and methods that represent the core of what an interaction is.


class rocon_interactions.interactions.Interaction(msg)[source]

Bases: object

This class defines an interaction. It does so by wrapping the base rocon_interaction_msgs.Interaction msg structure with a few convenient variables and methods.

__init__(msg)[source]

Validate the incoming fields supplied by the interaction msg and populate remaining fields with proper defaults (e.g. calculate the unique hash for this interaction). The hash is calculated based on the incoming display_name-role-namespace triple.

Parameters:msg (rocon_interaction_msgs.Interaction) – underlying data structure with fields minimally filled via load_msgs_from_yaml_resource().
Raises:InvalidInteraction if the interaction variables were improperly defined (e.g. max = -1)
__str__()[source]

Format the interaction into a human-readable string.

compatibility[source]

A rocon_uri string that indicates what platforms it may run on [int].

display_name[source]

A human friendly name that also uniquely helps uniquely identify this interaction (you can have more than one configured name instance) [int].

hash[source]

A crc32 unique identifier key for this interaction, see also generate_hash() [int32].

is_paired_type()[source]

Classify whether this interaction is to be paired with a rapp or not.

Returns:whether it is a pairing interaction or not
Return type:bool
max[source]

Maximum number of instantiations that is permitted (e.g. teleop should only allow 1) [int].

msg

Underlying data structure (rocon_interaction_msgs.Interaction)

name[source]

Executable name for this interaction, can be a roslaunch, rosrunnable, global executable, web url or web app [int].

namespace[source]

Default namespace under which ros services and topics should be embedded for this interaction [int].

role[source]

The group under which this interaction should be embedded [int].

rocon_interactions.interactions.generate_hash(display_name, role, namespace)[source]

Compute a unique hash for this interaction corresponding to the display_name-role-namespace triple. We use zlib’s crc32 here instead of unique_id because of it’s brevity which is important when trying to id an interaction by its hash from an nfc tag.

Might be worth checking http://docs.python.org/2.7/library/zlib.html#zlib.crc32 if this doesn’t produce the same hash on all platforms.

Parameters:
  • display_name (str) – the display name of the interaction
  • role (str) – the role the interaction is embedded in
  • namespace (str) – the namespace in which to embed this interaction
Returns:

the hash

Return type:

int32

rocon_interactions.interactions.load_msgs_from_yaml_file(file_path)[source]

Load interactions from a yaml resource.

Parameters:file_path (str) – file path of a yaml formatted interactions file (ext=.interactions).
Returns:a list of ros msg interaction specifications
Return type:rocon_interaction_msgs.Interaction []
Raises:YamlResourceNotFoundException if yaml is not found.
Raises:MalformedInteractionsYaml if yaml is malformed.
rocon_interactions.interactions.load_msgs_from_yaml_resource(resource_name)[source]

Load interactions from a yaml resource.

Parameters:resource_name (str) – pkg/filename of a yaml formatted interactions file (ext=.interactions).
Returns:a list of ros msg interaction specifications
Return type:rocon_interaction_msgs.Interaction []
Raises:YamlResourceNotFoundException if yaml is not found.
Raises:MalformedInteractionsYaml if yaml is malformed.

rocon_interactions.interactions_table

This module provides a class that acts as a database (dictionary style) of some set of interactions.


class rocon_interactions.interactions_table.InteractionsTable(filter_pairing_interactions=False)[source]

Bases: object

The runtime populated interactions table along with methods to manipulate it.

__init__(filter_pairing_interactions=False)[source]

Constructs an empty interactions table.

Parameters:filter_pairing_interactions (bool) – do not load any paired interactions
__str__()[source]

Convenient string representation of the table.

filter(roles=None, compatibility_uri='rocon:/')[source]

Filter the interactions in the table according to role and/or compatibility uri.

Parameters:
  • roles (str []) – a list of roles to filter against, use all roles if None
  • compatibility_uri (str) – compatibility rocon_uri, eliminates interactions that don’t match this uri.
Returns interactions:
 

subset of all interactions that survived the filter

Return type:

Interaction []

Raises:

rocon_uri.RoconURIValueError if provided compatibility_uri is invalid.

filter_pairing_interactions

Flag for indicating whether pairing interactions should be filtered when loading.

find(interaction_hash)[source]

Find the specified interaction.

Parameters:interaction_hash (str) – in crc32 format
Returns:interaction if found, None otherwise.
Return type:Interaction
generate_role_view()[source]

Creates a temporary copy of the interactions and sorts them into a dictionary view classified by role.

Returns:A role based view of the interactions
Return type:dict { role(str) : :class:`.interactions.Interaction`[] }
interactions

List of Interaction objects that will form the elements of the table.

load(msgs)[source]

Load some interactions into the interaction table. This involves some initialisation and validation steps.

Parameters:msgs (rocon_interaction_msgs.Interaction []) – a list of interaction specifications to populate the table with.
Returns:list of all additions and any that were flagged as invalid
Return type:(Interaction [], rocon_interaction_msgs.Interaction []) : (new, invalid)
roles()[source]

List all roles for the currently stored interactions.

Returns:a list of all roles
Return type:str[]
unload(msgs)[source]

Removed the specified interactions interactions table. This list is typically the same list as the user might initially send - no hashes yet generated.

Parameters:msgs (rocon_interaction_msgs.Interaction []) – a list of interactions
Returns:a list of removed interactions
Return type:rocon_interaction_msgs.Interaction []

rocon_interactions.loader

This module provides a class that lets you conveniently load interactions from outside the interactions manager node post startup (i.e. not using params). This class is the skeleton of the load_interactions script which can be used in a roslaunch file in the following way:

<!-- instead of params, use the external loader and configure groups with default namespaces -->
<node pkg="rocon_interactions" type="load_interactions" name="load_interactions" args="-n '/web' rocon_interactions web">
  <remap from="load_interactions/set_interactions" to="interactions/set_interactions"/>
</node>

class rocon_interactions.loader.InteractionsLoader[source]

Bases: object

This class is responsible for loading the role manager with the roles and app specifications provided in the service definitions.

__init__()[source]

Don’t do any loading here, just set up infrastructure and overrides from the solution.

Raises:rocon_python_comms.NotFoundException, rospy.exceptions.ROSException, rospy.exceptions.ROSInterruptException
load_from_file(interactions_yaml_filepath, namespace='/', load=True)[source]

Parse a set of configurations specified in a yaml file found from file path and send the command toload/unload these on the interactions manager. For convenience, it also allows the setting of a namespace for the whole group which will only get applied if an interaction has no setting in the yaml.

Parameters:
  • interactions_yaml_filepath (str) – yaml absolute file path for role-app parameterisation
  • namespace (str) – namespace to push connections down into (e.g. /interactions)
  • load (bool) – either load or unload the interaction information.
Raises:

YamlResourceNotFoundException, MalformedInteractionsYaml

load_from_resource(interactions_yaml_resource, namespace='/', load=True)[source]

Parse a set of configurations specified in a yaml file found from resource (package/file name pair) and send the command toload/unload these on the interactions manager. For convenience, it also allows the setting of a namespace for the whole group which will only get applied if an interaction has no setting in the yaml.

Parameters:
  • interactions_yaml_resource (str) – yaml resource name for role-app parameterisation
  • namespace (str) – namespace to push connections down into (e.g. /interactions)
  • load (bool) – either load or unload the interaction information.
Raises:

YamlResourceNotFoundException, MalformedInteractionsYaml

rocon_interactions.manager

This module defines the class used to execute a ros node responsible for managing the ros api that manipulates interactions. —-

class rocon_interactions.manager.InteractionsManager[source]

Bases: object

Manages connectivity information provided by services and provides this for human interactive (aka remocon) connections.

is_pairing()[source]

Whether this interactions manager is currently managing a pairing interaction or not.

Returns:whether there is an active pairing or not
Rtype bool:
spin()[source]

Loop around parsing the status of 1) connected remocons and 2) an internal rapp manager if the node was configured for pairing. Reacts appropriately if it identifies important status changes (e.g. a rapp went down while this node is currently managing its associated paired interaction).

rocon_interactions.rapp_handler

This module provides a class that can be used by other nodes to introspect and start/stop rapps on a rapp manager running on the same ros master.

class rocon_interactions.rapp_handler.RappHandler(status_callback)[source]

Bases: object

Initialises from a conductor message detailing information about a concert client. Once established, this instance can be used as a convenience to start and stop rapps on the concert client.

__init__(status_callback)[source]

Initialise the class with the relevant data required to start and stop rapps on this concert client.

Parameters:function (status_callback) – handles toggling of pairing mode upon appropriate status updates
initialised

Flag indicating that the rapp manager has been found and services/topics connected.

is_running

Flag indicating if there is a monitored rapp running on the rapp manager.

start(rapp, remappings)[source]

Start the rapp with the specified remappings.

Parameters:
  • rapp (str) – name of the rapp to start (e.g. rocon_apps/teleop)
  • remappings (rocon_std_msgs.Remapping []) – remappings to apply to the rapp when starting.
Raises:FailedToStartRappError
start_rapp

Service proxy to the rapp manager’s start_rapp service

status_callback

Callback that handles status updates of the rapp manager appropriately at a higher level (the interactions manager level).

status_subscriber

Subscriber to the rapp manager’s status publisher

stop()[source]

Stop a rapp on this concert client (if one should be running). This doesn’t need a rapp specification since only one rapp can ever be running - it will just stop the currently running rapp.

Raises:FailedToStopRappError
stop_rapp

Service proxy to the rapp manager’s stop_rapp service

rocon_interactions.remocon_monitor

This module defines a class used monitor the status of connected remocons and trigger when certain status updates happen. —-

class rocon_interactions.remocon_monitor.RemoconMonitor(topic_name, remocon_status_update_callback)[source]

Bases: object

Attaches a subscriber to a remocon publisher and monitors the status of the remocon.

name

Name of the connected remocon.

status

Holds the latest status (rocon_interaction_msgs.RemoconStatus) update from the remocon.

unregister()[source]

Unregister the subscriber attached to this remocon’s status topic.

rocon_interactions.web_interactions

Module for parsing web interaction strings provided to the interactions manager.


class rocon_interactions.web_interactions.WebInteraction(interaction_type, interaction_url)[source]

Bases: object

Generic web interaction object that stores the type (web url or app) and the actual url to be used. This is important because the resulting url that will get formed for this interaction will have many extra arguments (name, remappings, parameters) appended to the url here if it is a web app.

WEB_APP = 'web_app'

Prefix used to define web apps (e.g. web_app(https://github.com/...)

WEB_URL = 'web_url'

Prefix used to define web urls (e.g. web_url(http://wiki.ros.org/rocon_interactions)

__init__(interaction_type, interaction_url)[source]

Don’t instantiate this directly, use the parse() method instead.

Parameters:
  • interaction_type (str) – either WEB_APP or WEB_URL.
  • interaction_url (str) – the parsed url
__weakref__

list of weak references to the object (if defined)

is_web_app()[source]

Is a web app or not.

Returns:result of the query
Return type:bool
is_web_url()[source]

Is a web url or not.

Returns:result of the query
Return type:bool
url[source]

The interaction url (e.g. http://wiki.ros.org/rocon_interactions).

rocon_interactions.web_interactions.parse(interaction)[source]

Tries to parse the specified string to see if it is a valid web interaction (web app or web url). If it is, it passes back a web interaction object, or None if it is not valid.

Parameters:str (interaction) – the string to parse.
Returns:the web interaction object if parsed
Return type:WebInteraction or None