Bill Napier | 0b1f5a9 | 2009-08-10 09:56:08 -0700 | [diff] [blame] | 1 | SIMPLE PROTOCOL FOR AUTOMATED NETWORK CONTROL |
Bill Napier | a68dbdb | 2009-08-07 11:34:12 -0700 | [diff] [blame] | 2 | |
Bill Napier | 0b1f5a9 | 2009-08-10 09:56:08 -0700 | [diff] [blame] | 3 | The Simple Protocol for Automated Network Control was designed to be a |
| 4 | low-level way to programmability inject KeyEvents and MotionEvents |
| 5 | into the input system. The idea is that a process will run on a host |
| 6 | computer that will support higher-level operations (like conditionals, |
| 7 | etc.) and will talk (via TCP over ADB) to the device in Simple |
| 8 | Protocol for Automated Network Control. For security reasons, the |
| 9 | Monkey only binds to localhost, so you will need to use adb to setup |
| 10 | port forwarding to actually talk to the device. |
Bill Napier | a68dbdb | 2009-08-07 11:34:12 -0700 | [diff] [blame] | 11 | |
| 12 | INITIAL SETUP |
| 13 | |
| 14 | Setup port forwarding from a local port on your machine to a port on |
| 15 | the device: |
| 16 | |
| 17 | $ adb forward tcp:1080 tcp:1080 |
| 18 | |
| 19 | Start the monkey server |
| 20 | |
| 21 | $ adb shell monkey --port 1080 |
| 22 | |
| 23 | Now you're ready to run commands |
| 24 | |
| 25 | COMMAND LIST |
| 26 | |
| 27 | Individual commands are separated by newlines. The Monkey will |
| 28 | respond to every command with a line starting with OK for commands |
| 29 | that executed without a problem, or a line starting with ERROR for |
Bill Napier | f948160 | 2009-08-17 11:20:15 -0700 | [diff] [blame] | 30 | commands that had problems being run. For commands that return a |
| 31 | value, that value is returned on the same line as the OK or ERROR |
| 32 | response. The value is everything after (but not include) the colon |
| 33 | on that line. For ERROR values, this could be a message indicating |
| 34 | what happened. A possible example: |
Bill Napier | a68dbdb | 2009-08-07 11:34:12 -0700 | [diff] [blame] | 35 | |
| 36 | key down menu |
| 37 | OK |
| 38 | touch monkey |
| 39 | ERROR: monkey not a number |
Bill Napier | f948160 | 2009-08-17 11:20:15 -0700 | [diff] [blame] | 40 | getvar sdk |
| 41 | OK: donut |
| 42 | getvar foo |
| 43 | ERROR: no such var |
Bill Napier | a68dbdb | 2009-08-07 11:34:12 -0700 | [diff] [blame] | 44 | |
| 45 | The complete list of commands follows: |
| 46 | |
| 47 | key [down|up] keycode |
| 48 | |
| 49 | This command injects KeyEvent's into the input system. The keycode |
| 50 | parameter refers to the KEYCODE list in the KeyEvent class |
| 51 | (http://developer.android.com/reference/android/view/KeyEvent.html). |
| 52 | The format of that parameter is quite flexible. Using the menu key as |
| 53 | an example, it can be 82 (the integer value of the keycode), |
| 54 | KEYCODE_MENU (the name of the keycode), or just menu (and the Monkey |
| 55 | will add the KEYCODE part). Do note that this last part doesn't work |
| 56 | for things like KEYCODE_1 for obvious reasons. |
| 57 | |
| 58 | Note that sending a full button press requires sending both the down |
| 59 | and the up event for that key |
| 60 | |
| 61 | touch [down|up|move] x y |
| 62 | |
| 63 | This command injects a MotionEvent into the input system that |
| 64 | simulates a user touching the touchscreen (or a pointer event). x and |
| 65 | y specify coordinates on the display (0 0 being the upper left) for |
| 66 | the touch event to happen. Just like key events, touch events at a |
| 67 | single location require both a down and an up. To simulate dragging, |
| 68 | send a "touch down", then a series of "touch move" events (to simulate |
| 69 | the drag), followed by a "touch up" at the final location. |
| 70 | |
| 71 | trackball dx dy |
| 72 | |
| 73 | This command injects a MotionEvent into the input system that |
| 74 | simulates a user using the trackball. dx and dy indicates the amount |
| 75 | of change in the trackball location (as opposed to exact coordinates |
| 76 | that the touch events use) |
| 77 | |
| 78 | flip [open|close] |
| 79 | |
| 80 | This simulates the opening or closing the keyboard (like on dream). |
| 81 | |
Bill Napier | ad90429 | 2009-08-10 13:22:32 -0700 | [diff] [blame] | 82 | wake |
| 83 | |
| 84 | This command will wake the device up from sleep and allow user input. |
| 85 | |
Bill Napier | bdc2220 | 2009-08-10 20:50:30 -0700 | [diff] [blame] | 86 | tap x y |
| 87 | The tap command is a shortcut for the touch command. It will |
| 88 | automatically send both the up and the down event. |
| 89 | |
| 90 | press keycode |
| 91 | |
| 92 | The press command is a shortcut for the key command. The keycode |
| 93 | paramter works just like the key command and will automatically send |
| 94 | both the up and the down event. |
| 95 | |
Bill Napier | 3faef17 | 2009-08-11 16:07:38 -0700 | [diff] [blame] | 96 | type string |
| 97 | |
| 98 | This command will simulate a user typing the given string on the |
| 99 | keyboard by generating the proper KeyEvents. |
| 100 | |
Bill Napier | f948160 | 2009-08-17 11:20:15 -0700 | [diff] [blame] | 101 | listvar |
| 102 | |
| 103 | This command lists all the vars that the monkey knows about. They are |
| 104 | returned as a whitespace separated list. |
| 105 | |
| 106 | getvar varname |
| 107 | |
| 108 | This command returns the value of the given var. listvar can be used |
| 109 | to find out what vars are supported. |
| 110 | |
Bill Napier | 9d8557c | 2009-08-11 16:36:43 -0700 | [diff] [blame] | 111 | quit |
| 112 | |
| 113 | Fully quit the monkey and accept no new sessions. |
| 114 | |
| 115 | done |
| 116 | |
| 117 | Close the current session and allow a new session to connect |
| 118 | |
Bill Napier | a68dbdb | 2009-08-07 11:34:12 -0700 | [diff] [blame] | 119 | OTHER NOTES |
| 120 | |
| 121 | There are some convenience features added to allow running without |
| 122 | needing a host process. |
| 123 | |
| 124 | Lines starting with a # character are considered comments. The Monkey |
| 125 | eats them and returns no indication that it did anything (no ERROR and |
| 126 | no OK). |
| 127 | |
| 128 | You can put the Monkey to sleep by using the "sleep" command with a |
| 129 | single argument, how many ms to sleep. |