Part 3: unleash your code
1. Introductionβ
The first two parts of the Get started tutorial are now done. Good work! πͺ
In this part, we will learn how to configure Luos engine to access to multiple boards in your physical network. Then, we will run our first example into these boards.
We will use the same board from the first two parts, but you also need a second board to create a network. Supported boards are listed here.
2. Create a physical networkβ
- Board
- No board
As we saw in Part 1, Luos engine allows you to define services and use them together on one MCU. What really sets Luos apart and makes it special is that you can also make services work together on separated MCUs.
Let's make a network with two boards!
In this part, we will use the βdefault wiringβ defined by Luos to create a network of two MCUs. We will use a OneWire network, limiting the circuit to simple wires and pins:
- Tx and Rx pins, which are connected together and wired to the Tx and Rx pins of the other board (see the next image).
- One PTP wire.
π‘ Luos Point-To-Point (PTP) connection allows you to find your board's physical position. Luos engine can deal with up to 8 PTP lines on each board to connect as many boards as you want.
To prevent any mistakes, unplug the USB cables from the boards before wiring.
To create your network, you have to identify the pins used to perform Luos communication:
Function name | Arduino pin | STM32L432KC pin | STM32F072RB pin | STM32F401RE pin | STM32F410RB pin | STM32G431KB pin | Seeeduino XIAO pin | ESP32 WROOM 32 Dev Kit |
---|---|---|---|---|---|---|---|---|
TX | Tx | PA9 (D0) | PA9 (D8) | PB7(21) | PB7 (21) | PA9 (D0) | D6 | Tx (SD2) |
RX | Rx | PA10 (D1) | PA10 (D2) | PB6 (D10) | PB6 (D10) | PA10 (D1) | D7 | Rx (SD3) |
PTP | D6 | PB5 (D12) | PA8 (D7) | PB5 (D5) | PB5 (D5) | PB5 (D12) | D1 | IO26 |
Below are the schematics of various boards and how to wire them:
- Arduino MKR
- Arduino Classic
- Seeeduino Xiao
- NUCLEO 32
- NUCLEO 64
- ESP32 WROOM-32 DevKit
- STM32F072RB
- STM32F401RE/STM32F410RB
You should now be able to wire the two boards together. From now on, we will call these boards board 1 and board 2.
After wiring the boards together, you will have to power both of them for the network to work correctly. In the next steps of this tutorial, board 1 will already be plugged to the computer with the USB cable. To power board 2, you can either connect the power output pin of board 1 (5V pin) to the power input pin of board 2 (Vin pin), or simply plug board 2 to another USB cable so that both boards are powered by the computer. In the first case, do not forget to wire the GND pins together on both boards.
3. Build a Luos distributed systemβ
In Part 1, you have downloaded or cloned the Get started code folder in your computer. We will use this code to demonstrate how Luos engine works using a network. We will begin by moving the blinker app service from board 1 to board 2 and see what happens next.
Flash board 1β
Connect the USB cable of board 1 and leave the USB cable of board 2 disconnected.
-
In VS Code, open the folder Get_started that corresponds to your board 1:
file/open folder
. -
From the left panel, locate and open the file src/main.c or src/Arduino.ino.
-
Comment the following two lines to remove the blinker service from this board:
Blinker_Init();
andBlinker_Loop();
...
Luos_Init();
Led_Init();
Pipe_Init();
Gate_Init();
//Blinker_Init(); <== comment this line
...
Luos_Loop();
Led_Loop();
Pipe_Loop();
Gate_Loop();
//Blinker_Loop(); <== comment this line
These lines trigger the initialization and looping execution of all the packages in your project.
- Check whether the proper board environnement is selected depending on your board:
- Build and flash board 1 by clicking on the arrow pointing to the right on the bottom left in VS Code.
Flash board 2β
You should now unplug the USB cable of board 1 and connect the USB cable of board 2.
-
In VS Code, open the folder Get_started project corresponding to your board 2,
file/open folder
. (If you have the same boards twice, you can open the same folder.) -
From the left panel, find and open the file src/main.c (or src/Arduino.ino for Arduino users).
-
This time, comment the following six lines to remove all of the services except the blinker:
Led_Init();
,Pipe_Init();
,Gate_Init();
,Led_Loop();
,Pipe_Loop();
, andGate_Loop();
...
Luos_Init();
//Led_Init(); <== comment this line
//Pipe_Init(); <== comment this line
//Gate_Init(); <== comment this line
Blinker_Init();
...
Luos_Loop();
//Led_Loop(); <== comment this line
//Pipe_Loop(); <== comment this line
//Gate_Loop(); <== comment this line
Blinker_Loop();
In order to keep using Luos engine in your MCU, don't comment Luos_init()
nor Luos_Loop()
.
- Check if the right board environment is selected depending on your board:
- Build and flash board 2 by clicking on the arrow pointing to the right on the bottom left in VS Code.
We are done!
To check if everything is OK, plug a USB cable into board 1, and power board 2 according to your previous choice (power pins from board 1 or USB cable from computer).
The LED of board 1 should blink thanks to the blinker app in board 2.
Congratulation, you've just created your first Luos distributed system. The objective of this part of our Get started was to use a service located in your first board, in another board to perform an action on it.
4. Use Pyluos to control your networkβ
You can now use pyluos-shell
in your terminal, as we did in Part 2. You should see the following:
**$ pyluos-shell**
Searching for a gate available
Testing /dev/cu.usbserial-D308N885
Testing /dev/cu.usbmodem13102
Connected to "/dev/cu.usbmodem13102".
Sending detection signal.
Waiting for routing table...
Device setup.
Hit Ctrl-D to exit this interpreter.
Your luos device have been successfully mounted into a "device" object:
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β βnode 1 /!\ Not certified β
β β Type Alias ID β
β β> State led 2 β
β β> Pipe Pipe 3 β
β β°> Gate gate 1 β
β>ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββ 0>β0 βnode 2 /!\ Not certified β
β β Type Alias ID β
β β°> Unknown blinker 4 β
>ββββββββββββββββββββββββββββββββββββββββββββββββββββ
As we saw in Part 1, Luos engine allows you to define services and use them together on one program. What really sets Luos apart and makes it special is that you can also make services work together on separated programs.
In Part 1, you have downloaded or cloned the Get started code folder in your computer. We will use this code to demonstrate how Luos engine works using a network. To create a link between multiple programs on your computer, Luos will use WebSockets to exchange information instead of a serial communication between electronic boards.
To be able to do that, you need to run a broker that will share any transmitted message with all other programs.
This broker is a simple Python script. To make it run, you need to install simple_websocket_server:
pip install simple_websocket_server==0.4.2
Then you can run the broker script on Get_started/No-Board/
:
python broker.py
By default the broker will use localhost IP address. If you want to experiment it using multiple computers, you can configure your IP and port:
python broker.py --ip 'YOUR_LOCAL_IP' -p 8000
3. Build a Luos distributed systemβ
We will begin by moving the blinker app service from board 1 to board 2 and see what happens next.
Run board 1β
-
In VS Code, open the folder Get_started/No-Board:
file/open folder
. -
From the left panel, locate and open the file src/main.c.
-
Comment the following two lines to remove the blinker service from this board:
Blinker_Init();
andBlinker_Loop();
...
Luos_Init();
Led_Init();
Pipe_Init();
Gate_Init();
//Blinker_Init(); <== comment this line
...
Luos_Loop();
Led_Loop();
Pipe_Loop();
Gate_Loop();
//Blinker_Loop(); <== comment this line
These lines trigger the initialization and looping execution of all the packages in your project.
By default the program will use a localhost IP address.
If you want to experiment it using multiple computers, you can set the broker IP and port in the node_config.h file by replacing #define WS_BROKER_ADDR "ws://YOUR_LOCAL_IP:8000"
with the correct IP and port.
- Build the project.
Windows users must install a specific 64-bit version of GCC to compile the no-board projects. For example, the current version has been tested with MinGW-w64 (MSVCRT runtime). This library can be downloaded at https://winlibs.com/
- In a new terminal, run the compiled binary:
./.pio/build/native/program
Run board 2β
-
In VS Code, open the same folder Get_started/No-Board: File/Open folder.
-
From the left panel, find and open the file src/main.c.
-
This time, comment the following six lines to remove all of the services except the blinker:
Led_Init();
,Pipe_Init();
,Gate_Init();
,Led_Loop();
,Pipe_Loop();
, andGate_Loop();
:...
Luos_Init();
//Led_Init(); <== comment this line
//Pipe_Init(); <== comment this line
//Gate_Init(); <== comment this line
Blinker_Init();
...
Luos_Loop();
//Led_Loop(); <== comment this line
//Pipe_Loop(); <== comment this line
//Gate_Loop(); <== comment this line
Blinker_Loop();
In order to keep using Luos engine in your program, don't comment Luos_init()
nor Luos_Loop()
.
- Build the project.
- On a new terminal run the compiled binary:
./.pio/build/native/program
We are done!
To check if everything is OK, the LED displayed on the terminal running board 1 should blink thanks to the blinker app in board 2.
Congratulation, you've just created your first Luos distributed system. The objective of this part of our Get started was to use a service located in your first program, in another board to perform an action on it.
4. Use Pyluos to control your networkβ
You can now use pyluos-shell -p 'localhost'
in your terminal, as we did in Part 2. You should see the following:
**$ pyluos-shell -p 'localhost'**
Connected to "localhost".
Sending detection signal.
Waiting for routing table...
Sending telemetry...
Device setup.
Hit Ctrl-D to exit this interpreter.
Your luos device has been successfully mounted into a "device" object:
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β βnode 1 /!\ Not certified β
β β Type Alias ID β
β β> State led 2 β
β β> Pipe Pipe 3 β
β β°> Gate gate 1 β
β>ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββ 0>β0 βnode 2 /!\ Not certified β
β β Type Alias ID β
β β°> Unknown blinker 4 β
>ββββββββββββββββββββββββββββββββββββββββββββββββββββ
As we can see, the blinker application is now displayed on a separate board. You still can control and interact with services on both boards with pyluos, as we did in Part 2.
For example, with your network connected to the computer, follow the step 3 from Part 2 and try to execute these lines one by one in an IPython session:
- Set up the blinking timing to 250ms (you should see the LED blink faster):
device.blinker.time=0.25
- Pause the blinking of the LED:
device.blinker.pause()
- Turn on the LED:
device.led.state=True
- Turn off the LED:
device.led.state=False
- Restart the blinking of the LED:
device.blinker.play()
5. Test your skillsβ
Congratulation, you have plugged, configured, and used your first Luos network!
The next step will show you how to visualize your network online through the Luos Network Display tool.
You can check out our tutorials to learn more about Luos and understand how to use the features of Luos engine. We also invite you to check out our documentation to learn more about the core concepts of Luos engine.
β If you liked this tutorial, feel free to star our Luos engine repositoryβ