Software

Compiling

This project requires some tools and dependencies:

  • The GCC ARM compiler and debugger.

  • A C standard library implementation.

  • OpenOCD 1 for programing and debugging.

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.

  1. Clone the project including submodules to get libopencm3 3:

    git clone --recursive git@github.com:Bulebots/bulebule.git
cd bulebule

  2. Create the container image:

    make image

  3. Setup and compile libopencm3 3:

    make libopencm3

  4. Compile the source code with:

    make

  5. 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

References

1(1,2)

http://openocd.org/

2

https://www.gnu.org/software/gdb/

3(1,2,3)

https://github.com/libopencm3/libopencm3

4

https://podman.io/

5

https://www.docker.com/