# Ahoy

Let nearby devices hook into your app.

**README coming soon!** Apologies for the delay.


## What the... ?

...

<!--
# Hook

Hook is a client-server solution whereby apps can easily connect to other apps on the same network.

Imagine an app running on a laptop connected to a wireless network. Now imagine being able to use an app on the mobile device to easily interact with the app running on the laptop.

## How it works

The apps are arranged in a client server relationship, where the app on the laptop is the "server" and the app on the mobile device (and any other devices) is a "client".

The server app uses Hook to translate its IP address into a passcode composed of 4 to 6 letters.

This passcode can be shared to the user(s) of the client app, who can enter it into their app, where it is converted back into an IP address. The client makes a JSON-P AJAX request to `hook.json` at the IP address on port 1941, e.g. `http://192.168.1.123:1941/hook.json`.

If successful, the client then navigates to the endpoint specified in the server's `hook.json` and is connected to the server app.

Hook works with IPv4 addresses in the following formats:

- `10.XXX.XXX.XXX`
- `172.XX.XXX.XXX`
- `192.168.XXX.XXX`

Each block of an IPv4 address (separated by the `.` characters) has a value of 0 to 255 which gives us a range of 256 alternatives which is `16 * 16`, giving us two values each between 0 and 15.

The only exepction to this rule is with `127.XX.XXX.XXX` addresses, where the second block (`XX`) has a small enough range (from 16 to 31) that the value can be handled decimally, giving us a value of between 0 and 15.

These rules mean that passcodes are different sizes for each address range:

- `10.XXX.XXX.XXX` addresses are 6 letters long
- `172.XX.XXX.XXX` addresses are 5 letters long
- `192.168.XXX.XXX` addresses are 4 letters long

Finally, we need an encoding array of 16 alphabetical characters in which we can find letters by their index. Our current encoder consists of the 16 leftmost keys on a QWERTY keyboard:

`var encoder = ["Q", "A", "Z", "W", "S", "X", "E", "D", "C", "R", "F", "V", "T", "G", "B", "Y"]`

Now we can look up the alphabetical character stored at `encoder[index]` of each value generated from converting the IP address blocks...

### Server

Let's run through a simple example of how the server converts `192.168.1.123` into a usable passcode.

As the address starts with `192.168`, we know that we need to convert the last two blocks, creating a four-letter long passcode.

The first block value is `1`. If we convert that into a hexadecimal string by running `parseInt(1, 10).toString(16)`, we get a result of `"1"`. We need two characters in our string, so we prepend it with `"0"`, giving us `"01"`.

The second block value is `123`. If we convert that into a hexadecimal string by running `parseInt(123, 10).toString(16)`, we get a result of `"7b"`.

Join the two strings together and convert each letter in the resulting string back into a decimal number and we have four indexes (`0`, `1`, `7` and `11`) for looking up letters in our encoder array. This means that an IP address of `192.168.1.123` gives us a passcode of `QADV`.

This passcode can be displayed to the user of the server, who can share it with user(s) of the client(s).

## Modules and components

Hook's functionality is split into client and server implementations and distributed as Common JS modules via [NPM](https://npmjs.org/packages/hookahoy).
-->