This module describes the software installation required for EiE Firmware using the gcc-based Visual Studio Code IDE. All software packages are either freeware or have free versions with some limitations that will not impact the program. All software is industry-grade and proven stable on Windows operating systems. VSC should also work on Mac and Linux, but these instructions and all the EiE examples and tutorials will focus on Windows.
Most software will be current versions downloaded from the web, but the archive below has three programs that are essential versions and/or more difficult to access online and thus provided here:
https://embeddedinembedded.com/eie_software_2023.zip
Visual Studio Code Integrated Development Environment (IDE)
To develop code for an embedded system, you need at least a file editor, a compiler, and a way to download (“flash”) the compiled code onto the microcontroller. Commercial IDEs like IAR and Keil use custom compilers and thus cost a lot of money though some may have limited or trial versions.
In 2024, EiE is transitioning to VSC to overcome the commercial limitations. Massive thanks to James Bootsma and Andy Smit at Garmin International – two EiE Leaders who got this going.
Installing Visual Studio Code IDE
The first step is download and install Visual Studio Code for the operating system you use. At present the version is 1.93. The URL is:
https://code.visualstudio.com/download
Run the executable and follow the installation instructions. When complete, launch VS Code and configure your environment how you want.
Under Fundamentals, install the following extensions. Be sure the correct version/author is selected as some have multiple versions under the same name:
- Arm Assembly (dan-c-underwood.arm) provides syntax highlighting for GCC Arm assembly files.
- C/C++ extension pack (ms-vscode.cpptools-extension-pack) is the defacto set of extensions for adding C/C++ intellisense and syntax highlighting.
- Cortex-Debug (marus25.corex-debug) provides the integration of vscodes debugger using gdb/JLink tools. It can be a little janky but it’s the best I’ve found so far for vscode. Generally works fine for debugging normal C code though. You might also consider teaching the ozone debugger that segger provides as an alternative.
- GNU Linker Map files (trond-snekvik.gnu-mapfiles) adds syntax highlighting for GCC’s map file format. Really handy when looking at the build output trying to understand why you ran out of ROM or RAM.
- Intel HEX format (keroc.hex-fmt) for syntax highlighting the .hex firmware files.
- LinkerScript (zixuanwang.linkerscript) provides syntax support for GCC linker scripts.
- Config Defaults (spadin.config-defaults) automatically populates some settings files from .defaults.json. I did it this way rather than having settings.json checked in as often people want to customize vscode’s settings a bit more.
When you run VS Code later, there is a tab of “Recommended Extensions” that may contain some additional extensions to install which you are free to do.
Python 3 Installation
Python 3 is used to run the waf script that controls the configuration and build process of the project. Install the latest version of python 3 for your operating system from python.org (https://www.python.org/downloads/. Select the option to add python to the path if available during the install.
Run the installer then click “Close” once complete.
ARM GNU Toolchain
The GNU arm toolchain contains the compiler and other tools necessary to build the project. To install:
- Go to the page for the ARM GNU Toolchain Download (https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
- Download the version 13.3.Rel1 of the ARM-none-eabi toolchain for your operating system.
- For windows this is the .exe file.
- For macOS this is the .pkg file (make sure to get the correct one for if you are running an x86 or Apple Silicon Mac).
- For debian based linux you can run
sudo apt install gcc-arm-non-eabiand skip downloading from the website.
Run the installer. On Windows when prompted at the end deselect all boxes except for “Add to path“
EiE J-Link Configuration
A huge benefit of the EiE development board is that it has a “J-Link Onboard” programmer / debugger. This is pre-programmed on the top-right processor. If you fiddle with this processor you run the risk of destroying the J-Link code and bricking your whole dev board.
Aside from saving you over $100 to buy an external J-Link, the J-Link Onboard also provides a virtual serial port connection to the main microcontroller. A serial connection is one of those essential tools to an embedded system.
Once upon a time, J-Link Onboard was very picky about the J-Link software version that worked and would only run V6.10e. This seems to be resolved and all V7.58 versions have proven to work. All versions are available on the Segger website (https://www.segger.com/downloads/jlink/) and it is likely the latest version (7.98i at present) will work, so download and install that.
Once downloaded, run the installer.
For optional components you have some choices. If you have not installed JLink before, use the settings shown below. IMPORTANT: the “Install legacy USB Driver” must be checked. In some cases, you may want to choose “Update existing installation” which will update any current JLink software. However, developers may want to keep older versions of the JLink software for backwards / historical compatibility. If in doubt, choose “Install a new instance.”
Follow these instructions carefully to connect the virtual COM port!
Open up Windows Device Manager. You’ll need this application often, so creating a link on your desktop might be handy. The file is “\\Windows\System32\devmgmt.msc” or you can hunt for it in the search bar by typing “dev man”
Device manager is where you will check if your dev board’s serial connection is established. Plug in the EiE development board to the right USB Port J1 labelled “JLINK/CDC” and watch the Device Manager. The board should power on a few LEDs and Device Manager should beep and refresh.
If you see “JLink CDC UART Port (COMx)” you do not need to do anything else in this step.
If the port is not present, run “J-Link Commander” from the folder where you installed the J-Link software.
If you are prompted to upgrade the firmware on the J-Link processor, click YES.
In the J-Link Commander, type “vcom enable” and the press enter. Be sure you see “The new configuration applies after power cycling the debug probe.”
Close J-Link Commander.
Unplug the USB cable from the Development board and count to 5.
Make sure Windows Device Manager is open.
Plug the USB cable back in. You should see two new devices. Wait patiently while the driver loads. On some computers this happens almost immediately, on others it takes a few minutes. If nothing happens after 5 minutes, unplug the USB cable, count to 10, then plug it back in.
If everything has worked, you should now see “JLink CDC UART Port (COMxx) where “xx” is some number that you need to know for the next step. It may or may not change each time you plug in the dev board, so make sure you know how to open Device Manager to check the port. If it hasn’t worked, seek some assistance or try to repeat the process. If all else fails, restart your computer and try again.
Terminal
There are tons of terminal programs available and you are welcome to use your favorite if you have one. The preferred terminal for EiE is Tera Term and the version used in all the examples is 4.87 which is included in the EiE Software archive. Make sure Tera Term is installed and your EiE dev board is connected to the JLINK/CDC USB port.
Choose File > New Connection and choose “Serial” along with the “JLink CDC UART Port (COMx)” option.
Now select Setup > Serial Port… to configure the following settings (use the COM port shown in Device Manager).
So you don’t have to do this every time you launch Tera Term, choose Setup > Save Settings and overwrite the TERATERM.INI file. You’ll still have to make a new connection to the COM port, but you will not have to update the serial port settings.
Press the reset button on the EiE development board and observe the startup sequence on the terminal output.
Git and Github
All EiE firmware is stored on GitHub. If you are familiar with git and Github, feel free to use your preferred method of accessing firmware repositories.
For the intergrated git functionality of VS Code, git needs to be installed. Follow the installation instructions for git from the git-scm (https://git-scm.com/download/win) for your operating system.
Run the installer and careful choose the options that apply to you. For this installation, the default editor will be set to VSC.
We’ll let Git decide how to name default branches:
Allow Git from the command line and 3rd party apps:
Use the bundled Secure Shell:
Use the OpenSSL library:
Checkout Windows-style:
Use Window’s default command line:
Default behaviour “Fast-forward”
No credential helper:
Enable file system caching:
Don’t enable experimental options:
Code Repository on Github
Navigate over to github.com and find the “eiefirmware” user. Select “Repositories”
Select the “eie_sam3u2_vsc” repository and the “gcc-port” branch.
Click the “<> Code” button and select “Download ZIP.” This will get you a copy of the code base that should work. Note this is NOT how we will be using git, but just a temporary method of grabbing the code to test. Save and extract the .zip file to a location you can find easily on your computer.
Loading, Building, Flashing in VS Code
Open VS Code and choose, “Open Folder” from the File menu or the Welcome screen. The project folders should be visible in the EXPLORER window.
waf Build System
waf is a build system that uses Python to execute a project build script. There is nothing to install as long as Python has been installed on your system.
Make sure the EIE_SAM3U2_VSC folder is open in VS Code. Find the “wscript” file in the VS Code project and look for the JLink program paths around line 340. Modify these to match where you installed JLink. Note that any backslash “\” character in the file path is written as double backslashes “\\” in the script.
Repeat to update the gcc installed location on your computer (around line 391).
Open the readme.md file and note the instructions to compile the project (green box below). These may be slightly different depending on your terminal implementation. If you followed this installation guide, select Terminal > New Terminal and type “python waf -?” to ensure Python is running the waf script.
If you will be using an EiE development board with ASCII (character) display, type “python waf configure –board=ASCII” and press enter. You should see a bunch of messages in green with the final message, “finished successfully” if everything worked. If you will be using a Dot Matrix LCD dev board, then type “python waf configure –board=DOT_MATRIX” and you’ll get the same messages. This step need only be done once for the project unless you change dev boards from ASCII to DOT_MATRIX or vise-versa.
Lastly, type “python waf build” and ensure the build is successful.
If you have a development board available, connect the JLINK/CDC USB connector and ensure the board appears in Device Manager as you did earlier in this module.
In the Terminal type “python waf build -F” and you should see a bunch of messages. Look for successful connection to J-Link, Flash download, and ‘build’ finished successfully. If there are any errors, read them and work through them. If you are stuck, grab an EiE Leader for some help. There are too many error scenarios to try to document here, so you will have to work through any error messages to resolved them.
Summary
Indeed one of the hugely challenging steps in any embedded system is getting new hardware and new firmware on a new IDE / compiler working! But once you have it, then future trouble shooting becomes much easier since you know certain parts of the system are working correctly. It’s a good idea to keep a known-working firmware project and development board available that you can test things on if you are having trouble.
If everything above worked properly, you are now ready to proceed with the EiE firmware modules. Whenever you begin working with the EiE development board (or any board), make sure your tools are working properly with a known build of firmware like the Board Test application.
[LAST UPDATE: 2024-SEP-20]