Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2024-10-01 01:45:38 -04:00
Code Issues Packages Projects Releases Wiki Activity
c9755e4cca
tillitis-key/doc/quickstart.md
Daniel Lublin 34407a32ce
Update doc for revised tpt
2022-09-28 08:30:31 +02:00

3.5 KiB
Raw Blame History

This document describes how to build the FPGA bitstream, including the firmware, and get this programmed onto the flash memory of the Tillitis Key 1 USB device.

The Tillitis Key 1 kit includes:

  • Tillitis Key 1 USB stick with USB-C plug, marked MTA1-USB V1
  • Programmer board based on Raspberry Pi Pico, with a white holder/jig
  • USB cable with micro-B plug, for connecting the programmer to computer
  • USB-C extension cable
  • USB-C to USB-A adapter

Programming FPGA bitstream and firmware onto Tillitis Key 1

Connect the programmer to the computer using the USB cable with micro-B plug.

Place the Tillitis Key 1 (the USB stick) correctly in the programming jig and close the hatch.

The USB stick can remain in the jig during repeated development, programming and testing cycles. The USB stick should then be connected to the computer using the provided USB-C cable (use the USB-C-to-A adapter if needed). Note that connecting the USB stick to the computer is not required for programming it. For this purpose, the jig also has a cutout to allow touching where the touch sensor is located, next to the LED.

On Linux, lsusb should list the connected programmer as cafe:4004 Blinkinlabs ICE40 programmer. If the USB stick is also connected it shows up as 1207:8887 Tillitis MTA1-USB-V1.

To install the software needed for building and programming, please refer to toolchain_setup.md.

You are now ready to generate the FPGA bitstream (including building the standard firmware) and program it onto the flash memory of the USB stick. The following should be run as your regular non-root user, but the programming is currently done using sudo (so sudo is expected to be set up for your user; the Makefile runs sudo tillitis-iceprog …).

$ git clone https://github.com/tillitis/tillitis-key1
$ cd tillitis-key1/hw/application_fpga
$ make prog_flash

After programming, the Tillitis Key 1 USB stick can be connected to your computer (use the USB-C-to-A adapter if needed) and will boot the firmware. When boot has completed it will start flashing the LED white. This indicates that it is ready to receive and measure an app.

To try out an app, continue to the README.md the apps repo: https://github.com/tillitis/tillitis-key1-apps#readme

To learn more about the concepts and workings of the firmware, see: system_description/system_description.md and system_description/software.md.

Device personalization

To personalize Tillitis Key 1, you need to modify the hex file that contains the Unique Device Secret (UDS). You should also update the Unique Device Identity (UDI). These hex files are located in hw/application_fpga/data/. Note that after modify the files in this directory, you need to rebuild and program the device again (as above).

To make this easier there is a tool that can generate these files. The tool can be found in hw/application_fpga/tools/tpt. The tool allow you to supply a secret used as part of the UDS generation. The tool can be run interactively, or by suppling inputs on the command line:

usage: tpt.py [-h] [-v] [--ent ENT] [--vid VID] [--pid PID] [--rev REV] [--serial SERIAL]

options:
  -h, --help       show this help message and exit
  -v, --verbose    Verbose operation
  --ent ENT        User supplied entropy
  --vid VID        Vendor id (0 - 65535)
  --pid PID        Product id (0 - 2555
  --rev REV        Revision number (0 - 15)
  --serial SERIAL  Serial number (0 - (2**31 - 1))