Andrew Lehmer | 2d3f8a1 | 2017-05-09 10:33:40 -0700 | [diff] [blame] | 1 | Overview |
| 2 | ======== |
| 3 | |
| 4 | This project is included in the internal Android source tree to support |
| 5 | automated latency testing with Salad Fingers, a robot designed and built by |
| 6 | Steve Pfetsch (spfetsch@). The three main components we use and modify are: |
| 7 | |
| 8 | - the android app (android/) |
| 9 | - the WALT device firmware (arduino/) |
| 10 | - the TCP-to-serial bridge (pywalt/) |
| 11 | |
| 12 | Salad Fingers uses a single Teensyduino running WALT firmware to test multiple |
| 13 | devices without human intervention. The devices under test are connected to the |
| 14 | same host as the Teensy. An end-to-end connection for a single device (only one |
| 15 | device can use the WALT at a time) looks like this: |
| 16 | |
| 17 | Device ------ Host ------ Teensy |
| 18 | (android/) (pywalt/) (arduino/) |
| 19 | |
| 20 | For the device to communicate with the host over TCP on a physical USB |
| 21 | connection, a "reverse" port has to be set up with adb. For example: |
| 22 | |
| 23 | $ adb reverse tcp:50007 tcp:45454 |
| 24 | |
| 25 | Any traffic the device sends to 127.0.0.1:50007 will come into the host on port |
| 26 | 45454 and vice versa. Port 50007 is defined in the app source, but the device |
| 27 | port can be selected arbitrarily. |
| 28 | |
| 29 | The TCP-to-serial bridge runs on the host and connects the app's TCP pipe to |
| 30 | the Teensy's serial pipe. However, there are two special commands the app can |
| 31 | send to the bridge to synchronize the clocks between the device and the Teensy: |
| 32 | "bridge sync" and "bridge update". |
| 33 | |
| 34 | This setup requires some modifications from the original source, which are |
| 35 | explained in the next section, but behaves very similarly to a direct, Teensy- |
| 36 | to-device USB connection. |
| 37 | |
| 38 | |
| 39 | Modifications |
| 40 | ============= |
| 41 | |
| 42 | - Clock synchronization |
| 43 | Despite the reliability and accuracy of NTP, device and host wall clocks can |
| 44 | become significantly out of sync, especially if a device loses Wi-Fi |
| 45 | connectivity. To avoid this problem and take advantage of the low-latency |
| 46 | connection between the host and device, the clocks are synchronized based on |
| 47 | the time difference between when the bridge zeroed the Teensy's clock and |
| 48 | when the reply to the "bridge sync" command was sent to the device. This |
| 49 | required parallel changes in pywalt/ and android/. |
| 50 | |
| 51 | - Automation intents |
| 52 | The test scripts which control the robot (Salad Fingers) on which the Teensy |
| 53 | is mounted require the ability to control certain aspects of the app running |
| 54 | on a device. These are defined in a separate RobotAutomationEvent interface. |
| 55 | This required changes to android/. |
| 56 | |
| 57 | - Reverse port support |
| 58 | The WaltTcpConnection class was originally intended to communicate over a |
| 59 | true network from a Chromebook to a dedicated bridge with a specific IP |
| 60 | address. This address was changed to localhost in android/. |
| 61 | |
| 62 | - Strict networking and request ordering |
| 63 | To prevent crashes due to network accesses performed on the main thread, |
| 64 | which is disallowed in strict mode, all such accesses were moved to a |
| 65 | dedicated network thread. As a side benefit, all requests sent to the bridge |
| 66 | now wait for a response before the next request is sent. This complies with |
| 67 | the serial nature of the device and guarantees correct ordering. This |
| 68 | required changes to android/. |
| 69 | |
| 70 | - Hardware-specific firmware |
| 71 | The Teensy on Salad Fingers uses sensors that are not bundled with the |
| 72 | standard WALT hardware, so new thresholds for accelerometer shocks and photo- |
| 73 | diode readings were required to achieve accurate results. This required |
| 74 | changes to arduino/. |
| 75 | |
| 76 | |
| 77 | Usage |
| 78 | ===== |
| 79 | |
| 80 | This project is not intended to be automatically built. Instead, as needed, the |
| 81 | app will be built manually and checked in as a prebuilt that PTS will pick up. |
| 82 | The firmware cannot be built or loaded automatically, as it requires a modded |
| 83 | version of the Arduino project for Teensy. The required software can be loaded |
| 84 | on a laptop to flash the Teensy mounted on Salad Fingers. |
| 85 | |
| 86 | |
| 87 | See Also |
| 88 | ======== |
| 89 | |
| 90 | Project metadata: vendor/google_meta/platform/external/walt/ |
| 91 | PTS integration: vendor/google_testing/pts/tests/salad_fingers/ |