diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 0000000..ccd096b --- /dev/null +++ b/.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 diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..ab08c82 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/build/prawnblaster/prawnblaster.uf2 b/build/prawnblaster/prawnblaster.uf2 deleted file mode 100644 index 25bd19e..0000000 Binary files a/build/prawnblaster/prawnblaster.uf2 and /dev/null differ diff --git a/build/prawnblaster/prawnblasteroverclock.uf2 b/build/prawnblaster/prawnblasteroverclock.uf2 deleted file mode 100644 index 32c4928..0000000 Binary files a/build/prawnblaster/prawnblasteroverclock.uf2 and /dev/null differ diff --git a/docker-compose.yaml b/docker-compose.yaml new file mode 100644 index 0000000..4771131 --- /dev/null +++ b/docker-compose.yaml @@ -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 diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..4ed746c --- /dev/null +++ b/docker/Dockerfile @@ -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= 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/ diff --git a/prawnblaster/prawnblaster.cpp b/prawnblaster/prawnblaster.cpp index 010a0ea..6366f7f 100644 --- a/prawnblaster/prawnblaster.cpp +++ b/prawnblaster/prawnblaster.cpp @@ -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; diff --git a/prawnblaster/pseudoclock.pio b/prawnblaster/pseudoclock.pio index 05051e4..ececb7b 100644 --- a/prawnblaster/pseudoclock.pio +++ b/prawnblaster/pseudoclock.pio @@ -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. # ;# # ;####################################################################### diff --git a/readme.md b/readme.md index 59baae6..882e2e2 100644 --- a/readme.md +++ b/readme.md @@ -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.