SoftBank Robotics documentation What's new in NAOqi 2.8?

ALExpressionWatcher

NAOqi Core - Overview | API | ExpressionObject API


What it does

ALExpressionWatcher module allows you to be notified or query the validity of a condition expression.

This module is useful when you want to create an higher ordered event based on a combination of others events.

Especially, with various time-based operators (~, #, @, bang(), etc...), ALExpressionWatcher lets you create complex events combinations without needing to implement complex asynchronous time-based code.

How it works

  • A condition expression mixes several ALMemory events and/or ALValues using Conditions expression language.
  • Adding a condition expression into ALExpressionWatcher, provides a unique ExpressionObject embedding methods and a also a qi::Signal (see C++ qi API Reference or Python qi API reference).
  • This ExpressionObject should be kept alive as a variable otherwise the expression is not watched anymore.
  • This signal is triggered with the condition expression result value when the expression is valid relative to the selected report mode.
  • ALExpressionWatcher is usable with 3 different report modes:

    Report Modes Emit ExpressionObject signal...
    REPORT_CHANGE Any time the Value of the condition expression changes.
    REPORT_EDGE Only when the Boolean casted value of the condition expression changes.
    REPORT_EDGE_TRUE Only when the Boolean casted value of the condition expression goes from False to True.

Getting started

Step Action

Create a condition expression:

Mix several ALMemory events and/or ALValues using Conditions expression language.

Add the condition expression using ALExpressionWatcher::add.

Result:

An ExpressionObject object, with an embedded qi::Signal, returning the condition expression value, triggered according to the chosen report mode.

Example

Suppose you want to be notified if the left bumper was pressed for 5 seconds and then released. With ALExpressionWatcher you can do something like:

sample_alexpressionwatcher.py

#! /usr/bin/env python
# -*- encoding: UTF-8 -*-

"""
Example: Use the ALExpressionWatcher Module

Use the parameter --qi-url=tcp://10.0.0.2:9559 on the command line to connect
to your robot, replacing 10.0.0.2 with your robot's IP address.
"""

import qi
import sys

def onExpressionReport(expression_value):
    print "Got ALExpressionWatcher signal with value: ", expression_value
    # you can check the expression value, though report_mode=2 gauanteed it is true
    if expression_value:
        print "You held the left bumber for at least 5 seconds, then let go!"

if __name__ == "__main__":
    # Initialize qi framework by creating a local app and connecting to robot
    app = qi.Application(sys.argv)
    app.start()

    # Get a reference to the Expression Watcher service
    expression_svc = app.session.service("ALExpressionWatcher")

    # Setup the expression
    report_mode = 2  # see API doc for behavior of different report modes
    # The left bumper is not currently pressed, but 0.1 seconds ago, it was
    # pressed continuously for at least 5 seconds.
    expression_condition = "!'LeftBumperPressed' && ('LeftBumperPressed' ~ 5 @ 0.1)"

    # Add the expression, and get back an object representing it.
    # When this object goes out of memory scope, the expression is deleted.
    expression_obj = expression_svc.add(expression_condition, report_mode)
    # Connect expression object signal to a callback, which is called based on report_mode
    # To stop listening to this callback, you can call expression_obj.signal.disconnect(signal_id)
    signal_id = expression_obj.signal.connect(onExpressionReport)

    app.run() # Will block until the app connection is destroyed, or ctrl+c