|Description||This application note shows how to configure a 4D display to act as a serial slave and how to use the Serial Commander (one of the several tools available in Workshop) to send commands to the display. Thru the use of the Serial Commander, the programmer will be acquainted with the Serial Protocol or more specifically the nature and format of the serial commands. This knowledge will then allow the user to properly program any external host controller for the display module.|
This application note explores the possibilities provided by the Serial environment in Workshop for a 4D display to work with an external host controller. In this example, the host is a PC thru the use of the Serial Commander.
Before getting started, the following are required:
and other superseded modules
Visit www.4dsystems.com.au to see the latest products using the Goldelox graphics processor.
- 4D Programming Cable / µUSB-PA5/µUSB-PA5-II
- micro-SD (µSD) memory card
- Workshop 4 IDE (installed according to the installation document)
When downloading an application note, a list of recommended application notes is shown. It is assumed that the user has read or has a working knowledge of the topics presented in these recommended application notes.
The Goldelox processor can be programmed to act as a serial slave device, responding to serial commands received from any host controller. Communication between the slave (the 4D Goldelox display) and the host must follow the Serial Protocol, which defines a set of commands with associated parameters. These commands enable the host controller to make the slave device display primitives, text, and images, play audio and video, and log data to a micro-SD card in the simplest manner available. For more information on the Serial Protocol, refer to the Goldelox Serial Command Set Reference Manual.
This application note shows how to configure a 4D display to act as a serial slave and how to use the Serial Commander (one of the several tools available in Workshop) to send commands to the display. Thru the use of the Serial Commander, the programmer will be acquainted with the Serial Protocol or more specifically the nature and format of the serial commands. This knowledge will then allow the user to properly program any external host controller for the display module.
There is a shortcut for Workshop 4 on the desktop. Launch Workshop 4 by double-clicking on the icon.
Workshop 4 opens and displays the Recent page.
To create a new project, there are two options.
Click on the top left-most icon, New.
Or Click on the icon beside Create a new Project.
The Choose-Your-Product window appears.
Select the appropriate screen and preferred orientation. The screen used in this example is the uOLED-128-G2 (Portrait orientation).
A new Serial project opens and displays some information.
Connect the display module to the PC using a 4D USB Programming Cable or a µUSB-PA5 programming adaptor. Go to the Comms menu to check if the module is detected. The light goes blue when the connection is established. Below is an example of how the Comms tab will look like if a uOLED-128-G2 is connected to the PC.
If not familiar with how to actually connect a 4D display to the PC using a 4D USB programming cable or a uUSB-PA5 and with how to update the firmware, the user should consult the document:
Under the Tools menu, click on the SPE Load icon
The application is now downloaded to the display module.
The SPE splash screen should now be shown on the display module.
The default baud rate is 9600 and the latest firmware is loaded on to the display. To learn how to modify the default settings, refer to Section 2.2 (Additional Configuration Parameters for Serial Communication) of the Goldelox Serial Command Set Reference Manual.
The Serial Commander icon is found under the Tools menu in Workshop. Note that the Serial Commander is available in the Serial environment only.
The Serial Commander window appears.
Note how the commands are categorized. These commands are documented in the Goldelox Serial Command Set Reference Manual.
The Serial Protocol is made up of commands and parameters that are sent over the Serial Port in byte format to the display module. Each command is unique and has a specific set of parameters associated with it. Some commands expect a response from the display module (e.g., when the host is trying to detect the model of the display module). Some commands do not require a specific response (e.g., the command for clearing the screen). For the latter type, the display module will reply with an acknowledgement once the command is successfully executed. For commands that require a specific response, the display module may reply with a varying number of bytes, depending on the command and what the response is. Each command sent to the display will require a certain amount of time before the response is returned. This depends on the command and the operation that has to be performed. Commands should only be sent and their response received, before another command is sent. If two commands are sent before the first response is received, incorrect operation may follow.
The following sections will now demonstrate the use of some serial commands.
The display module is going to receive and send messages to the host. This section explains to the user how to interpret these messages. An understanding of this section is necessary for the user to be able to properly program the host controller. The Goldelox Serial Command Set Reference Manual is recommended for advanced users.
In the Serial Commander window, click on the Gfx (or Graphics) tab and select gfx_Cls.
Click on the send button.
The display module is now cleared.
Also, messages are sent to and received from the display module. The value inside the brackets is the message sent to the display module. The value inside the parentheses is the message received from the display module.
The equivalent byte values for the gfx_Cls command are 0xFF (MSB) and 0xD7 (LSB). The display module responds with an acknowledgment (ACK) after 0.073 seconds. The byte value for ACK is 0x06 and is not shown.
For more information on the gfx_Cls command, refer to section 5.2.1 Clear Screen of the Goldelox Serial Command Set Reference Manual.
The screen of a uOLED-128-G2 will scroll by default. To disable scrolling, select SSTimeout under the tab “Other”, as shown below.
Note that the box at the bottom shows 0 (ms). Click on the Send button.
The screen should now stop scrolling. The message area displays the messages sent to and received from the display module.
The format for the SSTimeout command is defined in section 5.9.4 Screen Saver Timeout of the Goldelox Serial Command Set Reference Manual.
To illustrate the use of commands that require a specific response from the display module, the command sys_GetModel will now be sent. Under the tab “Other”, select sys_GetModel as shown below.
At the bottom part of the serial commander window click on the Send button.
The message area displays the following.
Section 5.9.1 Get Display Model of the Goldelox Serial Command Set Reference Manual gives the following information.
Another example of a command that contains a specific set of parameters is the command putstr. Under the tab “Other” select putstr.
Input the string “Hello World” into the InString box.
Click on the Send button.
The string “Hello World” should now be printed on the screen.
The message area displays the following.
The putstr command is sent with the user-defined string as the parameter. Refer to section 5.1.3 Put String of the Goldelox Serial Command Set Reference Manual for more information. Experimentation with the different commands using the Serial Commander is now left to the user as an exercise. The user may use the Goldelox Serial Command Set Reference Manual as a reference.