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

| On Linux, you must have write access to the raw usb device for the following to work. This can be achieved automatically by using putting the following udev rule in the udev directory, for instance in `/etc/udev/rules.d/99-paparazzi.rules`:
    SUBSYSTEM=="usb", ATTR{idVendor}=="1209", ATTR{idProduct}=="0001", GROUP="plugdev"
This will work if you are a member of the unix `plugdev` group. Otherwise, you should adapt the example to your configuration and system. In case the procedure below does not work without reporting any error, it is worth checking the same commands with `export LIBUSB_DEBUG=1` in your environment.

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