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.FailedToListRappsError

Bases: exceptions.Exception

Failed to list rapps.

exception rocon_interactions.exceptions.FailedToStartRappError

Bases: exceptions.Exception

Failed to start rapp.

exception rocon_interactions.exceptions.FailedToStopRappError

Bases: exceptions.Exception

Failed to stop rapp.

exception rocon_interactions.exceptions.InvalidInteraction

Bases: exceptions.Exception

Whenever an interaction has been specified incorrectly.

exception rocon_interactions.exceptions.MalformedInteractionsYaml

Bases: exceptions.Exception

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

exception rocon_interactions.exceptions.RappNotRunningError

Bases: exceptions.Exception

Rapp isn’t running.

exception rocon_interactions.exceptions.YamlResourceNotFoundException

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)

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)

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 name-group-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__()

Format the interaction into a human-readable string.

command

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

compatibility

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

group

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

hash

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

is_paired_type()

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

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

msg

Underlying data structure (rocon_interaction_msgs.Interaction)

name

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

namespace

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

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)

Bases: object

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

Variables:

• interactions (rocon_interactions.interactions.Interaction[]) – list of objects that form the elements of the table
• filter_pairing_interactions (bool) – flag for indicating whether pairing interactions should be filtered when loading.

__init__(filter_pairing_interactions=False)

Constructs an empty interactions table.

Parameters:filter_pairing_interactions (bool) – do not load any paired interactions

__str__()

Convenient string representation of the table.

__weakref__

list of weak references to the object (if defined)

filter(groups=None, compatibility_uri='rocon:/')

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

Parameters:

• groups (str []) – a list of groups to filter against, use all groups 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.

find(interaction_hash)

Find the specified interaction.

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

generate_group_view()

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

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

groups()

List all groups for the currently stored interactions.

Returns:a list of all groups Return type:str[]

load(msgs)

Load some interactions into the 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)

sorted()

Return the interactions list sorted by name.

unload(msgs)

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

Bases: object

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

__init__()

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)

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)

Parse a set of configurations specified in a yaml file found from resource (package/file name pair) and send the command to load/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

Bases: object

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

Currently assumes static configuration, i.e. load everything from yaml at startup.

To upgrade for dynamic configuration, i.e. load from ros api, then you’ll need to touch a bit of the logic herein.

• set interactions service call
• don’t prefilter interactions at startup
• instead prefilter them on get_interactions requests

__weakref__

list of weak references to the object (if defined)

spin()

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(rapp_running_state_changed_callback)

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.

Variables:

• is_running (bool) – flag indicating if there is a monitored rapp running on the rapp manager.
• _running_rapp (dict) – None, or dict representation of the running rapp (result of rapp_msg_to_dict())

__init__(rapp_running_state_changed_callback)

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

__weakref__

list of weak references to the object (if defined)

initialise()

Loops around (indefinitely) until it makes a connection with the rapp manager and retrieves the rapp list.

matches_running_rapp(rapp_name, remappings, parameters)

Compare the running rapp with an interaction’s specification for a paired rapp.

Todo

currently it checks against the rapp name only, expand this to consider remappings and parameters

Parameters:

• rapp_name (str) – ros package resource name for this interaction’s rapp rapp
• remappings (rocon_std_msgs/Remapping[]) – rapp remapping rules for this interaction
• parameters (rocon_std_msgs/KeyValue[]) – rapp parameter rules for this interaction

Returns:

whether the incoming interaction specification matches the running rapp (used for filtering)

:rtype; bool

Raises:rocon_interactions.exceptions.RappNotRunningError if the rapp wasn’t running

start(rapp, remappings, parameters=[])

Start the rapp with the specified remappings.

Parameters:

• rapp (str) – ros package resource name of the rapp to start (e.g. rocon_apps/teleop)
• remappings ([rocon_std_msgs.KeyValue]) – remappings to apply to the rapp when starting.
• parameters – paramters to apply to the rapp when starting.

Raises:FailedToStartRappError

stop()

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

rocon_interactions.rapp_handler.rapp_msg_to_dict(rapp)

Convert rapp message to a dictionary. This is not really necessary and we’d be better off flinging around the actual msg or a wrapper around the msg.

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)

Bases: object

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

status

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

unique_name

Name of the connected remocon.

unregister()

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)

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)

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()

Is a web app or not.

Returns:result of the query Return type:bool

is_web_url()

Is a web url or not.

Returns:result of the query Return type:bool

url

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

rocon_interactions.web_interactions.parse(interaction)

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