Running and Tuning Scripts

How to tune and run scripts.
Ysobel Sims GitHub avatar
Updated 18 Oct 2023

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 is on the Motion page. Information on Script Runner and Script Tuner is on the Behaviour page.

Script Runner

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

./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:

./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:

-----------------------------------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.

CommandDescription
,Moves to the frame that is to the left of the currently selected frame. When moving to the frame, the robot's joints will move to the joint positions for that frame.
.Moves to the frame that is right of the currently selected frame. When moving to the frame, the robot's joints will move to the joint positions for that frame.
NCreates a new frame after the currently selected frame. This frame will be a duplicate of the selected frame. It will be added in after the currently selected frame, and the selected frame will not change.
IDeletes the currently selected frame. The frame after the deleted frame will be selected, if there's one. Otherwise the one before will be selected.
spaceToggles locking and unlocking of servos. When a servo is locked, you will not be able to manually move its joint on the robot, and the angle it is at will be stored in the table on the script tuner interface. When it is unlocked, you are able to freely move that joint on the robot to adjust the angle of the joint for that frame. Space bar can be pressed to edit any field that is editable.
TEdits the duration that the current frame plays for, in milliseconds. After pressing this key, type the duration and press Enter to submit.
JJumps to a specified frame. After pressing this key, type the frame number you want to jump to and then press Enter.
GOpens the interface for editing the gain of the entire script or frame. Provides a quick way to change all servo gains, only the upper body gains (arms and head), or only lower body gains (legs) at the same time. The change can be applied to the entire script or to a particular frame. Press X to exit the edit gain interface when done.
PPlays the script from the first frame to the last frame.
SSaves the new script or saves the edited script.
ASaves the script with a particular name (equivalent to "save as"). After pressing this key, type the name of the script and press Enter.
RManually refreshes view. Useful if for some reason the view gets stuck.
MMirrors the script in the sagittal plane.
XExits the help view or exits the gain editing interface.
CTRL+CQuits script tuner.
:helpLists all commands that can be used in script tuner.

List of Scripts

Script NameDescription
DiveLeft.yamlThe robot stretches its arm out to the left and moves its left leg so that it will dive to the left.
DiveRight.yamlThe robot stretches its arm out to the right and moves its right leg so that it will dive to the right.
KickLeft.yamlThe robot kicks with its left foot.
KickRight.yamlThe robot kicks with its right foot.
NodYes.yamlThe robot nods its head.
Relax.yamlThe robot relaxes all of its joints. Be prepared to hold it if it's standing, as it will fall over.
RollOverFront.yamlThe robot rolls from its back onto its front.
Stand.yamlThe robot moves into a standing position.
StandUpBack.yamlThe robot gets up from its back and moves into a standing position.
StandUpFront.yamlThe robot gets up from its front and moves into a standing position.
Zombie.yamlThe robot moves into a standing zombie position, with arms straight out.

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

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

<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.

Main Codebase
NUClear
NUbots acknowledges the traditional custodians of the lands within our footprint areas: Awabakal, Darkinjung, Biripai, Worimi, Wonnarua, and Eora Nations. We acknowledge that our laboratory is situated on unceded Pambalong land. We pay respect to the wisdom of our Elders past and present.
Copyright © 2024 NUbots - CC-BY-4.0
Deploys by Netlify