README.google
1Overview
2========
3
4This project is included in the internal Android source tree to support
5automated latency testing with Salad Fingers, a robot designed and built by
6Steve 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
12Salad Fingers uses a single Teensyduino running WALT firmware to test multiple
13devices without human intervention. The devices under test are connected to the
14same host as the Teensy. An end-to-end connection for a single device (only one
15device can use the WALT at a time) looks like this:
16
17 Device ------ Host ------ Teensy
18 (android/) (pywalt/) (arduino/)
19
20For the device to communicate with the host over TCP on a physical USB
21connection, a "reverse" port has to be set up with adb. For example:
22
23 $ adb reverse tcp:50007 tcp:45454
24
25Any traffic the device sends to 127.0.0.1:50007 will come into the host on port
2645454 and vice versa. Port 50007 is defined in the app source, but the device
27port can be selected arbitrarily.
28
29The TCP-to-serial bridge runs on the host and connects the app's TCP pipe to
30the Teensy's serial pipe. However, there are two special commands the app can
31send to the bridge to synchronize the clocks between the device and the Teensy:
32"bridge sync" and "bridge update".
33
34This setup requires some modifications from the original source, which are
35explained in the next section, but behaves very similarly to a direct, Teensy-
36to-device USB connection.
37
38
39Modifications
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
77Usage
78=====
79
80This project is not intended to be automatically built. Instead, as needed, the
81app will be built manually and checked in as a prebuilt that PTS will pick up.
82The firmware cannot be built or loaded automatically, as it requires a modded
83version of the Arduino project for Teensy. The required software can be loaded
84on a laptop to flash the Teensy mounted on Salad Fingers.
85
86
87See Also
88========
89
90Project metadata: vendor/google_meta/platform/external/walt/
91PTS integration: vendor/google_testing/pts/tests/salad_fingers/
92
