Twist tutorials SPIN 2 Serial Monitor - owntech-foundation/Tutorials GitHub Wiki
Objective
The goal of this tutorial is to understand the architecture of the code in your main.cpp file and to use the microcontroller for the first time. For that, you will turn ON and OFF the embedded LED of the SPIN.
The previous tutorial need to be completed.
Required hardware
* TWIST `v_1_1_2` and/or SPIN 'v_0_9'
* STLinkV3
* PC 64-bits (windows or linux)
Required software
* Git
* Visual Studio Code with PlatformIO [Check our previous tutorial](Twist-tutorial-Setting-up-your-environment)
Setup the work environment
1. We will create the project by copying the previous tutorial in a new branch, that will be called serial_monitor.
2. In the bottom menu, left click on the empty_canvas 
.
3. This will open a menu which will prompt you to create a new branch. Click on + Create new branch....
4. You will be prompted to provide a branch name. Call it my-branch.
(uploads/29ca3e34ed48684131fe86fd40270270/image.png)
5. You will automatically change branches and see that now you are on branch my-branch
6. You are now ready to continue with this tutorial
Understand the code architecture
Let's have a bit of an explanation before going further. Inside the micro-controller you are using, there is a digital stack. This digital stack is divided into several blocks. Each block has its own different execution time as represented in the figure below.
You will find a communication, an application and a control loop in your 'main.cpp' file. What are they used for ?
- Communication loop: handles data exchanges with the outside world, be it you, the user, or other power modules. It operates on a millisecond scale;
- Application loop: Deploys the application to which you wish to associate your module. In practice, this translates into a state machine. This layer operates on the scale of a hundred microseconds;
- Control loop: Follows up commands and retrieves analog data from the converter. This layer operates to the nearest ten microseconds.
For this section, we won't use the control loop, as we won't use the power features yet.
Modify the code
7. Define the variables
In src/main.cpp, in the section USER VARIABLE DECLARATIONS, do not modify anything.
8. Configure the hardware peripherals
In src/main.cpp, in the function setup_hardware(), check that we load the version TWIST_v_1_1_2 of the TWIST using the setBoardVersion() function and that the console is activated for exchanging messages via serial with the console_init() function.
If you don't set up either of these, the microcontroller OS - called Zephyr - will crash.
void setup_hardware(){
hwConfig.setBoardVersion(TWIST_v_1_1_2);
console_init();
}
9. Configure the software scheduling
In src/main.cpp, in the function setup_software(), check that the communication and application tasks are initialized.
void setup_software()
{
application_task_number = scheduling.defineAsynchronousTask(loop_application_task);
communication_task_number = scheduling.defineAsynchronousTask(loop_communication_task);
scheduling.startAsynchronousTask(application_task_number);
scheduling.startAsynchronousTask(communication_task_number);
}
10. Loop communication task
To define the communication task, we implement a communication loop function that will treat the characters it receives via the serial port. Each character will be associated with a different mode.
In src/main.cpp, in the list enum serial_interface_menu_mode, declare a new mode called SERIALMODE.
enum serial_interface_menu_mode //LIST OF POSSIBLE MODES FOR THE OWNTECH CONVERTER
{
IDLEMODE =0,
SERIALMODE
};
In src/main.cpp, in the function loop_communication_task(), add the following code. This code listens to the serial port and performs an action depending on the character it has received. The character h displays the help menu. The character i switches to IDLEMODE. The character s switches to SERIALMODE. It will allow you to change the duty cycle manually.
void loop_communication_task()
{
received_serial_char = console_getchar();
switch (received_serial_char) {
case 'h':
//----------SERIAL INTERFACE MENU-----------------------
printk(" _____________________________________\n");
printk("| ------- MENU --------- |\n");
printk("| press i : idle mode |\n");
printk("| press s : serial mode |\n");
printk("|_____________________________________|\n\n");
//------------------------------------------------------
break;
case 'i':
printk("idle mode\n");
mode = IDLEMODE;
break;
case 's':
printk("serial mode\n");
mode = SERIALMODE;
break;
default:
break;
}
}
11. Loop application task
Let's create an application task that turns the LED1 ON or OFF depending on the mode. In src/main.cpp, in the function loop_application_task(), add the following code.
void loop_application_task()
{
if(mode==IDLEMODE) {
hwConfig.setLedOff();
}else if(mode==SERIALMODE) {
hwConfig.setLedOn();
}
scheduling.suspendCurrentTaskMs(100);
}
12. Loop control task
In src/main.cpp, in the loop_control_task() function, do not modify anything. This control task will remain empty for this tutorial.
13. Connect hardware (see environment tutorial)
- Connect the USB power supply cable. The LED2 of the SPIN should be ON.
- Connect the micro-JTAG connector of the SPIN to the PC through to the STLinkV3.
14. Build and Upload (
+ 
).
15. In the bottom toolbar, click on the Serial Monitor icon 
. Select it and press the h key.
Expected outputs
- Press the
hkey to display the help menu. - Press the
skey to switch to SERIALMODE and turn the LED1 ON. - Press the
ikey to switch to IDLEMODE and turn the LED1 OFF.
That’s it!
Contributors
- 2021.11.04: Romain Delpoux, Loïc Quéval, Adrien Prévost
- 2021.11.07: Luiz Villa, Antoine Boche
- 2022.01.24: Luiz Villa, Adrien Prevost, Loïc Quéval
- 2022.02.01: Luiz Villa, Clement Foucher
- 2022.02.22: Luiz Villa
- 2022.03.13: Luiz Villa
- 2022.06.23: Loïc Quéval
- 2023.01.14: Luiz Villa
- 2023.07.10: Luiz Villa
- 2023.10.01: Mathilde Longuet
- 2023.10.18: Luiz Villa