tillitis-key/hw/production_test/README.md
Matthew Mets 072b204d3d
Add (hardware) production tests for the TK-1 and TP-1 (#69)
* ch552 firmware: add ch55x support files directly

* Add sdcc compiler to docker image, for building CH552 firmware

* Rework production test script

* Add menu-based test runner
* Rewrite production test flows as lists of individual tests
* Add both production flows and manual tests to menu

* Switch to using included binaries

* production test: Update message format
* test_txrx_touchpad: Retry if device communications fail
* production test: put all binaries in binaries/ folder
* binaries/top.bin: replace broken binary

* flash_check: Check for explicit flash IDs

* Document most test procedures

* Test plan documentation

* Sample udev rules

* Production test: allow external references to be overridden

* Remove outdated descriptions

* Correct shebang

* Update shebangs to comply with PEP 394

Change the python scripts to call python instead of python3, as this
works cross platform. See:
https://peps.python.org/pep-0394/#for-python-script-publishers

* Move production test to higher-level directory

* Clarify production test setup

* Move USB C connector test to separate directory

Co-authored-by: Michael Cardell Widerkrantz <mc@tillitis.se>
2023-01-11 16:33:01 +01:00

337 lines
12 KiB
Markdown

# TK-1 and TP-1 production tests
Production tests for the TK-1 and TP-1 PCBs
## Usage
These instructions are tested on Ubuntu 22.10.
Set up a python virtualenv to run the production test:
sudo apt install python3.10-venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
deactivate
To run the production test script:
source venv/bin/activate
./production_test.py
The script will then print a menu with all available tests:
Tillitis TK-1 and TP-1 Production tests
=== Test sequences ===
1. tk1_test_sequence: voltage_test, flash_validate_id, flash_program, sleep_2, test_extra_io, ch552_program, test_txrx_touchpad
2. tp1_test_sequence: program_pico, sleep_2, flash_validate_id
3. mta1_usb_v1_programmer_test_sequence: program_pico, sleep_2, voltage_test, flash_validate_id, sleep_2, test_extra_io
=== Manual tests ===
4. program_pico: Load the ice40 flasher firmware onto the TP-1
5. voltage_test: Measure 3.3V 2.5V, and 1.2V voltage rails on the TK-1
6. flash_validate_id: Read the ID from TK-1 SPI flash, and verify that it matches the expected value
7. flash_program: Program and verify the TK-1 SPI flash with the application test gateware
8. flash_check: Verify the TK-1 SPI flash is programmed with the application test gateware
9. test_extra_io: Test the TK-1 RTS, CTS, and GPIO1-4 lines by measuring a test pattern generated by the app_test gateware
10. ch552_program: Load the CDC ACM firmware onto a CH552 with a randomly generated serial number, and verify that it boots correctly
11. test_txrx_touchpad: Test UART communication, RGB LED, and touchpad by asking the operator to interact with the touch pad
12. enable_power: Enable power to the TK-1
13. disable_power: Disable power to the TK-1
Please type an option number and press return:
There are two types of tests listed: test sequences, which are used
to run full production tests, and manual tests, which are used to
test a single subcircuit. It is recommended to test all boards using
a test sequence first, and to use the manual tests for diagnosing
issues with individual boards, or for re-testing repaired boards.
## Test Sequences
These sequences are used as production tests for the TK-1 and TP-1.
### TK-1 production test (tk1_test_sequence)
This test checks all major subcircuits on the TK-1, and is used to
verify that the PCBA was assembled correctly. It should be run on all
newly assembled TK-1 boards.
Requirements:
* Programmed MTA1_USB_V1_Programmer board, fitted with a wider (green)
plastic clip
* Unprogrammed TK-1
* USB micro cable to attach TP-1 board to computer
* USB C extension cable to attach TK-1 to computer
It runs the following tests, in order:
1. voltage_test
2. flash_validate_id
3. flash_program
4. sleep_2
5. test_extra_io
6. ch552_program
7. test_txrx_touchpad
Note: If the CH552 has been programmed already, then the test
sequence will fail. In that case, manually run the other tests
in the sequence, skipping the 'ch554_program' test.
### TP-1 (tp1_test_sequence)
This test programs a TP-1, then tests that it can program a TK-1.
It should be run on all newly assembled TP-1 boards.
Requirements:
* Unprogrammed TP-1
* TK-1 programmed with the application test gateware
* USB micro cable to attach TP-1 board to computer
The TP-1 production test runs the following tests, in order:
1. program_pico
2. sleep_2
3. flash_validate_id
### MTA1_USB_V1_Programmer (mta1_usb_v1_programmer_test_sequence)
Requirements:
* Unprogrammed MTA1_USB_V1_Programmer
* TK-1 programmed with the application test gateware
* USB micro cable to attach MTA1_USB_V1_Programmer board to computer
The TP-1 production test runs the following tests, in order:
1. program_pico
2. sleep_2
3. voltage_test
4. flash_validate_id
5. sleep_2
6. test_extra_io
## Individual tests
These tests target a specific sub-circuit or funcationality on the
TP-1 and TK-1. Each test is designed to be run successfully in
isolation.
### program_pico: Load the ice40 flasher firmware onto the TP-1
This test loads the ice40_flasher firmware into the TP-1.
Usage instructions:
1. Attach an unprogrammed TP-1 to the computer using a micro USB
cable.
2. Run the test.
3. The test program will copy the firmware onto the TP-1.
4. Once the firmware is copied, the TP-1 will automatically reset,
and re-initialize as a ice40_flasher.
Notes:
* This test assumes that the computer is configured to auto-mount USB
storage devices, and that the Pico will be mounted to
/media/lab/RPI-RP2. This is true for a computer runnnig Ubuntu 22.10
when a user is logged into a Gnome GUI session. The script will need
to be adjusted for other environments.
### voltage_test: Measure 3.3V 2.5V, and 1.2V voltage rails on the TK-1
This test uses ADC in the Pico to measure the power supplies on the
TK-1. It samples the voltage of each power supply multiple times,
averages the result, and verifies that they are within +/-0.2V of the
specification.
Usage instructions:
1. Attach a programmed/tested MTA1_USB_V1_Programmer to the computer
using a micro USB cable.
2. Place a TK-1 into the MTA1_USB_V1_Programmer. The TK-1 can be
programmed or unprogrammed.
3. Run the test.
4. The test will use the MTA1_USB_V1_Programmer to power on the TK-1,
measure the voltage rails, then power off the TK-1.
5. The test will report the measurements and pass/fail metric.
Notes:
* The accuracy of the ADC is poor; external hardware would be
required to do a more extensive test. The power supplies used are
all fixed-voltage devices, so the chance of of an off-spec (but
still working) device is considered to be low.
* This test does not verify that the power sequencing is correct.
### flash_validate_id: Read the ID from TK-1 SPI flash, and verify that it's not all 0's or 1's
This test uses the TP-1 or MTA1_USB_V1_Programmer to read a TK-1 SPI
flash ID. It can be used to quickly check if a TK-1 device is
inserted properly into the programmger.
Usage instructions:
1. Attach a programmed/tested MTA1_USB_V1_Programmer or TP-1 to the
computer using a micro USB cable.
2. Place a TK-1 into the MTA1_USB_V1_Programmer. The TK-1 can be
programmed or unprogrammed.
3. Run the test.
4. The test will use the programmer to power on the TP-1, read out
the SPI flash ID, then power off the TK-1.
5. The test will check if the flash ID matches any known valid flash
ID types.
6. If the flash ID matches an known value, the test will print the
type and return a pass metric.
7. If the flash ID does not match a known value, the test will print
the type and return a pass metric.
Notes:
* An earlier version of this test just checked if the flash ID was
0x00000000 or 0xFFFFFFFF; this version is more exact.
### flash_program: Program and verify the TK-1 SPI flash with the application test gateware
This test uses the TP-1 or MTA1_USB_V1_Programmer to write the
application test gateware a TK-1 SPI flash. This gateware is needed
to run the test_extra_io and test_txrx_touchpad tests. The test uses
the external iceprog utility to perform the flash operation.
Usage instructions:
1. Attach a programmed/tested MTA1_USB_V1_Programmer or TP-1 to the
computer using a micro USB cable.
2. Place a TK-1 into the MTA1_USB_V1_Programmer. The TK-1 can be
programmed or unprogrammed.
3. Run the test.
4. The test will use the programmer to power on the TP-1, program the
SPI flash with the gateware, verify the flash by reading the data
back out, then power off the TK-1.
5. The test will report a pass/fail metric vased on the result of the
verification phase.
### flash_check: Verify the TK-1 SPI flash is programmed with the application test gateware
This test uses the TP-1 or MTA1_USB_V1_Programmer to verify that the
application test gateware is written to a TK-1 SPI flash. The test
uses the external iceprog utility to perform the verification
operation.
Usage instructions:
1. Attach a programmed/tested MTA1_USB_V1_Programmer or TP-1 to the
computer using a micro USB cable.
2. Place a programmed TK-1 into the MTA1_USB_V1_Programmer.
3. Run the test.
4. The test will use the programmer to power on the TP-1, verify the
flash by reading the data back out, then power off the TK-1.
5. The test will report a pass/fail metric vased on the result of the
verification phase.
### test_extra_io: Test the TK-1 RTS, CTS, and GPIO1-4 lines by measuring a test pattern generated by the app_test gateware
This test uses MTA1_USB_V1_Programmer to verify that the RTS, CTS, and
GPIO1-4 lines are connected correctly to the ICE40 FPGA.
On the FPGA side, the application gateware implements a simple state
machine for this test. The RTS line is configured as an input, and
the CTS, GPIO1, GPIO2, GPIO3, and GPIO4 lines are configured as
outputs. The values of the outputs are configured so that only one
output is high at a time, while the rest are low. After reset, the
GPIO4 line is high. Each time the RTS line is toggled, the next
output on the list is set high.
On the programmer side, the Pico GPIO pin connected to the TK-1 RTS
line is configured as an output, and the Pico GPIO pins connected to
the other TK-1 line are configured as inputs. The pico checks that
each input line is working by cycling the RTS output high and low,
then reading the values of each input. This process is repeated 5
times until all output lines are measured, then the results are
compared to a table of expected values.
Usage instructions:
1. Attach a programmed/tested MTA1_USB_V1_Programmer or TP-1 to the
computer using a micro USB cable.
2. Place a programmed TK-1 into the MTA1_USB_V1_Programmer.
3. Run the test.
4. The test will use the programmer to power on the TP-1, run the IO
test, then power off the TK-1.
5. The test will report a pass/fail metric vased on the result of the
test.
### ch552_program: Load the CDC ACM firmware onto a CH552 with a randomly generated serial number, and verify that it boots correctly
TODO
### test_txrx_touchpad: Test UART communication, RGB LED, and touchpad by asking the operator to interact with the touch pad
TODO
### enable_power: Enable power to the TK-1
This test uses the TP-1 or MTA1_USB_V1_Programmer to enable power to
an attached TK-1. This isn't a functional test, but can be used for
manual testing such as measuring voltage rails with a multimeter,
probing clock signals with an oscilloscope, etc.
Usage instructions:
1. Attach a programmed/tested MTA1_USB_V1_Programmer or TP-1 to the
computer using a micro USB cable.
2. Place a TK-1 into the MTA1_USB_V1_Programmer. The TK-1 can be
programmed or unprogrammed.
3. Run the test.
4. The test will use the programmer to power on the TP-1
5. The test will report a pass metric if the command completed
successfully.
### disable_power: Disable power to the TK-1
This test uses the TP-1 or MTA1_USB_V1_Programmer to disable power to
an attached TK-1. This isn't a functional test, but can be used after
the enable_power command was used to turn on a device.
Usage instructions:
1. Attach a programmed/tested MTA1_USB_V1_Programmer or TP-1 to the
computer using a micro USB cable.
2. Place a TK-1 into the MTA1_USB_V1_Programmer. The TK-1 can be
programmed or unprogrammed.
3. Run the test.
4. The test will use the programmer to power off the TP-1
5. The test will report a pass metric if the command completed
successfully.
## Firmware binaries
To make the test environment easier to set up, some pre-compiled
binares are included in the binaries/ subdirectory. These can also be
built from source, by following the below instructions.
Before building the firmware, follow the [toolchain setup](https://github.com/tillitis/tillitis-key1/blob/main/doc/toolchain_setup.md)
instructions.
### CH552 firmware
See the build instructions in the
[ch552_fw](../boards/mta1-usb-v1/ch552_fw/README.md) directory.
### Test Application gateware
This uses the Symbiflow toolchain:
cd ~/tillitis-key1/hw/production_test/application_fpga_test_gateware
make
cp top.bin ../binaries/
### TP-1 Raspberry Pi Pico firmware
Follow the instructions in the [ice40_flasher](https://github.com/Blinkinlabs/ice40_flasher#building-the-firmware)
repository, then copy the output 'main.uf2' file to the binaries
directory.