Unit test: game pad

Purpose and summary

To test that:

• the device works properly as a gamepad in a computer.
• the device can send and receive data by the means of HID feature reports.

This procedure is the same for USB and BLE connectivity, however, a different sketch may be needed:

• To test the BLE implementation based on h2zero's wrapper (NimBLE): h2zeroImplTest.ino

• To test BLE-only connectivity on boards not having USB-TO-UART port: BLEimplTest.ino

• To test USB-only connectivity on boards not having USB-TO-UART port, but having USB-OTG support: USBImplTest.ino

• In other cases: CombinedHIDImplTest.ino

  When running this sketch, this test procedure must be executed twice: using BLE connectivity and again using USB connectivity. The firmware automatically switches to USB connectivity when the USB cable is plugged in.

Hardware setup

• BLE connectivity: nothing required, except for an external antenna on some devices.
• USB connectivity: a board with USB-OTG support is required (LillyGo T-QT and ESP32S3-DevKit-C were tested).

Output through USB serial port at 115200 bauds.

Arduino IDE setup

Press the reset button while holding the Boot (or IO0) button to enter bootloader mode.

If your board has an USB-TO-UART port, use it for console output and ignore the rest of this section.

If your board does not have USB-TO-UART port:

• To test USB connectivity you will be "blind", configure Arduino IDE in this way:

  • USB mode: USB-OTG (TinyUSB).
  • USB CDC On Boot: disabled.

• To test BLE connectivity, configure Arduino IDE in this way:

  • USB mode: USB-OTG (TinyUSB).
  • USB CDC On Boot: enabled.

Software setup

Computer:

• Windows 10 or later
• Bluetooth 4.2 or later (not required in the USB implementation)
• Joystick testing software able to display 128 buttons. Note that Window's device property page is not suitable for this.
• SimpleHIDWrite.exe: available at http://janaxelson.com/hidpage.htm. There is a modern clone at https://github.com/Robmaister/SimplerHidWrite.

Smartphone (BLE implementation only):

• nRF Connect application (Android/iOS).

Specific notes for testing BLE connectivity

• If the device is paired because of a previous test, unpair it first (delete from the Bluetooth control panel).
• Before pairing, wait for the *** DISCOVERING *** notification at the serial monitor.
• It will be shown as "h2zeroImplTest", "BLEimplTest", USBimplTest" or "CombinedHIDImplTest" (depending on the test sketch).

Procedure and expected output

• There is no serial output in some ESP32S3 devkit boards when using the USB implementation. Ignore that part unless you have dual USB ports in your DevKit. In such a case, attach two USB cables: one for serial output and another for the HID implementation.
• The expected factory VID in USB devices is 0x303A (Espressif).
• Ignore this output message while running this test: (Waiting for connection).

Automatic shutdown

Not applicable to the USB implementation, but applicable to the combined USB+BLE implementation.

1. Reset

2. Output must show:

   --GO--
   (Waiting for connection)
   

3. Wait for a minute or so.

4. Output must show:

   *** POWER OFF ***
   (Reset required)
   

Analog Axes (left clutch, right clutch and combined clutch)

1. Reset.

2. Output must match:

   --GO--
   (Waiting for connection)
   

3. Before a minute elapses, pair and connect with the device using the Bluetooth controls in your computer.

4. Output must match:

   *** CONNECTED ***
   

5. Open the joystick test application and keep it visible.

6. Rx, Ry and Rz axes should increase each second. At almost max value, must return to zero.

Battery level

Not applicable to the USB implementation, but applicable to the combined USB+BLE implementation when the USB cable is not plugged in.

1. Go to the Bluetooth page of the control panel. Look for the device.
2. Check battery level. Must show a decreasing number from 100% down to 50%, then up to 100% again.

Buttons

1. Buttons should be pressed and released every second. If buttons are numbered starting with #1, pressed buttons must follow this timed pattern :
   • Buttons #1 and #65 are pressed at the same time.
   • Previous buttons are released and buttons #2 and #66 are pressed at the same time.
   • Previous buttons are released and buttons #3 and #67 are pressed at the same time.
   • The pattern continues until buttons #64 and #128 are pressed.
   • Then, the pattern starts again.
2. Restart this test if something is missed.
3. Point-of-view control (aka "Hat switch" or "POV") must follow this pattern in a loop:
   • Not pressed
   • Up
   • Up-right
   • Right
   • Down-right
   • Down
   • Down-left
   • Left
   • Up-left

HID reports

Open "SimpleHidWriter.exe". Locate this test device in the top area, and click on it:

• BLE implementation: look for Device VID= ... PID= .... The proper values were printed at boot (Actual VID / PID).
• USB implementation: look for the device name.

You should see continuous report lines starting with RD 01. Ignore them. Click on Clear from time to time.

Just check there are no error messages in SimpleHidWriter. The behavior of these HID reports is not part of this tests. That is the subject of another automated test.

1. Enter 02 at field ReportID.
2. Click on Set Feature, then on Get Feature.
3. Enter 03 at field ReportID.
4. Click on Set Feature , then on Get Feature.
5. Enter 04 at field ReportID.
6. Click on Set Feature , then on Get Feature.
7. Enter 05 at field ReportID.
8. Click on Set Feature , then on Get Feature.
9. Note: do not confuse Set Report with Set Feature.
10. Enter 14 at field ReportID.
11. Click on Set Report.
12. Enter 15 at field ReportID.
13. Click on Set Report.
14. Enter 16 at field ReportID.
15. Click on Set Report.
16. Enter 17 at field ReportID.
17. Click on Set Report.
18. Enter 18 at field ReportID.
19. Click on Set Report.
20. Enter 1E at field ReportID.
21. Click on Set Report.

Reconnect

Regression test for Issue #3. Not applicable to the USB implementation, but applicable to the combined USB+BLE implementation when the USB cable is not plugged in.

1. Reset. Wait a few seconds.
2. Ensure the device is connected again to the host computer. Look for the message *** CONNECTED *** at the serial monitor.
3. Reopen the joystick test application (close and run again).
4. Ensure the buttons test is running again (as described before).

Battery status (BLE only)

Not applicable to the USB implementation, but applicable to the combined USB+BLE implementation when the USB cable is not plugged in. To perform this test, you will type one-character commands into the serial monitor:

• "L": enable/disable the state of charge (yes/unknown).
• "W": cycle the wire presence (yes/no/unknown).
• "C": cycle the charging status (charging/discharging/unknown).
• "B": cycle the battery presence (yes/no/unknown).

The simulated battery status will be printed to the serial monitor on each command. Type "?" to reprint the last status.

1. Remove the device from the Bluetooth control panel, so the device is unpaired and disconnected.
2. Open nRF Connect (make sure both geolocation and Bluetooth radio are enabled).
3. Reset the device.
4. Discover the device and connect (but do not pair).
5. Expand the Battery Service and the Battery Level Status characteristic. Subscribe to that characteristic.
6. For each command (described above) cycle through all possible values. Check that nRF Connect reflects the battery status printed.