LX: Sensors - Inertial Measurement Unit (IMU)#

What you will need

What you will get

  • Running the Sensors - IMU learning experience

This Learning Experience introduces Inertial Measurement Units (IMU), and in particular the model equipped on the Duckiedrone (DD24-B). You will learn what an IMU measures, how rotations in 3D are represented, how the Duckiedrone’s IMU data flows from the flight controller to a ROS 2 topic via MAVROS2, and how to write a ROS 2 node that reads sensor_msgs/Imu messages in real time.

Model inertial measurement unit (IMU)

Fig. 97 An IMU sensor chip with its three accelerometer axes and three gyroscope axes.#

Intended Learning Outcomes

After completing this learning experience, learners will be able to:

  • Explain what an accelerometer and a gyroscope each measure, and predict what happens to a position estimate built by integrating acceleration over time.

  • Compare Euler angles, rotation matrices and quaternions as ways of writing an orientation, and identify the orientations at which Euler angles break down.

  • Trace an IMU reading from the sensor chip to a ROS 2 topic, naming what changes it at each step and what sets its rate.

  • Write, deploy, and run a ROS 2 node on a Duckiedrone that subscribes to the IMU topic and reports acceleration, angular velocity, and roll, pitch and yaw.

Available repositories

Access to the solution repository is reserved to Duckietown instructors. Reach out to info@duckietown.com or upgrade your plan through the Duckietown Hub.

Warning

If you are using a Duckietown Workspace, the WebGL (browser) versions of the Duckietown Viewer and Duckiematrix can be run inside or outside the Duckietown Workspace. If dts is installed on the host machine, commands that launch native Duckietown Viewer apps or the Duckiematrix Renderer, such as dts matrix run, can also be run in either location. When one of these commands is run inside the Duckietown Workspace, it is automatically delegated to the host machine, where it launches the native UI. The --standalone flag starts the Duckiematrix Engine in the environment where the command is run.

About these learning activities#

Note

This learning experience runs on a virtual Duckiedrone in the Duckiematrix and on a physical Duckiedrone.

Forking the Repository#

Important

The public lx-dd-sensors-imu repository is not published yet. The steps below can be applied to the solutions repo instead.

The recommended way to use the repository of an LX is to make a fork, and then clone that fork. Forking can be done through the GitHub web interface, and creates a personal copy that can still be synchronized with the upstream Duckietown code.

Cloning the repository directly also works, at the cost of not being able to push personal changes.

  1. Create a fork: navigate to the lx-dd-sensors-imu repository.

    Find and press the “Fork” button on the top right:

    how to fork a Duckietown LX repository

    Fig. 98 Fork the LX to be able to make local changes while still being able to receive updates.#

    This creates a new repository at <your_github_username>/lx-dd-sensors-imu.

  2. Clone the fork: clone the fork on the computer, replacing the GitHub username in the command below, and navigate to the new folder:

     git clone [email protected]:<your_github_username>/lx-dd-sensors-imu
 cd lx-dd-sensors-imu

  3. Configure upstream repo: configure the Duckietown version of this repository as the upstream repository to synchronize with the fork.

    List the current remote repository for the fork,

     git remote -v

    Specify a new remote upstream repository,

     git remote add upstream https://github.com/duckietown/lx-dd-sensors-imu

    Confirm that the new upstream repository was added to the list,

     git remote -v

    Work can now be pushed to the personal repository using the standard GitHub workflow, and the beginning of every exercise prompts a pull from the upstream repository, updating the exercises to the latest version.

Keeping the System Up To Date#

  • 💻 These instructions are for ente learning experiences. Ensure that the Duckietown Shell is set to an ente profile (and not a daffy one). The current profile is shown by:

    dts profile list

    To switch to an ente profile, follow Initial setup.

  • 💻 Pull from the upstream remote to synchronize the fork with the upstream repo:

    git pull upstream ente

  • 💻 Make sure the Duckietown Shell is updated to the latest version:

    pipx upgrade duckietown-shell

  • 💻 Update the shell commands:

    dts update

  • 💻 Update the computer and the Duckiedrone: follow Preparing the software stack.

SSL Certificate Setup#

Note

This procedure is only needed the first time an LX is run on a new computer.

Duckietown uses SSL certificates and TLS encryption to guarantee the highest standard of safety and privacy. Set up a local SSL certificate needed to run the LX editor inside the browser:

sudo apt install libnss3-tools
dts setup mkcert

Note

If a Duckietown Workspace is in use, install mkcert on the host system by following the workspace setup instructions instead of running these commands inside the dev container.

Launching the Code Editor#

Important

All dts code commands must be executed inside the root directory of the learning experience.

From inside the directory of the learning experience, open the code editor by running:

dts code editor

Wait for a URL to appear on the terminal, then click on it or copy-paste it in the address bar of the browser to access the code editor. The first thing shown in the code editor is a version of these instructions. The indications shown in the code editor take precedence over this page.

Walkthrough of Notebooks#

Inside the code editor, use the navigator sidebar on the left-hand side to navigate to the notebooks directory and open the first notebook.

Follow the instructions on the notebook and work through them in sequence.

In many cases the last notebook instructs the learner to write some code inside the learning experience directory. That code needs to be built before testing it.

Testing with the Duckiematrix#

Testing code in the Duckiematrix requires a virtual Duckiedrone attached to an ongoing session.

1. Creating and starting a virtual Duckiedrone#

If this has not been done already (e.g., for a different LX), create a virtual Duckiedrone with the command:

dts duckiebot virtual create --type duckiedrone --configuration DD24 [VDRONE]

where [VDRONE] is the hostname. It can be any name, subject to the same naming constraints of physical Duckiedrones.

When the command runs, DTS prompts for a password for the virtual Duckiedrone’s duckie account, and asks to confirm it. The password must contain at least eight characters and cannot contain colons or line breaks. The typed characters are not displayed.

Then start the virtual robot with the command:

dts duckiebot virtual start [VDRONE]

The virtual Duckiedrone appears with status Booting and finally Ready in the output of dts fleet discover:

         | Hardware |    Type     | Model |  Status  |    Address
-------- | -------- | ----------- | ----- | -------- | --------------
[VDRONE] |  virtual | duckiedrone | DD24  |  Ready   | [VDRONE].local

Note

The Duckiedrone software stack runs on ROS 2. When running ROS 2 commands against a virtual or physical Duckiedrone from the computer, the ROS_DOMAIN_ID must match the one used by the robot.

2. Starting the Duckiematrix with the virtual Duckiedrone#

Once the virtual robot is ready, start the Duckiedrone simulation environment:

dts matrix run --standalone --map sandbox_drone --embedded

where --standalone starts both the Duckiematrix Engine and the Renderer in the same environment, and --embedded loads sandbox_drone, the Duckiedrone map shipped with the Duckiematrix.

Note

This command must be run from a local terminal and not from inside a Duckietown Workspace.

The Unity-based Duckiematrix simulator starts up in the sandbox_drone map, which contains a single Duckiedrone. For more details about using the Duckiematrix see the Duckiematrix manual.

the Duckiedrone in the Duckiematrix sandbox map

Fig. 99 The Duckiedrone in the Duckiematrix sandbox map used by this learning experience.#

To activate the Duckiematrix window, click anywhere on it and press ENTER. Press ESC at any time to disengage the mouse.

While the window is active, the point of view is moved with the W, A, S, and D keys, and the viewing angle with the mouse. All available keyboard commands are summarized in the “Settings” tab at the bottom left of the Duckiematrix window.

3. Attaching the virtual Duckiedrone to the Duckiematrix#

The virtual Duckiedrone and the Duckiematrix run as separate entities, and are connected with:

dts matrix attach [VDRONE] map_0/vehicle_0

where [VDRONE] is the name of the virtual Duckiedrone, and map_0/vehicle_0 is the name of the Duckiedrone entity in the sandbox_drone map. Once attached, the sensor data produced by the Duckiematrix reaches the robot, and the commands produced by the robot move the Duckiedrone in the simulation.

Other useful virtual Duckiedrone commands#

To disconnect the virtual Duckiedrone from the Duckiematrix without stopping it:

dts matrix detach [VDRONE]

Once the work session is over, stop the virtual robot:

dts duckiebot virtual stop [VDRONE]

The status of all virtual robots can be checked at any time with:

dts duckiebot virtual list

Building the Code#

From inside the learning experience root directory, build the code with:

dts code build -R [ROBOT_NAME]

where [ROBOT_NAME] is the name of either a physical or a virtual Duckiedrone.

This command packages the LX code and its dependencies into the image that will run on that Duckiedrone. The image is prepared for the selected robot, but the build command does not deploy it.

Deploying the code on a (physical or virtual) Duckiedrone#

To test the code on the Duckiedrone:

dts code workbench -R [ROBOT_NAME]

This command deploys the image built in the previous step to the specified Duckiedrone and starts the workbench, so that the code can be tested on the robot.

While the workbench is running, an interactive shell can be attached to its container from a second terminal:

dts code workbench -R [ROBOT_NAME] --shell

The shell can be used to inspect the running environment and execute commands inside the container.

After every change to the learning experience code, stop the workbench, then run dts code build -R [ROBOT_NAME] and dts code workbench -R [ROBOT_NAME] again to ship the new changes.

Troubleshooting#

For more detailed instructions, refer to General Procedure for Running Learning Experiences. For help troubleshooting common problems, refer to its troubleshooting section.