For everything onboarding, this is the place to be. We work hard to ensure you can contribute to NER firmware on any platform, but note that many of us who developed these docs are on Linux, and are less familiar with issues that may pop up on other platforms. With that being said, if anything below does not make sense or doesn’t seem to be working as expected, please reach out to one of us on slack in #s_embedded-software channel!

Environment Setup

PLEASE READ IF USING Windows

We use WSL on Windows. All commands henceforth are either from WSL (labelled WSL) or the Windows “terminal” app (labelled Windows) .

To get ready for this guide, run with Windows Terminal app:

1. Install Python

We use various packages and tools from these ecosystems, and so its essential to have both installed on your machine. Obviously, you can skip this step if you already have these installed.

Mac

1. Install python with whatever package manager you like, if not already installed

Linux and WSL

1. Install python with whatever package manager you like, if not already installed

ex on Debian based systems with apt (including WSL):

2. Install and setup Docker (all platforms)

Follow the guidelines found here to install Docker (Linux) or Docker Desktop (Macos and Windows) Setting Up Docker

Windows users: Turn on WSL integration in Docker Desktop settings. Do this by going to Settings → Resources → WSL Integration → Turn on “Ubuntu”

3. Setup Scripts

To make installs easier, there is a python script found in our embedded-base repo that will install and build every python, along with downloading our docker image.

1. Clone Embedded Base

To do this, you'll need to setup ssh keys on your machine. If you aren’t sure how to do this, take a look at this resource. You'll also need to be added to our GitHub Organization - if you’ve gotten this far, hopefully you’ve been informed of a slack thread where you can add your username so that we can add you. If not reach out to the #s_embedded_software channel

2. Open the Embedded-Base repo, and run

^^^ WINDOWS USERS, do this from WSL. If you did not do it from WSL, remove the folder ner-venv and start again.

This script does quite a bit behind the scenes. It pull our docker image, it creates a python venv, and installs packages and sets up entry-points for it. It also installs some other local packages, like OpenOCD (an open source debugger). For a list of all tools that we use, take a look at the next section.

This script will prompt you to answer ‘yes’ (or simply ‘y') or no (or simply 'n’) quite a bit. For most users, you should select yes to all of the prompts. These options are mostly just there in case you have a really weird linux distro (cough cough jack rubacha), or really know what you are doing and want to go about it manually.

3. Set up shell aliases
   This is by no means mandatory, but it might be helpful and is a bit hard to automate in the above script. If you’d like to save time activating and de-activating the virtual environment, you can alias these commands for whichever shell you are using For now, I’m not going to walk through instructions for doing this here; there’s many shells you all might be using, and a million ways to do this, but if you are unsure of how to do it feel free to ask someone and they can help you through it. I use fish shell on Linux, so I’ve added this line to my config.fish file:

so that I can activate the venv by typing 'nervenv” instead of the longer command after. But again, this will look slightly different depending on your platform and shell.

Without this alias, activating the ner-venv (or any python venv for that matter) is done by going to the directory where the venv is located (for this case, it should be one higher directory level than the “Embedded-Base” repo) and running:

To begin developing on Linux/Mac/WSL:

Windows users, see below to Firmware Environment Setup | c. (Windows only) WSL passthrough when you want to interact with external hardware!

The virtual environment can then be deactivated from anywhere by running “deactivate”

Developing on our Team

a. Overview

Even if a lot of this is made easier for developers, it is still a good idea to become pretty familiar with what’s going on behind the scenes. As mentioned above, our embedded toolkit combines a python virtual environment with a docker container running Ubuntu to combine the ease and freedom of a local, pip-managed environment with the consistency and reliably of a single-platform backend. As long as docker, python. git and rust have been properly installed, everything below is set up automatically with the setup script!

Open

Mainly, our Cmake build system and Renode Emulator work in docker. Whenever executing commands related to this, the command is passed into the container and run in there, streaming the output back to the user’s console. Most other tools, such as those to flash and debug, monitor serial output, and using git happen locally on the user’s machine inside of their venv.

b. Commands

See this page for a full overview of the NER build system

c. (Windows only) WSL passthrough

Basically, WSL doesnt get the USB devices such as our circuit boards, by default. A program usbipd fixes that. But, it cannot be run from WSL and therefore not automated.

First, to install, run winget install usbipd in a Windows (non WSL) terminal.

Now, every time a new circuit board is plugged in for the first time, open a adminstrator command prompt terminal and run:

Every time you plug in the device, run from a non-adminstrator windows terminal (not wsl):