robots package

robots.robot module

class robots.robot.GenericRobot(actions=None, supports=0, dummy=False, immediate=False, configure_logging=True)[source]

Bases: object

This class manages functionalities that are shared across every robot ‘backends’ (ROS, Aseba,...)

You are expected to derive your own robot implementation from this class, and it is advised to use instances of GenericRobot within a context manager (ie with MyRobot as robot: ... construct).

Its role comprises of:

  • automatic addition of proxy methods for the robot actions
  • actions execution (spawning threads for actions via self.executor
  • pose management through the robot.poses instance variable
  • event monitoring through the robot.on(...).do(...) interface

GenericRobot defines several important instance variables, documented below.

  • state – the state vector of the robot. By default, a simple dictionary. You can overwrite it with a custom object, but it is expected to provide a dictionary-like interface.
  • poses – an instance of PoseManager.
  • executor – instance of RobotActionExecutor responsible for spawning and starting threads for the robot actions. You should not need to access it directly.

Example of a custom robot:

from robots import GenericRobot

class MyRobot(GenericRobot):

    def __init__(self):
        super(MyRobot, self).__init__()

        # create (and set) one element in the robot's state. Here a bumper.
        # (by default, self.state is a dictionary. You can safely
        # overwrite it with any dict-like object.
        self.state["my_bumper"] = False

        # do whatever other initialization you need for your robot

    # Implement here all the accessors you need to talk to the robot
    # low-level, like:

    def send_goal(self, pose):
        # move your robot using your favorite middleware
        print("Starting to move towards %s" % pose)

    def stop(self):
        # stop your robot using your favorite middleware
        print("Motion stopped")

    def whatever_other_lowlevel_method_you_need(self):

# create actions
def move_forward(robot):

with MyRobot() as robot:

    # Turn on DEBUG logging.
    # Shortcut for logging.getLogger("robots").setLevel(logging.DEBUG)

    # subscribe to events...
    robot.whenever("my_bumper", value = True).do(move_forward)

        while True:
    except KeyboardInterrupt:


A note on debugging

Several methods are there to help with debugging:

  • loglevel(): default to INFO. logging.DEBUG can be useful.
    • silent(): alias for loglevel(logging.WARNING)
    • info(): alias for loglevel(logging.INFO)
    • debug(): alias for loglevel(logging.DEBUG)
  • running(): prints the list of running tasks (with their IDs)
  • actioninfo(): give details on a given action, including the exact line being currently executed
  • actions (list) – a list of packages that contains modules with actions (ie, modules with functions decorated with @action). Proxies to these actions are appended to the instance of GenericRobot upon construction.
  • supports – (default: 0) a mask of middlewares the robot supports. Supported middlewares are listed in For example supports = ROS|POCOLIBS means that both ROS and Pocolibs are supported. This requires the corresponding Python bindings to be available.
  • dummy (boolean) – if True (defults to False), the robot is in ‘dummy’ mode: no actual actions are performed. The exact meaning of ‘dummy’ is left to the subclasses of GenericRobot.
  • immediate (boolean) – if True (defaults to False), actions are executed in the main thread instead of their own separate threads. Useful for some specific debugging scenarios.
  • configure_logging (boolean) – if True (default), configures a default colorized console logging handler.

Print details on a running action (including the current line number).


Sends a ‘cancel’ signal (ie, the ActionCancelled exception is raised) to all running actions.

Note that, if called within a running action, this action is cancelled as well. If this is not what you want, use cancel_all_others() instead.

Actions that are not yet started (eg, actions waiting on a resource availability) are simply removed for the run queue.


Sends a ‘cancel’ signal (ie, the ActionCancelled exception is raised) to all running actions, except for the action that call :meth:`cancel_all_others` (note that its currently running subactions will be cancelled).

Actions that are not yet started (eg, actions waiting on a resource availability) are simply removed for the run queue.

static configure_console_logging()[source]
filtered(name, val)[source]

Helper to easily filter values (uses an accumulator to average a given ‘name’ quantity)


Print the list of running actions.

static sleep(duration)[source]

Active sleep. Must used by actions to make sure they can be quickly cancelled.

wait(var, **kwargs)[source]

Alias to wait on a given condition. Cf for details on the acceptable conditions.


Blocks until the robot state has been updated.

This is highly dependent on the low-level mechanisms of your robot, and should almost certainly be overriden in your implementation of a GenericRobot subclass.

The default implementation simply waits ACTIVE_SLEEP_RESOLUTION seconds.

class robots.robot.State[source]

Bases: dict

robots.introspection module

robots.roslogger module

class robots.roslogger.RXConsoleHandler(topic='/rosout')[source]

Bases: logging.Handler