Skip to content

cw-leia/cw-leia-standalone-firmware

Repository files navigation

LEIA Firmware

This repository hosts the source code files of the LEIA firmware. With them, you can (re)build the firmware to adapt it to your needs. To do so several compilation options are detailed below.

Build options

Option Environment variable Description
Board Choice LEIA=1 (default) This is basically the board choice.
WOOKEY=1 For now, LEIA boards, WooKey boards
DISCO407=1 and F407 / F429 discovery boards are
DISCO429=1 supported. Depending on the specific
board selected, the pins mapping
will vary and must be adapted.
---------------- ---------------------- --------------------------------------
Communication USB=1 (default) This is the prefered channel used to
USB=0 communicate with the board. By
default, two USB /dev/ttyACMx are
used for protocol and debug purposes.
USB=0 will make use of dedicated
physical UARTs on the board (with
dedicated pins).
---------------- ---------------------- --------------------------------------
ISO7816 driver (X) This is an ISO7816 specific option.
(dynamically chosen) This will select either the use of
a physical USART for the ISO7816
communication or bitbanging GPIOs.
Each option has advantages and
drawbacks:
- USART: since ISO7816 is hardware
accelerated, this is fast and can
support high frequency rates. On
the other side, handling low level
protocol modifications (for bits
reception and so on) is complex
(sometimes impossible).
- Bitbang: this allows very low level
handling of the protocol, yielding
in easier modifications (for
conformance tests, glitches, etc.).
The drawback is that the clock
frequency must be kept at very low
rates (~1MHz to 4MHz) so that the
MCU can keep up with bitbanging
the protocol pins properly.
NOTE: Bitbanging is not compatible
with the WooKey board because of some
limitations on its pins. You can
however tune the WooKey configuration
files to dedicate pins to Bitbang
(at the expanse of using an external
ISO7816 pin adapter, not the one
embedded on the board).
---------------- ---------------------- --------------------------------------
Debug DEBUG=0 (default) This activates or desactivates
DEBUG=1 the debug console. This console shows
the protocol commands and responses
and can help when debugging issues.
FORCE_TTY_DEBUG=0 This forces the debug output to go
FORCE_TTY_DEBUG=1 to the console tty output even if
the USB backend is used, allowing
to get a debug without using USB
ACMs. Default is 0 (no force tty
debug).
---------------- ---------------------- --------------------------------------
PLL override HSE_PLLM_OVERRIDE=XX This option should be manipulated
with care as it can break the
firmware of existing boards. This
option should be used when adding a
new board or when using a flavour
of the existing boards that use a
crystal (HSE external oscillator)
that is not on par with the public
schematics of the boards.
This modifies the internal value
of the HSE (external clock) of the
MCU in MHz (e.g. HSE_PLLM_OVERRIDE=8
means a clock at 8MHz).
---------------- ---------------------- --------------------------------------

NOTE: the USART and BITBANG modes can be dynamically chosen (i.e. it is possible to switch from one to another at firmware runtime) using the set_mode protocol command. When using this command, all the ISO7816 backend will switch from one mode to another.

Please beware that the BITBANG mode is interesting, but suffer from obvious limitations when it comes to frequency or "agressive" ETUs: in general, it is recommended to stick to an ISO7816 clock frequency of less than 1MHz (usually 500 KHz is a conservative value), the issue being that some smart cards will not accept such low frequencies. On the ETU side, is is recommended to use slow ETUs such as 372, since the agressive ones (e.g. ETU=8) will put the bitbanging software handling beyond its limits. Generally speaking, each smart card will be different and more or less tolerant when configuring bitbanding. Additionally, T=0 and T=1 protocols will make a difference here since the T=1 protocol is inherently more sensible to baud rate.

Dependencies

The main compilation dependency is an arm-none-eabi toolchain that should be packaged with your favourite distro, allowing bare metal firmware compilation for ARM v7m (Cortex-M) microcontrollers.

The other required dependencies are mainly for flashing the firmware, and will depend on the board you target:

  • For LEIA boards where the DFU protocol can be used, the dfu-util tool must be installed and used (this should be packaged in your distro). You will also need the python3-usb (either from your distro packages or from pip).
  • For the other boards where SWD is used to flash the firmware, the st-flash tool is necessary. This is packaged on some distros, but can also be compiled from sources. An alternative way of flashing firmwares using SWD is to use openocd, this is not in the current Makefile and is left as a side work for those who prefer to use this tool.

Compilation

Compilation is as simple as:

FLAGS=... make

where FLAGS are the ones previously specified.

If you want to build a production firmware for the LEIA board while forcing the debug output:

DEBUG=1 make

And if you want to force the debug output on the physical tty console of the board:

FORCE_TTY_DEBUG=1 DEBUG=1 make

The end of the compilation should grant you with a summary of the firmware chosen options, for example with a make with no specific option:

$ make
...
   text	   data	    bss	    dec	    hex	filename
  50364	   1840	  51692	 103896	  195d8	build/leia-halst.elf
   [+] **LEIA** board selected (default) 
      ---------------------------------
   [+] DEBUG activated
       (debug on physical UART forced)
       (debug on USB UART abstraction)
   [+] Protocol on USB UART abstraction
       (this is the default protocol and debug consoles channel)
   [+] ISO7816 using USART or BITBANG (selected at runtime, default is USART)

When compiling with DISCO407=1 USB=0 DEBUG=1 options:

$ DISCO407=1 USB=0 DEBUG=1 make
...
   text	   data	    bss	    dec	    hex	filename
  46820	   1220	  49056	  97096	  17b48	build/leia-halst.elf
   [+] **DISCO** board selected
          (DISCO F407 board)
      ---------------------------------
   [+] DEBUG activated
       (debug on physical UART)
   [+] Protocol on physical UART
   [+] ISO7816 using USART or BITBANG (selected at runtime, default is USART)

Programming the boards

On LEIA boards, you can use the DFU mode of the STM32F4 bootrom. To activate it, you need to:

1. Connect LEIA to one of your USB ports
2. Hold the reset button
3. Press *also* the DFU button
4. Release the reset button while keeping the DFU button pressed for 1 second
5. Run `make dfu` from your favorite shell

On the WooKey board, you will have to use SWD (Single Wire Debug) protocol to flash the board, using e.g. an ST-Link V2 connector connected to the proper pins. Once connected, you can use the make burn target to burn the firmware in the board.

On the DISCO boards (STM32 Discovery F407 and F429), an ST-Link V2 chip is already present on the board and you should be able to directly run make burn to flash the boards. Beware that the mini-USB port is used for flashing, and the micro-USB OTG port is used for LEIA protocol and debug /dev/ttyACMx interfaces.

Boards specific pinouts

The supported boards are LEIA, WOOKEY (WooKey board), DISCO407 (STM32 Discovery F407) and DISCO429 (STM32 Discovery F429). Other boards can be added by modifying the source code, mainly by adapting the configuration files. The pinout is not the same depending on the board, here is a summary:

Board ISO7816 USART ISO7816 Bitbang Protocol USART Debug USART
LEIA Reset: PC12 Reset: PC12 TX: PA0 TX: PB6
Vcc : PD7 Vcc : PD7 RX: PA1 RX: -
I/O : PA2 I/O : PA2
I/O dir: PE3 I/O dir: PE3 NOTE: no RX pin
Clock: PA4 Clock: PA3 since debug is
Contact: PC11 Contact: PC11 monodirectional
(optional pins) (optional pins)
Vpp : PC10 Vpp : PC10
Aux1 : PE5 Aux1 : PE5
Aux2 : PE6 Aux2 : PE6
NOTE: I/O dir is NOTE: I/O dir is
used for opto- used for opto-
coupling. coupling.
--------- ----------------- ------------------ ---------------- ----------------
WOOKEY Reset: PE3 - TX: PA0 TX: PB6
Vcc : PD7 RX: PA1 RX: -
I/O : PA2 NOTE: WooKey does
I/O dir: - not support NOTE: no RX pin
Clock: PA4 Bitbang as is. since debug is
Contact: PE2 monodirectional
(optional pins)
Vpp : PE7
Aux1 : PE5
Aux2 : PE6
--------- ----------------- ------------------ ---------------- ----------------
DICO: Reset: PE3 Reset: PE3 TX: PC10 TX: PB6
Vcc : PD7 Vcc : PD7 RX: PC11 RX: -
DISCO407 I/O : PA2 I/O : PA2
and I/O dir: - I/O dir: - NOTE: no RX pin
DISCO429 Clock: PA4 Clock: PA3 since debug is
Contact: PE2 Contact: PE2 monodirectional
(optional pins) (optional pins)
Vpp : PE7 Vpp : PE7
Aux1 : PE5 Aux1 : PE5
Aux2 : PE6 Aux2 : PE6
--------- ----------------- ------------------ ---------------- ----------------

NOTE1: regarding UARTs, TX and RX are board centric, meaning that TX means data from board to PC host, and RX means data from PC host to board.

NOTE2: "Protocol USART" and "Debug USART" are only available when selecting the USB=0 toggle (and DEBUG=1 specifically for the "Debug USART"). By default (USB=1), protocol and debug communication channels use the USB FS (Full Speed) connector and show up as /dev/ttyACMx and /dev/ttyACMy devices on the PC host side. Usually, /dev/ttyACMx is the protocol console and /dev/ttyACMy is the debug console when x < y.

WARNING: beware that some services such as modemmanager might interfere with the boards proper functionning when they see /dev/ttyACMx. You will have to manually disable such packages for the LEIA firmware nominal usage.

The flasher mode

WARNING: regarding LEIA, only new revisions of the board include the flasher mode (old revisions do not include it). Please check your hardware revision before trying to use this mode.

For the LEIA and DISCO boards, there is a specific mode called the flasher mode that has nothing to do with ISO7816. This mode allows to flash AVR based funcards (e.g. ATMega8515 based chips) using the standard AVR ISP protocol.

The firmware can be put in this specific mode (from the nominal ISO7816 mode) using the goto_flasher protocol command that resets the board and reconfigures it in this mode.

When switched to the flasher profile, the board exposes an STK500 compatible interface over USB, allowing to use standard tools such as avrdude that should be packaged in most distributions. The first ttyACM interface exposed by the board must be used for the flashing purpose, the other is used for debug purposes (similarly to the ISO7816 mode).

Let us imagine that a firmware has been compiled for the ATMega8515 AVR based funcard in two HEX files: /tmp/flash.hex for the internal flash, and /tmp/eeprom.hex for the EEPROM. Then, if /dev/ttyACM0 is the interface exposed by the board, it is possible to flash this firmware using avrdude and the following command line:

$ avrdude -p m8515 -c avrisp2 -P /dev/ttyACM0 -U flash:w:/tmp/flash.hex:i -U eeprom:w:/tmp/eeprom.hex:i