Getting Started

This page provides instructions on how to set up the PicoNut project on any Linux operating system. There are two methods available: the recommended approach is to use Docker, but you can also install all the necessary dependencies natively. The Setup has to be done for both methods.

Setup

Clone the PicoNut repository.

Docker (Recommended)

Install

1. Set up Docker’s apt repository:
   Note: The Example below is for Ubuntu. More information about installing docker for other distrobutions can be found here.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

2. Install latest version of docker

$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2. Add User to docker group: replace your username with <user>.

$ sudo usermod -aG docker <user>

Log out and log back in after running this command for the changes to take effect.

3. Build the docker piconut image:
   Note: This creates a docker image of size ~10Gb. Make sure there is ~30Gb disk space available before continue, this extra space is needed for the build process of some packages! Depending on the hardware this process takes ~2h.
   First, navigate to the PicoNut repository directory.

$ cd tools/docker
$ chmod +x docker-create-piconut-image.sh
$ ./docker-create-piconut-image.sh

Note: If the riscv stage fails, try restarting the shell script. This is likely due to a git clone timeout caused by overloaded remote servers.

Now there should be a docker images created named piconut_image. To check it use:

$ docker images

There should be a image listed called piconut_image listed with ~10Gb.

4. Add GUI support:
   To run the Docker container with GUI support, you’ll need to configure X11 server access.

$ xhost +local:docker

Workflow

1. Start the docker container:
   First, navigate to the PicoNut repository directory.

To start a docker container docker compose is used. If no container for the piconut_image exists the docker compose command creates a container based on the previous built piconut_image. The created container is called piconut_container. Else it just starts the container called piconut_container.

$ docker compose up -d

Note: The docker compose behaveiour is found in docker-compose.yml. If you want to mount additional directories you can do this there.

2. Open a terminal inside the docker container:

To start a terminal, with user privilege, inside the piconut_cotainer type:
Note: Use this in almost all cases.

$ docker exec -it piconut_container bash

To start a terminal, with root privilege, inside the piconut_cotainer type:
Note: E.g. needed when you want to install additional packages etc.

$ docker exec -itu root piconut_container bash

The PicoNut repository is mounted to ~/ees/piconut.

3. Use VSCode with docker container:
   When you don’t use VSCode you can skip this part.

Install the VSCode extension ms-vscode-remote.remote-containers.

When you start VSCode from the Piconut Project base directory. There will be a popup in the bottom left corner. Showing a button Reopen in Container. When it is clicked the VSCode connects to the container and you are working inside the container.

Run reference design simulation

$ cd ~/ees/piconut/systems/refdesign/hw
$ make run-tb

If everything works, console should show the output of a simple hello world program.

Native install

For native install you can install the packages and software by hand listed in tools/docker/Dockerfile.

Run reference design simulation

$ cd <path-to-piconut-repository>/systems/refdesign/hw
$ make run-tb

If everything works, console should show the output of a simple hello world program.