File	Date	Author	Commit
clients	2014-12-21	Andrew Green	[be8586] First pass at Bluetooth.
hosts	2014-12-21	Andrew Green	[be8586] First pass at Bluetooth.
.gitignore	2014-11-30	Andrew Green	[e99eb0] Initial commit.
readme.txt	2014-11-30	Andrew Green	[e99eb0] Initial commit.

Read Me

RLCD is an Android app that provides a simulated LCD that is controlled wirelessly by another device. This enables the non-Android device to display a simple text-based UI on Android devices. RLCD also handles touches to the simulated LCD and reports touches to the remote device enabling interactive UIs. Thus small resource-constrained devices can have dynamic interactive UIs on mobile devices.

The Remote LCD protocol is simple and open allowing simulated display implementations on other mobile OSes. The protocol consists of the following commands:

    RLCD API:<major>.<minor> - Must be first data sent to display host.
    INIT <width> <height> - Define new display size in characters.
    SETCHARS <x> <y> <string> - Sets text at specified position.
    BLANK 1 | 0 - Blanks the display, but text is preserved.
    COLORS [<BG>] [<FONTBG>] [<FONT>] - Colors must be in hexadecimal ARGB format.
    WRAP 1 | 0 - Enables/disables word wrapping at end of line.
    SHIFT U | D - Shifts display up/down one row. Row off edge is lost.
    DEINIT - Releases display. Socket will be disconnected.
    TAP <cell> - Sent to remote device when LCD touched. <cell> is index into 1D array of all cells. (Divide by display width to get y value.)


WiFi
When RLCD starts to connect it will broadcast a UDP packet on port 8765. The packet contains "RLCD API:<major>.<minor> PORT:<tcpport>". After broadcast RLCD will listen on port 6666 for TCP connections. The first thing sent to RLCD needs to be "RLCD API:0.1" in ASCII text as a greeting. In response to this and all commands RLCD sends "ACK" or "NACK <error>".

Next any command can be sent as ASCII text over TCP connection, but generally INIT is sent to set desired size and clear display. INIT can be used to clear the display of all characters at any time even if size does not change.


Touch Handling
When user touches sumulated LCD the touch is converted into the index of the cell that was touched and sent to the connected device. The connected device must then determine what if anything is at that cell index and take appropriate action. Cell index is into 1D array of cell characters. To get X, Y back divide cell index by display width to get Y and remainder is X.


Reference implementations:
RLCD - Android App providing virtual remote LCD.
rlcd_client.py - Python RLCD client demo.
rlcd_client.sh - BASH RLCD client utility.
rlcd_uidemo_spark_core.ino - Interactive UI demo for Spark Core.


To run a demo, run RLCD and the device demo then select "Connect via WiFi" from the RLCD menu.