# 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

Glossary Site map Index Support Contact Legal Notices