Skip to content

Commit

Permalink
Update the pages in the Guides section (#299)
Browse files Browse the repository at this point in the history
Out-of-date information in the guides section have been updated.

### Preview


<https://deploy-preview-299--nubook.netlify.com/guides/main/getting-started>
for the first page then click through.
  • Loading branch information
ysims committed Oct 18, 2023
1 parent 53ae05c commit 559b178
Show file tree
Hide file tree
Showing 28 changed files with 99 additions and 125 deletions.
4 changes: 2 additions & 2 deletions src/book/02-system/02-subsystems/06-behaviour.mdx
Expand Up @@ -102,7 +102,7 @@ To use this module, build the [PS3Walk role](https://github.com/NUbots/NUbots/bl

### Script Runner

[ScriptRunner](https://github.com/NUbots/NUbots/tree/96357855b059cd499021552b3e25a4b158828dc5/module/behaviour/tools/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.
[ScriptRunner](https://github.com/NUbots/NUbots/tree/8bfdde1ac3f51764515908dd514e653f6b38cf04/module/purpose/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.

Expand All @@ -114,7 +114,7 @@ An example of using ScriptRunner to run a script called `Stand.yaml` is:

### Script Tuner

[ScriptTuner](https://github.com/NUbots/NUbots/tree/96357855b059cd499021552b3e25a4b158828dc5/module/behaviour/tools/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](<https://en.wikipedia.org/wiki/Curses_(programming_library)>) 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.
[ScriptTuner](https://github.com/NUbots/NUbots/tree/0a948978ba5806ee532bc1120a76e9e58c4e6533/module/purpose/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](<https://en.wikipedia.org/wiki/Curses_(programming_library)>) 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.

Expand Down
65 changes: 19 additions & 46 deletions src/book/03-guides/01-main-codebase/01-getting-started.mdx
Expand Up @@ -11,13 +11,13 @@ authors:
- Lachlan Court (@LachlanCourt)
---

Throughout this guide we will focus on completing a specific example task. This task will involve setting up the codebase, running the fake/keyboardwalk binary (which uses simulated hardware) and seeing the robot move in NUsight.
Throughout this guide we will focus on completing a specific example task. This task will involve setting up the codebase, running the `fake/keyboardwalk` binary (which uses simulated hardware) and seeing the robot move in NUsight.

## Prerequisites

### Git

For our example, we will need Git to get the codebase. This will happen later in this guide.
For our example, we will need Git to get the codebase later on in this guide.

[Git](https://git-scm.com/) is a [version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) tool. We use it to track changes to the codebase and work together on the same codebase without getting in each other's way.

Expand All @@ -39,52 +39,25 @@ You will need to perform the steps correctly to set up Docker for your operating

<details>

<summary>Ubuntu/Linux Mint</summary>
<summary>Ubuntu</summary>

To install on Ubuntu, use the [official Docker instructions](https://docs.docker.com/engine/install/ubuntu/). These work with Linux Mint, with some adjustments. There are multiple ways to install Docker, as detailed on the website. NUbots recommends the following for installing Docker
To install on Ubuntu, use the [official Docker instructions](https://docs.docker.com/engine/install/ubuntu/). These instructions should work for Ubuntu-like Linux distributions, such as Pop!\_OS. There are multiple ways to install Docker, as detailed on the website. NUbots recommends the following for installing Docker

1. Navigate to the section where you [Install Docker using the Repository](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository). Complete the three steps under the heading 'Set Up the Repository'.
1. Navigate to the section for [installing using the Apt repository](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository). Complete the three steps under this section.

If you are using Linux Mint, please read the info bubble below.

<Alert type='info'>

The third step will not work on Linux Mint for two reasons.

1. You will get a malformed input error. Removing `[arch=amd64]` fixes this.

2. You cannot use the command `$(lsb_release -cs)` on Linux Mint. This command returns the name of the Ubuntu LTS. On Linux Mint, you will need to manually enter the LTS name.

If you are using the latest Linux Mint version, 'Ulyana', you will need to replace the command with `focal`. This refers to the Ubuntu LTS that Linux Mint Ulyana is build off, 'Focal Fossa'.

If you are using an old version of Linux Mint, you can find out what Ubuntu LTS it uses on the [Linux Mint all downloads page](https://www.linuxmint.com/download_all.php). For example, if you are using Linux Mint Tricia, use `bionic`.

If you are using Linux Mint Ulyana - the latest Linux Mint version - then your command for step three will be

```bash
sudo add-apt-repository \
"deb https://download.docker.com/linux/ubuntu \
focal \
stable"
```

</Alert>

2. Complete the three steps under the heading 'Install Docker Engine', which is just below the previous section, 'Set Up the Repository'. After you complete this step, you are finished with the Docker install page.

3. Install python3 and pip.
2. Install python3 and pip.

```bash
sudo apt-get install python3 python3-pip
```

4. Add the current user to the Docker group, so you can run Docker commands without `sudo`.
3. Add the current user to the Docker group, so you can run Docker commands without `sudo`.

```bash
sudo usermod -aG docker "${USER}"
```

5. Reboot to make the group change take effect.
4. Reboot to make the group change take effect.

</details>

Expand Down Expand Up @@ -228,7 +201,7 @@ Run all these commands for our example, and pay special attention to the instruc

To build the code, open a terminal and change into the NUbots code directory. Then do the following:

1. Select the platform (e.g. type of computer) that the built binaries will run on and create the Docker image. You do this by running the command:
1. Select the platform (type of computer) that the built binaries will run on and create the Docker image. You do this by running the command:

```bash
./b target <PLATFORM>
Expand All @@ -237,7 +210,7 @@ To build the code, open a terminal and change into the NUbots code directory. Th
Replace `<PLATFORM>` with your desired platform. The available platforms are:

- `generic` - used to build the code for a "generic" computer. This will enable you to run the built binaries on the computer you're building the code on.
- `nuc7i7bnh` - used to build the code for the platform that the robots run on. This will build binaries that are optimised for the NUgus robots.
- `nuc12wshi7` - used to build the code for the platform that the robots run on. This will build binaries that are optimised for the NUgus robots.

If you are following the example, use `generic`.

Expand All @@ -248,11 +221,11 @@ To build the code, open a terminal and change into the NUbots code directory. Th
./b configure -i
```

Note that you will need to do `configure` without `-i` the very first time you do this. Using `-i` will show a menu that will allow you to choose the roles to build. Enable the roles you want to build and disable the ones you don't by highlighting them using using the <kbd>↑</kbd> and <kbd>↓</kbd> arrow keys and pressing the spacebar to toggle on and off.
Note that you will need to do `configure` without `-i` the very first time you do this. Using `-i` will show a menu that will allow you to choose the roles to build. Enable the roles you want to build and disable the ones you don't by highlighting them using the <kbd>↑</kbd> and <kbd>↓</kbd> arrow keys and pressing the spacebar to toggle on and off.

If you are following the `fake/keyboardwalk` example, you will need to make sure `fake/keyboardwalk` is set to `ON`. Find the list of items that are prefixed with `ROLE_` and set all to `OFF` except for `fake/keyboardwalk`, which should be `ON`. You do not need to change any other build options in this example.
If you are following the `fake/keyboardwalk` example, you will need to make sure `ROLE_fake-keyboardwalk` is set to `ON`. Find the list of items that are prefixed with `ROLE_` and set all to `OFF` except for `fake-keyboardwalk`, which should be `ON`. You do not need to change any other build options in this example.

Press <kbd>c</kbd> to configure. This will show a confirmation menu, press <kbd>e</kbd> to go back to the main menu. Press <kbd>g</kbd> to generate the build list, and then press <kbd>e</kbd> to exit.
Press <kbd>c</kbd> to configure. Once configuration has finished, press <kbd>g</kbd> to generate the build list. Press <kbd>e</kbd> to exit if it has not automatically returned you to the terminal.

3. Build the code by running:

Expand Down Expand Up @@ -300,8 +273,8 @@ To run the code on a robot, you need to make sure the robot is powered on, insta

Where:

- `[options]` corresponds to zero, one, or multiple options as detailed in the [Build System](/system/foundations/build-system#install)
- `<robot>` corresponds to the name of the robot such as `n1` or `nugus1`
- `[options]` corresponds to zero, one, or multiple options as detailed in the [Build System](/system/foundations/build-system#install) page
- `<robot>` corresponds to the name of the robot such as `n1` or `nugus1`, or an IP address

2. Next, open a new terminal and `ssh` into the robot by running:

Expand All @@ -321,7 +294,7 @@ To run the code on a robot, you need to make sure the robot is powered on, insta

In addition to the stand script, the `scriptrunner` role can run other scripts. These can be found in the `scripts` folder. See [Configuration and Script System](/system/foundations/config-script) for details.

4. You can also run other roles that are not `scriptrunner`. For example, to run the `robocup` role enter the command:
You can also run other roles that are not `scriptrunner`. For example, to run the `robocup` role enter the command:

```bash
./robocup
Expand Down Expand Up @@ -397,8 +370,8 @@ By now you will have gone through this page and have everything set up to make t

With the `fake/keyboardwalk` binary running, and with NUsight running and your browser open to [localhost:9090](localhost:9090), do the following

- Select the 'localisation' tab in NUsight.
1. Select the 'localisation' tab in NUsight.

- You will see a stationary robot. To focus on the robot, click inside the window and press <kbd>space</kbd> to change perspective.
2. You will see a stationary robot. To focus on the robot, click inside the window and press <kbd>space</kbd> to change perspective.

- To make the robot walk, go into the terminal that is running `fake/keyboardwalk` and hit <kbd>e</kbd> to enable walking. Use <kbd>w</kbd>, <kbd>a</kbd>, <kbd>s</kbd> and <kbd>d</kbd> to make the robot move. Note that this is a basic simulation that does not use gravity, so the robot will move its limbs but it likely won't move in the world.
3. To make the robot walk, go into the terminal that is running `fake/keyboardwalk` and hit <kbd>e</kbd> to enable walking. Use <kbd>w</kbd>, <kbd>a</kbd>, <kbd>s</kbd> and <kbd>d</kbd> to make the robot move. Note that this is a basic simulation that does not use gravity, so the robot will move its limbs but may not move in the world.
24 changes: 12 additions & 12 deletions src/book/03-guides/01-main-codebase/02-nuclear-tutorial.mdx
Expand Up @@ -27,7 +27,7 @@ Make sure you have

If the last two commands ran successfully, you are ready to go!

### The folder structure
### The Folder Structure

Before getting into it, let's look at what we are working with.

Expand All @@ -45,17 +45,17 @@ Other folders that are important but won't be visited in this tutorial are the f

### Generate the Module

There is a neat tool that you can run that will generate the boilerplate code for a module. Here's the command
The generate tool will create the boilerplate code for a module. Here's the command

```bash
./b module generate TestModule
```

Run it if you haven't already done so. If you look in the `module` folder, you will see a new folder called `TestModule`!
Run it if you haven't already done so. If you look in the `module` folder, you will see a new folder called `TestModule`.

This module wasn't created in a folder, but if you are making a new module in a real scenario you should identify the folder your module best fits in and put it in there.

Ok, so lets see what we have in this folder.
Lets see what we have in this folder.

- **data/config**: Contains a `TestModule.yaml` file, which holds configuration values. Rather than hardcoding values in your implementation, put the values in this file so they can be easily seen and updated. This file is generated with one value, `log_level`. We will look into how this works later.
- **src**: This folder contains the `.hpp` and `.cpp` files for the module. If you look in the `.hpp`, you'll see a TestModule class is declared that extends `NUClear::Reactor`. The `.cpp` file implements the constructor with one lambda statement that reads configuration values.
Expand Down Expand Up @@ -87,7 +87,7 @@ Most of this is copied from other role files. The first three modules are necess

The last module added is our new module, `TestModule`.

This should compile. Let's have a go. First we'll need to turn the role we just made `ON`. Run
This should compile. First we'll need to turn the role we just made `ON`. Run

```bash
./b configure
Expand Down Expand Up @@ -120,7 +120,7 @@ This file will store any of values for the program that might change. It is bad

Open `module/TestModule/src/TestModule.cpp`. There is one `on` statement here, the Configuration `on` statement. The code inside this function will run on startup and whenever the configuration file `TestModule.yaml` is changed.

Inside this statement, after the log_level is set, add the following code
Inside this statement, after the `log_level` is set, add the following code

```cpp
log<NUClear::TRACE>("This is a TRACE log.");
Expand All @@ -131,20 +131,20 @@ log<NUClear::ERROR>("This is a ERROR log.");
log<NUClear::FATAL>("This is a FATAL log.");
```

`log` will print to the terminal. The log level set from the configuration file determines what level logs are printed. The log level is currently on `DEBUG`. Let's compile and run the program again.
`log` will print to the terminal. The log level set from the configuration file determines what level logs are printed. The log level is currently on `INFO`. Let's compile and run the program again.

```cpp
./b build
./b run testprogram
```

You should see all of the logs print except for `TRACE`. This is because all logs with level `DEBUG` and higher will run. Lets change the configuration file without stopping the program! Open a new terminal and run `./b edit config/TestModule.yaml`. This will open the TestModule configuration file in `nano`. Change `DEBUG` to `TRACE`. Save with <kbd>CTRL</kbd> + <kbd>O</kbd> and then <kbd>Enter</kbd>. If you look at the program, you will see the logs print out again, but with `TRACE` included. Go back and change the config file to `WARN`. You will now see the logs print again, but with only `WARN`, `ERROR` and `FATAL`.
You should see all of the logs print except for `TRACE` and `DEBUG`. This is because all logs with level `INFO` and higher will run. Lets change the configuration file without stopping the program! Open a new terminal and run `./b edit config/TestModule.yaml`. This will open the TestModule configuration file in `nano`. Change `INFO` to `TRACE`. Save with <kbd>CTRL</kbd> + <kbd>O</kbd> and then <kbd>Enter</kbd>. If you look at the program, you will see the logs print out again, but with `TRACE` and `DEBUG` included. Go back and change the config file to `WARN`. You will now see the logs print again, but with only `WARN`, `ERROR` and `FATAL`.

The log level system allows you to keep statements for debugging or tuning without the logs spamming the terminal when someone is running the module for other purposes.

Remove all of the log statements. We will be making a 'ping-pong' program that sends an incrementing count between reactions. The increment size will be a configuration value. Let's add that configuration value now.

In `TestModule.yaml` (in your text editor, not in the terminal since this is not persistent), add in the following lines
In `TestModule.yaml` (in your text editor, not with `./b edit` since this is not persistent), add in the following lines

```yaml
# Each time the Ping Pong messages are sent, a count is incremented and the increment is of the following size
Expand Down Expand Up @@ -174,7 +174,7 @@ Save, recompile and check that the program prints the message.
./b run testprogram
```

Make sure you see your `INFO` log and then lets move onto making the messages that we need.
Make sure you see your `INFO` log and then lets move onto making the messages that we need. If you can't see the log in the terminal, make sure that `log_level` in `TestModule.yaml` is set to `INFO`.

### Protobuf Messages

Expand All @@ -196,7 +196,7 @@ message Pong {
}
```

There is an integer in each of these messages. This is the count that will be incremented each time a new `Ping` or `Pong` message is sent. The number it is assigned, `1`, is not the value but its position in the Protobuf message. Save this file and head back over to `TestModule.cpp`.
There is an unsigned 32-bit integer in each of these messages. This is the count that will be incremented each time a new `Ping` or `Pong` message is sent. The number it is assigned, `1`, is not the value but its position in the Protobuf message. Save this file and head back over to `TestModule.cpp`.

Up at the top of the file, include the protobuf message we just created. Note that these messages are transcompile into C++ code, so include the generated header.

Expand Down Expand Up @@ -256,7 +256,7 @@ And for the second reaction
// Print the Pong message!
log<NUClear::INFO>("Pong count", pong.count);
// Make a Pong message to send
// Make a Ping message to send
auto ping = std::make_unique<Ping>();
ping->count = pong.count + config.increment;
Expand Down

0 comments on commit 559b178

Please sign in to comment.