Intoduction
This page is intended for those that would like to implement a server that is compatible with HomeToucher
RFB Protocol
HomeToucher is basically a remote UI client similar in functionality to software such as Microsoft remote desktop or VNC. The underlying protocol used for transferring screen changes and touch events between HomeToucher and the server is the same protocol used by VNC. This protocol is called "Remote Frame Buffer" protocol or RFB. The full specification of this protocol can be found here.
HomeToucher supports raw encoding and hextile encoding, so these are the encoding types that the server needs to support.
HomeToucher extends the RFB protocol in order to support client-side caching. In the type of applications that HomeToucher is tuned for (for example home automation), it is common that the same screen image needs to be used multiple times (for example, the application's main screen). Instead of transferring the screen bits over and over the network, the server can "tell" the client that it is about to transfer data for a screen image update with a given size and a given 32 bits hash-code (checksum). If HomeToucher has such data in its local cache it can use it instead of the server sending it over the network. If it does not have such data, the HomeToucher asks the server to send the data (and it will store it in the cache). Note that the support for this mechanism is optional and HomeToucher will work fine with RFB servers that do not support it.
HomeToucher indicates to the server that it supports side client caching by stating that it supports encoding number 101
The client-side caching extension is supported with one new HomeToucher to server RFB message: Frame Update Extension (101), and one new server to HomeToucher message: Request frame update data (101).
The first scenario, it is assumed that HomeToucher does not have the screen update data in its cache:
HomeToucher
Server
Request Frame Buffer Update (0)
Frame Update extension message (101) with update length and hash but without the actual data
Update with this length and hash does not exist in cache
Request frame update data (101)
Frame Update extension message (101) with update length and hash with the actual data
HomeToucher stores the data in the cache
Request next Frame Buffer Update (0)
In the second scenario, HomeToucher does have the required update data in its cache;
HomeToucher
Server
Request Frame Buffer Update (0)
Frame Update extension message (101) with update length and hash but without the actual data
Update with this length and hash exist in the cache, HomeToucher uses it
Request next Frame Buffer Update (0)
Frame Update Extension Message (server to HomeToucher)
The format of this message is as follow:
Request Server Data (HomeToucher to server)
The format of this message is as follow:
HomeToucher Manager Service
Before establishing a remote UI session, HomeToucher to which server (IP address/Port) it should connect. Determining this is the role of the HomeToucher manager. HomeToucher sends a query to the HomeToucher manager and gets a reply with an address/port that should be connected to. The query contains information such as device name, screen resolution, etc. HomeToucher Manager uses this information to connect to a running server instance or to start and new server instance and configure it so its UI will be compatible with the device (i.e. resolution)
The HomeToucher manager publishes itself using mDNS (Bonjour) protocol. HomeToucher supports multiple HomeToucher managers (called "domain"). Furthermore, a HomeTouch Manager can be associated with a geographical location (longitude, latitude), allowing HomeToucher to automatically use the one that is closest (for example, in case of a multiple home automation applications, to pick the right home). If HomeToucher identifies multiple managers (domains) and it is not clear which one should be used (based on geo-location or the one that was used previously), a list will be shown to the user and he will be requested to pick which one should be used.
mDNS (Bonjour) settings
Service name: _HtVncConf._udp.
TXT record fields: (optional)
latitude
longitude
HomeToucher Query
After using mDNS to figure out the address (IP address/port) of a HomeTouch manager service, HomeToucher sends a query in order to get the address of the server for which a UI remoting session (RFB session) is to be established.
The query is sent in a UDP packet. This packet contains a list of name/value pairs. Each value pair is encoded as follows:
The list is terminated with an empty name-value pair (4 bytes of 0)
The following fields are expected:
These values are used by the HomeTouch manager service implementation to determine which IP-address/port should be returned. For example. a possible implementation can use the device name (Name field) to determine if a server instance for this device is already running and returns its IP-address/port. If an instance is not running, it can start a new instance passing to it the query fields so it will be able to configure the UI to be compatible with the mobile device running HomeToucher.
The SafeTop, SafeBottom, SafeLeft, SafeRight fields allow the UI to be configured for compatibility with devices such as iPhone X which have a notch.
HomeToucher Manager Reply
After receiving the query, the HomeTouher Manager service should reply with a UDP packet with the same format as the query with the following fields: