Remote displays
The GDISP module offers the possibility to connect a remote display. In the following we will use the two terms headless and display, where headless refers to the embedded target project (your microcontroller) and the display is the device that will act as the remote display.
Contents
Configuration
From the application point of view, there's no difference between using a local or a remote display. The headless device will still run the entire logic and also process the GUI. The only difference is the interface (TCP/IP). There are several advantages compared to directly running the GUI on the remote display and simply pass the raw values:
Multiple clients
It's possible to connect from a variety of different devices to the headless device without implementing the logic function and the GUI toolkit for each. For example, you can control your target device from another embedded remote, a tablet and a computer and all the parameters are always the same (as they only exist once). However, currently you can only have one remote display connected at once. This limitation shall be removed soon.
Multiple displays
By using the multiple displays support, you can use both, a local and a remote display without the need to write another line of code.
Upgradability
A firmware upgrade of your device will automatically upgrade the GUI on all clients. Therefore you never have to give different client software to your customers along with the firmware upgrade itself. One updated - all interfaces updated.
Services
Imagine your device is installed somewhere in a factory floor. A technican can now go to the device and just hook up a display module and he'll have the same view as the operator on the remote display. This can simplify the troubleshooting and improvement process a lot.
Supported IP stacks
The uGFXnet driver currently supports the following systems:
However, you can extend the uGFXnet driver to use any IP stack.
Example
As stated above, you don't have to change your application code of the headless device. However, you have to initialise the sockets. At startup, the uGFXnet driver will call a function named Start_LWIP(). You have to ensure that LwIP is up and running after this function has been called.
The part left to do is the code for the remote display. There's a premade example that can be found in /tools/uGFXtool. As this tool uses µGFX itself, it can be used to act as a remote display running on Windows, Linux and Mac OS-X without any modification. just compile it as you would any µGFX application (Makefiles can be found in the Getting Started article). After a successful build, simply start the executable with the IP of the headless device as a parameter and the GUI will show up. When you disconnect, the current state will be the same once you reconnect again. The default port of the uGFXnet driver is 13001.
./ugfx 192.168.1.20
Protocol
However, you don't have to use µGFX on the remote display side. The protocol of the uGFXnet driver is documented and therefore you can build your own application using anything you want. The uGFXnet protocol can be found in /drivers/multiple/uGFXnet/uGFXnetProtocol.h. This is the current protocol:
#define GNETCODE_INIT 0xFFFF // Followed by version,width,height,pixelformat,hasmouse #define GNETCODE_FLUSH 0x0000 // No following data #define GNETCODE_PIXEL 0x0001 // Followed by x,y,color #define GNETCODE_FILL 0x0002 // Followed by x,y,cx,cy,color #define GNETCODE_BLIT 0x0003 // Followed by x,y,cx,cy,bits #define GNETCODE_READ 0x0004 // Followed by x,y - Response is GNETCODE_READ,color #define GNETCODE_SCROLL 0x0005 // Followed by x,y,cx,cy,lines #define GNETCODE_CONTROL 0x0006 // Followed by what,data - Response is GNETCODE_CONTROL,0x0000 (fail) or GNETCODE_CONTROL,0x0001 (success) #define GNETCODE_MOUSE_X 0x0007 // This is only ever received - never sent. Response is GNETCODE_MOUSE_X,x #define GNETCODE_MOUSE_Y 0x0008 // This is only ever received - never sent. Response is GNETCODE_MOUSE_Y,y #define GNETCODE_MOUSE_B 0x0009 // This is only ever received - never sent. Response is GNETCODE_MOUSE_B,buttons. #define GNETCODE_KILL 0xFFFE // This is only ever received - never sent. Response is GNETCODE_KILL,retcode
