Lumio Release Note Lumio Multi-Touch Communication Protocol Note Number RN00009 - Revision A0 Release Date Product Lumio Crystal Touch PCB Controller Abstract This note describes the Lumio Multi Touch communication protocol between the Lumio Crystal Touch PCB Controller and a 3rd party multi touch application Contents General....................................................... 2 Definitions..................................................... 2 System Interface Setup........................................... 2 Compatibility................................................... 2 Hardware Interface.............................................. 3 USB Hardware Interface........................................ 3 Serial Hardware Interface....................................... 3 Mapping the Serial Connector to the Serial Cable.................. 3 Software Interfaces.............................................. 5 USB Software Interface........................................ 5 Detecting Lumio Devices..................................... 5 USB Messages............................................ 5 Message Checksum........................................ 5 Incoming Data............................................. 5 Serial Software Interface........................................ 6 Message Structure.............................................. 7 Message Structure......................................... 8 Multiple Touch Event Associated Data.......................... 8 Touch Event Packet in a Multi Touch Event Message............... 8 6355 Topanga Blvd. #335, Woodland Hills, CA 91367, USA Information herein is proprietary information and trade secrets of Lumio Inc. Copyright 2011 Lumio Inc. All rights reserved. 1 of 9
General This document describes the Lumio Multi touch communication protocol between the Lumio Crystal Touch PCB Controller and a 3rd party multi touch application. Definitions The following definitions apply to this document: Table 1: Definitions Term Lumio Crystal Touch PCB Controller Client Conventional Firmware (Dual sensor firmware) Multi User Firmware (Quad sensor firmware) Definition The Crystal Touch PCB Controller (hereafter: Crystal Touch Controller ) is responsible for managing and reporting one or more simultaneous XY touch events The client is a 3rd party multi touch application that responds to the XY events sent by the Crystal Touch Controller Crystal Touch PCB Controller that supports 1 or 2 touches Crystal Touch PCB Controller that supports up to 4 touches System Interface Setup The direct interface between the Crystal Touch Controller and the Client is configured in either of the following manners: USB connection: The Client communicates with the Crystal Touch Controller via a USB connection Serial connection: The Client communicates with the Crystal Touch Controller via a Serial (RS-232) connection IMPORTANT : Please ensure that the PCB Controller that you have ordered, or is in your possession, is compatible to the application interface (USB / Serial). Compatibility The following table describes the compatibility between the Lumio protocol and the available Lumio Firmware versions. Table 2: Compatibility Table Firmware Conventional Firmware (Dual sensor firmware) Multi User Firmware (Quad sensor firmware) Version v 1.2.6.0 and up v 2.1.9.0 and up General 2 of 9
Hardware Interface The following hardware interfaces are available for Crystal Touch Controllers: USB interfaces Serial interfaces USB Hardware Interface All Crystal Touch Controllers are equipped with USB interfaces. The Crystal Touch Controller USB interface includes the following properties: Table 3: USB Interface Properties Property USB interface v2.0 Setting Serial Hardware Interface Not all Crystal Touch Controllers are equipped with serial interfaces. Only the Tx, Rx and Gnd pinouts are required for serial interface communication. The signal voltage level for serial interface communication is: RS232-6v to +6v. Mapping the Serial Connector to the Serial Cable The following section describes how to map the serial connection between the serial cable and the Crystal Touch Controller. Serial Connector Properties The serial connector reference number is JP4. The Pinout properties of the serial connector are displayed in the following table. Hardware Interface 3 of 9
Table 4: : Serial Connector Pinout Properties Pinout of JP4 Signal description Connectivity to female DB9 connector Connectivity to male DB9 connector Pin 1 (square) GND Pin 5 Pin 5 Pin 2 Controller receive from PC Pin 3 Pin 2 Pin 3 Controller receive from PC Pin 2 Pin 3 The following diagrams display serial male and female cable connections. Figure 1 Serial Male and Female Connections Hardware Interface 4 of 9
Software Interfaces The following software interfaces are available for Crystal Touch Controllers: USB Software Interface on page 5 Serial Software Interface on page 6 USB Software Interface This section includes: Detecting Lumio Devices on page 5 USB Messages on page 5 Message Checksum on page 5 Incoming Data on page 5 Detecting Lumio Devices Lumio firmware is identified according to its features. Currently the Lumio firmware identification is as follows. Table 5: Lumio Firmware Identification Firmware Package Conventional Firmware Multi user Firmware USB Messages 0x202E/0x0007 0x202E/0x0006 Vendor ID / USB PID All USB messages are 64 bytes long. Therefore a message sent to the Crystal Touch Controller must be configured in a 64-byte buffer, initially set to zero. Message Checksum No checksum processing is performed when interfacing via a USB connection, due to the layer of USB message validity checking at the application layer. The checksum byte appears in the protocol, but will not appear in incoming messages, as its inclusion in sent messages is not required. Incoming Data Once a connection is established, the Client receives all events, in the form of a Multiple Touch Event Message (USN:0x44), from the Crystal Touch Controller. Events are received upon detecting a change of state on the Crystal Touch Panel (that is, Touch Down, Move or Up). Software Interfaces 5 of 9
The Crystal Touch Controller does not provide handshaking, polling or error recovery. Therefore it is the responsibility of the Client to read the data, and buffer if required. NOTE: All coordinates and widths are in the 0-4095 sensor pixel range, which must be mapped to the screen resolution prior to display and/or processing. Serial Software Interface Configure the Crystal Touch Controller serial connection properties as displayed in the following table: Table 6: Serial Interface Connection Properties Property Start bit 1 Data bits 8 Stop bit 1 Hardware controls (CTS, RTS) None Baud rate 115,220 Parity None Flow Control (X-on / X-off) Off Setting Once a connection has been established, all events, in the form of a Multiple Touch Event Message (USN:0x44) will be received by the application. Events are received upon detecting a change of state on the Crystal Touch Panel (that is, Touch Down, Move or Up). The Crystal Touch Controller does not provide handshaking, polling or error recovery. Therefore it is the responsibility of the Client to read the data, and buffer if required. Message validation is provided by a checksum that appears at the end of each message. NOTE: All coordinates and widths are in the 0-4095 sensor pixel range, which must be mapped to the screen resolution prior to display and/or processing. Software Interfaces 6 of 9
Message Structure The message structure between the Client and Crystal Touch Controller in both directions (input and output), is divided into segments, as displayed in the following table. Table 7: Serial Interface Connection Properties Property Header Unique Service number (USN) Data Length Data Sector Checksum (SC) Setting The Header is a fixed byte 0 x7f The USN describes the service requested / type of command, for example a message concerning a touch event The number of Bytes in the following Data segment Contains the contents of the message. Parsing of the message depends on the service number The checksum of the whole message, including header, USN, length and data (summation of unsigned chars for the entire message). Note: The checksum is required and available only in serial interface. Table 8: Multiple Touch Event Message (USN:0x44) A multiple touch event message is a message sent by the Crystal Touch Controller to the Client. The multiple touch event message informs the Client of a touch event (Down, Move or Up) in the active area. The touch event has absolute XY coordinates as well as absolute width. Each touch event has an associated TagID for tracking. The following diagram display a multiple touch event message. Table 9: Multiple Touch Event Message (USN 0x44) Message Structure 7 of 9
Message Structure The following table displays the message structure. Table 10: Message Structure Element Type Size Value / Meaning Header Unsigned Char 1 Byte 0x7F - constant header for all messages USN Unsigned Char 1 Byte The code of the message is 0x44 for multi-touch event reports Data length Unsigned Char 1 Byte Depends on the length of data sector. The data length can be a value between 0 to 254 (0x00 to 0xFE) Multiple Touch Event Associated Data The following table displays the multiple touch event associated data. Table 11: Multiple Touch Event Associated Data Element Type Size Value / Meaning Number of Touch event packets in multi touch event message Size of Touch Event Packet in Multi Touch Event Message Unsigned char 1 Byte Specifies the number of Touch Event packets, supported number 1 to n Unsigned char 1 Byte Specifies the size of a Touch Event packet. All packets must be of same size/type. In this case this is fixed 11 Bytes Touch Event Packet in a Multi Touch Event Message The following table displays a touch event packet in a multiple touch event message. Table 12: Touch Event Packet in a Multi Touch Event Message Element Type Size Value / Meaning Touch Area / Operation Unsigned char 1 Byte This field consists of 2 nibbles defining the type of operation and area in which touch events occurred, where: Bits 0-3 Touch Operation 0 Touch Move 1 Touch Down 2 Touch Up Bits 4-7 Touch Area 0 Touch Screen Mode V-mode Unsigned char 1 Byte Value is constant 0 - ignore this value Message Structure 8 of 9
Element Type Size Value / Meaning X Co-ordinate Unsigned char 2 Byte Absolute X-coordinate of the touch event. (Left Side Bottom first). Range of values 0-4095 Y Co-ordinate Unsigned char 2 Byte Absolute Y-coordinate of the touch event. ((Left Side Bottom first). Range of values: 0-4095 X Width Unsigned char 2 Byte Specifies the horizontal width of the detected object. (Left Side Bottom first). Range of values: 0-4095 Y Width Unsigned char 2 Byte Specifies the vertical height of the detected object. (Left Side Bottom first). Range of values: 0-4095 Tag ID Unsigned char 1 Byte Specifies the event ID. The Ids are enumerated starting from 1. This is for helping the application to track movements of multiple events without confusing between them Message Structure 9 of 9