- [Tcp2UsbBridge iOS](#tcp2usbbridge-ios)
      - [1. Command reference](#1-command-reference)
      - [2. USBMux Example](#2-usbmux-example)
    + [3. Implementation of UsbMuxD Command Reference](#3-implementation-of-usbmuxd-command-reference)
- [Merging Multiple Devices](#merging-multiple-devices)
  * [Implementation](#implementation)
    + [1. ListDevices](#1-listdevices)
    + [2. Listen](#2-listen)
    + [3. Connect](#3-connect)
    + [4. ReadPair](#4-readpair)
    + [5. SavePair](#5-savepair)
    + [6. DeletePair](#6-deletepair)
    + [7. ReadBUID](#7-readbuid)
    + [8. ListListeners](#8-listlisteners)
- [UsbMux Command Reference](#usbmux-command-reference)
      - [1. List Devices](#1-list-devices)
        * [Request](#request)
        * [Response](#response)
      - [2. Connect](#2-connect)
        * [Request](#request-1)
        * [Response](#response-1)
      - [3. ReadPairRecord](#3-readpairrecord)
        * [Request](#request-2)
      - [Response](#response-2)
      - [4. ReadBUID](#4-readbuid)
        * [Request](#request-3)
        * [Response](#response-3)
      - [5. SavePairRecord](#5-savepairrecord)
        * [Request](#request-4)
        * [Response](#response-4)
      - [6. Listen](#6-listen)
        * [Request](#request-5)
        * [Response](#response-5)
        * [Attached a new Device](#attached-a-new-device)
        * [Detached device](#detached-device)
      - [7. ListListeners](#7-listlisteners)
      - [8. DeletePairRecord](#8-deletepairrecord)


# Tcp2UsbBridge iOS
The Tcp Bridge will basically work exactly like Android.
The difference is, the tcp ports won't pipe directly to services on the phone but expose a usbmux compatible protocol for a number of reasons:
- Unlike adb-server, there is no way to connect a running instance of usbmuxd to another remote device. It only has usb support.
- Anything else you could think of, will just end up in writing a custom usbmux clone, that does exactly the same things just in another custom protocol
- Exposing a fully compatible usbmux protocol makes using the bridge at any part of the stack super easy! just run j4ios directly or use socat to make a device available locally on /var/run/usbmuxd

#### 1. Command reference
`GET /devices` returns json containing devices and their properties
```
[{..,"serial":"udid01"},
 {..,"serial":"udid02"},
 {..,"serial":"udid03"}]
```

`PUT -d {\"descriptor\":\"udid01\"} /bridges`
Will start the device bridge for iOS device with udid01 and return the TCP/IP port.

`DELETE "/bridge?descriptor=udid01"`
Will stop the device bridge for iOS device with udid01

#### 2. USBMux Example

The most important commands for understanding usbmuxd are the ListDevices and the Connect command (see [UsbMux Command Reference](#UsbMux-Command-Reference)).
The following explanation will use an example to show how exactly the TcpBride will work.

First `PUT -d {\"descriptor\":\"udid01\"} /bridges` is executed to start a bridge for iOS-Device01 (udid01). Let's assume it returns `15000` as the port. We consider two scenarios now:
1. Using iOS-Device01 with java for ios
 This is fairly easy, as java for ios supports TCP Sockets out of the box. So connecting to the device is as easy as creating a new ChannelInstance connecting to `bridgeIp:15000`
2. Using the device on a Mac or with MacOS/libimobiledevice based tools
These tools require the device to be available on a Unix Domain Socket, so we need to convert our TCP port into a UDS and create it at the common location `/var/run/usbmuxd`. We can use Socat or a custom netty tool for that.

When you run the ListDevices command with either of these tools, you will always receive the same plist:
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>DeviceList</key>
	<array>
		<dict>
			<key>DeviceID</key>
			<integer>27</integer>
			<key>MessageType</key>
			<string>Attached</string>
			<key>Properties</key>
			<dict>
				<key>ConnectionSpeed</key>
				<integer>480000000</integer>
				<key>ConnectionType</key>
				<string>USB</string>
				<key>DeviceID</key>
				<integer>0</integer>
				<key>LocationID</key>
				<integer>337641472</integer>
				<key>ProductID</key>
				<integer>4779</integer>
				<key>SerialNumber</key>
				<string>udid01</string>
			</dict>
		</dict>
	</array>
</dict>
</plist>
```
This way, every software will only be able to access one device per TCP Port. In other words, devices will be perfectly isolated, just the same as they are for android. Clients will only be able to run Connect calls specifying the DeviceID of 0 and therefore only connect to services on the device they are allowed to use.
Should it be desired to have multiple or all devices of a tcpbridge available, see [Merging multiple Devices](#Merging-Multiple-Devices)

### 3. Implementation of UsbMuxD Command Reference
(see [UsbMux Command Reference](#UsbMux-Command-Reference))
ListDevices -> Always return the same Device, the one associated with the TCP Port of the connection ListDevices was called on

Connect -> Only allow a Connection to the one allowed Device

SavePairRecord -> Ignore, maybe log a warning

DeletePairRecord -> Ignore, maybe log a warning

Listen -> ignore, no new devices will ever be attached

ReadPairRecord -> Send this devices PairRecord

# Merging Multiple Devices
We will need a Java Library/Component that can do the following:
Manage A list of DeviceEntries to associate a tuple of (TcpConnection, DeviceID, udid) with a newly generated DeviceID.
It needs to discover devices from a local unix domains socket automatically. Remote devices need to be added and removed by API calls.
When a remote service tries to execute a UsbMux Command, the merger must decide what to do like so:
## Implementation
### 1. ListDevices
Return a Plist conforming to usbmux protocol, containing all devices this merger manages
### 2. Listen
- When devices are Added, Removed via API calls, send attached/detached message
- On connect, send attached for all already connected devices
- Send a Listen command to the local unix domain socket and if something happens there update managed devices, then forward the message further
### 3. Connect
- Forward the connect call to the correct device by mapping the DeviceIDs
### 4. ReadPair
- Retrieve the correct PairRecord using the udid from remote or local device
### 5. SavePair
Forward to remote or local usbmuxd
### 6. DeletePair
Forward to remote or local usbmuxd
### 7. ReadBUID
This is only needed for pairing, so
If a local usbmuxd is connected, forward to there
else return random UUID
### 8. ListListeners
if local unix domain socket is connected, Return all Listeners from local unix domain socket
else return emptylist



# UsbMux Command Reference

UsbMux Commands are basically just an RPC mechanism for calling remote procedures on the usbmux daemon (a process running on the mac host). This is important to distinguish, not every command listed here will actually do something with the iOS device. Most of them run on the host machine only.
The Request is a Plist that usually contains a MessageType that indicates the procedure to invoke. The return type will be also a Plist.

#### 1. List Devices
List devices is the entry point for doing anything with devices connected to the host. It enumerates all of them and lets applications know which devices they can use. You will typically see this being executed whenever applications start. It is the equivalent of the device discovery if you wish. As you can see the return value is just an array of device properties, most notably the `DeviceID` which is a simple int enumerating devices on the host as well as the `SerialNumber` which uniquely identifies the device independent from the actual host it is connected to.
No interaction with the iOS Device takes place.
##### Request
```
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>ClientVersionString</key>
	<string>arbitraryString</string>
	<key>MessageType</key>
	<string>ListDevices</string>
	<key>ProgName</key>
	<string>arbitraryName</string>
</dict>
</plist>
```
##### Response
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>DeviceList</key>
	<array>
		<dict>
			<key>DeviceID</key>
			<integer>27</integer>
			<key>MessageType</key>
			<string>Attached</string>
			<key>Properties</key>
			<dict>
				<key>ConnectionSpeed</key>
				<integer>480000000</integer>
				<key>ConnectionType</key>
				<string>USB</string>
				<key>DeviceID</key>
				<integer>27</integer>
				<key>LocationID</key>
				<integer>337641472</integer>
				<key>ProductID</key>
				<integer>4779</integer>
				<key>SerialNumber</key>
				<string>6303db9964ec93381d6d80077a30c62089f16706</string>
			</dict>
		</dict>
	</array>
</dict>
</plist>
```
#### 2. Connect
Connect is the command that forwards the TCP Connection used to make the connect call transparently to a TCP Service on the phone. The DeviceID is used to determine the device instead of the udid. The port is the port where the service runs on the phone.
Beware, the port is in little endian byte order.
Beware2, after the response is sent back, that connection will immediately send and receive bytes
directly to and from the phone, without any further delay.
##### Request
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BundleID</key>
	<string>go.ios.control</string>
	<key>ClientVersionString</key>
	<string>go-usbmux-0.0.1</string>
	<key>DeviceID</key>
	<integer>27</integer>
	<key>MessageType</key>
	<string>Connect</string>
	<key>PortNumber</key>
	<integer>32498</integer>
	<key>ProgName</key>
	<string>go-usbmux</string>
	<key>kLibUSBMuxVersion</key>
	<integer>3</integer>
</dict>
</plist>
```
##### Response
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>MessageType</key>
	<string>Result</string>
	<key>Number</key>
	<integer>0</integer>
</dict>
</plist>
```
#### 3. ReadPairRecord
This is used to retrieve a pairrecord (usually in /var/db/lockdown/{udid}.plist)
for a device. The `PairRecordID` is the device' udid.
No interaction with the iOS Device takes place.
##### Request
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BundleID</key>
	<string>go.ios.control</string>
	<key>ClientVersionString</key>
	<string>go-usbmux-0.0.1</string>
	<key>MessageType</key>
	<string>ReadPairRecord</string>
	<key>PairRecordID</key>
	<string>6303db9964ec93381d6d80077a30c62089f16706</string>
	<key>ProgName</key>
	<string>go-usbmux</string>
	<key>kLibUSBMuxVersion</key>
	<integer>3</integer>
</dict>
</plist>
```
#### Response
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PairRecordData</key>
	<data>
    {Base64 encoded FileBytes of pairrecord}
	</data>
</dict>
</plist>
```
#### 4. ReadBUID
Reads the BUID which is stored in the pair record and later will be used for starting lockdown sessions. It's usually some random UUID.
This command is only used before Pairing, because the BUID is used during pairing and persisted in the pairrecord.
No interaction with the iOS Device takes place.
##### Request
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BundleID</key>
	<string>org.libimobiledevice.usbmuxd</string>
	<key>ClientVersionString</key>
	<string>usbmuxd built for freedom</string>
	<key>MessageType</key>
	<string>ReadBUID</string>
	<key>ProgName</key>
	<string>libusbmuxd</string>
	<key>kLibUSBMuxVersion</key>
	<integer>3</integer>
</dict>
</plist>
```
##### Response
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BUID</key>
	<string>50E770E0-FF35-444B-96BC-AA365041FB82</string>
</dict>
</plist>
```
#### 5. SavePairRecord
UsbMux will store the PairRecord file in `/var/db/lockdown`
No interaction with the iOS Device takes place.
##### Request
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BundleID</key>
	<string>org.libimobiledevice.usbmuxd</string>
	<key>ClientVersionString</key>
	<string>usbmuxd built for freedom</string>
	<key>MessageType</key>
	<string>SavePairRecord</string>
	<key>ProgName</key>
	<string>libusbmuxd</string>
	<key>kLibUSBMuxVersion</key>
	<integer>3</integer>
	<key>PairRecordID</key>
	<string>6303db9964ec93381d6d80077a30c62089f16706</string>
	<key>PairRecordData</key>
	<data>
   {Base 64 Encoded Pair Record}
	</data>
</dict>
</plist>
```
##### Response
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>MessageType</key>
	<string>Result</string>
	<key>Number</key>
	<integer>0</integer>
</dict>
</plist>
```
#### 6. Listen
Creates a persistent TCP Connection that will send a message (see examples) whenever a new device is connect or disconnected from USB. Also it will send a Attached message right after the first response, for every device that is already connected.
All apple tools use this and start it by default.

##### Request
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BundleID</key>
	<string>com.apple.AccessibilityInspector</string>
	<key>ClientVersionString</key>
	<string>usbmuxd-423.208.1</string>
	<key>ConnType</key>
	<integer>0</integer>
	<key>MessageType</key>
	<string>Listen</string>
	<key>ProgName</key>
	<string>Accessibility Inspector</string>
	<key>kLibUSBMuxVersion</key>
	<integer>3</integer>
</dict>
</plist>
```
##### Response
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>MessageType</key>
	<string>Result</string>
	<key>Number</key>
	<integer>0</integer>
</dict>
</plist>
```
##### Attached a new Device
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>DeviceID</key>
	<integer>27</integer>
	<key>MessageType</key>
	<string>Attached</string>
	<key>Properties</key>
	<dict>
		<key>ConnectionSpeed</key>
		<integer>480000000</integer>
		<key>ConnectionType</key>
		<string>USB</string>
		<key>DeviceID</key>
		<integer>27</integer>
		<key>LocationID</key>
		<integer>337641472</integer>
		<key>ProductID</key>
		<integer>4779</integer>
		<key>SerialNumber</key>
		<string>6303db9964ec93381d6d80077a30c62089f16706</string>
	</dict>
</dict>
</plist>
```
##### Detached device
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>DeviceID</key>
	<integer>28</integer>
	<key>MessageType</key>
	<string>Detached</string>
</dict>
</plist>
```
#### 7. ListListeners
Returns a list of all Listener connections
#### 8. DeletePairRecord