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 |
| 30 | commands that had problems being run. The Monkey may decide to return |
| 31 | more information about command execution. That information would come |
| 32 | on the same line after the OK or ERROR. A possible example: |
| 33 | |
| 34 | key down menu |
| 35 | OK |
| 36 | touch monkey |
| 37 | ERROR: monkey not a number |
| 38 | |
| 39 | The complete list of commands follows: |
| 40 | |
| 41 | key [down|up] keycode |
| 42 | |
| 43 | This command injects KeyEvent's into the input system. The keycode |
| 44 | parameter refers to the KEYCODE list in the KeyEvent class |
| 45 | (http://developer.android.com/reference/android/view/KeyEvent.html). |
| 46 | The format of that parameter is quite flexible. Using the menu key as |
| 47 | an example, it can be 82 (the integer value of the keycode), |
| 48 | KEYCODE_MENU (the name of the keycode), or just menu (and the Monkey |
| 49 | will add the KEYCODE part). Do note that this last part doesn't work |
| 50 | for things like KEYCODE_1 for obvious reasons. |
| 51 | |
| 52 | Note that sending a full button press requires sending both the down |
| 53 | and the up event for that key |
| 54 | |
| 55 | touch [down|up|move] x y |
| 56 | |
| 57 | This command injects a MotionEvent into the input system that |
| 58 | simulates a user touching the touchscreen (or a pointer event). x and |
| 59 | y specify coordinates on the display (0 0 being the upper left) for |
| 60 | the touch event to happen. Just like key events, touch events at a |
| 61 | single location require both a down and an up. To simulate dragging, |
| 62 | send a "touch down", then a series of "touch move" events (to simulate |
| 63 | the drag), followed by a "touch up" at the final location. |
| 64 | |
| 65 | trackball dx dy |
| 66 | |
| 67 | This command injects a MotionEvent into the input system that |
| 68 | simulates a user using the trackball. dx and dy indicates the amount |
| 69 | of change in the trackball location (as opposed to exact coordinates |
| 70 | that the touch events use) |
| 71 | |
| 72 | flip [open|close] |
| 73 | |
| 74 | This simulates the opening or closing the keyboard (like on dream). |
| 75 | |
Bill Napier | ad90429 | 2009-08-10 13:22:32 -0700 | [diff] [blame] | 76 | wake |
| 77 | |
| 78 | This command will wake the device up from sleep and allow user input. |
| 79 | |
Bill Napier | bdc2220 | 2009-08-10 20:50:30 -0700 | [diff] [blame] | 80 | tap x y |
| 81 | The tap command is a shortcut for the touch command. It will |
| 82 | automatically send both the up and the down event. |
| 83 | |
| 84 | press keycode |
| 85 | |
| 86 | The press command is a shortcut for the key command. The keycode |
| 87 | paramter works just like the key command and will automatically send |
| 88 | both the up and the down event. |
| 89 | |
Bill Napier | 3faef17 | 2009-08-11 16:07:38 -0700 | [diff] [blame] | 90 | type string |
| 91 | |
| 92 | This command will simulate a user typing the given string on the |
| 93 | keyboard by generating the proper KeyEvents. |
| 94 | |
Bill Napier | 9d8557c | 2009-08-11 16:36:43 -0700 | [diff] [blame^] | 95 | quit |
| 96 | |
| 97 | Fully quit the monkey and accept no new sessions. |
| 98 | |
| 99 | done |
| 100 | |
| 101 | Close the current session and allow a new session to connect |
| 102 | |
Bill Napier | a68dbdb | 2009-08-07 11:34:12 -0700 | [diff] [blame] | 103 | OTHER NOTES |
| 104 | |
| 105 | There are some convenience features added to allow running without |
| 106 | needing a host process. |
| 107 | |
| 108 | Lines starting with a # character are considered comments. The Monkey |
| 109 | eats them and returns no indication that it did anything (no ERROR and |
| 110 | no OK). |
| 111 | |
| 112 | You can put the Monkey to sleep by using the "sleep" command with a |
| 113 | single argument, how many ms to sleep. |