You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# OpenLog Artemis : How To Compile The OLA Firmware Binary
2
2
3
-
These are _abbreviated_ instructions on how to compile the OLA firmware. It's more of an aide-memoire really... Sorry about that.
3
+
*[Using Docker](#using-docker)
4
+
*[How SparkFun does it](#how-sparkfun-does-it)
5
+
*[Using Arduino IDE (Deprecated)](#using-arduino-ide-deprecated)
4
6
5
-
## Install Arduino IDE
7
+
## Using Docker
8
+
9
+
Installing the correct version of the Apollo3 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 core or library installed, or forgot to patch the core correctly... It is much easier to sandbox the firmware compilation using an environment like [Docker](https://www.docker.com/).
10
+
11
+
Docker is open-source. It is our new favourite thing!
12
+
13
+
Here is a step-by-step guide for how to install Docker and compile the firmware from scratch:
14
+
15
+
### Clone, fork or download the OpenLog_Artemis repo
16
+
17
+
To build the OpenLog_Artemis firmware, you obviously need a copy of the source code.
18
+
19
+
If you are familiar with Git and GitHub Desktop, you can clone the OpenLog_Artemis repo directly into GitHub Desktop:
20
+
21
+
22
+
23
+
If you want to _contribute_ to OpenLog_Artemis, and already have a GitHub account, you can Fork the repo:
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.
28
+
29
+
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:
30
+
31
+
[](https://github.com/sparkfun/OpenLog_Artemis/archive/refs/heads/main.zip"Download ZIP (main branch)")
32
+
33
+
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...
34
+
35
+
[](https://github.com/sparkfun/OpenLog_Artemis/archive/refs/heads/release_candidate.zip"Download ZIP (release_candidate branch)")
36
+
37
+
### Install Docker Desktop
38
+
39
+
***(Optional)** Head to [Docker](https://www.docker.com/) and create an account. A free "Personal" account will cover occasional compilations of the firmware
40
+
* 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.
41
+
* Run the Desktop
42
+
* You don't _need_ to have an account and you don't _need_ to be signed in
43
+
* You only need to be signed in if you want to store or share your Container on Docker Hub
44
+
* If you don't sign in, Docker Desktop will run in Personal mode - which will cover local compilations of the firmware
45
+
* 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:
46
+
* Open a command prompt
47
+
* Type `wsl --update` to update WSL. At the time of writing, this installs Windows Subsystem for Linux 2.6.1
48
+
* Restart the Docker Desktop
49
+
* 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_
50
+
* On Windows, you may want to give Docker Desktop permission to access to your Network, so it can access (e.g.) HTML ports
51
+
* You can Stop the container and Delete it when you are done
52
+
* You may want to prevent Docker from running when your machine starts up
53
+
* Uncheck "Start Docker Desktop when you sign in to your computer" in the Desktop settings
54
+
55
+
### Using Docker to create the firmware binary
56
+
57
+
***Make sure you have Docker Desktop running.** You don't need to be signed in, but it needs to be running.
58
+
* Open a Command Prompt and `cd` into the OpenLog_Artemis folder
59
+
* Check you are in the right place. Type `dir` and hit enter. You should see the following files and folders:
60
+
61
+
```
62
+
.gitattributes
63
+
.github
64
+
.gitignore
65
+
ADDING_SENSORS.md
66
+
Binaries
67
+
CHANGELOG.md
68
+
COMPILE_BINARY.md
69
+
CONTRIBUTING.md
70
+
Firmware
71
+
```
72
+
73
+
*`cd Firmware` and then `dir` again. You should see:
74
+
75
+
```
76
+
compile_with_docker.bat
77
+
Dockerfile
78
+
Extras
79
+
OpenLog_Artemis
80
+
Test Sketches
81
+
```
82
+
83
+
* The file that does most of the work is the `Dockerfile`. You can run the Dockerfile manually to create a container and image, from which you can extract the firmware binary.
84
+
85
+
* But, if you're short on time, simply run `compile_with_docker.bat`. It does everything for you:
86
+
87
+
88
+
89
+
* Hey presto! You have your newly compiled firmware binary!
90
+
91
+
You can then use the [SparkFun Artemis Uploader App](https://github.com/sparkfun/Artemis-Firmware-Upload-GUI) to upload the binary onto the Artemis. See [UPGRADE](./UPGRADE.md) for more instructions.
92
+
93
+
On Linux, you will need to convert `compile_with_docker.bat` into a shell script. Or run each of the four docker commands manually to: build the image, create the container, extract the firmware binary, and delete the container:
At SparkFun, we use GitHub Actions and a Workflow to compile each release of the OpenLog Artemis firmware. We run the [compilation workflow](https://github.com/sparkfun/OpenLog_Artemis/blob/main/.github/workflows/build-for-release.yml) directly on GitHub. A virtual ubuntu machine installs the [Arduino CLI](https://github.com/arduino/arduino-cli/releases), installs the Apollo3 Arduino core, patches the core in a couple of places, installs all the required libraries at the required version, and generates the firmware binary for the Artemis. That binary is either uploaded as an Artifact (by [non-release-build](https://github.com/sparkfun/OpenLog_Artemis/blob/main/.github/workflows/non-release-build.yml)) or pushed to the [Binaries Folder](https://github.com/sparkfun/OpenLog_Artemis/tree/main/Binaries) (by [compilation workflow](https://github.com/sparkfun/OpenLog_Artemis/blob/main/.github/workflows/build-for-release.yml)).
105
+
106
+
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.
107
+
108
+
You can then download the firmware binary and use the [SparkFun Artemis Uploader App](https://github.com/sparkfun/Artemis-Firmware-Upload-GUI) to upload the binary onto the Artemis. See [UPGRADE](./UPGRADE.md) for more instructions.
109
+
110
+
## Using Arduino IDE (Deprecated)
111
+
112
+
We strongly suggest using Docker to compile the binary, it is **much** easier.
113
+
114
+
These are _abbreviated_ instructions on how to compile the OLA firmware using Arduino IDE. It's more of an aide-memoire really... Sorry about that.
115
+
116
+
### Install Arduino IDE
6
117
7
118
Tested version: 1.8.19
8
119
9
120
(IDE version 2 has not been tested)
10
121
11
-
## Add Apollo3 To The Additional Boards Manager URLs
122
+
###Add Apollo3 To The Additional Boards Manager URLs
12
123
13
124
Open `File \ Preferences`
14
125
@@ -26,15 +137,15 @@ Click OK
26
137
27
138
Close and re-open the IDE
28
139
29
-
## Install the Apollo3 Board Package
140
+
###Install the Apollo3 Board Package
30
141
31
142
Open `Tools \ Board \ Boards Manager`
32
143
33
144
Enter `Apollo3` in the search box
34
145
35
146
Install the SparkFun Apollo3 Boards. Tested version: 2.2.1
36
147
37
-
## Install All The Required Libraries
148
+
###Install All The Required Libraries
38
149
39
150
Copy and paste the following into an empty sketch. Click on each link in turn to install the libraries via the Library Manager:
40
151
@@ -72,25 +183,26 @@ Copy and paste the following into an empty sketch. Click on each link in turn to
The Apollo3 core (2.2.1) requires patching - using code kindly provided by Paulvha. For more information, open [this link](https://github.com/sparkfun/OpenLog_Artemis/issues/117#issuecomment-1085881142) in a web browser.
106
218
@@ -121,42 +233,18 @@ Unzip it (Extract All files)
121
233
122
234
Follow the instructions contained in `uart_power_3.odt`
123
235
124
-
In summary: replace the following five files with the ones from `UartPower3.zip` :
236
+
In summary: replace the following six files with the ones from `UartPower3.zip` :
0 commit comments