Goal

Manipulate the rules in Kuri’s rules engine to enable, modify or disable Kuri behaviors

Overview

Much of Kuri’s behavior is driven by a rules engine. The rules engine takes inputs, called triggers, and information about Kuri’s current state, defined by properties, and decides what task Kuri should do next.

Consider the following rule:

        {
            "trigger": "tap touch",
            "match": ["prop.task == 'choreo_dance'"],
            "task": "stop",
            "priority": 3,
            "description": "Stops Pancake Robot when touched"
        },

This says that when Kuri is tapped on the head, and Kuri is in the choreo_dance state (playing Pancake Robot), she should stop dancing and playing the song.

Anatomy of a rule

• Trigger: Almost all rules have a trigger field. The rule only activates if the trigger matches.
  • A very few rules have no trigger field, they then match any trigger and rely on the rules being evaluated top to bottom.
  • There is a special trigger called tick which fires once a second
• Match commands: This is a list of conditions required to activate the rules. They can query properties or get information about when tasks were last called or triggers last seen.
• Reaction: An animation to play when the rule matches. See creating-animations
• Task: The task to enter when the rule matches.
  • It’s possible to play a reaction without entering a new task but it’s not generally recommended. Use the special task go_idle or long_reaction instead.
  • A Task can be interrupted by another rule, or a Task can transition to idle or sleep when it finishes
• Priority: The priority that the rule is matched at

Task Priority vs Rule Priority:

Each task has a priority. This represents how important the Task is, with lower numbers being more important. Each rule also has a priority. A rule will only execute if the current task’s priority is >= the rule priority. This is an easy way to build a hierarchy of behavior, so that, for instance, being picked up prevents lots of rules from firing.

The priority levels currently in use are:

• 0: used only for picked up and robot reboot/reset
• 1: used for first moment capture, which touch or trying to drive doesn’t interrupt
• 2: used for situations where the user is driving the robot through Kuri Live
• 3: used for normal interactive behavior
• 4: used for lower priority autonomous behavior like dancing, wandering, and being bored

Less commonly used rule fields:

• log_msg: changes the default log message emitted when the rule is matched
  • setting it to “” suppresses logging for rules that match often
• happy_delta, excited_delta: alter the Mood service, which is not currently hooked to any behaviors
• verbose: setting “verbose”: true in a rules entry causes it to print every time it is evaluated and NOT matched, with the reason why. This can be spammy but is useful sometimes in debugging the rule
• task_params: This is used to pass parameters to a Task, see below

Properties

The following is a list of properties. Each property is a function on an object of type Robot.

Triggers

Triggers are sent programatically by calling the trigger method on the Robot object. The signature is:

def trigger(self, trigger, params)

Tasks

Tasks are functions on the Robot object. The signature of a task is:

def a_task(self, trigger, params, reaction)

Trigger is a tuple (trigger_name, trigger_params_dict). Triggers can be sent in by publishing a Command.msg to the /triggers topic. The name parameter becomes the trigger_name and the params key-value pairs become the entries in trigger_params_dict.

Params is a dictionary of task parameters, defined by the task_params field in the rule entry.

Reaction is the name of the reaction to play, see Creating New Animations

The description for all the existing tasks can be found in the rules file itself.

Modifying the Rules File

The rules file lives at /opt/gizmo/share/gizmo/configs/robot.json

For an example project involving modifying the rules file see Making Kuri play with your kitties