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_embbedded-software channel!
Environment Setup
1. Install Python & Rust
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.
if these are not properly installed, the setup script mentioned below will fail miserably unless I ever make it more robust :)
Mac
Install python with whatever package manager you like, if not already installed
ex with homebrew:
brew install python
Install Rust with rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Linux
Install python with whatever package manager you like, if not already installed
ex on Debian based systems with apt:
sudo apt update sudo apt install python3 python3-pip
Install Rust with rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Windows
Install Python through the official installer
Download the Python installer from https://www.python.org/downloads/ .
Run the installer, and make sure to check the box that says "Add Python to PATH."
Follow the installation prompts.
Install Rust through the official installer
Download and run the Rust installer from https://rust-lang.org/ .
Follow the installation prompts.
2. Install Git
Same deal with package managers as above, but generally:
Mac
brew install git
Linux
sudo apt install git
Windows
Download git from the official installer https://gitforwindows.org/
Run the .exe and follow the steps
3. Install and setup Docker (all platforms)
Follow the guidelines found here: Setting Up Docker
4. Setup Scripts
It is strongly recommended to maintain a directory structure like the following
> NER
> NER Repo 1
> NER Repo 2
…
This ensures that the virtual environment will be placed at the same directory level as all repos, which happens automatically if setup like above
To make installs easier, there is a python script found in our embedded-base repo that will install and build every python and rust package, along with building our docker image
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 some of our git resources linked further down in this doc, or the many resources online that can walk through this
Open the Embedded-Base repo, and run
python setup.py
This should work for any platform, but as mentioned above, it hasn’t been rigorously tested, so let someone know if it doesn't work
This script sets up a python virtual environment, installs packages within it, binds the running of the docker container to the opening/closing of this virtual environment, adds some aliases, and a few other small things. For a list of tools that we use, take a look at the next section.
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.
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!
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
We alias a lot of the most helpful commands to make them easier to use. Here is a (likely incomplete) list of some that you may use the most:
Build - runs the cmake build command in docker
Flash - runs the probe-rs command to upload code to a connected board
Debug - runs the probe-rs command to open a gdb server and debug code