Add documentation.

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+We are happy to accept any contributions that make sense and respect the rules listed below.
+
+## How to contribute
+
+1. Fork the repo.
+2. Create a feature branch for your contribution out of the `master` branch. Only one contribution per branch is accepted.
+3. Implement your contribution while respecting our rules (see below).
+4. Make sure that your contribution builds and all necessary files have been committed.
+5. Submit a pull request against our `master` branch!
+
+## Rules
+
+* **Do** use feature branches.
+* **Do** conform to existing coding style so that your contribution fits in.
+* **Do** use [EditorConfig](http://editorconfig.org/) to enforce our [whitespace rules](.editorconfig). If your editor is not supported, enforce the settings manually.
+* **Do not** commit any generated files, unless already in the repo. If absolutely necessary, explain why.
+* **Do not** create any top level files or directories. If absolutely necessary, explain why and update [.gitignore](.gitignore) if appropriate.
+
+## License
+
+By contributing your code, you agree to license your contribution under our [LICENSE](LICENSE).

LICENSE

@@ -0,0 +1,13 @@
+Copyright © CyberAgent, Inc. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,288 @@
+# minitouch
+
+Minitouch provides a socket interface for triggering multitouch events and gestures on Android devices. On SDK 19 and lower, it can run without root if started via [ADB](http://developer.android.com/tools/help/adb.html). The lowest SDK level we test is 10 (i.e. Android 2.3.3).
+
+## Building
+
+Building requires [NDK](https://developer.android.com/tools/sdk/ndk/index.html), and is known to work with at least with NDK Revision 10 (July 2014).
+
+We include [libevdev](http://www.freedesktop.org/wiki/Software/libevdev/) as a Git submodule, so first make sure you've fetched it.
+
+```
+git submodule init
+git submodule update
+```
+
+Then it's simply a matter of invoking `ndk-build`.
+
+```
+ndk-build
+```
+You should now have the binaries available in `./libs`.
+
+## Running
+
+You'll need to [build](#building) first. Then, figure out which ABI your device supports:
+
+```bash
+ABI=$(adb shell getprop ro.product.cpu.abi | tr -d '\r')
+```
+
+_Note that as Android shell always ends lines with CRLF, you'll have to remove the CR like above or the rest of the commands will not work properly._
+
+_Also note that if you've got multiple devices connected, setting `$ANDROID_SERIAL` will make things quite a bit easier as you won't have to specify the `-s <serial>` option every time._
+
+Now, push the appropriate binary to the device:
+
+```bash
+adb push libs/$ABI/minitouch /data/local/tmp/
+```
+
+At this point it might be useful to check the usage:
+
+```bash
+adb shell /data/local/tmp/minitouch -h
+```
+
+Currently, this should output be something along the lines of:
+
+```
+Usage: /data/local/tmp/minitouch [-h] [-d <device>] [-s <socket>]
+  -d <device>: Use the given touch device. Otherwise autodetect.
+  -s <socket>: Start a unix domain socket at the given path. (/data/local/tmp/minitouch.sock)
+  -h:          Show help.
+````
+
+So, we can simply run the binary without any options, and it will try to detect an appropriate device and start listening on a unix domain socket.
+
+```bash
+adb shell /data/local/tmp/minitouch
+```
+
+Unless there was an error message and the binary exited, we should now have a socket open on the device. Now we simply need to create a local forward so that we can connect to the socket.
+
+```bash
+adb forward tcp:1111 localfilesystem:/data/local/tmp/minitouch.soc
+```
+
+Now you can connect to the socket using the local port.
+
+```bash
+nc localhost 1111
+```
+
+This will give you some strange output that will be explained in the next section.
+
+## Usage
+
+It is assumed that you now have an open connection to the minitouch socket. If not, follow the [instructions](#running) above.
+
+The minitouch protocol is based on LF-separated lines. Each line is a separate command, and each line begins with a single ASCII letter which specifies the command type. Space-separated command-specific arguments then follow.
+
+When you first open a connection to the socket, you'll get some protocol metadata which you'll need need to read from the socket. Other than that there will be no responses of any kind.
+
+### Readable from the socket
+
+#### `v <version>`
+
+Example output: `v 1`
+
+The protocol version. Argument layout may change between versions, so you might want to check if your code supports this version or not.
+
+#### `^ <max-contacts> <max-x> <max-y> <max-pressure>`
+
+Example output: `^ 2 320 480 255`
+
+This gives you the upper bounds of arguments, as reported by the touch device. If you use larger values you will most likely confuse the driver (possibly freezing the screen, requiring a reboot) or the value will simply be ignored.
+
+It's also very important to note that the maximum X and Y coordinates may, but usually do not, match the display size. You'll need to work out a good way to map display coordinates to touch coordinates if required, possibly by using percentages for screen coordinates.
+
+### Writable to the socket
+
+#### `c`
+
+Example input: `c`
+
+Commits the current set of changed touches, causing the to play out on the screen. Nothing visible will happen until the commit, but depending on the device type, they may already have been buffered.
+
+Commits are not required to list all active contacts. Changes from the previous state are enough.
+
+Same goes for multi-contact touches. The contacts may move around in separate commits or even the same commit. If one contact moves, the others are not required to.
+
+The order of touches in a single commit is not important either. For example you can list contact 5 before contact 0.
+
+Note however that you cannot have more than one `d`, `m` or `u` *for the same `<contact>`* in one commit.
+
+#### `r`
+
+Example input: `r`
+
+Attemps to reset the current set of touches by creating appropriate `u` events and then committing them. As an invalid sequence of events may cause the screen to freeze, you should call for a reset if you have any doubts about the integrity of your events. For example, two `touchstart` events for the same contact is very suspect and most likely means that you lost a `touchend` event somehow.
+
+We try to discard obviously out-of-order events automatically, but sometimes it's not enough.
+
+If the screen freezes you'll have to reboot the device. With careful use this will not happen.
+
+#### `d <contact> <x> <y> <pressure>`
+
+Example input: `d 0 10 10 50`
+
+Schedules a touch down on contact `<contact>` at `<x>,<y>` with `<pressure>` pressure for the next commit.
+
+You cannot have more than one `d`, `m` or `u` *for the same `<contact>`* in one commit.
+
+#### `m <contact> <x> <y> <pressure>`
+
+Example input: `m 0 10 10 50`
+
+Schedules a touch move on contact `<contact>` at `<x>,<y>` with `<pressure>` pressure for the next commit.
+
+You cannot have more than one `d`, `m` or `u` *for the same `<contact>`* in one commit.
+
+#### `u <contact>`
+
+Example input: `u 0`
+
+Schedules a touch up on contact `<contact>`. If you need the contact to move first, use a combination of `m` and `u` separated by a commit.
+
+You cannot have more than one `d`, `m` or `u` *for the same `<contact>`* in one commit.
+
+### Examples
+
+Tap on (10, 10) with 50 pressure using a single contact.
+
+```
+d 0 10 10 50
+c
+u 0
+c
+```
+
+Long tap on (10, 10) with 50 pressure using a single contact.
+
+```
+d 0 10 10 50
+c
+<wait in your own code>
+u 0
+c
+```
+
+Tap on (10, 10) and (20, 20) simultaneously with 50 pressure using two contacts.
+
+```
+d 0 10 10 50
+d 1 20 20 50
+c
+u 0
+u 1
+c
+```
+
+Tap on (10, 10), keep it pressed, then after a while also tap on (20, 20), keep it pressed, then release the first contact and finally release the second contact.
+
+```
+d 0 10 10 50
+c
+<wait in your own code>
+d 1 20 20 50
+c
+<wait in your own code>
+u 0
+c
+<wait in your own code>
+u 1
+c
+```
+
+Swipe from (0, 0) to (100, 0) using a single contact. You'll need to wait between commits in your own code to slow it down.
+
+```
+d 0 0 0 50
+c
+m 0 20 0 50
+c
+m 0 40 0 50
+c
+m 0 60 0 50
+c
+m 0 80 0 50
+c
+m 0 100 0 50
+c
+u 0
+c
+```
+
+Pinch with two contacts going from (0, 100) to (50, 50) and (100, 0) to (50, 50). You'll need to wait between commits in your own code to slow it down.
+
+```
+d 0 0 100 50
+d 1 100 0 50
+c
+m 0 10 90 50
+m 1 90 10 50
+c
+m 0 20 80 50
+m 1 80 20 50
+c
+m 0 20 80 50
+m 1 80 20 50
+c
+m 0 30 70 50
+m 1 70 30 50
+c
+m 0 40 60 50
+m 1 60 40 50
+c
+m 0 50 50 50
+m 1 50 50 50
+c
+u 0
+u 1
+c
+```
+
+The same pinch but with more chaotic (or natural) ordering.
+
+```
+d 1 100 0 50
+c
+d 0 0 100 50
+c
+m 1 90 10 50
+m 0 10 90 50
+c
+m 0 20 80 50
+c
+m 1 80 20 50
+c
+m 0 20 80 50
+m 1 80 20 50
+c
+m 0 30 70 50
+c
+m 1 70 30 50
+c
+m 1 60 40 50
+c
+m 0 40 60 50
+c
+m 0 50 50 50
+m 1 50 50 50
+c
+u 0
+c
+u 1
+c
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+See [LICENSE](LICENSE).
+
+Copyright © CyberAgent, Inc. All Rights Reserved.