Summary

In the previous article I showed you how to integrate the Matrix Orbital Driver into a PSoC4200M project.  I am planning on using this device on a bus with multiple displays, and using an RTOS.  The byte based driver in the previous example isn’t that great for this situation.  In one of the earlier articles I showed you how to build a packet based interface instead of a byte-based interface.  Lets integrate that into the PSoC4200M project, and add some more commands.

In this article I will

1. Integrate the packet driver
2. Add event handlers
3. Add some new commands
4. Fix a nasty little bug that is lurking in the driver

Integrate the Packet Driver

In the file gtt_parser.c there is a big long function which reads a byte at a type every time that it is called.  It then assembles the packet into a buffer of bytes that the rest of the system can consume.  After the packet is completely read, it sets up pointers to the start and end of the packet and finally calls the function “gtt_process_packet”.  For me what I will do is read in a packet, then call this function to setup things and call the gtt_process_packet.

// This function process a whole packet at a time    
uint8_t gtt_parser_process(gtt_device *device)
{
    gtt_packet_error_t rval;
    rval = device->ReadPacket(device);
    if(rval == GTT_PACKET_NODATA)
        return 0;
    
    if(rval != GTT_PACKET_OK)
    {
#if DEBUG_PSOC        
        sprintf(buff,"GTT_PACKET_ERROR %d\r\n",rval);
        UART_UartPutString(buff);
#endif
        return 0; // No data
    }

    device->Parser.PacketStart = device->Parser.Index;
    device->Parser.Index += device->Parser.Length;
    
	uint8_t Result = gtt_process_packet(device, device->Parser.PacketStart);
	if (Result)
	    return 0;
	else
	    return 1;

}

I use almost the same packet driver as I built in the earlier example.  Except that I need to modify it to read into the gtt buffers that the gtt driver library expects.  The biggest benefit of this whole thing is that it makes complete I2C transactions, rather than issuing a bunch of start/address/reads which makes it significantly more efficient.

gtt_packet_error_t readPacketI2C(gtt_device *device)
{
    
    uint8_t data;
    uint32_t i2cerror;
    
    i2cerror = I2C_I2CMasterSendStart( ((i2cContext_t *)device->Context)->slaveAddress,I2C_I2C_READ_XFER_MODE , ((i2cContext_t *)device->Context)->timeout);
    i2cerror |= I2C_I2CMasterReadByte(I2C_I2C_NAK_DATA,&data,((i2cContext_t *)device->Context)->timeout);
    i2cerror |= I2C_I2CMasterSendStop(((i2cContext_t *)device->Context)->timeout);
    
    
    // Something bad happened on the I2C Bus ....
    if(i2cerror)
    {
        sprintf(buff,"I2C Return Code %X\r\n",(unsigned int)i2cerror);
        UART_UartPutString(buff);
        return GTT_PACKET_I2CERROR;
    }
    
     // The screen returns a 0 when there is nothing in the buffer.
    if(data == 0)
    {
        return GTT_PACKET_NODATA;
    }

    // This is bad because there was something other than a packet start byte
    if(data != 252)
    {
        sprintf(buff,"bad data = %d\r\n",data);
        UART_UartPutString(buff);
        return GTT_PACKET_DATABAD;
    }
    
    // We know that we have a command
    i2cerror = I2C_I2CMasterSendStart( ((i2cContext_t *)device->Context)->slaveAddress,I2C_I2C_READ_XFER_MODE , ((i2cContext_t *)device->Context)->timeout);
    i2cerror |= I2C_I2CMasterReadByte(I2C_I2C_ACK_DATA,&data,((i2cContext_t *)device->Context)->timeout); // command
    device->Parser.Command = data;

    // Read the Length
    i2cerror |= I2C_I2CMasterReadByte(I2C_I2C_ACK_DATA,&data,((i2cContext_t *)device->Context)->timeout); // length
    device->Parser.Length = data<<8;
    i2cerror |= I2C_I2CMasterReadByte(I2C_I2C_NAK_DATA,&data,((i2cContext_t *)device->Context)->timeout); // length
    device->Parser.Length += data;
    i2cerror |= I2C_I2CMasterSendStop(((i2cContext_t *)device->Context)->timeout);
    
    if(i2cerror)
        return GTT_PACKET_I2CERROR;
    
    if(device->Parser.Length > device->rx_buffer_size)
    {
        return GTT_PACKET_SIZE;
    }
    
    // If the packet has any data... then read it.
    if(device->Parser.Length != 0)
    {
        i2cerror |= I2C_I2CMasterSendStart( ((i2cContext_t *)device->Context)->slaveAddress,I2C_I2C_READ_XFER_MODE , ((i2cContext_t *)device->Context)->timeout);
    
        for(uint32_t i=0;i < device->Parser.Length-1; i++)
        {
            i2cerror |= I2C_I2CMasterReadByte(I2C_I2C_ACK_DATA,&data,((i2cContext_t *)device->Context)->timeout); // length
            device->rx_buffer[device->Parser.Index+i] = data;
        }

        // Read the last byte
        i2cerror |= I2C_I2CMasterReadByte(I2C_I2C_NAK_DATA,&data,((i2cContext_t *)device->Context)->timeout); // length
        device->rx_buffer[device->Parser.Index +device->Parser.Length - 1 ] = data;
        i2cerror |= I2C_I2CMasterSendStop(((i2cContext_t *)device->Context)->timeout);
        
        if(i2cerror)
            return GTT_PACKET_I2CERROR;
    }
      
    sprintf(buff,"command = %d length = %d bytes= ",device->Parser.Command,device->Parser.Length);
    UART_UartPutString(buff);
    for(uint32_t i=0;i<device->Parser.Length;i++)
    {
        //sprintf(buff,"%d ",inbuff[i]);
        sprintf(buff,"%d ",device->rx_buffer[device->Parser.Index+i]);
        UART_UartPutString(buff);
    }
    UART_UartPutString("\r\n");
    return GTT_PACKET_OK;
}

Add Event Handlers

I noticed when I looked at the gtt_device.h that the structure for the gtt_device has an member called “gtt_events”, but what is that?

typedef struct gtt_device
{
	void* Context;            /* device depended storage */
	gtt_write Write;          /* Function for writing data */
	gtt_read Read;            /* Function for reading data */
    gtt_packet_error_t (*ReadPacket)(gtt_device *);

	uint8_t secured_packets;  /* 0 = regular protocol, 1 = wrap all outgoing packets with crc protection*/
	
	/* The fields below are internal and shall NOT be used by the read/write functions */
	
	gtt_parser Parser;        /* Protocol parser data */
	uint8_t *rx_buffer;       /* Buffer for incoming data */
	size_t rx_buffer_size;    /* size of the rx buffer in elements */
	uint8_t *tx_buffer;       /* Buffer for outgoing data */
	size_t tx_buffer_size;    /* size of the tx buffer in elements */
	size_t tx_index;          /* current index for the packet writer */
	gtt_events events;        /* Event Callbacks */
	size_t wait_idx;          /* Current Packet Index for the waitlist */
	gtt_waitlist_item waitlist[8]; /* Packet recieve waitlists */
} gtt_device;

Well. the gtt_events structure is defined in gtt_events.h.  Basically it is a bunch of function pointers, which if you provide functions, it will call those functions when things happen on the screen.  For instance the function that gtt_event_slider_change is pointing to will be called when a slider changes.

typedef void(*gtt_event_key)(gtt_device* device, uint8_t key, eKeypadRepeatMode type);
typedef void(*gtt_event_sliderchange)(gtt_device* device, eTouchReportingType type, uint8_t slider, int16_t value);
typedef void(*gtt_event_touch)(gtt_device* device, eTouchReportingType type, uint16_t x , uint16_t y);
typedef void(*gtt_event_regiontouch)(gtt_device* device, eTouchReportingType type, uint8_t region);
typedef void(*gtt_event_baseobject_on_property_change)(gtt_device* device, uint16_t ObjectID, uint16_t PropertyID);
typedef void(*gtt_event_visualobject_on_key)(gtt_device* device, uint16_t ObjectID, uint8_t Row, uint8_t Col, uint8_t ScanCode, uint8_t Down);
typedef void(*gtt_event_button_click)(gtt_device* device, uint16_t ObjectID, uint8_t State);

typedef struct gtt_events {
	gtt_event_key key;
	gtt_event_sliderchange sliderchange;
	gtt_event_touch touch;
	gtt_event_regiontouch regiontouch;
	gtt_event_baseobject_on_property_change baseobject_on_property_change;
	gtt_event_visualobject_on_key visualobject_on_key;
	gtt_event_button_click button_click;
} gtt_events;

To start with I just created stub functions that would just print out the information.  Here is an example of a function for the “gtt_event_button_click”

void my_gtt_event_button_click(gtt_device* device, uint16_t ObjectID, uint8_t State)
{
    (void)device;
    (void)ObjectID;
    (void)State;
    UART_UartPutString("event button click\r\n");
}

Once you have those functions you need to add them to the gtt_device structure like this:

gtt_events myEvents = {
    .sliderchange = my_gtt_event_sliderchange,
    .touch = my_gtt_event_touch,
    .regiontouch = my_gtt_event_regiontouch,
    .baseobject_on_property_change = my_gtt_event_baseobject_on_property_change,
    .visualobject_on_key = my_gtt_event_visualobject_on_key,
    .button_click = my_gtt_event_button_click
};

Add New Commands

Now we are ready to update the test project to add some more commands.  Here are a few examples which call the “gtt25” functions.

            case 'q':
                UART_UartPutString("Set Text\r\n");
                gtt25_set_label_text(gtt,2,t);
            break;
                       
            case '2':
                gtt25_set_slider_value(gtt,3,2);
            break;
               
            case '9':
                gtt25_set_slider_value(gtt,3,9);
            break;
                    
            case 'I':
                gtt_set_default_channel(gtt, eChannel_I2C);
            break;
                    
            case '+':
                count += 1;
                if(count>100)
                    count = 100;
                gtt25_set_gauge_value(gtt,9,count);
            break;    
                
            case '-':
                if(count > 0)
                    count -= 1;
                gtt25_set_gauge_value(gtt,9,count);
            break;

Fix a Nasty Little Bug

While I was debugging the library I found myself where the program was hung.  When I ran the debugger I found myself here.  This means that there was an ARM exception.  But why?

Then when you look at the call stack you find out that the exception is in the function “gtt_parser_getS16”

OK… but what in the world?  All this function is doing is taking the bytes and casting them into a uint16_t

Well it turns out that if the address that is being read is ODD meaning not even aligned, you will endup with an ARM exception for an unaligned access of the memory.  This is why you need to be super careful with a pointer cast.  In this case you are casting a uint8_t pointer which can be byte aligned.

Here is a proper fix to this problem, assemble the composite type byte-by-byte.

int16_t gtt_parser_getS16(gtt_device* device, size_t index, size_t *outIndex)
{
    
    int16_t data = (device->rx_buffer[index]<<8 | device->rx_buffer[index+1]);	    
	*outIndex = index + 2;
    return data;
  
}

In the next article I will port all of this stuff to PSoC 6.

You can "git" these projects from

https://github.com/iotexpert/GTT43A

And the driver library from 

https://github.com/iotexpert/GTT-Client-Library

Summary

In this article Im going to show you how to build a driver for the Matrix Orbital GTT43A that I have been talking about in the last several articles.  As you can see from the protocol manual, the Matrix Orbital Display has a bunch of different commands.  And I know that I need a driver.  But there isn’t (yet) one on the Matrix Orbital Website.  However, when I look at the pre-release of the GTT25 protocol guide, it seems clear that they are planning on one.  But what to do in the interim?  As usual Google is your friend and after looking around a little bit I found this YouTube video of a Matrix Orbital Demo.  One more Google search lead me to this Matrix Orbital GitHub repo which appears to hold the driver that they wrote for this demo.

Clone it! Clone it! Good.

Now what?  In this article Ill show you:

1. How to port the library to PSoC
2. How to implement the HAL as conceived by Matrix Orbital
3. How to make a test jig

And in the next Article I will

1. Replace the HAL and Parser with a Packet based HAL, much better
2. Show you how to fix some bugs in the library (nastiness)
3. Add more test code

And in the one after that Ill port the whole thing to PSoC6 & RTOS

Port the GTT Client Library

After running “git@github.com:MatrixOrbital/GTT-Arduino-Thermometer-Demo.git” I look around a little bit… and immediately find “GttClient”.  And when you look there, perfect a bunch of C and Header files.

The first step is to make a new PSoC Creator project.  As I have done in the past, Ill drive the display with I2C, and Ill build a command line parser to talk to the system.  Here is the schematic:

Assign the Pins (I am using a PSoC 4200M, my favorite PSoC, development kit, specifically the CY8CKIT-044)

After running “Generate Application”, the next thing I do is pull in the library into PSoC Creator.  To do this

1. Right click on the Source Files and make a new Folder, rename it “GTT”
2. Right click on the GTT Folder and do “Add Existing Item…”
3. Navigate to the GttClient directory, select all of the .h and .c files

Your WorkSpace Explorer should look like this now:

Because those files are not in the normal build path, you next need to add the directory to the include path so that PSoC Creator can find the header files.  Right click on the project and pick “Build Settings”.

Then add a path to the library in the “Additional Include Directories”

Before we fix up the library to work, I always like to hit build to make sure everything is working.

Implementing the Hardware Abstraction Layer

In order to use the driver you need a Hardware Abstraction Layer.  After looking around a little bit I find the “.ino” file which is the Arduino main project file.  In that file, the first thing that they do is declare a structure of type “struct gtt_device”.  All of the function calls to the library take a pointer to this structure.  OK.  Lets have a look at the structure

1. First it appears that they let you store some generic data via a “Context”
2. Then there are two functions to read and write data
3. Then some private stuff (which is used by the packet parser)

typedef struct gtt_device
{
	void* Context;            /* device depended storage */
	gtt_write Write;          /* Function for writing data */
	gtt_read Read;            /* Function for reading data */
  

	uint8_t secured_packets;  /* 0 = regular protocol, 1 = wrap all outgoing packets with crc protection*/
	
	/* The fields below are internal and shall NOT be used by the read/write functions */
	
	gtt_parser Parser;        /* Protocol parser data */
	uint8_t *rx_buffer;       /* Buffer for incoming data */
	size_t rx_buffer_size;    /* size of the rx buffer in elements */
	uint8_t *tx_buffer;       /* Buffer for outgoing data */
	size_t tx_buffer_size;    /* size of the tx buffer in elements */
	size_t tx_index;          /* current index for the packet writer */
	gtt_events events;        /* Event Callbacks */
	size_t wait_idx;          /* Current Packet Index for the waitlist */
	gtt_waitlist_item waitlist[8]; /* Packet recieve waitlists */
} gtt_device;

That means you need to provide a function called “Write” and one called “Read” which reads bytes from the serial interface.  Here is how they setup the structure for the Arduino Demo.  Apparently they are going to make two functions called i2cWrite and i2cRead.

  gtt.Write = i2cWrite; //Set the write function
  gtt.Read = i2cRead; //Set the read function
  gtt.rx_buffer = rx_buffer; //Declare a buffer for input data
  gtt.rx_buffer_size = sizeof(rx_buffer); //Declare the size of the input buffer
  gtt.tx_buffer = tx_buffer; //Declare a buffer for output data
  gtt.tx_buffer_size = sizeof(tx_buffer); //Declare the size of the output buffer

So, what do those functions look like?

The I2C Write function just uses the Arduino Wire library to send bytes out the I2C.  And the I2C read function just reads one byte from the I2C and returns it.  OK I know how to do that on the PSoC

}     

int i2cWrite(gtt_device* gtt_device, char* data, byte data_length) {//Write an array of bytes over i2c
  Wire.beginTransmission(I2C_Address);  
  for (int i = 0; i < data_length; i++) {
    Wire.write(data[i]);        
  }
  Wire.endTransmission();  
  return 0;
}

byte i2cRead(gtt_device* gtt_device) { //Wait for one byte to be read over i2c  
  byte data;
  Wire.beginTransmission(I2C_Address);  
  Wire.requestFrom(I2C_Address, 1);     
  if(Wire.available()<1) 
  {
    return -1;
  }
  else{
    data = Wire.read();  
    Serial.println(data);
    return data;
  } 
}

To do this exact same thing on the PSoC do this.  Notice that I put in a little bit of error checking.  I also make complete legal I2C transactions, Start, Address, R/W, bytes, Stop

int generic_write(gtt_device *device, uint8_t *data, size_t length)
{
    (void)device;
    uint32 returncode;
    
   
    sprintf(buff,"length = %d ",length);
    UART_UartPutString(buff);

            
    returncode = I2C_I2CMasterSendStart( ((i2cContext_t *)device->Context)->slaveAddress,I2C_I2C_WRITE_XFER_MODE , ((i2cContext_t *)device->Context)->timeout);
    if(returncode != I2C_I2C_MSTR_NO_ERROR)
    {
        sprintf(buff,"error = %X\r\n",(unsigned int)returncode);
        UART_UartPutString(buff);
    }
    
    for(size_t i=0;i<length;i++)
    {
        I2C_I2CMasterWriteByte(data[i],((i2cContext_t *)device->Context)->timeout);
        sprintf(buff,"%d ",data[i]);
        UART_UartPutString(buff);
    }
    
    I2C_I2CMasterSendStop(((i2cContext_t *)device->Context)->timeout);
    UART_UartPutString("\r\n");
    return length;
        
}

And to make the PSoC read one byte at a time from the I2C do this … notice for some reason I didnt put in error checking.

int generic_read(gtt_device *device)
{
    (void)device;
     uint8 data;
     
    //uint32 returncode;
    I2C_I2CMasterSendStart( ((i2cContext_t *)device->Context)->slaveAddress,I2C_I2C_READ_XFER_MODE,((i2cContext_t *)device->Context)->timeout);
    I2C_I2CMasterReadByte(I2C_I2C_NAK_DATA,&data,((i2cContext_t *)device->Context)->timeout);
    I2C_I2CMasterSendStop(((i2cContext_t *)device->Context)->timeout);
    return data;
}

Matrix Orbital Parser

The Matrix Orbital Parser is build around a function which you are supposed to call every time through your main loop.

uint8_t gtt_parser_process(gtt_device *device)

If you look in this function you will find a state machine that calls the Read function pointer, then based on the value read and the state of the state machine read in the packet.  Remember that there are two somewhat different packet formats, and this thing handles it.

uint8_t gtt_parser_process(gtt_device *device)
{
	int Res = device->Read(device);
	if (Res != -1)
	{
		switch (device->Parser.state)
		{
		case GTT_PARSER_IDLE:
			if (Res == 252)
				device->Parser.state = GTT_PARSER_COMMAND;
			else if (Res == 0) // Ignore 0's 
            {
                return 0;
            }

I notice in gtt_parser.h that they decided to use #defines for the states, which works, but would have been better done with an enumerated datatype.

#define GTT_PARSER_IDLE       0
#define GTT_PARSER_COMMAND    1
#define GTT_PARSER_LENGTH_1   2
#define GTT_PARSER_LENGTH_2   3
#define GTT_PARSER_DATA       4

One thing that took a little but of looking at is how they handle the packets that come in.  Remember from the previous articles that there are three possible sources of packets that you might read from the buffer.

1. Packets that were generated by the configuration scripts residing in the display
2. Packets that are generated from the user of the display doing something e.g. pressing a button
3. Packets that are responses to the application sending it packets (e.g. get slider value)

They handle this by keeping a list of packets that are going to elicit a response.

The bottom line is that all of their code appears to do the right thing, and all you need to do is call the parser.

Add Test Project Code to main.c

I turns out that I am writing this Article after I already did all of the work for the next one where I replace the byte-by-byte parser with my own packet processor.  In order to make that work, I #ifdef to select which packet processor to use.

#ifdef GTT_ORIG_PARSER
// The original Matrix Orbital Byte Based Parser
    
uint8_t gtt_parser_process(gtt_device *device)

PSoC Creator will allow you to add this to your project on the build settings dialog.  If you click on the compiler option, you can then add defines to the command line on the “Preprocessor Definitions” box.  Notice that I added “GTT_ORIG_PARSER”

OK now the punchline.  In the main loop you need to startup the I2C, UART and setup the GTT interface.  Then you loop infinitely.  Read a key from the keyboard and do something based on what they press.

You can see that I call a bunch of their driver functions which all start with “gtt_”.

int main()
{
    CyGlobalIntEnable; /* Enable global interrupts. */
    I2C_Start();
    UART_Start();
    UART_UartPutString("Started\r\n");
    
    gtt_device *gtt = &gtt_device_instance;
    char c;
    int16_t val;
    while (1)
    {
        c = UART_UartGetChar();
        switch(c)
        {
            case 0:  break;
            case 'l':   gtt_draw_line(gtt, 0, 0, 480, 272);  break; 
            case 'c': gtt_clear_screen(gtt);  break;
            case 'R':  gtt_reset(gtt);      break;                  
            case 'v':
                gtt25_get_gauge_value(gtt,9,&val);
                sprintf(buff,"Gauge Value = %d\r\n",val);
                UART_UartPutString(buff);
                break;
            case 'z':
                UART_UartPutString("System Mode = IDLE\r\n");
                systemMode = MODE_IDLE;
                break;
            case 'Z':
                UART_UartPutString("System Mode = POLLING\r\n");
                systemMode = MODE_POLLING;
            break;
            case '?':
                UART_UartPutString("-------- GTT Display Functions -------\r\n");
                UART_UartPutString("l\tDraw a line\r\n");
                UART_UartPutString("c\tClear Screen\r\n");
                UART_UartPutString("R\tReset\r\n");
                UART_UartPutString("v\tGet and print value of gauge \r\n");
                UART_UartPutString("-------- System Control Functions -------\r\n");
                UART_UartPutString("z\tSystemMode = IDLE\r\n");
                UART_UartPutString("Z\tSystemMode = POLLING\r\n");
            break;    
        }
        if(systemMode == MODE_POLLING)
            gtt_parser_process(gtt);
                
    }
    return 0;
}

In the next article I am going to replace their “gtt_parser_process” with a complete packet reader.

You can "git" these projects from

https://github.com/iotexpert/GTT43A

And the driver library from 

https://github.com/iotexpert/GTT-Client-Library

Summary

As I have been working my way through understanding the Matrix Orbital displays, I think that the whole scheme for programming them is very clever.  The bottom line of this article is that Matrix Orbital created a command language for making things work in the display, then the built the rest of their toolset around that language.  In this article Ill show you how it is all connected.

A Buffer Full of Mystery

While I was trying to understand how the GTT Support Tool works, I send a “Reset Module” also known as {254, 1}.  When I ran the script, the screen rebooted, and then the serial monitor dumped out a boat load of stuff.  You can see it in the picture below:

This was not very different than when I first attached to the screen using the Bridge Control Panel.  Here are the first I2C reads after the reboot.

So, what is all of this stuff?  The answer to that question resides in how this whole thing is put together.

GTT Scripts

All interactions with the display are done via the command language.  There are multiple paths for sending commands to the screen, the ones we have talked about so far, I2C, USB and UART.  And the one path that I have not specifically talked about but works exactly the same way, the mass storage sd-card.

When you design a screen in GTT Designer, what it does is take that screen, and spit out a text based command language.  Here is a screenshot of that for the test project that I am working on.

Then GTT Designer compiles the text into a binary file with the GTT2.0 and GTT2.5 commands.  You can look at the binary file with a binary file editor.  Here it is for Screen1.bin

And you should recognize the bytes you see.  Look at the top and you will see {FE, 05, 00} which in decimal is {254, 05, 00} and if you look in the GTT20 manual you will find that is “Set Communication Channel to None”.  Here is the screenshot from the manual.

But, what happens when the device boots?  Well, they followed the lead from MS-DOS and created a file called “autoexec”.  And, if you look in that file they so graciously tell you what happens.

How cool is that?  All of these commands are just the things that you did on the project setting and the display settings.  And the last line of the file launches just launches Screen1.bin, which is just the binary file of the commands it takes to load the Screen1.

Now back to the original question.  What is the buffer full of mystery?  Simple, it is the output of all of the commands (if they make output) that are in the autoexec binary and the screen1 binary.  If you had happened to set the default channel to “none” you will find that the buffer doesnt have anything in it… which should make sense.

So, when the manual says to delete the autoexec at the top level directory in order to reset the board.  All that does it remove all of the settings that you created in your project.

The only thing that I wish is that they gave you access to the txt–>bin compiler.  But oh well.

You can "git" these projects from

https://github.com/iotexpert/GTT43A

And the driver library from 

https://github.com/iotexpert/GTT-Client-Library

Summary

I have recently found myself way way down a rabbit hole on a project that uses a Matrix Orbital GTT43A.   This display is a super cool, though expensive, intelligent touch screen display.  Here is a picture:

I call it intelligent because it has a fully featured CPU that runs all of the display and touch functions for you.  Basically you build all of the screens with GTT GUI elements (sliders, buttons, text etc.) using the Matrix Orbital design tool called GTT Designer.  Then you program that configuration into an sd-card that is attached to the display.  When you power up the display, your configuration comes up and you are off to the races.  Then, in your system you can then simply interact with the display via I2C, UART, USB or SPI.

I know that it seems simple, but I will say that this has turned into quite an adventure which has, in turn, been an awesome learning experience.

Matrix Orbital GTT43A

The Matrix Orbital GTT43A is a 4.3″ backlit LCD display with a capacitive touch screen.  Here is a screenshot from the Matrix Orbital website.  Yes, you read the price right, it is $155.84…. well actually $165.84 with capacitive touch.

Here is a picture of the back of the screen.

On the far left you can see the connector labeled “Keyboard Power”.  This is a place where you can plug in a matrix keyboard that looks like the next picture.  Though I am not exactly sure why you would make a nice touch screen interface and then use a mechanical button interface?

In the middle of the picture you can see a micro-sd card which holds all of your screen configuration information.  The sd-card is a normal mass storage card and you can drag and drop your configuration, or new firmware for the screen using normal Windows.  You can also put the display into mass-storage mode and then access the card via the mini-usb-b connector that is in the upper left.

The display also supports 6 digital GPIOs (which you can see on the lower left of the picture).  It also has a piezoelectric buzzer and a haptic vibrator.

In order to talk to the display with your system controller you can use I2C, UART, SPI or USB.  It is interesting that you seem to be able to use multiple interfaces at the same time, which is pretty convenient for debugging.

The display requires a decent amount of juice.  Here is a picture on my desk, 5V and 375mA,  which is more than the development kit I was using will provide.  In fact it, will sort of work for a while off the devkit power supply, but when you push a button on the screen it will reboot the display.

GTT Designer

GTT Designer is a Windows GUI building tool.  It is straight forward to use.  When you start up the software it will give you a choice of displays to build for.  In the picture below you can see that it detected that I had a GTT43A attached to my computer via USB.

After setting up the name of my project and clicking “New Project” I am given the choice of customizing the global settings for the display.

Once the project is setup, you are now given the ability to configure the display settings.  On this screen you can setup a number of things, including the I2C address of the display.  Also, on the screen below you can see “Default Channel” is set to none.  What this means is that any GUI thing that happens will send messages to the default channel.  In this case none.  But that isnt what I want so I change it to I2C (next picture)

What I really want it all of the output to go to the I2C.  But given that the screen is an I2C slave, and it cant send out data, what does that really mean?  What it means is that all of the output goes into a buffer, that slowly fills up until you read the data out of it via I2C.  If you setup the Default channel as Serial, the data will go directly out via UART.

Once the display settings are done you will end up with a screen that looks like this.  On the left side of the screen you can pick out the different GUI elements (buttons, text labels, sliders, images etc) and the drag them onto the screen.  Notice that there are four tabs, Tools, Legacy Tools, Assets, Overview.  At some point very recently Matrix Orbital did a massive re-engineering project to make things simpler to interact with the screen.  When they did this, the created a who new set of widgets called “GTT2.5” widgets.  You can still use the old widgets which they now call “Legacy”

On the screen below you can see that I placed a bunch of different GUI elements for my test project.  When you click on an element, the right hand side of the screen will let you update properties of the object e.g. color, size, name.  You can also create events (more on that in the next article)

One you have drawn your screen you then want to build and program the project.  Or in their language generate and deploy.  To do this you can either click generate then click deploy, or just click deploy.  When you do this it will first build all of your project into a directory on your computer called “Output”.  There are three interesting things in the output directory.

1. autoexec.txt/bin – files that contains a script that runs when the display turns on (more on that in the next article)
2. Report.txt – a file that contains information about the objects, names, ids etc (this is important for your software)
3. GTTProject1 – a directory with all of the files required for your project.

When you look in the GTTProject1 directory you will see that it contains a directory for “Screen1”.  If I had made multiple screens it would have made multiple directories.  It also has a directory called “Fonts”, which big surprise, contains the Fonts that are used by the project.

In the “Screen1” directory you will see a bunch of bitmap files, text files etc.

Screen1.txt contains a textual version of the “program” that creates the screen.  Here is a snapshot of the top of the file.

And “Screen1.bin” which is the compiled version of the “Screen1.txt”- more on this in the next article.

When you click the deploy button, it sends a command to the screen to put it into mass storage mode which just turns the screen into a flash disk which can be written/read by your PC.  Here is what the screen looks like when it is in mass storage mode:

After the device is in mass storage mode, GTT Designer copies all of the file onto the sd-card of the display and the reboots the display to run the program.

When you are running GTT Designer you can switch the display back and forth between Mass Storage mode and Display mode on the Tools menu by selecting “Switch Mode”

In the next several articles Ill show you how to build firmware to talk to the screen.

You can "git" these projects from

https://github.com/iotexpert/GTT43A

And the driver library from 

https://github.com/iotexpert/GTT-Client-Library