I now have more than 180 repo’s in GitHub giving examples of experiments or full projects for the Pico and Pico 2 ecosystem. Spread between my JonDurrant identity and the newer DrJonEA Organisation. I am probably a bit brief in my explanations of how to build projects in the README files. So lets put a consistent guide here on how to work with my Pico and Pico 2 Projects.
Getting the Repo to your desktop
We need to download the repo to our local desktop environment to work with it. In GitHub terminology, this is called cloning. I normally use command line tools (alternatives latter in the article) and the git utility. So the following git command will pull the project into the current folder.
git clone <a href="https://github.com/jondurrant/RPIPico2WS2812BRings">https://github.com/jondurrant/RPIPico2WS2812BRings</a>
Note the project is given as a URL. It’s on GitHub under the account jondurrant and the project called RPIPico2WS2812Brings.
Sometimes people report issues cloning projects with HTTPS. It seems to be something to do with poor internet connections. I get into a conversation about this every six months or so. You can clone over SSH instead, but it has a more involved setup. Take a look at this article here.
Sub Repositories as Libraries
I don’t tend to copy and paste others’ code into my projects unless I have to. There are several reasons for this, but one of them is the simple traceability of the library and the version I am using. This does make cloning the library a bit more difficult because we have to tell GIT to recurse the submodules.
git clone --recurse-submodules <a href="https://github.com/jondurrant/RPIPico2WS2812BRings">https://github.com/jondurrant/RPIPico2WS2812BRings</a>
If you are like me then you forget to type the “–recurse-submodules” quite often. This means that the submodules are then just empty folders. Obviously, this breaks things. So to recover from this you can use the following GIT command to initialise the submodules.
git submodule update --init --recursive
Final note on Libraries and versions. I don’t use the head of the repo except when I have to. Repo head is kind of dangerous as often not a released version of code and therefore may have bugs or inconsistencies. So instead, I use a tagged version label. Some people have tried to repatch together a repo from my code using libraries from head of version and it creates an inconsistent code ball.
Project Anatomy
I’ve talked about project structure in a few vlogs, including this one. All my projects have a similar structure with the following consistent features.
- CMakeLists.txt: The top level make file. This include any library definitions and sets the Pico device name. It also sets the C/C++ version I am using and turns on exceptions if I need them.
- *.cmake: These are the library make definitions that I import.
- src: This folder has the main source folder code
- src/CMakeLists.txt: This is the project make file. It defines the source files for the project, the libraries to link and how STDIO is provided (Over UART or USB).
- lib: This is the library folder. On some projects, I place this elsewhere so I can share the libraries across projects. That is a dangerous strategy, but I do it with care where I have multiple experiments produced at the same time.
- port: This folder contains configuration or porting code for the libraries I am using
- build: This is the folder I build the project in. I never check this into the repo.
WiFi and other Credentials
Accidentally checking credentials into GitHub is a quick recipe for being hacked. Yet my makefiles need to often reference the credentials from WiFi access point details, to Web Service keys. My strategy for handling this is to define all these keys as environment variables. Then reference the environment variables within “src/CMakeLists.txt”.
The following two environmental variables are my WiFi credentials.
- WIFI_SSID: The WiFi Access Points SSID service name
- WIFI_PASSWORD: The password for the WiFi Accedd Point SSID
Command Line Build
Though I can build using an IDE like VSCode I mainly don’t. VSCode often injects clutter into the make files that then causes others to fall over. Mainly I build using a command-line install of the Pico Toolchain on a Mac or sometimes Ubuntu Linux.
To build a project I create a “build” folder inside the project. I then issue the command “cmake ..” to build the make system. Finally, I use the command “make” to build the binary. On some system “ninja” is used instead.
mkdir build
cd build
cmake ..
make
The binary is now in the folder “build/src”. This will contain an “elf” file, which we can use to flash the pico using openocd in SWD mode or picotools can use to load in bootsel mode. The folder also contains a “UF2” file, which can just be copied to the Pico when it is in bootsel model as if it were a flash drive.
VSCode Build
I did a vlog recently showing how you can go from GitHub to flashing a Pico all within VSCode. If everything goes smoothly, it is really easy. If something goes wrong, though, it can be frustrating to fix, in my experience. A few thoughts on things to check.
Has VSCode pulled down the submodules? In the vlog I show VSCode did an amazing job and pulled down all the submodules without me having to do anything. I have also had VSCode not do that, though and had to go in and manually initialise the submodules. Do check the submodules are initialised, look under the lib folder.
Import the project as a Pico project into the Pico Tools Extension. When you do this, you need to check the use of the CMake extension toggle. The project structure I shared above is too complex for the Pico Tools Extension to build on its own. In my experience, anything apart from the simplest project is too complex! So I always use the CMake extensions toggle.
Anything Else
This blog was a big of a brain dump on things to think about when replicating one of my repo projects. If there are other things I should add to this article, please let me know, and I will update. I am hoping this can become a linked article across my repos.
