path: root/docs/fingerprint/fingerprint-dev-for-partners.md

# FPMCU Development for Partners

This document is intended to help partners (sensor vendors, MCU vendors, etc)
that are currently (or interested in) developing fingerprint solutions for
Chromebooks. The document assumes that you're using Linux to do the
development; preferably a recent version of Ubuntu or Debian. Some partners
have had success developing in a VM, but please note that we don't test that
configuration.

[TOC]

## Hardware Required for Standalone Development (no Chromebook)

The following hardware components can be used to set up a standalone
development environment for FPMCU development (i.e., it does not rely on a
Chromebook). Development for other [EC]s is often done in a similar manner, but
some of them have their own standalone development or evaluation kits that don't
require the use of [servo].

### Servo v2

Servo v2 is a general purpose debug board that connects to a header on the
FPMCU board. It supports SPI as well as JTAG/SWD.

*** note
NOTE: More information on servo can be found in the [servo] documentation.
***

![Servo v2]

### Yoshi Flex Cable

The Yoshi Flex cable is used to connect Servo v2 to the FPMCU board. The
standard cable does not work with SWD, but a simple rework can be performed to
support SWD.

#### Standard Yoshi Flex

![Standard Yoshi Flex]

#### Yoshi Flex Reworked to Support SWD

*   Remove R18 and R19
*   Wire from Pin 6 of U21 to right side of R18
*   Wire from Pin 6 of U21 to right side of R19

![Yoshi Flex Reworked to Support SWD]

### FPMCU board

The FPMCU board has the MCU that handles all fingerprint-related functionality
(matching, encryption, etc). The fingerprint sensor itself connects to the
FPMCU board.

![DragonClaw board]

### Micro USB Cable

A micro USB cable is needed to connect the the servo v2 board to your host Linux
development machine.

*   [Micro USB Cable]

## Hardware Setup

### Connect Yoshi Flex

Connect the Yoshi Flex cable to servo, paying attention to the pin numbering.

![Connect Yoshi Flex]

![Another Yoshi Flex image]

### Connect Yoshi Flex to FPMCU Board

Connect the other end of the Yoshi Flex cable to the servo header on the FPMCU
board.

![Connect Yoshi Flex to FPMCU board]

![Another image]

### Connect Sensor to FPMCU

Connect the fingerprint sensor to the header on the FPMCU board.

### Connect USB to Servo

Connect the micro USB cable to servo's `HOST_IN` port. The other end of the USB
cable should be plugged into your host development machine.

![Connect USB to Servo]

### Optional: Connect SWD Debugger

If you want to use SWD for debugging, connect your debugger to the `JTAG` header
on servo v2.

![Connect SWD Debugger]

## Software Setup

### Get the Chromium OS source code

*   First, make sure you [have the prerequisites].
*   Then [get the source].
*   Create and [enter the `chroot`].
    *   You can stop after the `enter the chroot` step.

### Build the [EC] (embedded controller) codebase

Open **two** terminals and enter the chroot in each:

```bash
# from a terminal on your machine
(outside chroot) $ cd ~/chromiumos/src

# enter the chroot (the flag is important)
(outside chroot) $ cros_sdk --no-ns-pid
```

*** note
NOTE: More information on servo can be found in the [servo] documentation.
***

In the one of the terminals, build and start `servod`:

Build and install `servod` in the chroot:

```bash
(chroot) $ sudo emerge hdctools
```

Run `servod`:

```bash
(chroot) $ sudo servod --board=bloonchipper
```

You should see something like this. Leave it running:

```bash
2019-04-11 15:21:53,715 - servod - INFO - Start
2019-04-11 15:21:53,765 - servod - INFO - Found servo, vid: 0x18d1 pid: 0x5002 sid: 911416-00789
2019-04-11 15:21:53,766 - servod - INFO - Found XML overlay for board zerblebarn
2019-04-11 15:21:53,766 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servo_v2_r1.xml, None, 0)
2019-04-11 15:21:53,767 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servo_v2_r0.xml, None, 0)
2019-04-11 15:21:53,771 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/common.xml, None, 0)
2019-04-11 15:21:53,772 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/power_tools.xml, None, 0)
2019-04-11 15:21:53,774 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/keyboard.xml, None, 0)
2019-04-11 15:21:53,775 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/uart_common.xml, None, 0)
2019-04-11 15:21:53,777 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/ftdii2c_cmd.xml, None, 0)
2019-04-11 15:21:53,777 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/usb_image_management.xml, None, 0)
2019-04-11 15:21:53,784 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servo_zerblebarn_overlay.xml, None, 0)
2019-04-11 15:21:53,785 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servoflex_v2_r0_p50.xml, None, 0)
2019-04-11 15:21:53,792 - Servod - INFO - Initializing interface 1 to ftdi_dummy
2019-04-11 15:21:53,792 - Servod - INFO - Initializing interface 2 to ftdi_i2c
2019-04-11 15:21:53,795 - Servod - INFO - Initializing interface 3 to ftdi_uart
2019-04-11 15:21:53,799 - Servod - INFO - /dev/pts/8
2019-04-11 15:21:53,799 - Servod - INFO - Initializing interface 4 to ftdi_uart
2019-04-11 15:21:53,802 - Servod - INFO - /dev/pts/9
2019-04-11 15:21:53,802 - Servod - INFO - Use the next FTDI part @ pid = 0x5003
2019-04-11 15:21:53,802 - Servod - INFO - Initializing interface 5 to ftdi_dummy
2019-04-11 15:21:53,802 - Servod - INFO - Use the next FTDI part @ pid = 0x5003
2019-04-11 15:21:53,802 - Servod - INFO - Initializing interface 6 to ftdi_dummy
2019-04-11 15:21:53,802 - Servod - INFO - Use the next FTDI part @ pid = 0x5003
2019-04-11 15:21:53,802 - Servod - INFO - Initializing interface 7 to ftdi_uart
2019-04-11 15:21:53,805 - Servod - INFO - /dev/pts/10
2019-04-11 15:21:53,805 - Servod - INFO - Use the next FTDI part @ pid = 0x5003
2019-04-11 15:21:53,805 - Servod - INFO - Initializing interface 8 to ftdi_uart
2019-04-11 15:21:53,808 - Servod - INFO - /dev/pts/11
2019-04-11 15:21:53,808 - Servod - INFO - Initializing interface 9 to ec3po_uart
2019-04-11 15:21:53,811 - PD/Cr50 - EC3PO Interface - INFO - -------------------- PD/Cr50 console on: /dev/pts/12
2019-04-11 15:21:53,811 - Servod - INFO - Initializing interface 10 to ec3po_uart
2019-04-11 15:21:53,812 - EC - EC3PO Interface - INFO - -------------------- EC console on: /dev/pts/14
2019-04-11 15:21:54,316 - Servod - INFO - Initialized i2c_mux to rem
2019-04-11 15:21:54,317 - Servod - INFO - Initialized i2c_mux_en to on
2019-04-11 15:21:54,319 - Servod - INFO - Initialized pch_disable to off
2019-04-11 15:21:54,320 - Servod - INFO - Initialized jtag_buf_on_flex_en to off
2019-04-11 15:21:54,321 - Servod - INFO - Initialized cold_reset to off
2019-04-11 15:21:54,322 - Servod - INFO - Initialized warm_reset to off
2019-04-11 15:21:54,323 - Servod - INFO - Initialized spi1_buf_on_flex_en to off
2019-04-11 15:21:54,324 - Servod - INFO - Initialized spi_hold to off
2019-04-11 15:21:54,326 - Servod - INFO - Initialized pwr_button to release
2019-04-11 15:21:54,327 - Servod - INFO - Initialized lid_open to yes
2019-04-11 15:21:54,328 - Servod - INFO - Initialized spi2_buf_on_flex_en to off
2019-04-11 15:21:54,330 - Servod - INFO - Initialized rec_mode to off
2019-04-11 15:21:54,331 - Servod - INFO - Initialized fw_up to off
2019-04-11 15:21:54,332 - Servod - INFO - Initialized usb_mux_sel1 to dut_sees_usbkey
2019-04-11 15:21:54,333 - Servod - INFO - Initialized prtctl4_pwren to on
2019-04-11 15:21:54,334 - Servod - INFO - Initialized uart3_en to on
2019-04-11 15:21:54,334 - Servod - INFO - Initialized dut_hub_pwren to on
2019-04-11 15:21:54,335 - Servod - INFO - Initialized kbd_en to off
2019-04-11 15:21:54,337 - Servod - INFO - Initialized spi1_vref to pp3300
2019-04-11 15:21:54,338 - Servod - INFO - Initialized spi2_vref to pp1800
2019-04-11 15:21:54,339 - Servod - INFO - Initialized uart2_en to on
2019-04-11 15:21:54,340 - Servod - INFO - Initialized uart1_en to on
2019-04-11 15:21:54,341 - Servod - INFO - Initialized jtag_buf_en to off
2019-04-11 15:21:54,342 - Servod - INFO - Initialized fw_wp_en to off
2019-04-11 15:21:54,343 - Servod - INFO - Initialized sd_vref_sel to off
2019-04-11 15:21:54,343 - Servod - INFO - Initialized ec_ec3po_interp_connect to on
2019-04-11 15:21:54,344 - Servod - INFO - Initialized uart3_vref to off
2019-04-11 15:21:54,345 - Servod - INFO - Initialized jtag_vref_sel0 to pp3300
2019-04-11 15:21:54,346 - Servod - INFO - Initialized jtag_vref_sel1 to pp3300
2019-04-11 15:21:54,346 - Servod - INFO - Initialized fpmcu_ec3po_interp_connect to on
2019-04-11 15:21:54,349 - ServoDeviceWatchdog - INFO - Watchdog setup for devices: set([(6353, 20482, '911416-00789')])
2019-04-11 15:21:54,351 - servod - INFO - Listening on localhost port 9999
```

In the other terminal, build and flash the firmware:

Navigate to the EC source:

```bash
(chroot) $ cd ../platform/ec
```

Build the firmware:

```bash
(chroot) $ make BOARD=bloonchipper -j
```

The resulting file will be in `build/bloonchipper/ec.bin`

Flash the firmware file:

```bash
(chroot) $ ./util/flash_ec --board=bloonchipper --image=./build/bloonchipper/ec.bin
```

Connect to the UART pty:

```bash
(chroot) $ sudo screen $(dut-control raw_fpmcu_uart_pty | cut -d: -f2)
```

Press enter key several times (may need to wait up to 20 seconds). Then you will
see a prompt:

```
>
```

At this point you are connected to the MCU's serial (UART) console. You can list
all of the available console commands with "help":

```
> help
```

```bash
Known commands:
  chan           fpcapture      hcdebugsherase     fpenroll       history        spixfer        waitms
  flashinfo      fpmatch        hostevent      sysinfo
  flashread      gettime        md             sysjump
  flashwp        gpioget        panicinfo      syslock
  flashwrite     gpioset        reboot         taskinfo
HELP LIST = more info; HELP CMD = help on CMD.
```

Start a fingerprint enrollment:

```
> fpenroll
```

### Contributing Changes

#### Using Gerrit and git

If you’re not familiar with `git`, Gerrit (code review) and `repo`, here are
some docs to help you get started:

*   [Git and Gerrit Intro for Chromium OS]: Useful to get started as quickly as
    possible, but does not explain how `git` works under the hood.
*   [Set your editor]: Use your favorite editor when writing `git` commit
    messages.
*   [Chromium OS Contributing Guide]: Detailed overview of contributing changes
    to Chromium OS and the workflow we use.
*   [Git: Concepts and Workflow]: Good overview of how `git` actually works.
*   [Gerrit: Concepts and Workflow]: Good overview of how Gerrit works; assumes
    you understand `git` basics.
*   [Life of a patch]: Android workflow, but similar to Chrome OS.

The Gerrit dashboard that will show your pending reviews (and ones we have for
you):

*   [Public Gerrit]
*   [Internal Gerrit]

#### Registering for a chromium.org *Internal* Account

If your partnership agreement requires non-public code sharing you will need to
register for an account on the [Internal Gerrit]. Refer to the
[Gerrit Credentials Setup] page for details. Once you register for an internal
account, your contact at Google can make sure you have the necessary permissions
to access the necessary repo.

## Working with Chromebooks

Chromebooks have an FPMCU (e.g., DragonClaw) board attached to the motherboard.
You can use the device to run `ectool` commands and test the fingerprint sensor
from the UI.

### Developer Mode and Write Protection

Make sure that your fingerprint-equipped Chrome OS device is in [developer
mode] with a *test* image flashed and [hardware write protection] disabled.
Using the test image will allow you to SSH into the device and disabling
hardware write protection allows you to have full access to flashing the FPMCU
firmware.

See [Installing Chromium] for details on flashing test images and enabling
[developer mode].

### Connecting

In general, most of our development is done by connecting to the DUT (device
under test) via SSH. We usually connect the DUT to ethernet (e.g., via USB-C to
Ethernet converter), but WiFi should also work (assuming corporate firewall
restrictions don’t block SSH port 22). To get the IP address, tap the
battery/time icon in the lower right corner. Then tap on “Ethernet” followed by
the gear icon in the upper right.

```bash
(chroot) $ ssh root@<IP_ADDRESS>
Password: test0000
```

Once you have SSH’ed into the DUT, you should be able to run `ectool` commands.

**Example**: Capture a "test_reset" image from the sensor and write it to a
[PNM] file (viewable with the ImageMagick `display` command):

```bash
(device) $ ectool --name=cros_fp fpmode capture test_reset; ectool --name=cros_fp waitevent 5 500; ectool --name=cros_fp fpframe > /tmp/test_reset.pnm
```

Alternatively, you can access a shell via the UI on device by pressing
`CTRL+ALT+F2` (third key on top row). Log in with `root` and `test0000`.

### Flashing FPMCU from DUT

Copy the firmware to the DUT:

```bash
(chroot) $ scp ./build/bloonchipper/ec.bin <DUT_IP>:/tmp/ec.bin
```

From the DUT, flash the firmware you copied:

```bash
(device) $ flash_fp_mcu /tmp/ec.bin
```

## Troubleshooting

### Verify that servo and debugger are connected to USB {#servo-connected}

Check whether servo is enumerating on USB. If you are using a debugger
(Lauterbach, J-Link, etc), also check to make sure it enumerates. Depending on
the debugger being used, it may need to be powered with an external power
supply.

```bash
(chroot) $ lsusb

Bus 002 Device 003: ID 0897:0004 Lauterbach  # ← This is my Lauterbach (debugger)
Bus 001 Device 013: ID 18d1:5002 Google Inc. # ← This is servo
```

### "No servos found" when running servod

If you get the following message, make sure that
[servo is connected to USB](#servo-connected). You may also want to try
restarting your machine (or VM).

```bash
(chroot) $ sudo servod --board=bloonchipper
2019-04-12 14:53:42,236 - servod - INFO - Start
2019-04-12 14:53:42,270 - servod - ERROR - No servos found
```

### Losing characters in servo UART console

Make sure that this interface is disabled:

```bash
(chroot) $ dut-control usbpd_ec3po_interp_connect:off
```

### "Sweetberry" board fails to build

If you're trying to run `make buildall -j` in the EC codebase and the build
fails when trying to build the "sweetberry" board, see this bug:
https://crbug.com/992082.

### FPMCU console commands

*   Once the console is working you can use `help` to see the commands.
*   There should be fingerprint commands that start with `fp` (see `fpsensor.c`
    in the [EC] code).

<!-- Links -->

[EC]: https://chromium.googlesource.com/chromiumos/platform/ec
[ectool_servo_spi]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/util/comm-servo-spi.c#15
[servo]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/README.md
[developer mode]: https://chromium.googlesource.com/chromiumos/docs/+/master/debug_buttons.md#firmware-keyboard-interface
[hardware write protection]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/docs/write_protection.md
[have the prerequisites]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#Prerequisites
[get the source]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#get-the-source
[enter the `chroot`]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#building-chromium-os
[Chromium OS Contributing Guide]: https://chromium.googlesource.com/chromiumos/docs/+/master/contributing.md
[Set your editor]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#Set-your-editor
[Life of a patch]: https://source.android.com/setup/contribute/life-of-a-patch
[Git: Concepts and Workflow]: https://docs.google.com/presentation/d/1IQCRPHEIX-qKo7QFxsD3V62yhyGA9_5YsYXFOiBpgkk/
[Gerrit: Concepts and Workflow]: https://docs.google.com/presentation/d/1C73UgQdzZDw0gzpaEqIC6SPujZJhqamyqO1XOHjH-uk/
[Public Gerrit]: https://chromium-review.googlesource.com
[Internal Gerrit]: https://chrome-internal-review.googlesource.com
[Gerrit Credentials Setup]: https://www.chromium.org/chromium-os/developer-guide/gerrit-guide
[Micro USB Cable]: https://www.monoprice.com/product?p_id=9762
[PNM]: https://en.wikipedia.org/wiki/Netpbm_format
[Git and Gerrit Intro for Chromium OS]: https://chromium.googlesource.com/chromiumos/docs/+/master/git_and_gerrit_intro.md
[Installing Chromium]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#installing-chromium-os-on-your-device

<!-- Images -->

[Servo v2]: ../images/servo_v2.jpg
[Standard Yoshi Flex]: ../images/yoshi_flex.jpg
[Yoshi Flex Reworked to Support SWD]: ../images/yoshi_flex_swd_rework.jpg
[DragonClaw board]: ../images/dragonclaw.jpg
[Connect USB to Servo]: ../images/servo_v2_with_micro_usb.jpg
[Connect Yoshi Flex]: ../images/servo_v2_with_yoshi_flex.jpg
[Another Yoshi Flex image]: ../images/servo_v2_with_yoshi_flex2.jpg
[Connect Yoshi Flex to FPMCU board]: ../images/dragonclaw_yoshi_flex_header.jpg
[Another image]: ../images/dragonclaw_yoshi_flex_header2.jpg
[Connect SWD Debugger]: ../images/servo_v2_jtag_header.jpg