Installation

Dependencies

You need the toolchain for cross compiling for arm-none-eabi. On Debian systems, these are provided by the two packages gcc-arm-none-eabi and binutils-arm-none-eabi.

If you intend to work on the source and are building from a clone of the repository, you need additional maintainer tools: autoconf, automake, libtool and asciidoctor. These are common tools that should be readily available on your distribution.

Check your system documentation for getting these software.

Compiling

The package is available in robotpkg in hardware/tk3-paparazzi and that’s the recommended way to install the latest release.
Alternatively, you can get the latest archive from https://www.openrobots.org/distfiles/tk3-paparazzi/. The package uses the autoconf framework to build and install itself. Simply run the bundled configure script to compile and install the software. For instance:
```
% ./configure --prefix=$HOME/devel
% make install
```
You can check the autoconf online documentation for more help.
In order to work on the source code, you can clone the git repository hosted on https://git.openrobots.org/projects/tk3-paparazzi/repository. Make sure to clone with the --recurse-submodule option in order to get the chibios submodule that is used by the project and install the maintainer dependencies mentionned in the previous section. You also will have to generate the build system files once and, in particular, the configure script. Just run the autoreconf command in the source tree.

Files

The package installs the firmware files in your installation prefix:

<prefix>/lib/tk3-firmware/chimera, for the Chimera board.
<prefix>/lib/tk3-firmware/tawaki, for the Tawaki board.

Bootstrapping

In order to program for the first time a brand new board, you first need to install the bootloader, so that subsequent updates are made easier. This has to be done only once. After that, even the bootloader itself can be updated by following the 'Flashing' procedure below.

The exact bootstrapping procedure depends on the hardware.

Chimera

TBD

Tawaki

You need to manually install the bootloader on the microcontroller. The program is located in <prefix>/lib/tk3-firmware/boot-tawaki. To do so, you need to convert the ELF file into a raw binary file that can be uploaded to the board’s flash memory. This is done with the objcopy binutils command for the arm-none-eabi architecture:

% arm-none-eabi-objcopy -O binary <prefix>/lib/tk3-firmware/boot-tawaki boot.bin

Then, put the board in DFU mode, by pressing the BOOT button and then powering the board via USB. You should see your board in the output of the lsusb command:

% lsusb
[...]
Bus bbb Device ddd: ID 0483:df11 STMicroelectronics STM Device in DFU Mode
[...]

To upload the boot.bin file, you need the dfu-util command. On Debian systems, this is provided by the dfu-util package. Check that the board is recognized:

% dfu-util -l
[...]
Found DFU: [0483:df11] ver=0200, devnum=19, cfg=1, intf=0, path="nnn", alt=1, name="@Option Bytes   /0x5200201C/01*128 e", serial="200364500000"
Found DFU: [0483:df11] ver=0200, devnum=19, cfg=1, intf=0, path="nnn", alt=0, name="@Internal Flash   /0x08000000/16*128Kg", serial="200364500000"

Match the Internal Flash interface and use the corresponding 'alt' number in the command below to upload the bootloader (normally `0'):

% dfu-util --alt 0 -s 0x08000000 -D boot.bin

If you have multiple DFU devices connected, you may have to specify the device PID explictly by passing the -d 0483:df11 option to dfu-util.

Once done, you can power cycle the board to reboot it normally. The four leds should light, indicating that the boot loader sucessfully loaded. You can also check and tune the bootloader parameters with tk3-flash, see next section.

When bootstrapping the board, there is no firmware apart from the bootloader installed, so that the bootloader has no firmware to jump to. So after the bootloader timeout, the board will most likely disconnect or fail. You have by default 5 seconds to program an initial firmware. Once there is a firmware installed, you can program a firmware at any time when the board is powered.

Flashing

In order to program the board, you have to upload the programs in the microcontroller flash memory. This can be done with the tk3-flash program, available at https://git.openrobots.org/projects/tk3-flash.

Even before programming a firmware, you should be able to check the current bootloader parameters. After powering the board, a new cdc_acm should be created. This can be checked from the dmesg kernel output:

% dmesg -T
[...]
usb b-n.m: Product: tk3-paparazzi
usb b-n.m: Manufacturer: LAAS/CNRS
usb b-n.m: SerialNumber: nnnnnnnnnnnnnnnnnnnnn
cdc_acm b-n.m:1.0: ttyACM0: USB ACM device

Note the device path and use the following tk3-flash command:

% tk3-flash set /dev/ttyACM0
Please power on or reset the device.....
Probed STM32 bootloader
STM32H742xxx/743xxx/753xxx/750xxx bootloader version 9.3
Searching for existing settings
Reading data from 0x8000000-0x8000003, 4 bytes
Reading data from 0x8020000-0x8020003, 4 bytes
Reading data from 0x8020000-0x803ffff, 131072 bytes
Found settings data at 0x8020000-0x8020067, 104 bytes

--- Settings --------------------------------------

serial          : nnnnnnnnnnnnnnnnnn.0
boot-timeout    : 5                (bootloader timeout (s))
boot-lock       : 0                (set to 1234567890 to update bootloader)

Flashing a new firware can be done with the following command:

When uploading a program for the first time, make sure to use the -i flag of tk3-flash to properly initialize the runtime parameters. You can skip the -i for further updates, thus keeping you previous settings.

% tk3-flash -i flash /dev/ttyACM0 <prefix>/lib/tk3-firmware/tawaki
Please power on or reset the device...
Probed STM32 bootloader
STM32H742xxx/743xxx/753xxx/750xxx bootloader version 9.3
Retrieving load data from <prefix>/lib/tk3-firmware/tawaki
Found data segment 0, paddr 0x8040000-0x80402df, 736 bytes
Found data segment 1, paddr 0x80402e0-0x8048e7f, 35744 bytes
Found data segment 2, paddr 0x8048e80-0x804954f, 1744 bytes
Found tk3 settings segment 3, paddr 0x8020000-0x8020213, 532 bytes
Erasing flash page 2.
Writing data to 0x8040000-0x804954f, 38224 bytes
Erasing flash page 1.
Writing data to 0x8020000-0x8020213, 532 bytes

--- Settings --------------------------------------

serial          : nnnnnnnnnnnnnnnnnn.0
boot-timeout    : 5                (bootloader timeout (s))
boot-lock       : 0                (set to 1234567890 to update bootloader)
mkbl-motors     : 6                (number of mkbl motors, 0=off)
poles           : 14               (number of motor poles)
servo-mode      : 0                (0=off, 1=PWM, 2=DSHOT, 3=BI-DSHOT)
servo-3d        : 0                (0=off, 1=reversible)
servo-freq      : 150              (PWM=50-490Hz, DSHOT=100-900kHz)
idle-throttle   : 6                (idle throttle (0%-20%))
rc-kill-chan    : -1               (RC kill channel [0-7], -1=disable)
rc-kill-mode    : 0                (kill trigger: -1=low, 0=edge, +1=high)
acc-range       : 8                (±2, 4, 8, 16 (g))
gyr-range       : 1000             (±250, 500, 1000, 2000 (°/s))

The board is ready!

Setting a custom serial number

On the tawaki boards, you have the possibility to program a custom serial number, that makes it easier to connect to the boards ttys.

By default, the serial number is computed from the UID of the microcontroller (unique for each manufactured device). To program a new serial, you must first unlock the boot-lock parameter by setting it to the magic number 1234567890:

% tk3-flash set /dev/ttyACM0 boot-lock 1234567890

Then, you must reboot the board and while the board is in the bootloader (all 4 LEDs are lit), you can issue the request for programming a new serial:

% tk3-flash set /dev/ttyACM0 serial myboard

For safety, you can then reset the boot-lock parameter to 0:

% tk3-flash set /dev/ttyACM0 boot-lock 0

The board’s ttys can now be accessed as myboard.0 or myboard.1 instead of /dev/ttyACM0 or /dev/ttyACM1.