Skip to content

Commit acc7b2d

Browse files
committed
Update docs - add compilation instructions
1 parent 9f1191f commit acc7b2d

File tree

2 files changed

+70
-0
lines changed

2 files changed

+70
-0
lines changed

docs/assets/img/Download_Zip.png

1.24 KB
Loading

docs/software_overview.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -439,3 +439,73 @@ The **[/Firmware/Binaries](https://github.com/sparkfun/SparkFun_GNSSDO/tree/main
439439

440440
You can update or reload the firmware using the [SparkFun RTK Firmware Uploader](https://github.com/sparkfun/SparkFun_RTK_Firmware_Uploader).
441441

442+
## :fontawesome-solid-screwdriver-wrench: Compiling Firmware
443+
444+
The GNSSDO Firmware can be compiled locally using Docker:
445+
446+
### Clone, fork or download the GNSSDO repo
447+
448+
To build the GNSSDO Firmware, you obviously need a copy of the source code.
449+
450+
Click on the icon below to download a copy of the main (released) branch:
451+
452+
[![Download ZIP](./assets/img/Download_Zip.png)](https://github.com/sparkfun/SparkFun_GNSSDO/archive/refs/heads/main.zip "Download ZIP (main branch)")
453+
454+
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...
455+
456+
[![Download ZIP - release candidate](./assets/img/Download_Zip.png)](https://github.com/sparkfun/SparkFun_GNSSDO/archive/refs/heads/release_candidate.zip "Download ZIP (release_candidate branch)")
457+
458+
### Install Docker Desktop
459+
460+
* **(Optional)** Head to [Docker](https://www.docker.com/) and create an account. A free "Personal" account will cover occasional compilations of the firmware
461+
* 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.
462+
* Run the Desktop
463+
* You don't _need_ to have an account and you don't _need_ to be signed in
464+
* You only need to be signed in if you want to store or share your Container on Docker Hub
465+
* If you don't sign in, Docker Desktop will run in Personal mode - which will cover local compilations of the firmware
466+
* 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:
467+
* Open a command prompt
468+
* Type `wsl --update` to update WSL. At the time of writing, this installs Windows Subsystem for Linux 2.6.1
469+
* Restart the Docker Desktop
470+
* If you are using Docker for the first time, the "What is a container?" and "How do I run a container?" demos are useful - _but not essential_
471+
* On Windows, you may want to give Docker Desktop permission to access to your Network, so it can access (e.g.) HTML ports
472+
* You can Stop the container and Delete it when you are done
473+
* You may want to prevent Docker from running when your machine starts up
474+
* Uncheck "Start Docker Desktop when you sign in to your computer" in the Desktop settings
475+
476+
### Using Docker to create the firmware binary
477+
478+
* **Make sure you have Docker Desktop running.** You don't need to be signed in, but it needs to be running.
479+
* Open a Command Prompt and `cd` into the SparkFun_GNSSDO folder
480+
* Check you are in the right place. Type `dir` and hit enter. You should see the following files and folders:
481+
482+
```
483+
.gitattributes
484+
.github
485+
.gitignore
486+
CONTRIBUTING.md
487+
docs
488+
Firmware
489+
```
490+
491+
* `cd Firmware` and then `dir` again. You should see:
492+
493+
```
494+
app3M_fat9M_16MB.csv
495+
Binaries
496+
compile_with_docker.bat
497+
Dockerfile
498+
GNSSDO_Firmware
499+
Utils
500+
```
501+
502+
* The file that does most of the work is the `Dockerfile`
503+
504+
* Run `compile_with_docker.bat` to compile the firmware. It does everything for you
505+
506+
* Type `dir` again. Hey presto! You have your newly compiled firmware binary!
507+
508+
You can then use (e.g.) the [SparkFun RTK Firmware Uploader](https://github.com/sparkfun/SparkFun_RTK_Firmware_Uploader) to upload the binary onto the ESP32.
509+
510+
You may find the `.elf` file useful if you are trying to debug the code with [me-no-dev's Exception Decoder](https://github.com/me-no-dev/EspExceptionDecoder).
511+

0 commit comments

Comments
 (0)