Skip to content

Commit 90557e8

Browse files
LeeLeahy2LeeLeahy2
committed
Firmware Build Documentation for Ubuntu
1 parent 3b1bd78 commit 90557e8

File tree

2 files changed

+213
-3
lines changed

2 files changed

+213
-3
lines changed

‎docs/firmware_build.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Building LoRaSerial Firmware
2+
3+
The open source [LoRaSerial firmware](https://github.com/sparkfun/SparkFun_LoRaSerial) builds under Windows and Linux. Use the following procedures to setup the environment and perform the build:
4+
5+
* [Windows](http://docs.sparkfun.com/SparkFun_LoRaSerial/firmware_build/#Windows)
6+
* [Linux](http://docs.sparkfun.com/SparkFun_LoRaSerial/firmware_build/#Linux)
7+
8+
# Virtual Machine
9+
10+
Execute the following commands in the [VirualBox](https://www.virtualbox.org/) application to create a virtual machine:
11+
12+
1. Click on the Machine menu item
13+
2. Click on the New submenu item
14+
3. Specify the machine Name, e.g.: Sparkfun_LoRaSerial_22.04.1
15+
4. Select Type, e.g.: Linux
16+
5. Select Version, e.g.: Ubuntu (64-bit)
17+
6. Click the Next> button
18+
7. Select the memory size: 7168
19+
8. Click the Next> button
20+
9. Click on Create a virtual hard disk now
21+
10. Click the Create button
22+
11. Select VDI (VirtualBox Disk Image)
23+
12. Click the Next> button
24+
13. Select Dynamically allocated
25+
14. Click the Next> button
26+
15. Select the disk size: 128 GB
27+
16. Click the Create button
28+
17. Click on the Settings button
29+
18. Click on Storage
30+
19. Click the empty CD icon
31+
20. On the right-hand side, click the CD icon
32+
21. Click on Choose a disk file...
33+
An operating system is needed for the virtual machine to enable it to run applications. Download one of the following operating system images (.iso files):
34+
35+
* [Ubuntu Desktop (Linux)](https://ubuntu.com/download/desktop)
36+
* Windows
37+
38+
22. Choose one of the .iso files downloaded above
39+
23. Click the Open button
40+
24. Click on Network
41+
25. Under 'Attached to:' select Bridged Adapter
42+
26. Click the OK button
43+
27. Click the Start button
44+
28. Install the operating system
45+
29. Log into the operating system
46+
47+
* For Ubuntu:
48+
1. Click on Activities
49+
2. Type terminal into the search box
50+
3. In the terminal window
51+
a. sudo apt install -y net-tools openssh-server
52+
b. ifconfig
53+
54+
Write down the IP address
55+
56+
4. On the PC (Linux) in a terminal window
57+
a. ssh-keygen -t rsa -f ~/.ssh/SparkFun_LoRaSerial_22.04.1
58+
b. ssh-copy-id -o IdentitiesOnly=yes -i ~/.ssh/SparkFun_LoRaSerial_22.04.1 <username>@<IP address>
59+
c. ssh -Y <username>@<IP address>
60+
61+
## Ubuntu Build Environment
62+
63+
The following setup and build instructions were tested on Ubuntu 22.04.1. The build can run on a physical or virtual CPU. The following section describes how to setup the a virtual machine. Further sections describe the build environment and how to perform the build.
64+
65+
Execute the following commands to create the build environment for the SparkFun LoRaSerial Firmware:
66+
67+
1. sudo adduser $USER dialout
68+
2. sudo shutdown -r 0
69+
70+
Reboot to ensure that the dialout privilege is available to the user
71+
72+
3. sudo apt update
73+
4. sudo apt install -y git gitk git-cola minicom python3-pip
74+
5. sudo pip3 install pyserial
75+
6. mkdir ~/SparkFun
76+
7. cd ~/SparkFun
77+
8. nano serial-57600.sh
78+
79+
Insert the following text into the file:
80+
81+
#!/bin/bash
82+
# serial-57600.sh
83+
#
84+
# Shell script to read the serial data from the LoRaSerial USB port
85+
#
86+
# Parameters:
87+
# 1: ttyACMn
88+
#
89+
sudo minicom -b 57600 -8 -D /dev/$1 < /dev/tty
90+
91+
9. chmod +x serial-57600.sh
92+
93+
Get the SparkFun LoRaSerial Firmware sources
94+
95+
10. mkdir ~/SparkFun/LoRaSerial
96+
11. cd ~/SparkFun/LoRaSerial
97+
12. git clone [https://github.com/sparkfun/SparkFun_LoRaSerial](https://github.com/sparkfun/SparkFun_LoRaSerial) .
98+
99+
Install the Arduino IDE
100+
101+
13. mkdir ~/SparkFun/arduino
102+
14. cd ~/SparkFun/arduino
103+
15. wget https://downloads.arduino.cc/arduino-1.8.15-linux64.tar.xz
104+
16. tar -xvf ./arduino-1.8.15-linux64.tar.xz
105+
17. cd arduino-1.8.15/
106+
18. sudo ./install.sh
107+
19. arduino
108+
109+
# Setup the Arduino Build Environment
110+
111+
Install the ARM Cortex-M0+ tools. See [SAMD21 MiniDev Hookup Guide](https://learn.sparkfun.com/tutorials/samd21-minidev-breakout-hookup-guide/setting-up-arduino) for more documentation.
112+
113+
1. Click on Tools in the menu bar
114+
2. Click on Board
115+
3. Click on Board Manager ...
116+
4. Scroll down to Arduino SAMD Boards (32-bits ARM Cortex-M0+)
117+
5. Click on Arduino SAMD Boards (32-bits ARM Cortex-M0+)
118+
6. Select version 1.8.13
119+
7. Click on the install button
120+
8. Click on the close button
121+
122+
## Install the SparkFun Board Packages
123+
124+
9. Click on File in the menu bar
125+
10. Click on Preferences
126+
11. Go down to the Additional Boards Manager URLs text box
127+
12. Only if the textbox already has a value, go to the end of the value or values and add a comma
128+
13. Add the link: https://raw.githubusercontent.com/sparkfun/Arduino_Boards/main/IDE_Board_Manager/package_sparkfun_index.json
129+
14. Note the value in Sketchbook location
130+
15. Click the OK button
131+
16. Click on Tools in the menu bar
132+
17. Click on Board
133+
18. Click on Board Manager ...
134+
19. Scroll down and click on SparkFun SAMD Boards (dependency: Arduino SAMD Boards 1.8.1)
135+
20. Select version 1.8.9
136+
21. Click on the install button
137+
22. Click on the close button
138+
23. Click on Tools in the menu bar
139+
24. Click on Board
140+
25. Click on SparkFun SAMD (32-bits ARM Cortex-M0+) Boards
141+
26. Click on SparkFun LoRaSerial
142+
143+
## Install the required libraries
144+
145+
The following procedure installs the libraries needed to successfully build the LoRaSerial firmware.
146+
147+
27. Click on Tools in the menu bar
148+
28. Click on Manage Libraries...
149+
29. For each library:
150+
151+
a. Enter the library name into the search box
152+
b. Scroll down the list if necessary to locate the specified libray
153+
c. Click on the library
154+
d. Select the specified version
155+
e. Click on the install button
156+
157+
30. Install the following libraries:
158+
159+
a. Crypto, v0.4.0
160+
a. FlashStorage_SAMD, v1.3.2
161+
a. JC_Button, v2.1.2
162+
a. RadioLib, v5.1.2
163+
a. SAMD_TimerInterrupt, v1.9.0
164+
165+
31. Click on File in the menu bar
166+
32. Click on Quit
167+
168+
## External Libraries
169+
170+
The WDT library is not registered with the Arduino IDE. It must be added outside of the Arduino IDE environment. Install the external libraries adding them to the Sketchbook location noted above.
171+
172+
33. cd ~/Arduino/libraries
173+
34. mkdir WDTZero
174+
35. cd WDTZero/
175+
36. git clone https://github.com/javos65/WDTZero.git .
176+
177+
# Build the LoRaSerial Firmware
178+
179+
Use the following procedure to get the project ready to build
180+
181+
1. arduino
182+
2. Click on File in the menu bar
183+
3. Click on Open
184+
4. Select the project file: ~/SparkFun/LoRaSerial/Firmware/LoRaSerial/LoRaSerial.ino
185+
5. Click on the Open button
186+
6. Click on Tools in the menu bar
187+
7. Verify that Board lists "SparkFun LoRaSerial"
188+
189+
## Connect the LoRaSerial Device
190+
191+
8. Plug the LoRaSerial device into a USB port on the PC
192+
9. In the arduino program, click on Tools
193+
10. Click on Ports
194+
11. Select the port for the LoRaSerial device
195+
196+
## Compile
197+
198+
12. Click on Sketch in the menu bar
199+
13. Click on Verify/Compile
200+
14. Using an editor or the Arduino IDE ake any source file changes until the Sketch (program) compiles cleanly
201+
202+
## Upload the Firmware
203+
204+
15. Click on Sketch
205+
16. Click on Upload
206+
207+
# Arduino CLI
208+
209+
The firmware can be compiled using [Arduino CLI](https://github.com/arduino/arduino-cli). This makes compilation fairly platform independent and flexible. All release candidates and firmware releases are compiled using Arduino CLI using a github action. You can see the source of the action [here](https://github.com/sparkfun/SparkFun_RTK_Firmware/blob/main/.github/workflows/compile-release.yml), and use it as a starting point for Arduino CLI compilation.

‎mkdocs.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ theme:
2020
- content.code.annotate
2121
# - navigation.tracking
2222
# - navigation.tabs.sticky
23-
# - navigation.tabs
23+
# - navigation.tabs
2424

2525
icon:
2626
repo: fontawesome/brands/github
@@ -71,7 +71,7 @@ extra:
7171
link: https://www.facebook.com/SparkFun
7272
- icon: fontawesome/brands/twitter
7373
link: https://twitter.com/sparkfun
74-
74+
7575
nav:
7676
- Introduction: index.md
7777
- quick_start.md
@@ -81,7 +81,8 @@ nav:
8181
- operating_modes.md
8282
- firmware_update.md
8383
- hardware_overview.md
84+
- firmware_build.md
8485

8586
extra:
8687
version:
87-
provider: mike
88+
provider: mike

0 commit comments

Comments
 (0)