RIOT/tests/periph/selftest_shield/README.md

# Peripheral Test Battery using the Peripheral Selftest Shield

@warning Before you power your board, make sure the shield's VCC voltage
         selector is matching the logic level of your board. E.g. having the
         VCC selector at 5 V and testing on a 3.3 V logic board with pins that
         are not 5 V tolerant, you might damage your board permanently.

## Quick Start

0. For the MCU family you want to test, find a compatible board
    - the board needs to be mechanically and electrically compatible with
      Arduino UNO shields
    - The Arduino GPIO pin mapping and ideally mapping of SPI, I2C, ADC, and
      PWM needs to be provided
1. Unplug your board (so that it is not powered)
2. Connect the shield
3. Move the VCC selector to match the logic level of the board.
    - If unsure, go for 3.3 V
    - The nRF52840DK works fine with 3.3 V, despite the logic level being only
      3.0 V
4. Close the loops for the peripherals you want to test be moving the DIP
   switches into the `ON` position, leave the untested open by moving it in the
   `OFF` position
    - Start by enabling all but UART
    - If the UART test is actually run and fails, also enable the UART switch
    - (Background: If the UART at D0 and D1 is used for stdio, it cannot be
       looped and tested)
5. Flash and run the test
    - In this directory, run `make BOARD=<YOUR_BOARD> flash test-with-config`

## Details

This test application does a full self test of any of the following peripheral
driver, if supported by the board and Arduino I/O mapping is available:

- `periph_adc` (1)
- `periph_gpio`
- `periph_gpio_irq`
- `periph_i2c` (2)
- `periph_pwm`
- `periph_spi` (3)
- `periph_uart` (4)

Notes:
1. The ADC input is generated via a 4-bit R-2R resistor ladder and the I2C
   attached GPIO extender and/or PWM. If neither is available, no tests are
   performed. If both are available, up to three ADC channels are tested:
   Those muxed to pins A0, A1, and A2.
2. I2C is indirectly tested by operating the PCF8574 I2C GPIO extender and
   observing the result using internal GPIOs connected to the external ones.
   This test is only enabled if both `periph_i2c` and `periph_gpio` is
   available
3. Correctness of the bit order and the clock phase is not checked due to the
   limitations of the loopback mode testing approach. The clock polarity is
   validated (at idle level), the correctness of the clock frequency is roughly
   tested when `periph_timer` is implemented.
4.  UART self testing is skipped when the D0/D1 UART interface is used for
    stdio. Correctness of the symbol rate (often incorrectly referred to as
    "baudrate") is only checked for plausibility when `periph_timer` is
    available. Checking different bits per character, number of stop bits,
    parity bit etc. is possible using `periph_timer`, but not yet implemented
    here.

## Debugging Failures

### Increase Verbosity

Compile with `make DETAILED_OUTPUT=1` to increase the verbosity of the output
at the cost of increased ROM. When you start seeing link failures due to the
ROM cost, you could disable some of the succeeding tests by blacklisting the
peripheral features unaffected. However, be aware some peripherals are tested
with the help of others; e.g. disabling the ADC will prevent testing the
duty cycle of PWM outputs for correctness.

### Early Critical Failure

If the application fails before performing any tests, e.g. the output looks
similar to this:

```
START
main(): This is RIOT! (Version: 2023.10-devel-348-gf1c68-peripheral-selftest)
self-testing peripheral drivers
===============================
CRITICAL FAILURE in tests/periph/selftest_shield/main.c:<line-number>
```

This will indicate a failure to initialize the GPIO extender. Possible reasons
are:

1. Wrong I2C configuration
    - Is the I2C bus (typically in the `periph_conf.h` or in a file included by
      `periph_conf.h`) correctly configured? Is it connected to the Arduino UNO
      pins D14 / D15?
    - Is the `ARDUINO_I2C_UNO` macro correctly defined to the index of the
      I2C bus connected Arduino UNO pins D14 / D15
2. Missing pull-up resistor
    - The shield has no pull up resistors on the I2C bus
    - All RIOT I2C drivers will enable the internal MCU pull up resistors for
      the I2C buses by default. But some MCUs do not have internal pull up
      resistors (on some pins) or may not be able to enable them when used in
      I2C mode.
    - If possible, the I2C driver / I2C board configuration in `periph_conf.h`
      should be configured so that robust operation works out of the box without
      having to add external pull ups.
    - If the board depends on external pulls ups (no suitable internal pull ups
      can be used and the board has no external pull ups on D15 / D15), pull
      ups need to be added to the board. The easiest is to just plug in an
      I2C sensor/EEPROM breakout into the I2C pin socket at J2, as those
      breakout boards typically have external pull up resistors integrated.
3. Bug in the I2C driver
    - A bug in the I2C driver could cause this
    - A logic analyzer connected to the I2C Header (J3), the I2C Socket (J2),
      or the I2C Groove Connector (J1) will come in handy
4. Hardware issue
    - This is the least likely cause :wink:

### Repeated Instances of the Same Error

Many tests are performed in a loop. E.g. some tests are repeated for
`flaky_test_repetitions` (by default `100`), as some tests may pass by chance.
Some tests also iterate over different configurations (such as clock speeds)
and repeat the same tests for each configuration.

To reduce the noise, you can pass `STOP_ON_FAILURE=1` as environment
variable or as parameter to `make` on compilation to abort the test run on the
first failing test.

## Configuration

The test requires no configuration and will by default test all of the above
peripheral drivers for which Arduino I/O mappings exists. To disable a subset
of the tests (e.g. to safe RAM/ROM to trim down the test to a low end board), it
is possible to disable features (`FEATURES_BLACKLIST += periph_<foobar>`).