...
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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:
| Code Block |
|---|
wsl --update |
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.
...
| Code Block |
|---|
brew install python |
Install Rust with rustup:
| Code Block |
|---|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh |
...
Linux and WSL
Install python with whatever package manager you like, if not already installed
ex on Debian based systems with apt (including WSL):
| Code Block |
|---|
sudo apt update
sudo apt install python3 python3-pip python3-venv |
...
2. Install Git
Same deal with package managers as above, but generally:
Mac
| Code Block |
|---|
brew install git |
Linux and WSL
| Code Block |
|---|
curlsudo --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
| Code Block |
|---|
brew install git |
Linux
| Code Block |
|---|
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
...
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. 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.
Open the Embedded-Base repo, and run
| Code Block |
|---|
python ner_setup.py |
(if your default python version is 2, run “python3” instead of “python. You can find your default version by running “python --version”)
| Info |
|---|
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 |
| Note |
|---|
If you are on Windows, please use bash shell for this. It comes installed with Git, and you can use any terminal ( just run “bash” to open it, or you will also see a dropdown on VSCode terminals to select any shell) |
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 aliases & entry-points for it. It also installs some other local packages, like probe-rs (an open source debugger written in Rust). 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.
(IF ON LINUX ONLY, ELSE SKIP) Fix Rust-Sudo Dynamic
...
Note: need to use “sudo” for steps 2 and 3 in the above link
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:
| Code Block |
|---|
alias nervenv="apt update && sudo apt upgrade -y sudo apt install git |
3. 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”
4. Setup Scripts
| Info |
|---|
It is strongly recommended to maintain a directory structure like the following |
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.
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
| Info |
|---|
Windows users: For better build performance, clone this to a folder within the Ubuntu disk. Do this by entering the ~ folder with |
Open the Embedded-Base repo, and run
| Code Block |
|---|
python3 ner_environment/ner_setup.py |
^^^ 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.
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:
| Code Block |
|---|
alias nervenv="source ner-venv/bin/activate.fish" |
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:
| Code Block |
|---|
source ner-venv/bin/activate.fish" |
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:
On Windows (using bash):
| Code Block |
|---|
source ner-venv/Scripts/activate |
On Linux/Mac:
| Code Block |
|---|
source ner-venv/bin/activate |
The virtual environment can then be deactivated from anywhere by running “deactivate”
| Note |
|---|
When activiating, you may see an error that says soemthing about ls: cant find /bin/bash. No worries if you do, it shouldnt prevent anything from working |
Developing on our Team
a. Overview
...
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
...
Windows users, see below to https://nerdocs.atlassian.net/wiki/spaces/NER/pages/edit-v2/524451844#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”
| Note |
|---|
You always need the venv active when trying to interact with our build system |
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
See /wiki/spaces/NER/pages/611516420 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:
| Code Block | ||
|---|---|---|
| ||
usbipd list
# identify the device from the list (usually called FTDI or CMSIS-DAP), and enter its bus ID below
usbipd bind --busid <BUS_ID> |
Every time you plug in the device, run from a non-adminstrator windows terminal (not wsl):
| Code Block |
|---|
usbipd attach --wsl --busid <BUS_ID> |
Learning Resources
a. Git
| View file | ||
|---|---|---|
|
...
Follow the link posted here, when available (expected by Saturday, 9/14 latest):
https://classroom.github.com/a/_1lecy_U
main.c - the application main code, with task/thread definitions and functional logic.
...
| Note |
|---|
I may not be able to give everyone a board. Whether you get a board or need to come to the RIchards Richards makerspace to test, you'll need to connect to an external LED, which will be setup in the makerspace, to view that component of the output. output. If a breadboard with an LED is not setup when you go down, feel free to skip this part in testing (I will still check code for the functionality), or challenge yourself by building your own breadboard setup. It only takes 3 components: a breadboard, an LED, and a resistor! |
You’ll need a micro-USB cable to connect your laptop to the device. If you don’t have one around, stop by the Richards Makerspace and test it with one of ours down there.
...
To upload the built code to the board, run
| Code Block |
|---|
lpflash |
To view logs
| Code Block |
|---|
platformio device monitor |
To view the Bluetooth data, download the NRF connect app on your phone. In the scanner, you should see an ESP device. Connect to that and you should be able to see the message!
Similarly you
...
The hall sensor normally would need to be calibrated to account for the ambient magnetic field in your environment. Doing so is out of scope of this task, so don’t worry about it too much, just try to set it up so that the light does not blink much at the reading level it gets without the magnet nearby. Depending on your environment, this might be at different reading values. All apps have the same ADC resolution, but you may read stronger or weaker fields, which is okay. Regardless, the strength should increase as the magnet gets closer. To test this, you may want to simply guess and check - you should incorporate some sort of “offset” ADC value, where the LED doesnt/barely blinks if the reading is as low as you record when no magnet is nearby. Also, it doesn't need to be extremely precise. Maybe you only have 2 or 3 blink speeds for strength ranges - this doesn't need to be a continuous and fine grained speed increase for every tiny change in field strength
When Using multiple threads like in an RTOS application, data atomicity is important. If a piece of data is accessed from multiple threads, it is important to use a locking mechanism, like a mutex or semaphore, to make sure that sharing this data is done safely
...
data is accessed from multiple threads, it is important to use a locking mechanism, like a mutex or semaphore, to make sure that sharing this data is done safely
Again, please ask questions! Bay times and meetings will dedicate time for launchpad discussions, if you are new to embedded, this stuff may seem really confusing and we are here to help make it less daunting.
Bonus: As mentioned, the LED that is being blinked in this program is not on the board, its connected to a floating gpio pin. While I may get some setups myself for you to use, if you want to do a little breadboarding, feel free to setup your own breadboard (we have some in the bay) and connect an external LED (we will have some in the bay). You may need to do some EE math to figure out what resistor to use so that you don’t explode the LED :)