Use docker to build locally and in CI (#26)

This adds docker configuration files so that PrawnBlaster firmware can be built within a docker container on personal devices and in GitHub actions.

## Changes

- Updates the pico-sdk to v1.5.1
- Remove uf2 files from the repository
- Add docker file to build a container designed to build rp2040 firmware using the pico-sdk
- Pin pico-sdk version via the docker file
- Update license to 3-clause BSD license (from 2-clause BSD license) and add missing license file to the repository
- Added GitHub action script that builds artefacts (containing the uf2 files) for pull requests and releases when commits are tagged.

Author: philipstarkey

.github/workflows/build.yaml

@@ -0,0 +1,39 @@
+name: Build firmware
+
+on:
+  create:
+    tags:
+      - '[0-9]+\.[0-9]+\.[0-9]+*'
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+
+jobs:
+  build-firmware:
+    runs-on: ubuntu-latest
+    name: Build firmware
+    steps:
+      - name: Check out this repository
+        uses: actions/checkout@v3
+
+      - name: Build Docker image
+        run: docker compose build --pull --build-arg APT_MIRROR="http://azure.archive.ubuntu.com/ubuntu/"
+
+      - name: Run docker container
+        run: docker compose up
+
+      - name: Upload firmware as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: prawnblaster-firmware-${{ github.sha }}
+          path: build/prawnblaster/*.uf2
+
+      - name: Create release
+        if: ${{ github.event.ref_type == 'tag' }}
+        uses: "marvinpinto/action-automatic-releases@latest"
+        with:
+          repo_token: "${{ secrets.GITHUB_TOKEN }}"
+          prerelease: false
+          files: |
+            LICENSE.txt
+            build/prawnblaster/prawnblaster.uf2
+            build/prawnblaster/prawnblasteroverclock.uf2

LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright 2021, Philip Starkey
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of
+conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list
+of conditions and the following disclaimer in the documentation and/or other materials
+provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be
+used to endorse or promote products derived from this software without specific prior
+written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

build/prawnblaster/prawnblaster.uf2

@@ -0,0 +1,11 @@
+name: prawnblaster
+
+services:
+  buildfirmware:
+    build:
+      dockerfile: docker/Dockerfile
+    command: /bin/bash -c 'cmake .. && make'
+    volumes:
+      - .:/prawnblaster
+    working_dir: /prawnblaster/build
+    init: true

build/prawnblaster/prawnblasteroverclock.uf2

@@ -0,0 +1,29 @@
+# Fetch ubuntu image
+FROM ubuntu:latest AS base
+# Attempt to auto-detect the best mirror (desn't always work well though)
+ARG APT_MIRROR="mirror://mirrors.ubuntu.com/mirrors.txt"
+# Use this one if you are in Australia
+# ARG APT_MIRROR="http://mirror.aarnet.edu.au/pub/ubuntu/archive/"
+
+# Configure mirror. Pass --build-arg APT_MIRROR=<mirror URL> to set a mirror if this is slow
+RUN sed -i "s#htt[p|ps]://archive.ubuntu.com/ubuntu/#$APT_MIRROR#g" /etc/apt/sources.list
+
+# Install packages
+RUN \
+    apt update && \
+    apt install -y git python3 && \
+    apt install -y cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential
+
+# Install Pico SDK into a new stage
+FROM base as buildtools
+
+RUN \
+    mkdir -p /pico/ && \
+    cd /pico/ && \
+    git clone https://github.com/raspberrypi/pico-sdk.git --branch 1.5.1 && \
+    cd pico-sdk/ && \
+    git submodule update --init && \
+    cd /
+    
+# Set the Pico SDK environment variable
+ENV PICO_SDK_PATH=/pico/pico-sdk/

docker-compose.yaml

@@ -12,7 +12,7 @@
 # This file is used to flash a Raspberry Pi Pico microcontroller      #
 # prototyping board to create a PrawnBlaster (see readme.txt and      #
 # http://hardware.labscriptsuite.org).                                #
-# This file is licensed under the Simplified BSD License.             #
+# This file is licensed under the 3-clause BSD License.               #
 # See the license.txt file for the full license.                      #
 #                                                                     #
 #######################################################################
@@ -33,9 +33,9 @@
 #include "pseudoclock.pio.h"
 
 #ifndef PRAWNBLASTER_OVERCLOCK
-const char VERSION[16] = "1.0.0";
+const char VERSION[16] = "1.0.1";
 #else
-const char VERSION[16] = "1.0.0-overclock";
+const char VERSION[16] = "1.0.1-overclock";
 #endif //PRAWNBLASTER_OVERCLOCK
 
 int DEBUG;

docker/Dockerfile

@@ -9,7 +9,7 @@
 ;# This file is used to flash a Raspberry Pi Pico microcontroller      #
 ;# prototyping board to create a PrawnBlaster (see readme.txt and      #
 ;# http://hardware.labscriptsuite.org).                                #
-;# This file is licensed under the Simplified BSD License.             #
+;# This file is licensed under the 3-clause BSD License.               #
 ;# See the license.txt file for the full license.                      #
 ;#                                                                     #
 ;#######################################################################

prawnblaster/prawnblaster.cpp

@@ -28,7 +28,7 @@ Note 2: The internal clock can be configured to run at up to 133 MHz. We set it
 You can increase the clock frequency at runtime (via a serial command) which scales the timing specifications accordingly.
 
 ## How to flash the firmware
-Download the latest [prawnblaster.uf2 file](https://github.com/labscript-suite/PrawnBlaster/blob/master/build/prawnblaster/prawnblaster.uf2).
+Download the latest [prawnblaster.uf2 file](https://github.com/labscript-suite/PrawnBlaster/releases/latest/download/prawnblaster.uf2).
 On your Raspberry Pi Pico, hold down the "bootsel" button while plugging the Pico into USB port on a PC (that must already be turned on).
 The Pico should mount as a mass storage device (if it doesn't, try again or consult the Pico documentation).
 Drag and drop the `.uf2` file into the mounted mass storage device.
@@ -120,6 +120,26 @@ An external clock of 100MHz means a minimum half-period of `5/100MHz=50ns`.
 Note: Officially, the documentation for the Pico says external clock sources can only be up to 50MHz. We have successfully tested up to 125MHz (see [#6](https://github.com/labscript-suite/PrawnBlaster/issues/6)).
 We recommend you personally verify the output of the PrawnBlaster is as expected if running from an external reference above 50MHz.
 
+## Compiling the firmware
+
+If you want to make changes to the firmware, or want to compile it yourself (because you don't trust binary blobs from the internet), we provide a docker configuration to help you do that.
+
+1. Install docker desktop and make sure it is running (if you are on Windows, you may have to mess around a bit to get virtualisation working at an operating system level)
+2. Clone this repository
+3. Open a terminal with the current working directory set to the repository root (the `docker-compose.yaml`` file should be there)
+4. Run `docker compose build --pull` to build the docker container
+5. Run `docker compose up` to build the PrawnBlaster firmware.
+
+Step 4 will take a while as it has to build the docker container.
+If it is slow to download packages from the Ubuntu package repositories, consider providing an explicit apt mirror that is fast for you: `docker compose build --pull --build-arg APT_MIRROR="http://azure.archive.ubuntu.com/ubuntu/"`.
+
+If you want to change which version of the pico SDK it builds against, this is set in the `build/docker/Dockerfile` file.
+Just change the git tag of the pico SDK that gets cloned out by git, then rebuild the docker container (see step 4).
+
+Note once the docker container is built, you can run step 5 as many times as you like.
+You do not need to rebuild the container, even if you make changes to the PrawnBlaster source code.
+You only need to rebuild the docker container if you modify the `build/docker/Dockerfile` file.
+
 ## FAQ:
 
 ### Why is it called a "PrawnBlaster"?
@@ -150,7 +170,7 @@ If you want to find out what pins, you should
 
 ### Can I overclock the Pico board?
 Yes, some people have reported being able to significantly overclock their Raspberry Pi Pico boards.
-While we do not recommend you do so (nor will we be liable for any damage to your Pico or attached devices should you overclock it), we have provided a version of the PrawnBlaster firmware with no upper limit to the clock frequency [here](https://github.com/labscript-suite/PrawnBlaster/blob/master/build/prawnblaster/prawnblasteroverclock.uf2).
+While we do not recommend you do so (nor will we be liable for any damage to your Pico or attached devices should you overclock it), we have provided a version of the PrawnBlaster firmware with no upper limit to the clock frequency [here](https://github.com/labscript-suite/PrawnBlaster/releases/latest/download/prawnblasteroverclock.uf2).
 Use at your own risk!
 We provide no support for the overclockable firmware.
 If you need to tweak any other operating parameters of the Pico in order to achieve a stable overclock, you will need to manually modify the firmware source code and recompile it with those changes.