Software¶
Compiling¶
This project requires some tools and dependencies:
The GCC ARM compiler and debugger.
A C standard library implementation.
We will also be using the libopencm3 3 firmware library. Our workspace is based on the simple template from that project.
We can manually install all those tools and dependencies in our system or we can use containers, which is a much more convenient approach. Just make sure you have Podman 4 or Docker 5 installed in your system.
Clone the project including submodules to get libopencm3 3:
git clone --recursive git@github.com:Bulebots/bulebule.git cd bulebule
Create the container image:
make image
Setup and compile libopencm3 3:
make libopencm3
Compile the source code with:
make
We can clean the compilation files with:
make clean
Note
The makefile on the src
folder combines the
libopencm3.target.mk
file, the board STM32F1 makefile and the
Bulebule project relative paths.
Programmer¶
The programmer is a generic ST-Link V2. Connecting this programmer to the board is very simple, just make sure to connect these pins together:
Board |
Programmer |
---|---|
3V3 |
<unconnected> |
<unconnected> |
3.3V |
SWIO |
SWDIO |
SWCLK |
SWCLK |
GND |
GND |
Warning
Note that the 3V3 line is not connected. We will be using the battery to power the mouse while flashing it. This way we avoid having two power sources on the microcontroller board while programming.
Note
The programmer uses an USB interface, which means we might need to set the proper permissions for our user:
sudo usermod -a -G dialout USER_NAME
We may need to log out and back in for this change to take effect.
Alternatively we could add some UDEV rules in /etc/udev/rules.d/99-stlink.rules:
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="0666"
And then simply reload the rules without logging out:
udevadm control --reload-rules
Flashing¶
Having the programmer connected, we can flash the microcontroller with:
make -C src/ flash
OpenOCD¶
To program the microcontroller we can also directly use OpenOCD 1. We need to specify the interface and target configuration files:
openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg
OpenOCD starts running as a server and waits for connections from clients (Telnet, GDB, RPC) and processes the commands issued through those channels.
We can try and connect to the OpenOCD server with Telnet:
telnet localhost 4444
Then we can, for example, display all registers and their values:
> reg
Or halt and re-run:
> reset halt
> reset run
We can flash the microcontroller using OpenOCD as well (assuming we are already connected with telnet):
> program filename.elf verify reset
Note
The program command will automatically execute the reset init scripts, flash the image, verify it (if verify parameter is given) and run it if reset parameter is given.
Alternatively, we can launch OpenOCD and flash the program with a single command:
openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
-c "program filename.elf verify reset exit"
Binary files need the flash address to be specified:
> program filename.bin verify reset 0x08000000
Debugging¶
We use GDB 2 for debugging. Note that we connect to OpenOCD gdbserver using the port 3333, rather than the port 4444 used with telnet:
$ arm-none-eabi-gdb main.elf
(gdb) target extended-remote localhost:3333
Note
Remember that you can shorten the commands: tar ext :3333
is
the same as target extended-remote localhost:3333
.
Once we are connected, we can execute OpenOCD commands simply prepending the word monitor:
(gdb) monitor reset halt
(gdb) monitor reset run
If we want to load the .elf file, we can simply execute the load command now:
(gdb) load