Improve README.md with feature, installation and usage sections

1 files changed, 112 insertions, 39 deletions

diff --git a/README.md b/README.md
index 9a75a18..52e4a43 100644
--- a/README.md
+++ b/README.md
@@ -1,67 +1,140 @@
 # libusbmuxd
 
-## About
+*A client library for applications to handle usbmux protocol connections with iOS devices*
 
-A client library to multiplex connections from and to iOS devices by connecting
-to a socket provided by a usbmuxd daemon.
+## Features
 
-## Requirements
+This project is a client library to multiplex connections from and to iOS
+devices alongside command-line utilities.
 
-Development Packages of:
-* libplist
+It is primarily used by applications which use the [libimobiledevice](https://github.com/libimobiledevice/)
+library to communicate with services running on iOS devices.
 
-Software:
-* usbmuxd (Windows and Mac OS X can use the one provided by iTunes)
-* make
-* autoheader
-* automake
-* autoconf
-* libtool
-* pkg-config
-* gcc or clang
+The library does not establish a direct connection with a device but requires
+connecting to a socket provided by the usbmuxd daemon.
 
-Optional:
-* inotify (Linux only)
+The usbmuxd daemon is running upon installing iTunes on Windows and Mac OS X.
 
-## Installation
+The [libimobiledevice project](https://github.com/libimobiledevice/) provides an open-source reimplementation of
+the [usbmuxd daemon](https://github.com/libimobiledevice/usbmuxd.git/) to use on Linux or as an alternative to communicate with
+iOS devices without the need to install iTunes.
 
-To compile run:
-```bash
+- **Protocol:** Provides an interface to handle the usbmux protocol
+- **Port Proxy:** Provides the `iproxy` utility to proxy ports to the device
+- **Netcat:** Provides the `inetcat` utility to expose a raw connection to the device
+- **Cross-Platform:** Tested on Linux, macOS, Windows and Android platforms
+- **Flexible:** Allows using the open-source or proprietary usbmuxd daemon
+
+Furthermore the Linux build optionally provides support using inotify if
+available.
+
+## Installation / Getting started
+
+### Debian / Ubuntu Linux
+
+First install all required dependencies and build tools:
+```shell
+sudo apt-get install \
+	build-essential \
+	checkinstall \
+	git \
+	autoconf \
+	automake \
+	libtool-bin \
+	libplist-dev
+```
+
+Then clone the actual project repository:
+```shell
+git clone https://github.com/libimobiledevice/libusbmuxd.git
+cd libusbmuxd
+```
+
+Now you can build and install it:
+```shell
 ./autogen.sh
 make
 sudo make install
 ```
 
-If dependent packages cannot be found when running autogen.sh (or configure)
-make sure that `pkg-config` is installed and set the `PKG_CONFIG_PATH` environment
-variable if required. It can be passed directly like this:
+## Usage
+
+### iproxy
 
-```bash
-PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh
+This utility allows binding local TCP ports so that a connection to one (or
+more) of the local ports will be forwarded to the specified port (or ports) on
+a usbmux device.
+
+Bind local TCP port 2222 and forward to port 22 of the first device connected
+via USB:
+```shell
+iproxy 2222:22
 ```
 
-If you require a custom prefix or other option being passed to `./configure`
-you can pass them directly to `./autogen.sh` like this:
-```bash
-./autogen.sh --prefix=/opt/local --without-cython
-make
-sudo make install
+This would allow using ssh with `localhost:2222` to connect to the sshd daemon
+on the device. Please mind that this is just an example and the sshd daemon is
+only available for jailbroken devices that actually have it installed.
+
+Please consult the usage information or manual page for a full documentation of
+available command line options:
+```shell
+iproxy --help
+man iproxy
 ```
 
-## Who/What/Where?
+### inetcat
+
+This utility is a simple netcat-like tool that allows opening a read/write
+interface to a TCP port on a usbmux device and expose it via STDIN/STDOUT.
 
-* Home: https://libimobiledevice.org/
-* Code: `git clone https://git.libimobiledevice.org/libusbmuxd.git`
-* Code (Mirror): `git clone https://github.com/libimobiledevice/libusbmuxd.git`
-* Tickets: https://github.com/libimobiledevice/libusbmuxd/issues
+Use ssh ProxyCommand to connect to a jailbroken iOS device via SSH:
+```shell
+ssh -oProxyCommand="inetcat 22" root@localhost
+```
+
+Please consult the usage information or manual page for a full documentation of
+available command line options:
+```shell
+inetcat --help
+man inetcat
+```
+
+### Environment
+
+The environment variable `USBMUXD_SOCKET_ADDRESS` allows to change the location
+of the usbmuxd socket away from the local default one.
+
+An example of using an utility from the libimobiledevice project with an usbmuxd
+socket exposed on a port of a remote host:
+```shell
+export USBMUXD_SOCKET_ADDRESS=192.168.179.1:27015
+ideviceinfo
+```
+
+This sets the usbmuxd socket address to `192.168.179.1:27015` for applications
+that use the libusbmuxd library.
+
+## Links
+
+* Homepage: https://libimobiledevice.org/
+* Repository: https://git.libimobiledevice.org/libusbmuxd.git
+* Repository (Mirror): https://github.com/libimobiledevice/libusbmuxd.git
+* Issue Tracker: https://github.com/libimobiledevice/libusbmuxd/issues
 * Mailing List: https://lists.libimobiledevice.org/mailman/listinfo/libimobiledevice-devel
 * Twitter: https://twitter.com/libimobiledev
 
+## License
+
+This library is licensed under the [GNU Lesser General Public License v2.1](https://www.gnu.org/licenses/lgpl-2.1.en.html),
+also included in the repository in the `COPYING` file.
+
+This utilities `iproxy` and `inetcat` are licensed under the [GNU General Public License v2.0](https://www.gnu.org/licenses/gpl-2.0.en.html).
+
 ## Credits
 
 Apple, iPhone, iPod, and iPod Touch are trademarks of Apple Inc.
 
-libusbmuxd is an independent software library and has not been
-authorized, sponsored, or otherwise approved by Apple Inc.
+This project is an independent software library and has not been authorized,
+sponsored, or otherwise approved by Apple Inc.
 
-README Updated on: 2020-06-08
+README Updated on: 2020-06-12