Add Dockerfile

Author: PaulZC

Firmware/Dockerfile

@@ -0,0 +1,119 @@
+FROM ubuntu:latest AS upstream
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+ENV FILENAME_PREFIX=RTK_Firmware
+ENV FIRMWARE_VERSION_MAJOR=99
+ENV FIRMWARE_VERSION_MINOR=99
+ENV CORE_VERSION=2.0.2
+
+# ESP32 Core Debug Level
+# We use "none" for releases and "error" for release_candidate
+# You may find "verbose" useful while you are debugging your changes
+ENV DEBUG_LEVEL=error
+
+# Developer Mode
+# You may find "true" useful while you are making changes
+# Set to false for releases
+ENV ENABLE_DEVELOPER=true
+
+# If you have your own u-blox PointPerfect token, define it here
+# or pass it in as an arg when building the Dockerfile
+ARG POINTPERFECT_TOKEN=0xAA,0xBB,0xCC,0xDD,0x00,0x11,0x22,0x33,0x0A,0x0B,0x0C,0x0D,0x00,0x01,0x02,0x03
+
+# Get curl and python3
+RUN apt-get update \
+    && apt-get install -y curl python3 python3-pip python3-venv python-is-python3 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Avoid the externally managed environment constraint
+RUN PYTHON_VER=$(ls /usr/lib | grep python3.) \
+    && echo "Python version: ${PYTHON_VER}" \
+    && rm /usr/lib/${PYTHON_VER}/EXTERNALLY-MANAGED
+
+# Install Python dependencies - esptool needs pyserial
+#RUN python3 -m pip install --upgrade pip && \
+RUN pip install pyserial
+
+# Setup Arduino CLI
+#RUN curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=/usr/local/bin sh
+RUN curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
+
+# Start config file
+RUN arduino-cli config init --additional-urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json,https://espressif.github.io/arduino-esp32/package_esp32_dev_index.json
+
+# Update core index
+RUN arduino-cli core update-index
+
+# Update library index
+RUN arduino-cli lib update-index
+
+# Install platform
+RUN arduino-cli core install "esp32:esp32@${CORE_VERSION}"
+
+# Get Known Libraries
+RUN arduino-cli lib install ArduinoJson@6.19.4
+RUN arduino-cli lib install ESP32Time@2.0.0
+RUN arduino-cli lib install ESP32_BleSerial@1.0.5
+RUN arduino-cli lib install "ESP32-OTA-Pull"@1.0.0
+RUN arduino-cli lib install Ethernet@2.0.2
+RUN arduino-cli lib install JC_Button@2.1.2
+RUN arduino-cli lib install PubSubClient@2.8.0
+RUN arduino-cli lib install "SdFat"@2.1.1
+RUN arduino-cli lib install "SparkFun LIS2DH12 Arduino Library"@1.0.3
+RUN arduino-cli lib install "SparkFun MAX1704x Fuel Gauge Arduino Library"@1.0.4
+RUN arduino-cli lib install "SparkFun u-blox GNSS v3"@3.0.14
+RUN arduino-cli lib install "SparkFun_WebServer_ESP32_W5500"@1.5.5
+RUN arduino-cli lib install "SparkFun Qwiic OLED Arduino Library"@1.0.13
+RUN arduino-cli lib install SSLClientESP32@2.0.0
+
+# Enable external libs
+RUN arduino-cli config set library.enable_unsafe_install true
+
+# Get external libs
+RUN arduino-cli lib install --git-url https://github.com/me-no-dev/ESPAsyncWebServer.git
+RUN arduino-cli lib install --git-url https://github.com/me-no-dev/AsyncTCP.git
+
+# Copy RTK_Everywhere into /work and build deployment image
+FROM upstream AS deployment
+
+# Create work directory
+WORKDIR /work
+ADD . .
+
+# Get current date
+#RUN echo "$(date +'%b_%d_%Y')" > date_scores.txt
+#RUN DATE_SCORES=$(cat date_scores.txt) && echo "Date: ${DATE_SCORES}"
+#RUN echo "$(date +'%b %d %Y')" > date_no_scores.txt
+#RUN DATE_NO_SCORES=$(cat date_no_scores.txt) && echo "Date: ${DATE_NO_SCORES}"
+
+# Patch Server.h to avoid https://github.com/arduino-libraries/Ethernet/issues/88#issuecomment-455498941
+WORKDIR /work/RTK_Surveyor/Patch
+RUN cp Server.h "/root/.arduino15/packages/esp32/hardware/esp32/${CORE_VERSION}/cores/esp32/Server.h"
+
+# Update form.h with index_html and main_js
+WORKDIR /work/Tools
+RUN python index_html_zipper.py ../RTK_Surveyor/AP-Config/index.html ../RTK_Surveyor/form.h
+RUN python main_js_zipper.py ../RTK_Surveyor/AP-Config/src/main.js ../RTK_Surveyor/form.h
+
+# Copy custom app3M_fat9M_16MB.csv
+WORKDIR /work
+RUN cp app3M_fat9M_16MB.csv "/root/.arduino15/packages/esp32/hardware/esp32/${CORE_VERSION}/tools/partitions/app3M_fat9M_16MB.csv"
+
+# Compile Sketch
+WORKDIR /work/RTK_Surveyor
+RUN arduino-cli compile --fqbn "esp32:esp32:esp32":DebugLevel=${DEBUG_LEVEL} \
+    ./RTK_Surveyor.ino \
+    --build-property build.partitions=app3M_fat9M_16MB \
+    --build-property upload.maximum_size=3145728 \
+    --build-property "compiler.cpp.extra_flags=\"-DPOINTPERFECTTOKEN=${POINTPERFECT_TOKEN}\" \
+    \"-DFIRMWARE_VERSION_MAJOR=${FIRMWARE_VERSION_MAJOR}\" \
+    \"-DFIRMWARE_VERSION_MINOR=${FIRMWARE_VERSION_MINOR}\" \
+    \"-DENABLE_DEVELOPER=${ENABLE_DEVELOPER}\"" \
+    --export-binaries
+
+# Copy the compile output. List the files
+FROM deployment AS output
+COPY --from=deployment /work/RTK_Surveyor/build/esp32.esp32.esp32 /
+CMD echo $(ls /*.*)

docs/firmware_update.md

@@ -273,9 +273,178 @@ As of writing, no additional releases of the NEO-D9S firmware have been made.
 
 ## Compiling Source
 
-### Windows
+This is information about how to compile the RTK Firmware from source. This is for advanced users who would like to modify the functionality of the RTK products.
+
+* [How SparkFun does it](#how-sparkfun-does-it)
+* [Using Docker](#using-docker)
+* [Compiling on Windows (Deprecated)](#compiling-on-windows-deprecated)
+* [Compiling on Ubuntu 20.04 (Deprecated)](#compiling-on-ubuntu-2004-deprecated)
+
+## How SparkFun does it
+
+At SparkFun, we use GitHub Actions and a Workflow to compile each release of RTK Firmware. We run the [compilation workflow](https://github.com/sparkfun/SparkFun_RTK_Firmware/blob/main/.github/workflows/compile-rtk-firmware.yml) directly on GitHub. A virtual ubuntu machine installs the [Arduino CLI](https://github.com/arduino/arduino-cli/releases), installs the correct ESP32 Arduino core, patches the core in a couple of places, installs all the required libraries at the required version, converts the embedded HTML and Bootstrap JavaScript to binary zip format, and generates the firmware binary for the ESP32. That binary is either uploaded as an Artifact (by [non-release-build](https://github.com/sparkfun/SparkFun_RTK_Firmware/blob/main/.github/workflows/non-release-build.yml)) or pushed to the [SparkFun RTK Firmware Binaries](https://github.com/sparkfun/SparkFun_RTK_Firmware_Binaries) repo (by the [compilation workflow](https://github.com/sparkfun/SparkFun_RTK_Firmware/blob/main/.github/workflows/compile-rtk-firmware.yml)).
+
+You are welcome to clone or fork this repo and do the exact same thing yourself. But you may need a paid GitHub Pro account to run the GitHub Actions, especially if you keep your clone / fork private.
+
+If you run the [compilation workflow](https://github.com/sparkfun/SparkFun_RTK_Firmware/blob/main/.github/workflows/compile-rtk-firmware.yml), it will compile the firmware and attempt to push the binary to the Binaries repo. This will fail as your account won't have the right permissions. The [non-release-build](https://github.com/sparkfun/SparkFun_RTK_Firmware/blob/main/.github/workflows/non-release-build.yml) is the one for you. The firmware binary will be attached as an Artifact to the workflow run. Navigate to Actions \ Non-Release Build, select the latest run of Non-Release Build, the binary is in the Artifacts.
+
+You can then use the [SparkFun RTK Firmware Uploader](https://github.com/sparkfun/SparkFun_RTK_Firmware_Uploader) to upload the binary onto the ESP32.
+
+## Using Docker
+
+Installing the correct version of the ESP32 core and of each required Arduino library, is tedious and error-prone. Especially on Windows. We've lost count of the number of times code compilation fails on our local machines, because we had the wrong ESP32 core installed, or forgot to patch Server.h... It is much easier to sandbox the firmware compilation using an environment like [Docker](https://www.docker.com/).
+
+Here is a step-by-step guide for how to install Docker and compile the firmware from scratch:
+
+### Clone, fork or download the RTK Firmware repo
+
+To build the RTK Firmware, you obviously need a copy of the source code.
+
+If you are familiar with Git and GitHub Desktop, you can clone the RTK Firmware repo directly into GitHub Desktop:
+
+<figure markdown>
+![Clone RTK Firmware with GitHub Desktop](./img/CompileSource/Clone_Repo_To_GitHub_Desktop.png)
+<figcaption markdown>
+Clone RTK Firmware with GitHub Desktop
+</figcaption>
+</figure>
+
+If you want to _contribute_ to the RTK Firmware, and already have a GitHub account, you can Fork the repo:
+
+<figure markdown>
+![Fork RTK Firmware](./img/CompileSource/Fork_Repo.png)
+<figcaption markdown>
+Fork a copy of RTK Firmware
+</figcaption>
+</figure>
+
+Clone your fork to your local machine, make changes, and send us a Pull Request. This is exactly what the SparkFun Team do when developing the code. Please use the `release_candidate` branch for any such changes. We are very unlikely to merge anything directly into `main`, unless it is (e.g.) docs corrections or improvements.
+
+If you don't want to do either of those, you can simply Download a Zip copy of the repo instead. You will receive a complete copy as a Zip file. You can do this from the green **Code** button, or click on the icon below to download a copy of the main (released) branch:
+
+[![Download ZIP](./img/CompileSource/Download_Zip.png)](https://github.com/sparkfun/SparkFun_RTK_Firmware/archive/refs/heads/main.zip "Download ZIP (main branch)")
+
+For the real Wild West experience, you can also download a copy of the `release_candidate` code branch. This is where the team is actively changing and testing the code, before it becomes a full release. The code there will _usually_ compile and will _usually_ work, but we don't guarantee it! We may be part way through implementing some breaking changes at the time of your download...
+
+[![Download ZIP - release candidate](./img/CompileSource/Download_Zip.png)](https://github.com/sparkfun/SparkFun_RTK_Firmware/archive/refs/heads/release_candidate.zip "Download ZIP (release_candidate branch)")
+
+### Install Docker Desktop
+
+* Head to [Docker](https://www.docker.com/) and create an account. A free "Personal" account will cover occasional compilations of the firmware
+* Download and install [Docker Desktop](https://docs.docker.com/get-started/get-docker/) - there are versions for Mac, Windows and Linux. You may need to restart to complete the installation.
+* Run the Desktop and sign in
+* On Windows, you may see an error saying "**WSL needs updating** Your version of Windows Subsystem for Linux (WSL) is too old". If you do:
+    * Open a command prompt
+	* Type `wsl --update` to update WSL. At the time of writing, this installs Windows Subsystem for Linux 2.6.1
+	* Restart the Docker Desktop
+* If you are using Docker for the first time, the "What is a container?" and "How do I run a container?" demos are useful
+    * On Windows, you may want to give Docker Desktop permission to access to your Network, so it can access (e.g.) HTML ports
+	* You can Stop the container and Delete it when you are done
+* You may want to prevent Docker from running when your machine starts up
+    * Uncheck "Start Docker Desktop when you sign in to your computer" in the Desktop settings
+
+### Running the Dockerfile to create an Image
+
+* **Make sure you have Docker Desktop running.** You don't need to be logged in, but it needs to be running.
+* Open a Command Prompt and `cd` into the SparkFun_RTK_Firmware folder
+* Check you are in the right place. Type `dir` and hit enter. You should see the following files and folders:
+
+```
+    .gitattributes
+    .github
+    .gitignore
+    docs
+    Firmware
+    Graphics
+    Issue_Template.md
+    License.md
+    README.md
+```
+
+* `cd Firmware` and then `dir` again. You should see:
+
+```
+    app3M_fat9M_16MB.csv
+    Dockerfile
+    readme.md
+    RTKFirmware.csv
+    RTK_Surveyor
+```
+
+* The file we will be using is the `Dockerfile`.
+* Type:
+
+```
+docker build -t rtk_firmware .
+```
+
+![Dockerfile starting](./img/CompileSource/Dockerfile_starting.png)
+
+![Dockerfile complete](./img/CompileSource/Dockerfile_complete.png)
+
+* If you want to see the full build progress including the output of echo or ls, use:
+
+```
+docker build -t rtk_firmware --progress=plain .
+```
+
+* If you want to rebuild the image completely from scratch, without using the cache, use:
+
+```
+docker build -t rtk_firmware --progress=plain --no-cache .
+```
+
+Building the full Image from scratch is slow, taking several minutes. You should only need to do it once - unless you make any changes to the Dockerfile.
+
+* When you make changes to the source code and want to recompile, use:
+
+```
+docker build -t rtk_firmware --no-cache-filter deployment .
+```
+
+This uses the cache for the `upstream` stage and avoids recreating the full ubuntu machine. But it ignores the cache for the `deployment` stage, ensuring the code is recompiled.
+
+### Access the firmware by running the Image
+
+In Docker Desktop, in the Images tab, you should now be able to see an Image named `rtk_firmware`. We now need to Run that Image to access the firmware binary. Click the triangular Run icon under Actions:
+
+![Docker image ready to run](./img/CompileSource/Docker_Image.png)
+
+Running the Image will create a Container, through which we can access the output of the arduino-cli code compilation.
+
+By default, the Container name is random. To avoid this, we define one in the **Optional settings** :
+
+![Docker Container - named rtk_container](./img/CompileSource/Docker_Container.png)
+
+Run the Container and you should see:
+
+![Container is complete](./img/CompileSource/Container_complete.png)
+
+In the Command Prompt, type the following :
+
+```
+docker cp rtk_container:/RTK_Surveyor.ino.bin .
+```
+
+Hey presto! A file called `RTK_Surveyor.ino.bin` appears in the current directory. That's the firmware binary we are going to upload to the ESP32.
+
+![Firmware binary](./img/CompileSource/Firmware_binary.png)
+
+If you need the `.elf` file so you can debug code crashes with me-no-dev's [ESP ExceptionDecoder](https://github.com/me-no-dev/EspExceptionDecoder):
+
+```
+docker cp rtk_container:/RTK_Surveyor.ino.elf .
+```
+
+If you want the files to appear in a more convenient directory, replace the single `.` with a folder path.
+
+Delete the `rtk_container` container afterwards, to save disk space and so you can reuse the same container name next time. If you forget, you will see an error:
+
+```Conflict. The container name "/rtk_container" is already in use by container. You have to remove (or rename) that container to be able to reuse that name.```
+
+### Compiling on Windows (Deprecated)
 
-The SparkFun RTK firmware is compiled using Arduino (currently v1.8.15). To compile:
+The SparkFun RTK Firmware is compiled using Arduino (currently v1.8.15). To compile:
 
 1. Install [Arduino](https://www.arduino.cc/en/software).
 
@@ -353,7 +522,7 @@ The following libraries are only available via GitHub:
 
     * [SparkFun Micro OLED Breakout](https://github.com/sparkfun/SparkFun_Micro_OLED_Arduino_Library)
 
-### Ubuntu 20.04
+### Compiling on Ubuntu 20.04 (Deprecated)
 
 #### Virtual Machine