Installation

MacOS / Linux

...

Clone repo

...

Install docker

...

Run Docker Desktop

...

Open a terminal in the repo directory

...

Overview

Embedded Software

For embedded firmware, we use a centralized docker container to contain embedded tools that work best on a single, Linux-based platform. This helps ensure we can allow all members to have easy and consistent access to certain tools that may not be available of work as well on different platforms. While in our setup, you may not manually need to interact with the container much, it is encouraged to understand how and why its used, as its a very industry-standard tool

Installation

1. Install docker. For Mac and Windows, you must install docker desktop instead.

2. If using Windows follow two more steps because Docker for Windows runs on WSL (Windows Subsystem for Linux):

   1. Install WSL by running wsl --install

   2. Setup wsl by launching ubuntu from the start menu

Usage

MacOS

1. Make sure Docker Desktop is started

2. Clone and open a terminal in a embedded project.

3. Pull down the Docker container you are using by running docker compose pull.

4. Start the container by running docker compose run --rm ner-gcc-arm.

   1. Note that you only have to do this once really or if the environment was updated, not every time you want to develop

5. Start sample STM dockerfile: sudo docker run --rm -it --privileged -v "$PWD:/home/app" ner-gcc-arm:latest bash

Windows

Installation of this environment is a bit more annoying in Windows smh

1. Clone repo

2. Install docker

3. Update wsl2 stuff https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package and install a distro (do Ubuntu, makes it much easier, I was just able to run wsl --install and it worked)

4. Open a Windows terminal

   1. Make sure you are running it in the root directory of the project (Ex. Cerberus, Shepherd, Iroh, Proteus, etc.)

Linux

1. Clone and open a terminal in a embedded project.

2. Pull down the Docker container you are using by running docker compose pull.

3. Start the container by running docker compose run --rm ner-gcc-arm.

   1. Make sure you are running it in the root directory of the project (Ex. Cerberus, Shepherd, Iroh, Proteus, etc.)

Windows

1. Make sure Docker Desktop is started and wsl ubuntu is installed (see above setup)

2. To mount any flashing hardware (this may be condensed into a script in the future):

   1. Open a Windows terminal with admin privileges and run winget install usbipd

   2. Open a WSL terminal (wsl

   -d ubuntu) and run sudo apt install linux-tools-virtual hwdata and sudo update-alternatives --install /usr/local/bin/usbip usbip `ls /usr/lib/linux-tools/*/usbip | tail -n1` 2 (might need to run sudo update-alternatives before running that last command ?)

3. Open Docker Desktop

4. Open a terminal in the repo directory

5. Build sample STM dockerfile with docker build -f ./Dockerfile -t ner-gcc-arm .

   1. Note that you only have to do this once really or if the environment was updated, not every time you want to develop

6. Start sample STM dockerfile with docker run --rm -it --privileged -v "$(PWD):/home/app" ner-gcc-arm:latest bash

7. Start the Ubuntu WSL client with wsl -d ubuntu in one terminal

   1. ) and run the following commands to enable mounting Windows USB devices in the Docker container

      1. Leave the terminal open

   2. (If interacting with hardware) Mount the Raspberry Pi probe by finding the device in another Windows terminal with usbipd

   wsl

   1. list and mount the device in a Windows terminal window (with admin privileges the first time you do this) with

   usbipd wsl

   1. usbipd bind --busid=<BUSID>

      1. You’re looking for the CMSIS-DAP v2 Interface device

         Image Added

   2. Run usbipd attach --

   distribution

   1. wsl=ubuntu --busid

   =

   1. <BUSID>

Usage

Start Container on MacOS/Linux

In any terminal that is in the directory:

# if need to rebuild image
sudo docker build -f ./Dockerfile -t ner-gcc-arm .
sudo docker run --rm -it --privileged -v "$(PWD):/home/app" ner-gcc-arm:latest bash

Start Container on Windows

In any terminal that is in the directory:

# if need to rebuild image
# docker build -f ./Dockerfile -t ner-gcc-arm .
docker run --rm -it --privileged -v "$(PWD):/home/app" ner-gcc-arm:latest bash

# mounting probe
# in another terminal run wsl -d ubuntu
usbipd wsl list
usbipd wsl attach --distribution=ubuntu --busid=<BUSID>
# close the other wsl window, the device should be mounted to any wsl instance

Tools / Utils

...

1. 1. .

   2. Clone and open a terminal in a embedded project.

   3. Pull down the Docker container you are using by running docker compose pull.

   4. Start the container by running docker compose run --rm ner-gcc-arm.

      1. Make sure you are running it in the root directory of the project (Ex. Cerberus, Shepherd, Iroh, Proteus, etc.)

All future mounts after the first time on the device should be:

1. Open docker desktop and plug in debug probe

2. usbipd list to get the pi debug probe BUS ID

3. usbipd attach --wsl --busid <BUSID>

4. docker compose run --rm ner-gcc-arm