kirdy/README.md

# Testing Firmware for the Sinara 1550 Kirdy

- This repo is for testing only. Not intended for production use.

## Building

### Reproducible build with Nix

kirdy firmware is packaged using the [Nix](https://nixos.org) Flakes system. Install Nix 2.4+ and enable flakes by adding ``experimental-features = nix-command flakes`` to ``nix.conf`` (e.g. ``~/.config/nix/nix.conf``). 

Once you have Flakes enabled, you can use ``nix build`` to build the firmware.

### Development environment

Clone this repository and with Nix Flakes enabled, use the following commands:

```shell
nix develop
cargo build
```

The resulting ELF file will be located under `target/thumbv7em-none-eabihf/release/kirdy`.

Alternatively, you can install the Rust toolchain without Nix using rustup; see the Rust manifest file pulled in `flake.nix` to determine which Rust version to use.

For building on FreeBSD or OpenBSD, see BSD.md.

## Debugging

Connect SWDIO/SWCLK/RST/GND to a programmer such as ST-Link v2.1. Run OpenOCD:
```shell
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
```

You may need to power up the programmer before powering the device.
Leave OpenOCD running. Run the GNU debugger:
```shell
gdb target/thumbv7em-none-eabihf/release/kirdy

(gdb) source openocd.gdb
```

## Flashing
If the firmware to be flashed involves an update on the flash settings, it is required to erase the flash settings before flashing the new firmware to avoid unexpected hardware behavior. There are several options for flashing kirdy. DFU requires only a USB-C cable or RJ45 cable, whereas OpenOCD needs a JTAG/SWD adapter.

### dfu-util on Linux
* Install the DFU USB tool (dfu-util).
* Convert firmware from ELF to BIN: `arm-none-eabi-objcopy -O binary kirdy kirdy.bin` (you can skip this step if using the BIN from Hydra)
* Put STM32 into DFU Mode. You can either
    * Connect to the USB Type C cable to kirdy next to the RJ45 Jack. After that, add BOOT0 jumper to kirdy near programming headers and then cycle board power to put it in DFU mode. OR
    * Plug in RJ45 cable, which connect to a network that is accessible by your computer and send the corresponding dfu json command via TCP Socket to kirdy. Please see the python test script for the command.
* Push firmware to flash: `dfu-util -a 0 -s 0x08000000:leave -D kirdy.bin`
* If you plugged in the BOOT0 jumper, you will need to
    1. Remove BOOT0 jumper
    2. Cycle power to leave DFU update mode
* If you plugged in the RJ45 cable, the MCU would start its application code automatically. No power cycle is needed.

### st.com DfuSe tool on Windows
On a Windows machine install [st.com](https://st.com) DfuSe USB device firmware upgrade (DFU) software. [link](https://www.st.com/en/development-tools/stsw-stm32080.html).
- add jumper to kirdy across 2-pin jumper adjacent to JTAG connector
- cycle board power to put it in DFU update mode
- connect USB Type C to PC
- use st.com software to upload firmware
- remove jumper
- cycle power to leave DFU update mode

### OpenOCD
```shell
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "program target/thumbv7em-none-eabihf/debug/kirdy verify reset; exit"
```

## Erasing Flash Settings
The flash settings are stored in the last flash sector(ID: 11) of bank 0 of stm32f405. You can erase it with JTAG/SWD adapter or by putting the device in Dfu mode. You may find it useful if you have set network settings incorrectly.

With JTAG/SWD adapter connected, issue the following command:

```shell
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "flash init; init; halt; flash erase_sector 0 11 last; reset; exit"
```

With STM32 in DFU Mode, connect the USB Type C cable and then issue the following command:

```
dfu-util -a 0 -s 0x080E0000:leave -D erase_flash_settings.bin
```