Bootloader
What you will learn:
In this tutorial, you will learn to use the bootloader feature offered by Luos engine.
1. Acquire and set up your equipment
To flash one or multiple boards using the Luos engine's bootloader, you need a main node that will manage the transmission of your binary trough the Luos network. So the minimal setup needed to use the bootloader is composed of the boards you want to flash, connected to a computer that will run the master node. We will make the main nodes with a gate run on the computer you are using to update your boards.
If you are not comfortable with the Luos network creation and Luos engine's firmware management and compiling, please follow the Luos Get started tutorial first.
It is not possible to update the main node running the gate using the bootloader feature. If you want to update it, you will have to make it amnually or use another node as main.
On this tutorial, we will use the examples available in the Luos engine's repository. You can download and unzip it or clone it using:
Git clone https://github.com/Luos-io/luos_engine.git
2. Compile the Gate on your computer
You can also make the Gate run on a board. To know how, please follow the the Luos Get started tutorial.
Open VS Code and open the gate_wscom project corresponding to your master board in Luos_engine/examples/projects/native/gate_wscom.
Click on Upload on the bottom left corner of the IDE. Wait for the compilation to be completed. If successful, you should see the following:
If this step fails, try to follow the Luos Get started tutorial.
To finish, we need to run this program. To do that, you can use the following command in a terminal:
cd Luos_engine/Examples/Projects/native/gate_wscom
./.pio/build/native/program
You should see the code running and asking you to select the serial port to use:
3. Load the bootloader on your board
Now, you will load the bootloader in the board. Following the same process as described in Step 2, but this time open the Bootloader example in Luos_engine/Examples/Projects/YOUR_BOARD/bootloader.
Luos engine example use Robus as default network, you will have to use Serial instead allowing you to communicate with the node on the computer. To do that you have to :
- Replace
robus_networkbyserial_networkin theplatformio.inifile. Make sure to also replace the-DROBUSHAL=BOARDby-DSERIALHAL=BOARDin thebuild_flagssection. - Replace
#include "robus_network.h"andLUOS_ADD_PACKAGE(Robus)by#include "serial_network.h"andLUOS_ADD_PACKAGE(Serial)in themain.cfile.
Connect the board with the USB programming port and click on Upload; you should see the following:
4. Detection
Connect your your board USB serial interface to your PC. Now we can start the Gate node on the computer. Open a terminal and type the following command:
cd Luos_engine/Examples/Projects/native/gate_wscom
./.pio/build/native/program
You should see the code running and asking you to select the serial port to use. Write its name and press enter:
Please enter the serial port name (ex: /dev/ttyUSB0): /dev/cu.usbserial-D308N897
Connection on serial port /dev/cu.usbserial-D308N897 at 1000000 baud
Starting WS listener on ws://localhost:9342/ws
As you can see the gate opened a websocket server on port 9342. We will use this to communicate with the gate from Pyluos :
$ pyluos-bootloader detect localhost
Luos detect subcommand on port : localhost
Luos detect subcommand at baudrate : 1000000
Connected to "localhost".
Sending detection signal.
Waiting for routing table...
Device setup.
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ╭────────────────── Node 1 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ├> Pipe Pipe 2 ┃
┃ ╰> Gate gate 1 ┃
╔■┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
║ ┏━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
╚════■┫ ╭────────────────── Node 2 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ╰> Void boot_service 3 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
boot_service indicates there is a bootloader running on your node. You are now able to communicate with it through the gate and load any application.
6. Compile a code on bootloader mode
Most of the examples available in Luos engine's folder are already compatible with the bootloader's feature. You will be able to use them as templates for your future applications. Follow the same process described in Step 3, but this time open the Button example in Luos_engine/Examples/Projects/YOUR_BOARD.
PlatformIO is able to manage multiple build configurations. By default, Luos engine's examples are compiling a firmware that can be loaded using the standard flash system. If you want your application to be bootloader-compatible, you need to compile it in with_bootloader mode.
To do that, when your button project is open you can click on the Switch PlatformIO Project Environment button at the bottom of the window, then select the with_bootloader option on the list of choice appearing on the top of your screen.
Don't forget to switch your button program to use Serial instead of Robus, then, click on Build.
If you click on the Upload button, PlatformIO will use the Luos bootloader CLI to load your firmware. For now, please be sure to do it in command line instead, like explained below.
The generated binary file can be found in Luos_engine/Examples/Projects/YOUR_BOARD/Button/.pio/build/*_with_bootloader under the name firmware.bin.
Now, you can use the bootloader's command line to load it, for example:
cd Luos_engine/Examples/Projects/l0/Button/.pio/build/l0_with_bootloader
pyluos-bootloader flash -t 2 -b firmware.bin localhost
For further information on the options used with the CLI, please read the dedicated documentation page, or type the following command:
pyluos-bootloader --help
The following lines should appear after typing the command:
Rebooting all nodes in bootloader mode.
Programming nodes:
─> Erasing flash memory.
╰> All flash erased
─> Sending binary data.
╰> Loading : 100.0 %
Rebooting all nodes in application mode.
Programming succeed in 74.165 s.
If any problem occurs during the loading process, please reboot your system and retry typing the command (you can also find information here).
Then relaunch a detection (as done in Step 4):
$ pyluos-bootloader detect localhost
Luos detect subcommand on port : localhost
Connected to "localhost".
Sending detection signal.
Waiting for routing table...
Device setup.
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ╭────────────────── Node 1 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ├> Pipe Pipe 2 ┃
┃ ╰> Gate gate 1 ┃
╔■┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
║ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
╚════■┫ ╭────────────────── Node 2 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ╰> ServoMotor button 3 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
You can see that boot_service has been replaced by another alias such as button, which is the name of the service running in your app: the bootloader switched to application mode and launched your freshly written app.
7. Update your app
You can also update your app and reload it in the node.
As an example, select a Led project and follow the previous steps with the Button example.
Compile it using the with_bootloader environment and by replacing Robus by Serial, then use the bootloader command to flash it.
You should see your updated service running in your node:
$ pyluos-bootloader detect localhost
Luos detect subcommand on port : localhost
Connected to "localhost".
Sending detection signal.
Waiting for routing table...
Device setup.
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ╭────────────────── Node 1 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ├> Pipe Pipe 2 ┃
┃ ╰> Gate gate 1 ┃
╔■┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
║ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
╚════■┫ ╭────────────────── Node 2 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ╰> ServoMotor led 3 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
8. Update your bootloader trough the bootloader
Luos-engine also allow you to update your bootloader using the bootloader feature. This process use the application space of your microcontroler to store a bootloader able to overwrite the actual bootloader on the bootloader space.
This process overwrite your app and your bootloader. If there is a failure during the bootloader update, you may have to use a programmer to recover your board.
Compile your bootloader updater app
Following the same process as described in Step 3, but this time open the Bootloader example in Luos_engine/Examples/Projects/YOUR_BOARD/bootloader in YOUR_BOARD_updater mode. This compilation mode will create a binary file acting like a bootloader that can be loaded using the bootloader feature in the application space.
Load your bootloader updater app
Now you can use the bootloader command to flash it.
cd Luos_engine/Examples/Projects/YOUR_BOARD/bootloader/.pio/build/YOUR_BOARD_updater
pyluos-bootloader flash -t 2 -b firmware.bin localhost
After the flash complete you can detect your board again and see that their is now a boot_updater instead of your led app.
$ pyluos-bootloader detect localhost
Luos detect subcommand on port : localhost
Connected to "localhost".
Sending detection signal.
Waiting for routing table...
Device setup.
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ╭────────────────── Node 1 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ├> Pipe Pipe 2 ┃
┃ ╰> Gate gate 1 ┃
╔■┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
║ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
╚════■┫ ╭────────────────── Node 2 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ╰> ServoMotor boot_updater 3 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
The bootloader updater app is not resilient, if you reboot your board you will fall into you original bootloader again. Make sure to not reboot your board before the end of the process.
Update your bootloader
Now you can compile your updated bootloader and load it using the bootloader feature. To make it you can follow the step 3 by compiling your bootloader with the default environnement. Then you can load it using the bootloader feature, this time the bootloader on the application space will update thee bootloader on the bootloader space.
cd Luos_engine/Examples/Projects/YOUR_BOARD/bootloader/.pio/build/YOUR_BOARD
pyluos-bootloader flash -t 2 -b firmware.bin localhost
After the flash complete you can detect your board again and see that their is now a boot_service intead of your boot_updater app.
$ pyluos-bootloader detect localhost
Luos detect subcommand on port : localhost
Connected to "localhost".
Sending detection signal.
Waiting for routing table...
Device setup.
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ╭────────────────── Node 1 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ├> Pipe Pipe 2 ┃
┃ ╰> Gate gate 1 ┃
╔■┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
║ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
╚════■┫ ╭────────────────── Node 2 ────────────────── ┃
┃ │ Type Alias ID ┃
┃ ╰> ServoMotor boot_service 3 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Now you can use this updated bootloader to flash your led app back.
Depending on your MCU (ARM M0+ for example) your bootloader may not be visible after the bootloader update. Reboot your board to see it again.
You have reached the end of this tutorial. You are now able to use the bootloader's feature included in Luos engine. You know the basics, but you can find some more helpful information on the dedicated documentation page.