Running and Tuning Scripts

Scripts are static motions for the robot. By static, we mean they are preconfigured motions that won't change at runtime. They specify what joint angles to move to and how long the robot should take to go to those joint angles. For example, standing up is a small script telling the robot to move its joints to the stand position over one second. There can be many of these position specifications in a row to make the robot do more complex movements like getting up or kicking.

Scripts are run using the script utility and the Director system. The script utility will convert a specified script yaml file into a Sequence Task message. It takes each joint position and time from the .yaml file and adds these frames to the Sequence of servo targets. The Sequence Provider will request a Director Task for each Group in its Sequence, and will only progress to the next Group when the previous has completed.

More information on the script system, Script Runner and Script Tuner is in the Background section below.

Script Runner

The scriptrunner command will run a script. It is used as follows:

Copy
./scriptrunner <script_name>

Where <script_name> is the name of the script you want to run, such as Stand.yaml. All scripts can be found in the NUbots repository under /shared/utility/skill/scripts.

The script you are running needs to be on the robot in the /scripts/ folder. These scripts can be robot specific. For example, you could have a stand script specifically for the NUgus 1 robot stored in /scripts/nugus1/Stand.yaml. When you run ./scriptrunner Stand.yaml on NUgus 1, the ScriptEngine will first look for the robot-specific Stand.yaml in the /scripts/nugus1/ folder. If found, it will execute it. If not, it will look for a platform-specific Stand.yaml in the /scripts/nugus/ folder, which it will execute if found. Otherwise, it will look for a more general Stand.yaml in the /scripts/ folder.

More on the script system can be found on the Configuration and Script System page.

Script Tuner

Script tuner is a tool that can be used to create and modify scripts. To use script tuner, run:

Copy
./scripttuner <script_path>

<script_path> is the path to the script you want to tune, such as scripts/nugus/Stand.yaml. The path can be to an existing script, if you want to edit it, or to a script that does not exist yet if you want to create a new script.

Running a command like the above will open the following interface, which will enable you to tune the script:

Copy
-----------------------------------Script Tuner-----------------------------------

Script: scripts/nugus2/walk.yaml
Frames: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
Duration:  3000
-


U Head Pan              Angle:  -.--- Gain: ---.-
U Head Tilt             Angle:  -.--- Gain: ---.-
L Right Shoulder Pitch  Angle: +1.963 Gain:  20.0
L Left Shoulder Pitch   Angle: +1.963 Gain:  20.0
L Right Shoulder Roll   Angle: -0.124 Gain:  20.0
L Left Shoulder Roll    Angle: +0.124 Gain:  20.0
L Right Elbow           Angle: -2.443 Gain:  25.0
L Left Elbow            Angle: -2.443 Gain:  25.0
L Right Hip Yaw         Angle: +0.030 Gain:  30.0
L Left Hip Yaw          Angle: +0.030 Gain:  30.0
L Right Hip Roll        Angle: -0.063 Gain:  30.0
L Left Hip Roll         Angle: +0.063 Gain:  30.0
L Right Hip Pitch       Angle: -0.204 Gain:  30.0
L Left Hip Pitch        Angle: -0.204 Gain:  30.0
L Right Knee            Angle: +0.257 Gain:  30.0
L Left Knee             Angle: +0.257 Gain:  30.0
L Right Ankle Pitch     Angle: -0.239 Gain:  30.0
L Left Ankle Pitch      Angle: -0.239 Gain:  30.0
L Right Ankle Roll      Angle: +0.060 Gain:  30.0
L Left Ankle Roll       Angle: -0.067 Gain:  30.0

Commands
, Left a frame  N New Frame        Lock/Unlock   J Jump to Frame P play
. Right a frame I Delete a Frame T Edit Duration G Change Gains  S Save

Type :help for a full list of commands
----------------------------------------------------------------------------------

The first line shows the name and path of the script you are creating or editing.

The second line specifies the number of frames and the current frame, which is highlighted. Each frame specifies different joint (i.e. servo) positions, and when these frames are combined they result in a motion.

The next line is the duration. This determines how long the robot will take to move to the servo positions you have specified. This is measured in milliseconds.

The next section is a table that shows the angle and gain for each servo for that frame.

The bottom of the interface shows what commands are available. It does not show all the commands. All commands can be viewed by typing :help and pressing Enter. Note that the letters should be pressed in UPPERCASE.

List of Scripts

Modifying and Adding Scripts

When installing NUbots code onto a robot for tuning scripts, ensure you are using the correct flag for installing configuration files, depending on whether you want to overwrite existing scripts on the robot, or not. Ensure that you have enabled the scripttuner and scriptrunner binaries by turning scripttuner.role and scriptrunner.role ON in ./b configure -i, before building and installing.

Use script tuner as detailed above to make or edit your script. It is a good idea to have one person using script tuner and another person holding the robot and moving the joints to new positions. Wait a few seconds after saving before you close the script, to allow it time to finish saving.

When you have finished making or editing your script, copy it from the robot to your computer using

Copy
scp nubots@<address>:<path_to_script> <path_on_your_computer>

or

Copy
./b retrieve <address> scripts # and watch the magic happen as it copies the script straight back to the codebase

<address> is the address of the robot, such as 10.1.1.1 for NUgus 1. <path_to_script> is the path to the script. <path_on_your_computer> is the path you want to copy the script to on your computer. Run this command on your computer.

After you copy the script to your computer, you should commit it to a new branch and make a pull request to merge it into the main branch on GitHub; unless the changes are not suitable to keep, in which case you can discard them. For information on Git and GitHub visit the Git guide.

Background

The Script System

Scripts are static motions for the robot. They specify what joint angles to move to and how long the robot should take to get to those joint angles. For example, standing up is a script telling the robot to move its joints to the stand position over one second. There can be many of these position specifications in sequence to make the robot do short movements that may be hard to dynamically implement, such as getting up.

Execution

To execute a script, we emit a Director Task message with the appropriate servo Sequence containing the script information. This script information comes from the load_script function in the script utility.

The load_script function takes a YAML file name (eg Stand.yaml), finds and reads the file and creates a servo Sequence representing the script. The Sequence is returned and emitted as a Director Task. The Director Task is then executed by the Director system.

Copy
emit<Task>(load_script<BodySequence>("Stand.yaml"));

Scripts can be given a start time. If a script has a start time, it will not start execution until that time. The following would execute the Stand script in five seconds.

Copy
emit<Task>(load_script<BodySequence>("Stand.yaml", NUClear::clock::now() + std::chrono::seconds(5)));

Script files

The script files are YAML files specifying a duration and list of servo targets, in a format like the following:

Copy
- duration: 1000
  targets:
    - id: HEAD_YAW
      position: 0
      gain: 10
      torque: 100
    - id: HEAD_PITCH
      position: 0.5
      gain: 10
      torque: 100
    - id: R_HIP_YAW
      position: -0.03
      gain: 5
      torque: 100

The fields are described in the table below.

Script files can be found in the ScriptEngine module. Scripts can be specific to a robot. More on scripts can be found on the Configuration and Script System page.

Script Runner

ScriptRunner is a purpose-level module. It takes the name of one or more script files as arguments and attempts to run the scripts. It does not take file paths, only the file name/s of the script/s to execute.

When ScriptRunner is executed, it stores the script file names passed to it as a vector of strings. When the green button on the robot is pushed, the scripts are executed in order of appearance, one after the other. ScriptRunner also provides an option to set a delay before the execution of the first script, as well as a delay between the execution of each script.

An example of using ScriptRunner to run a script called Stand.yaml is:

Copy
./scriptrunner Stand.yaml

Script Tuner

ScriptTuner is a purpose-level module. Using a command-line argument, it can either create a new script or open an existing script for editing. It uses curses to create a user interface in the terminal. Through this user interface, YAML files are created or edited that specify a script that can then be used by other modules.

A script consists of frames (also called targets) which specify the position of one or more servos at a given time. The ScriptTuner interface allows for stepping through and modifying those frames. When a frame is selected in ScriptTuner, a ServoCommand for that frame will be emitted to the robot. By stepping through multiple frames, the entire script can be played back on the robot, allowing the user to preview changes to the script.

ScriptTuner also allows for "locking" and "unlocking" servos on the robot. When a servo is "locked", its position can only be changed in ScriptTuner. When it is "unlocked", the servo can be moved physically on the robot, which will update the position value in the script. Locking a servo involves emitting a ServoCommand for the current position of the servo. Unlocking the servo involves emitting a ServoCommand with zero torque and gain.

To learn how to use ScriptTuner, see Script Tuner above.