This page provides a detailed overview about the priority node.
Contents
Node Description
Priority Node
By default, a Priority Node runs its children in order, until one returns success, at which point the priority node will stop running and return success to it's parent. This means that none of the other child branches of the priority will be run on that loop. If all of the children have been given a chance to run and none have succeeded, the node will return failure to it's parent.
Common Application
Suppose you have three testers and you want to service each tester when it is ready as indicated by a signal sent by the tester. This is easily handled by an instance of a Priority Node with 3 children, where each child is an instance of a Condition Node each testing the state of a signal associated with a different tester. Typically, the Priority Node will be a child of a Loop Node. The effect will be that each tester will be tested to see if it is ready to be serviced and if so, it will be serviced. If it isn’t ready to be serviced, it will be skipped until the next time through the loop.
Node Type
Composite - has 0 or more children, and is typically used to control the logical flow of execution of the tree.
Node Inspector
- ID
Not editable
- Name
Auto generated and user editable
- track cycle time
Determines the cycle time of how long it takes to execute the branch; the time it takes to complete all children contained within the Priority node. When turned on, it will create a variable for the specific Priority Node in Shared Data.
- Balance priorities
By default, each time an instance of a priority node starts running, it starts with its first child. If the first child always succeeds, the other children would never have a chance to run. In the tester example above, this might mean that one of the testers would never get serviced. If balance priorities is set to true, then the Priority Node keeps track of the last child that succeeded and the next time it starts running it starts with the child after the last child that succeeded (it wraps around to the first child if the last child that succeeded is also its last child).
- Comments
User editable - add comments about this node.
Note
An important behavior of the Priority Node occurs when none of the children return success because the Priority Node will return failure in that case, and this will propagate up the tree. If the parent of the Priority Node is an instance of a Loop Node, you typically will want to be sure that that its ‘stop on failure’ property is set to false (the default for Loop Nodes).
Benefits
The Priority node is similar to a Sequence node, but can be used in situations where you want the robot to do only one of several options. It is especially useful when the balance priorities is enabled which means that each of the options is given equal opportunity to run.
Example
The Priority Node evaluates its children in order until one succeeds, at which point the Priority Node ends. In the example above, the first Do-If node returns success if the condition associated with the Do-If node is true and failure if the condition is false. If the Do-If fails, the next child of the Priority Node will be given a chance to run if its condition is true.
By contrast, a Loop-If node always returns success, regardless of the value of its condition. While this is a subtle distinction, there may be unexpected results if a Loop-If is used as a direct child of a Priority Node. Since a Loop-If node always returns success, the Priority Node will always end after the Loop-If node, even if the condition associated with the Loop-If node is false. This means that any child of a Priority Node after a Loop-If node will never run.
One workaround is to make the Loop-If a child of a Do-If with an identical condition as the Loop-If and make the Do-If a child of the Priority Node. If the condition is true, the Do-If and its child Loop-If will run and the Priority Node will end when the Loop-If is finished. If the condition is false, the Do-If will return failure and the Priority Node will go on to the next child. This is typically the desired behavior.
