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.
The Script Engine executes script files by performing the robot motions that they describe. It takes each joint position and time from the .yaml file and sends the information to the servos, causing the robot to move.
Information on Script Engine 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 /module/motion/ScriptEngine/data/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.yamlFrames: 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 28Duration: 3000-
U Head Pan Angle: -.--- Gain: ---.-U Head Tilt Angle: -.--- Gain: ---.-L Right Shoulder Pitch Angle: +1.963 Gain: 20.0L Left Shoulder Pitch Angle: +1.963 Gain: 20.0L Right Shoulder Roll Angle: -0.124 Gain: 20.0L Left Shoulder Roll Angle: +0.124 Gain: 20.0L Right Elbow Angle: -2.443 Gain: 25.0L Left Elbow Angle: -2.443 Gain: 25.0L Right Hip Yaw Angle: +0.030 Gain: 30.0L Left Hip Yaw Angle: +0.030 Gain: 30.0L Right Hip Roll Angle: -0.063 Gain: 30.0L Left Hip Roll Angle: +0.063 Gain: 30.0L Right Hip Pitch Angle: -0.204 Gain: 30.0L Left Hip Pitch Angle: -0.204 Gain: 30.0L Right Knee Angle: +0.257 Gain: 30.0L Left Knee Angle: +0.257 Gain: 30.0L Right Ankle Pitch Angle: -0.239 Gain: 30.0L Left Ankle Pitch Angle: -0.239 Gain: 30.0L Right Ankle Roll Angle: +0.060 Gain: 30.0L 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.
| Command | Description |
|---|---|
| , | 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. |
| N | Creates 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. |
| I | Deletes the currently selected frame. The frame after the deleted frame will be selected, if there's one. Otherwise the one before will be selected. |
| space | Toggles 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. |
| T | Edits the duration that the current frame plays for, in milliseconds. After pressing this key, type the duration and press Enter to submit. |
| J | Jumps to a specified frame. After pressing this key, type the frame number you want to jump to and then press Enter. |
| G | Opens 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. |
| P | Plays the script from the first frame to the last frame. |
| S | Saves the new script or saves the edited script. |
| A | Saves the script with a particular name (equivalent to "save as"). After pressing this key, type the name of the script and press Enter. |
| R | Manually refreshes view. Useful if for some reason the view gets stuck. |
| M | Mirrors the script in the sagittal plane. |
| X | Exits the help view or exits the gain editing interface. |
| CTRL+C | Quits script tuner. |
| :help | Lists all commands that can be used in script tuner. |
List of Scripts
| Script Name | Description |
|---|---|
KickLeft.yaml | The robot kicks with its left foot. |
KickRight.yaml | The robot kicks with its right foot. |
NodYes.yaml | The robot nods its head. |
Relax.yaml | The robot relaxes all of its joints. Be prepared to hold it if it's standing, as it will fall over. |
RelaxHead.yaml | The robot relaxes its head joints. |
RollOverFront.yaml | The robot rolls from its back onto its front. |
Stand.yaml | The robot moves into a standing position. |
StandUpBack.yaml | The robot gets up from its back and moves into a standing position. |
StandUpFront.yaml | The robot gets up from its front and moves into a standing position. |
Zombie.yaml | The 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 visit the Git guide.
