Skip to content

Latest commit

 

History

History
499 lines (341 loc) · 19.6 KB

BUILD.md

File metadata and controls

499 lines (341 loc) · 19.6 KB
Raw

usbflashprogUSB Flash/EPROM Programmer

A memory device programmer (Flash/EPROM/E2PROM) board and software, connected to PC by USB port.

Build Instructions

Here are instructions on how to build the project.

Contents

GNU/Linux©

Requirements

Install Packages

  1. Run the following commands:
sudo apt update
sudo apt install git cmake doxygen graphviz build-essential gcc-arm-none-eabi libstdc++-arm-none-eabi-newlib automake autoconf texinfo libtool libftdi-dev libusb-1.0-0-dev

Install Pico C SDK

The Pico SDK contains a collection of tools and libraries used to facilitate development on the Raspberry Pi Pico (and other RP2040-enabled boards). There is also a set of C examples in the official repositories that are useful demonstrations of how to use the SDK.

  1. To install the required Pico C SDK, run the following commands:
cd ~
git clone -b master https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init
cd ..
echo "export PICO_SDK_PATH=$HOME/pico-sdk" >> .bashrc
source .bashrc

Install Visual Studio Code [Optional]

The purpose of this tutorial is to configure the popular cross-platform IDE Visual Studio Code, free and provided by Microsoft, to edit and compile the project. However, you can use another IDE instead (like Eclipse, for example), or even not use any IDE.

To install Visual Studio Code:

  1. Download the latest version from the Visual Studio Code Site. The version installed at the time of writing this tutorial was code_1.67.2-1652812855_amd64.deb.

  2. Run the following command:

sudo dpkg -i code_1.67.2-1652812855_amd64.deb
  1. After installation, open Visual Studio Code and in the "Extensions tab", install the following extensions:
  • CMake
  • CMake Tools
  • C/C++
  • Cortex-Debug

Build

  1. Clone the project from the repository:
git clone https://github.com/robsonsmartins/usbflashprog.git
  1. Change to firmware/usbflashprog directory:
cd usbflashprog/firmware/usbflashprog
  1. Run the following commands:
mkdir build
cd build
cmake ..
make -j$(nproc)
  1. The generated firmware binary will be in build/ directory, with the filename ufprog.uf2.

Test [Optional]]

  1. Clone the project from the repository:
git clone https://github.com/robsonsmartins/usbflashprog.git
  1. Change to firmware/usbflashprog directory:
cd usbflashprog/firmware/usbflashprog
  1. Run the following commands:
mkdir build
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DTEST_BUILD=ON .
cmake --build build --config Debug
cd build
ctest -C Debug

Generate Code Coverage Report [Optional]]

Note: This step requires lcov, which can be installed with the following commands:

sudo apt update
sudo apt install lcov
  1. Clone the project from the repository:
git clone https://github.com/robsonsmartins/usbflashprog.git
  1. Change to firmware/usbflashprog directory:
cd usbflashprog/firmware/usbflashprog
  1. Run the following commands:
mkdir build
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DTEST_BUILD=ON .
cmake --build build --config Debug
cd build
ctest -C Debug
cd ..
lcov --directory ./build/ --capture --output-file ./build/coverage.info --rc lcov_branch_coverage=1 --exclude \/usr\/include\/\* --exclude \/usr\/local\/include\/\* --exclude .\/build\/\* --exclude .\/test\/\*
genhtml ./build/coverage.info --output-directory <output_dir>

Generate Doxygen Documentation [Optional]

Note: This step requires doxygen, which can be installed with the following commands:

sudo apt update
sudo apt install doxygen graphviz
  1. Clone the project from the repository:
git clone https://github.com/robsonsmartins/usbflashprog.git
  1. Change to firmware/usbflashprog directory:
cd usbflashprog/firmware/usbflashprog
  1. Run the following commands:
doxygen

The documentation is generated under usbflashprog/docs/firmware/html directory.

Microsoft Windows©

Requirements

Install Git

Git makes downloading the code a lot easier, and the Windows version comes with Git Bash, which is a very useful shell that makes the Microsoft Windows command line a little more effective, like GNU/Linux. It is even possible to change the default terminal from VS Code to Git Bash, making it more powerful and similar to GNU/Linux.

  1. Download the latest Git SCM installer for Microsoft Windows from the Git for Windows Downloads Page. In this tutorial the Git-2.31.1-64-bit.exe version was used.

  2. Run the installer. Use all default options.

  3. When you get to the screen asking you to "choose a default editor", feel free to choose whatever you want. A good option is Notepad++, and if you don't have it installed, you can select Notepad (Windows default), if you don't want to use an editor in console mode.

Install CMake

CMake is a build utility, which helps to automate the process of building programs. Unlike Make, it does not call the compiler/linker tools, but generates (platform dependent) file and directory structures needed to run Make.

  1. Download the latest version of CMake from the official website: CMake Downloads Page. The version used in this tutorial was cmake-3.23.2-windows-x86_64.msi.

  2. Run the installer and accept the user license.

  3. Under "Install Options", select "Add CMake to the system PATH for all users".

  4. In "Destination Folder", write a short and easy path, for example c:\cmake.

Install GNU ARM Embedded Toolchain

The GNU ARM Embedded Toolchain package contains the set of ARM compilers needed to compile the C and C++ source code for the RP2040 microcontroller (present on the Raspberry Pi Pico).

  1. Open the GNU ARM Embedded Toolchain downloads page, and download the latest installer for Windows. At the time of writing this tutorial, the version used was gcc-arm-none-eabi-10-2020-q4-major-win32.exe.

  2. Run the installer. When prompted, change the install location to a short and easy path, for example c:\gcc-arm. The installer will automatically populate the destination folder with the name of the current version of the toolset.

  3. Continue with the installation process. On the last screen, leave all options selected.

Install MSys2 and MinGW

MSys2 is a collection of tools and libraries that provide an easy-to-use environment for building, installing and running native software for Microsoft Windows. It offers a terminal (command line) similar to the GNU/Linux console, several standard POSIX and GNU commands and utilities, and a package installer similar to the Arch Linux distribution, Pacman.

  1. To install MSys2, download the latest version of the installer package from msys2.org. In this tutorial, the msys2-x86_64-20210419.exe version was used.

  2. Run the installer. Enter the desired installation folder (short path with no accents, no spaces, no symlinks, no subdirectories or network drives).

  3. When finished, check Run MSYS2 64bit now.

To install MinGW on MSys2, follow the steps:

  1. First, update the package database and base packages. In the open console, run the command:
pacman -Syu
  1. After closing the MSys2 console, reopen it through the shortcut in the Start Menu, and execute the commands:
pacman -Sy
pacman -Su
  1. Install the packages for compilation by running the command:
pacman -S mingw-w64-x86_64-toolchain git make libtool pkg-config autoconf automake texinfo git

  1. When asked which members to mingw-w64-x86_64-toolchain install, press Enter to install them all (default).

  2. When asked about a conflict between pkg-config and pkgconf, choose option Y (Remove pkgconf).

  3. Downloading and installing the packages will take a long time.

  4. To configure Path in MSys2:

  • In the MSys2 terminal, open the file ~/.bashrc, like this: nano ~/.bashrc.
  • At the end of the file, add the line PATH=${PATH}:/c/cmake/bin (path of the cmake).
  • Save the file <Ctrl + O> and close <Ctrl + X> the editor, and run source ~/.bashrc.

Now it will be possible to execute and get the return of cmake --version.

  1. Run the commands:
echo "alias make=mingw32-make.exe" >> ~/.profile
source ~/.profile

This will configure the command make to call, the utility provided in the MinGW package.

Install Python

Pico's SDK needs Python to script and automate some of the build functions.

The Python version recommended in the Raspberry Pi Pico Datasheet for the C/C++ SDK is 3.9 or higher. Note that this version does not support Windows 7, and Python versions lower than this may not work with Pico.

  1. Download the latest Python version installer from the Python Downloads Page. The version used in this tutorial was python-3.9.4-amd64.exe.

  2. Run the installer. On the first screen, keep the "Install launcher for all users (recommended)" and "Add Python 3.9 to PATH" options checked. Choose the "Customize installation" option.

  3. Under "Optional Features", leave all options checked. Under "Advanced Options", select "Install for all users", thus leaving the first 5 options checked. In "Customize install location", type a short path as C:\python.

  4. Click "Install Now" and wait for Python to install.

At the end of the installation process, select the "Disable path length limit" option. If this option is not available, or if you leave it for later, it is important to manually disable the MAX_PATH length limit for the Pico SDK to work. Pico's SDK (and other SDKs from other cards) often have long, nested directory trees, resulting in pathnames that exceed the original Windows limit (260 characters).

  1. [Optional] If you haven't selected the "Disable path length limit" option in the Python installer, or want to do it manually:
  • Run regedit (Windows Registry Editor);
  • Open the subkey Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem;
  • Add a value entry (if it doesn't already exist), with name LongPathsEnabled, of type DWORD;
  • Change the value data to 1;
  • Before using the build tools for Pico, the computer must be restarted.

Install Pico C SDK

The Pico SDK contains a collection of tools and libraries used to facilitate development on the Raspberry Pi Pico (and other RP2040-enabled boards). There is also a set of C examples in the official repositories that are useful demonstrations of how to use the SDK.

  1. To install the required Pico C SDK, run the following commands (inside MSys2):
cd $USERPROFILE
git clone -b master https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init
cd ..

Install Doxygen [Optional]

Doxygen is a tool designated for creating documentation (HTML, LATEX, Unix Man Pages, RTF or PostScript) from comments annotated in source code. Supports multiple languages including C and C++.

Doxygen is not required to compile the binaries, but it can be useful if you want to generate the project's API documentation.

To install Doxygen:

  1. Download the latest version for Windows from the Doxygen Downloads Page. The version used in this tutorial was doxygen-1.9.4-setup.exe.

  2. Run the installer. When prompted, change the install location to a simple and easy path, such as c:\doxygen.

  3. Install all components.

Install GraphViz [Optional]

GraphViz is a software package capable of generating graphs from a programming API in languages such as C/C++, Python, C#, Ruby. It's used by Doxygen to generate class diagrams, dependency between packages, etc.

GraphViz is not needed to compile binaries, and it only makes sense to install it if Doxygen is also installed.

To install GraphViz:

  1. Download the latest version for Windows from the GraphViz Downloads Page. The version used in this tutorial was stable_windows_10_cmake_Release_x64_graphviz-install-2.47.1-win64.exe.

  2. When running the installer, under "Install Options", select the "Add Graphviz to the system PATH for all users" option.

  3. When prompted, enter the installation location ("Destination Folder") for a short, easy path such as c:\graphviz.

Install Visual Studio Code [Optional]

The purpose of this tutorial is to configure the popular cross-platform IDE Visual Studio Code, free and provided by Microsoft, to edit and compile the project. However, you can use another IDE instead (like Eclipse, for example), or even not use any IDE.

To install Visual Studio Code:

  1. Download the latest version from the Visual Studio Code Site. The version installed at the time of writing this tutorial was VSCodeSetup-x64-1.55.1.exe.

  2. Visual Studio Code can be installed with all default options.

  3. After installation, open Visual Studio Code and in the "Extensions tab", install the following extensions:

  • CMake
  • CMake Tools
  • C/C++
  • Cortex-Debug

The "CMake Tools extension" must be configured to generate files for MinGW.

To do this:

  1. Go to the CMake Tools extension settings, "Extension settings".

  2. Find "CMake: Generator" field, and enter the value "MinGW Makefiles".

Update Environment Variables

Some of the installed tools automatically update the Windows environment variables (specifically, the PATH). However, some do not. Either way, this section helps you identify all the necessary variables.

To check and change environment variables, search the "Windows Search Bar" for the word "env". Choose the option "Edit system environment variables", and click on "Environment variables...".

The following variables and inputs are required:

PATH

  • C:\msys\mingw64\bin
  • C:\cmake\bin
  • C:\gcc-arm\10 2020-q4-major\bin
  • C:\Program Files\Git\cmd
  • C:\python\Scripts\
  • C:\python\
  • C:\doxygen\bin (if Doxygen was installed)
  • C:\graphviz\bin (if GraphViz was installed)
  • C:\Program Files\Microsoft VS Code\bin (if Visual Studio Code was installed)

PICO_SDK_PATH

  • %userprofile%\pico-sdk

Build

  1. Clone the project from the repository (using the MSys2):
git clone https://github.com/robsonsmartins/usbflashprog.git
  1. Change to firmware/usbflashprog directory:
cd usbflashprog/firmware/usbflashprog
  1. Run the following commands:
mkdir build
cd build
cmake -G "MinGW Makefiles" ..
make -j$(nproc)
  1. The generated firmware binary will be in build/ directory, with the filename ufprog.uf2.

Debug [Optional]

To debug the firmware follow the tutorial Debugging the Raspberry Pi Pico in C/C++ with VS Code and MinGW for Windows (NO Build Tools for Visual Studio!).

Generate Doxygen Documentation [Optional]

  1. Clone the project from the repository (using the Git Bash Shell):
git clone https://github.com/robsonsmartins/usbflashprog.git
  1. Change to firmware/usbflashprog directory:
cd usbflashprog/firmware/usbflashprog
  1. Run the following commands:
doxygen

The documentation is generated under usbflashprog/docs/firmware/html directory.