GTT Protocol For all variants of the GTT35A, GTT38A, GTT43A, GTT50A & GTT70A Protocol Manual Revision 2.2 Firmware Revision: 2.
Revision History Revision 2.2 2.1 2.
Contents 1 Introduction ............................................................................................................................................... 1 1.1 Communication ................................................................................................................................... 1 Settings.................................................................................................................................................. 1 Transmission ....................
2.8 NineSlices .......................................................................................................................................... 27 2.9 Animations ........................................................................................................................................ 28 2.10 Graphs ............................................................................................................................................. 30 2.11 Keypad................................
1 Introduction 1.1 Communication Settings The multiple communication protocols available and simple command structure of the GTT mean that a variety of applications can be used to communicate with the display. Basic default settings for serial protocols, including USB, TTL, RS232, and RS422, as well as I2C are shown below. 2 Table 1: Serial Communication Settings Speed 115.
1.2 Basic Features Drawing The most basic commands available for the GTT line are the drawing features. Simple shapes, from pixels to triangles, can easily be drawn on the unit using a number of available commands. It should be noted that the coordinate system of the GTT references the top left pixel as 0,0 and increments positively to the right and down, as shown below.
Fonts TrueType Font (.ttf) files can be uploaded to the SD memory card, loaded into a font buffer, and used to display customizable text. Commands are provided to modify the size, colour, and rendering of the loaded text. True Type Font files can be copied from your Windows Fonts folder or downloaded online. Bitmaps Bitmaps typically display static graphic information, but can also be used to create dynamic touch regions or animations.
Animations While the image data for animations is stored in the Animation buffer, the actual state of animations is stored in a separate location. This allows animations to be removed from the screen, but remain in buffer memory. The animation descriptor file is a simple text file, with a series of lines of times to display a frame, and a path from the root directory to a bitmap file to use for that frame.
1.2 Interactive Input Keypad Unique values can be assigned for up to 25 keys. When a key event occurs it will be saved to a 20 key buffer. Key events will generate a return message that can be transmitted immediately or polled by toggling the auto transmit key press command. A sample return message is shown below.
Region File Touch regions may be defined using a simple text file for speed and greater ease of use. Each line in a region file describes a single touch. There must be no leading blank spaces, only a single space between each field, and no trailing spaces. Bitmap buffers specified must be pre-loaded with desired images. An example of the first row of the calculator demo is shown below. Figure 5: Region File Example The file above would define four touch regions.
1.5 Application Notes Full demonstration programs and code are available for many different Matrix Orbital displays in a number of different languages from the Application Note section at www.matrixorbital.ca/appnotes. In addition, all files required to run the short examples described in the Advanced Features section are available for download from www.matrixorbital.ca/manuals/GTT_Series. Each example runs as an autoexec script and is described in the Instructions document.
2 Commands 2.1 Basic Commands 1.1 Set Customer Data Dec 254 52 Length Data 2.0 Hex FE 34 Length Data ASCII þ 4 Length Data Write up to 255 bytes of data to the userdata.dat file in the \system\ folder of the SD card. This data can be used for any purpose the end user sees fit including unit identification, network information, system settings, or anything else specific to the module. Length Byte Length of the data to be transferred, in bytes. Data Byte(s) Data to be written to the SD card. 1.
1.6 Read ScratchPad Dec 254 205 Index Length Hex FE CD Index Length ASCII þ Í Index Length Read data previously stored in a specific section of volatile memory. Index Short Starting index of the data to be read. Length Short Length of the data requested. Return Message 252 205 Length Length Result Length Short Length of the data to be transferred, in bytes. Result Byte(s) Data read from specified location in volatile memory. 2.0 2.2 Communication 2.
2.4 Set Flow Control Mode Dec 254 58 FlowControl Hex FE 3A FlowControl ASCII þ : FlowControl Toggle flow control between hardware and off settings. Default is RTSCTS. Serial command only. FlowControl Byte Flow control setting, as per eFlowControl values. 2.0 Table 12: eFlowControl values Value 0 1 Description Off RTSCTS 2.5 Set I2C Address Dec 254 247 I2Caddress 2.0 Hex FE F7 I2Caddress ASCII þ ÷ I2Caddress Immediately change the I2C write address.
2.3 Module 3.1 Get Protocol Revision Dec 254 0 2.0 Hex FE 00 ASCII þ [NUL] Read the firmware version currently used by the display. Minor revisions will indicate an addition only, while major revisions will alter or remove commands; consult the appropriate PCN for more information on changes. For each command in this manual, the minimum firmware version required is listed at the top right. Return Message 252 0 Length Major Minor Major Byte Major revision of the protocol used.
3.6 Get Module Type Dec 254 55 Hex FE 37 ASCII þ7 Read a two byte value that can be used to identify the display. Return Message 252 55 Length Module Module Short The unique number of the module, as per eModule values. 2.0 Table 13: eModule values Value 37638 37648 37633 37634 37635 37636 Description GTT35A GTT38A GTT43A GTT50A GTT57A GTT70A 3.7 Get Module String Dec 254 56 Hex FE 38 ASCII þ8 Read the name of the module in string format.
2.4 Drawing 4.1 Set Background Drawing Colour Dec 254 86 R G B Hex FE 56 R G B ASCII þV RGB Set the display colour when the Clear Screen command is sent. The default colour on startup is black. R Byte Intensity of red, 0 to 255, limited to display metrics. G Byte Intensity of green, 0 to 255, limited to display metrics. B Byte Intensity of blue, 0 to 255, limited to display metrics. 2.0 4.
4.5 Enable Manual Update Dec 254 90 Enable 2.0 Hex FE 5A Enable ASCII þ Z Enable Stop all drawing commands from automatically updating the screen, send them to the display buffer, and allow a manual update to execute all updates at one time. Useful for displaying a complicated image as a single visual update. Default is disabled. Enable Byte Desired manual update setting, as per eEnable values. Table 14: eEnable values Value 0 1 Description Disable Enable 4.6 Manual Update Dec 254 91 2.
4.9 Get Drawing Colour Dec 254 100 Hex FE 64 ASCII þd Read the colour that is currently being used by all drawing commands. Return Message 252 100 Length R G B R Byte Intensity of red, 0 to 255, limited to display metrics. G Byte Intensity of green, 0 to 255, limited to display metrics. B Byte Intensity of blue, 0 to 255, limited to display metrics. 2.0 4.10 Continue Line Dec 254 101 X Y 2.
4.14 Draw Filled Rectangle Dec 254 120 X Y Width Height Hex FE 78 X Y Width Height ASCII þ x X Y Width Height Draw a filled rectangle using the current drawing colour. X Signed Short Leftmost coordinate of the rectangle. Y Signed Short Topmost coordinate of the rectangle. Width Short Width of the rectangle. Height Short Height of the rectangle. 2.0 4.15 Draw Circle Dec 254 123 X Y Radius 2.0 Hex FE 7B X Y Radius ASCII þ { X Y Radius Draw a circular frame one pixel wide using the current drawing colour.
4.19 Draw Dec 254 127 X Y Width Height Radius 2.0 Rounded Hex FE 7F X Y Width Height Radius Rectangle ASCII þ • X Y Width Height Radius Draw a rectangular frame one pixel wide with rounded corners using the current drawing colour. The radius must be equal to or less than half the length of the smallest side of the rectangle. X Signed Short Leftmost coordinate of the rectangle Y Signed Short Topmost coordinate of the rectangle Width Signed Short Width of the rectangle.
2.5 Buffers 5.1 Load Font Dec 254 40 Index FileName Hex FE 28 Index FileName ASCII þ ( Index FileName Load a font file from the SD card into a font buffer for use. Index Byte Index used to identify the font. Specific to fonts. FileName ASCII String Filename, including path from the root folder, of the font file to load. Return Message 252 40 Length Result Result Byte Outcome of Load Font command, as per eErrorCode values. 2.
5.3 Copy Dec 254 96 Index X Y Width Height 2.0 Screen Hex FE 60 Index X Y Width Height Rectangle ASCII þ ` Index X Y Width Height Save a rectangular region of the screen to a bitmap buffer, allowing it to be recalled at a later time. Index Byte Index used to identify the screen section. Specific to bitmaps and screen rectangles. X Signed Short Leftmost coordinate. Y Signed Short Topmost coordinate. Width Short Width of the screen section. Height Short Height of the screen section. 5.
5.7 Clear All Buffers Dec 254 209 Hex FE D1 ASCII þÑ Clear all data from all buffers, freeing significant buffer memory. Command Summary 2.
2.6 Text 6.1 Create a Label Dec 254 16 Index X Y Width Height Rot VJst HJst Font R G B 2.1 Hex FE 10 Index X Y Width Height Rot VJst HJst Font R G B ASCII þ [DLE] Index X Y Width Height Rot VJst HJst Font R G B Designate a portion of the screen that can easily be updated with one line of text; useful when displaying variables. Index Byte Index used to identify the label. Specific to labels. X Signed Short Leftmost coordinate of the label region. Y Signed Short Topmost coordinate of the label region.
6.3 Print Unicode String Dec 254 36 Length Text Hex FE 24 Length Text ASCII þ $ Length Text Print a Unicode formatted string on the screen, using the current font. Length Short Length of the Unicode string to be transmitted, in characters. Text String Unicode formatted string. 2.0 6.4 Print UTF-8 String 2.0 Dec 254 37 Length Text Hex FE 25 Length Text ASCII þ % Length Text Print a UTF-8 formatted string on the screen, using the current font.
6.8 Set Text Window Dec 254 43 X Y Width Height Hex FE 2B X Y Width Height ASCII þ + X Y Width Height Create an invisible rectangle to which future text and insertion commands will be confined. X Signed Short Leftmost coordinate of the text window. Y Signed Short Topmost coordinate of the text window. Width Short Width of the text window. Height Short Height of the text window. 2.0 6.9 Get Text Window Dec 254 44 Hex FE 2C ASCII þ, Read the extents of the current text window.
6.13 Get Font Dec 254 48 Hex FE 30 ASCII þ0 Read the font index of the font currently in use. Return Message 252 48 Length Index Index Byte Font index used to identify the current font file in the font buffer. 2.0 6.14 Set Font Dec 254 49 Index Hex FE 31 Index ASCII þ 1 Index Set the current font to one that has been loaded into the font buffer. Index Byte Font index used to identify the desired font file in the font buffer.
6.19 Get Text Insertion Point Dec 254 122 Hex FE 7A ASCII þz Read the upper left coordinate of the next text string to be displayed. Return Message 252 122 Length X Y X Signed Short Current leftmost coordinate of the insertion point. Y Signed Short Current topmost coordinate of the insertion point. 2.0 6.20 Set Font Rendering Style 2.0 Dec 254 211 RenderType Hex FE D3 RenderType ASCII þ Ó RenderType Set the font rendering style of the current font.
2.7 Bitmaps 7.1 Display Bitmap Dec 254 97 Index X Y Hex FE 61 Index X Y ASCII þ a Index X Y Display a bitmap previously loaded into a bitmap buffer. Index Byte Index used to identify the desired file in the bitmap buffer. X Signed Short Leftmost coordinate. Y Signed Short Topmost coordinate. Return Message 252 97 Length Result Result Byte Outcome of Display Bitmap command, as per eErrorCode values. 2.0 7.2 Set Bitmap Transparency Dec 254 98 Index R G B 2.
2.8 NineSlices 8.1 Display 9Slice Dec 254 145 Index X Y Width Height Hex FE 91 Index X Y Width Height ASCII þ ‘ Index X Y Width Height Display a 9-slice previously loaded into the 9-slice buffer. Index Byte Index used to identify the desired file in the 9-slice buffer. X Signed Short Leftmost coordinate. Y Signed Short Topmost coordinate. Width Short Width of the 9-slice. Height Short Height of the 9-slice. 27 Command Summary 2.
2.9 Animations 9.1 Set Up Animation Dec 254 193 Index Instance X Y 2.0 Hex FE C1 Index Instance X Y ASCII þ Á Index Instance X Y Define a region of the screen to be used to display a loaded animation. If an animation is already in use at that index it will be overwritten. Use the start animation command to display and play the file. Index Byte Index used to identify the desired file in the animation buffer. Instance Byte Index used to identify the state of a specific animation instance.
9.5 Stop All Animations Dec 254 198 Hex FE C6 ASCII þÆ Stop all currently running animations at their present frame. 2.0 9.6 Clear Animation Dec 254 199 Instance 2.0 Hex FE C7 Instance ASCII þ Ç Instance Stop the specified animation instance at the current frame and remove it from the animation queue. The animation image data will remain loaded in the animation buffer and can be reused by issuing the setup command. Instance Byte Index of specific animation instance to be deleted. 9.
2.10 Graphs 10.1 List All Bargraphs Dec 254 102 Hex FE 66 ASCII þf Read a list of all bargraph entries. Three bytes per entry indicate current display use, type, and current value. Return Message 252 102 Length BarType BarValue BarType Byte Type of bargraph entry. BarValue Signed Short Current value of bargraph entry. 2.0 Table 24: eBargraphType values Value 0 1 2 Description Unused Plain 9-Slice 10.2 Define A Plain Bargraph Dec 254 103 Index Min Max X Y Width Height FGR FGG FGB BGR BGG BGB D 2.
10.3 Define A 9Slice Bargraph Dec 254 104 Index Min Max X Y Width Height BFG BBG D 2.0 Hex FE 68 Index Min Max X Y Width Height BFG BBG D ASCII þ h Index Min Max X Y Width Height BFG BBG D Define a region of the screen to be used to display a new 9-slice bargraph identified by the specified index. New indices will overwrite old, invalid directions will default to 0, and inverted min and max values will be corrected. Index Byte Index used to identify the desired bargraph. Specific to bargraphs.
10.7 Reset a Trace Value Dec 254 109 Index Hex FE 6D Index ASCII þ m Index Clear all data from a specified trace, and erase the trace area. As a result, the next Update Trace command behaves as though it is the very first update after initialization. Index Byte Index used to identify the desired trace. Specific to Traces. 2.1 10.8 Reset Multiple Trace Values 2.
Table 26: eTraceTypeandDirection values Value 0 1 2 3 0 16 32 48 64 80 96 112 0 128 Description Bar Line Step Box Bottom Left Left Up Top Right Right Down Bottom Right Left Down Top Left Right Up Shift Toward Origin Shift Away From Origin 10.11 Update a Trace Dec 254 117 Index Value Hex FE 75 Index Value ASCII þ u Index Value Update the value of the trace at the specified index. Trace will be bounded to the minimum and maximum. Index Byte Index used to identify the desired trace. Specific to Traces.
10.14 Set Trace Min/Max Dec 254 148 Index Min Max 2.2 Hex FE Index Min Max ASCII þ Index Min Max Update the min and max values of the specified trace. Trace will update to new minimum and maximum values. Index Byte Index used to identify the previously defined trace. Specific to Traces. Min Signed Short Minimum value for the specified trace. Max Signed Short Maximum value for the specified trace. 10.
2.11 Keypad 11.1 Clear Key Buffer Dec 254 69 Hex FE 45 ASCII þE Clear all saved key presses from the key buffer. 2.0 11.2 Set Keypad Transmit Mode 2.0 Dec 254 79 AutoTransmit Hex FE 4F AutoTransmit ASCII þ O AutoTransmit Toggle auto transmission of key values. Can be used to poll the key buffer. AutoTransmit Byte Auto transmit mode, as per eOnOff values. Table 27: eOnOff values Value 0 1 Description Off On 11.3 Set Debounce Time Dec 254 85 Mode 2.
11.6 Set Auto Repeat Mode Dec 254 165 Mode 2.0 Hex FE A5 Mode ASCII þ ¥ Mode Set key press repeat mode to typematic or hold. In typematic mode if a key press is held, by default the key value is transmitted immediately, then 5 times a second after a 1 second delay. In hold mode, the key down value is transmitted once when pressed, and then the key up value is sent when the key is released. Default is Off. Mode Byte Desired keypad auto repeat mode, as per eKeypadRepeatMode values.
2.12 Touch 12.1 Create A Touch Region Dec 254 132 Index X Y Width Height Up Down Hex FE 84 Index X Y Width Height Up Down ASCII þ „ Index X Y Width Height Up Down Create a region of the screen that responds to touch events with a defined single byte and visual update. Index Byte Index used to identify the desired touch region. X Signed Short Leftmost coordinate of the touch region. Y Signed Short Topmost coordinate of the touch region. Width Short Width of the touch region.
12.5 Set Dragging Threshold Dec 254 137 Threshold 2.0 Hex FE 89 Threshold ASCII þ ‰ Threshold Set the distance a press is required to travel before a move event is reported. Precision will vary inversely to data transmitted; care should be taken to find a suitable balance. Distance is calculated as [∆x]^2 + [∆y]^2 = d^2. Threshold Short Dragging threshold value. Default is 3 pixels. 12.6 Calibrate Touch Screen Dec 254 139 2.0 Hex FE 8B ASCII þ‹ Initiate the touch screen calibration sequence.
12.9 Set Out of Region Setting Dec 254 142 Setting Hex FE 8E Setting ASCII þ Ž Setting Set reporting status for out of region touch responses. Setting Byte Desired out of region setting, as per eOnOff values. Default is Off. 2.0 12.10 Get Out of Region Setting Dec 254 143 Hex FE 8F ASCII þ• Read the current out of region setting. Return Message 252 143 Length Report Report Byte Current out of region setting, as per eOnOff values. 2.0 12.11 Set Region Activation State 2.
2.13 Output 13.1 Set GPO State Dec 254 73 Number Setting Hex FE 49 Number Setting ASCII þ I Number Setting Toggle the specified GPO on or off, sourcing up to 15mA current at 5V per GPO or sinking to ground. Number Byte GPO to be controlled. Setting Byte GPO state, as per eGPOSetting values. 2.0 Table 32: eGPOSetting values Value 1 0 Description On Off 13.
13.5 Activate Buzzer Dec 254 187 Frequency Duration Hex FE BB Frequency Duration ASCII þ » Frequency Duration Generate a tone from the piezo buzzer at the specified frequency for the defined duration. Frequency Short Frequency of the beep in Hertz. Duration Short Duration of the beep in milliseconds. 2.0 13.6 Set Default Buzzer Beep 2.
2.14 Scripts 14.1 Run Script File Dec 254 93 FileName 2.0 Hex FE 5D FileName ASCII þ ] FileName Send an array of bytes saved in the specified script file as if it was received from the serial port. Sending data to the serial port is still possible, but it will queue up in the receive buffer and will only be parsed after the execution of the script file. Scripts may be stacked up to 10 deep. FileName ASCII String Filename, and path from the root folder, of the script file to run. 14.
3 Appendix 3.1 Command Summary Available commands below include identifying number, required parameters, the returned response and the response type.
Table 37: Drawing Commands Name Set Background Drawing Colour Get Background Drawing Colour Clear Screen Scroll Screen Enable Manual Update Manual Update Flush Region Set Drawing Colour Get Drawing Colour Continue Line Draw Line Draw Pixel Draw Rectangle Draw Filled Rectangle Draw Circle Draw Filled Circle Draw an Ellipse Draw a Filled Ellipse Draw Rounded Rectangle Draw Filled Rounded Rectangle Draw Triangle Draw Filled Triangle Dec 86 87 88 89 90 91 92 99 100 101 108 112 114 120 123 124 125 126 127 128
Table 39: Text Commands Name Dec Hex ASCII Response $ % Parameters Index, X, Y, Width, Height, Rot, VJst, HJst, Font, R, G, B Index, Format, Value Length, Text Length, Text Create a Label 16 10 [DLE] Update a Label Print Unicode String Print UTF-8 String Set Control Character Mode Get Control Character Mode Get String Extents Set Text Window 17 36 37 11 24 25 38 26 & Mode None 39 27 ' None Mode 42 43 2A 2B * + Text X, Y, Width, Height Get Text Window 44 2C , None Reset Font
Table 42: Animations Commands Name Set Up Animation Start/Stop Animation Set Animation Frame Get Animation Frame Stop All Animations Clear Animation Clear All Animations Resume All Animations Dec 193 194 195 196 198 199 200 201 Hex C1 C2 C3 C4 C6 C7 C8 C9 ASCII Á Â Ã Ä Æ Ç È É Parameters Index, AnimationNum, X, Y AnimationNum, State AnimationNum, Frame AnimationNum None AnimationNum None None Response None None None Frame None None None None Table 43: Graphs Commands Name Dec Hex ASCII Parameter
Table 45: Touch Commands Name Create A Touch Region Clear A Touch Region Clear All Touch Regions Change Touch Reporting Style Set Dragging Threshold Calibrate Touch Screen Load Region File Restore Touch Calibration Set Out of Region Setting Get Out of Region Setting Set Region Activation State Get Region Activation State Dec 132 133 134 135 137 139 140 141 142 143 146 147 Hex 84 85 86 87 89 8B 8C 8D 8E 8F 92 93 ASCII „ … † ‡ ‰ ‹ Œ • Ž • Æ ô Parameters Index, X, Y, Width, Height, Up, Down Index None Rep
3.2 Data Types Common Language Representations The following table outlines native data types in common programming languages that can be used to represent the data types used in this manual.
4 Definitions 9-Slice: Graphic format used to scale bitmaps, usually rectangular, without distorting their geometry. Nine regions define the object center, four corners, and four sides for accurate up or down scaling. ASCII: American standard code for information interchange used to give standardized numeric codes to alphanumeric characters. Big Endian: Transmission protocol whereby the most significant byte is transmitted first. BPS: Bits per second, a measure of transmission speed.
