Orchard Manufacturing Developer's Guide

From Studio Kousagi Wiki
Jump to: navigation, search

When developing a hardware project, it is important to develop tests for individual subsystems. Tests may be declared by placing the orchard_test() directive in any compiled file. For more information, see the Firmware Developer's Guide.


The overall test sequence is as follows:

  1. Boot the test server -- a Raspberry Pi with / mounted readonly. The "green" light will illuminate when it is ready to test.
  2. Load the Device Under Test (DUT) into the jig and depress the lever.
  3. Press the button on the front of the jig. The "yellow" light will illuminate.
  4. Follow the instructions on the screen. They will appear after about fifteen seconds.
  5. When the test is complete, the "green" light will illumiate.
  6. If the test fails, the "red" light will illuminate.

The tester logs all data to RAM. Individual devices have a test coupon stored on flash. The tester may be powered off at any time without regard to data stability.

Tester Architecture

The tester program is started using the SysV-style init script called factory-test.sh. This script simply starts up the factory tester in the background. It does not take care of logging, nor does it handle instances where the program crashes. These situations should be handled by restarting the tester.

The tester will, by default, reprogram the board first, and then run all tests in order.

the default invokation is:

./build/factory-test \
     --swclk 20 --swdio 21 \
     --elf /home/pi/orchard-src/orchard/build/orchard.elf \
     --serial /dev/ttyAMA0 \
     --red 6 --yellow 13 --green 19 \
     --button 26 \
     -vvvv > /tmp/orchard.log 2>&1

Additionally, factory-test does not make assumptions about the system on which it is running, aside from assuming openocd is present in the path and has sysfsgpio enabled. You must specify the GPIOs to use for SWCLK and SWDIO, as well as specifying a serial port to use for running the tests. Optionally, you may specify a GPIO to use as a button, which will disable oneshot mode and enable a mode where a new board may be loaded into the tester without needing to re-run the command. This is how a tester in the factory should behave.

Optionally, you may specify GPIOs to use as red, yellow, and green LEDs to indicate current programming status. This is a recommended configuration, especially as the initial programming step can take a long time, and without any feedback it is unclear whether the device has started programming.

The tester program is contained entirely within factory-test.c. It is compiled alongside the rest of Orchard, and the resulting binary is placed inside build/. The program contains a help screen that can be invoked by running "sudo ./build/factory-test --help".

Additionally, it is possible to skip programming "-p" and/or skip running tests "-t". This mode may be useful when combined with the run-individual-test "-r" option, which specifies a specific test to run. In this manner, specific tests can be re-run without going through an entire cycle. For example, to skip programming and testall, but run the ws2812b, oled, and accel tests, run:

./build/factory-test [...] -p -t -r ws2812b -r oled -r accel

By default, the program does not print any output. You can increase verbosity by adding "-v". More instances of "-v" equals greater text spew.

Tester Parameters

Short Long Short Description Discussion
-c --config Specify an OpenOCD configuration file This option is not commonly used.
-s --serial Path to the serial port If no serial port is specified, then no tests are run, but the board will be programmed.
-e --elf Path to the .elf file to program If no elf file is specified, then programming is skipped.
-b --button GPIO to use for a "start test" button GPIO of a pull-to-ground button. If no GPIO is specified, operates in single-shot mode.
-k --swclk GPIO to use for SWD CLK If no SWD CLK is specified, programming is skipped.
-d --swdio GPIO to use for SWD DIO If no SWD DIO is specified, programming is skipped.
-0 --green GPIO to use for green LED Optional.
-1 --yellow GPIO to use for yellow LED Optional.
-2 --red GPIO to use for red LED Optional.
-r --run-test Run a specifically-named test Runs the named test after programming, but before running all tests. May be specified multiple times.
-v --verbose Increase program verbosity Print more data to stderr. May be specified multiple times to be even more verbose.
-p --no-program Skip programming step Avoid reprogramming the board, useful for running individual tests.
-t --no-tests Skip running all tests Avoid running all tests, useful for running individual tests, or programming the board without testing.
-h --help Print help screen Print a more up-to-date version of this table.