Serial (SPE) Extended

Description

Workshop5 is a comprehensive software from 4D Systems providing a code and graphics editor for 4D Systems' programmable display modules.

It can be used to design graphical interfaces for all sorts of applications using the IDE's various widgets. All application code can also be developed within the Workshop5 IDE, easily coupling it with the design, so is a one-stop shop for development with these modules.

The Workshop5 IDE utilises Arduili CLI tool to handle the compiling of Arduino-compatible projects.

This manual is dedicated to explaining the setup required to run Workshop5 IDE and develop applications for applicable display modules and Arduino compatible boards.

An overview of its basic functionality and uses will be explored. To use the Serial (SPE) Extended, the following items are required:

• Any 4D Systems Display Module which uses a 4D Labs processor
  • DIABLO16
  • PICASO
  • PIXXI44
  • PIXXI28
• 4D Programming Cable or Adaptor
• Arduino-compatible module
• A micro-SD memory card
• Workshop5 IDE

Note

Workshop5 Serial (SPE) Extended is identical to Workshop4 Arduino Extended.

Development Setup

This section describes how to set up Workshop5 for developing applications for 4D Systems' SPE-compatible display modules and an Arduino-compatible board.

Unlike Workshop4, Workshop5 doesn't require Arduino IDE to be installed alongside. Only Workshop5 itself is required, the installer can be downloaded here

To install Workshop5, please refer to the Installation section of the Workshop5 User Manual.

Note

Workshop5 is a Windows-only application.

Application Overview

It is often difficult to design a graphical display without being able to see the immediate results of the application code. Serial (SPE) Extended is a perfect software tool that allows the user to see the instant results of their desired graphical layout.

Additionally, there is a selection of inbuilt dials, gauges and meters that can simply be dragged and dropped onto the simulated module display. From here, each can have properties edited and at the click of a button, all relevant code is produced in the user program. Each feature of Serial (SPE) Extended will be outlined with examples below.

Setup Procedure

To install the Workshop5 IDE, follow the instruction on Workshop5 IDE User Manual

Development Roadmap

After having completed the setup procedure, we are now ready to create and develop a project.

This section discusses the overall development process including uploading SPE to the display module, graphics design, writing code and uploading to the Arduino-compatible module.

Launch Workshop5

There is an alias for 4D Workshop5 IDE on the desktop.

Launch 4D Workshop5 IDE by double-clicking on the icon.

Workshop5 will download the required Arduino board packages and Serial (SPE) libraries the first time it runs. This process can take time but after successfully completing it, the next time would be much shorter.

Create a New Project

At launch, Workshop5 IDE will display the Setup Window which defaults to Recent tab when there are recent projects available or to Create tab when there are no recent projects.

If in the Recents view, click the CREATE button.

Display Selection

There are two (2) options that can be use to select the target display.

1. Use the Search for products text box.
2. Use the slider or the mouse wheel.

Click the filter button and select the processor of the target display.

After finding the target display, follow the steps below to proceed.

1. Select target display.
2. Click the display image to select the desired display orientation.
3. Click the Confirm.

Select Serial (SPE) Extended

The next page will ask the environment to develop the project. To select the Serial (SPE) Extended environment click the ViSi and click confirm.

The development environment is now displayed.

The Main Screen

Let's discuss the different areas of the Serial (SPE) Extended environment. There are seven (7) different areas, from left to right, from top to bottom.

1. Menus
2. Ribbons with icons
3. Code Editor
4. Graphics Toolbar
5. Visual Editor
6. Object Properties
7. Message Window

Area 1: Ribbon Tabs

The ribbon menu tabs groups related options together and displays the applicable buttons/options accordingly.

For the extended environment, the ribbon tabs are:

• Home - contains the most common code and graphics editing options
• Graphics - provides a selection of widgets that can be added to the project
• Display Tools - includes tools related to the use of the display module, including a way to load SPE.
• Arduino Tools - includes tools related to the communication between the PC and the Arduino module
• Project - allows changing the target display and Arduino module and modify SPE settings

Area 2: Ribbon Menu Buttons

Buttons are grouped with closely related commands.

As shown, the ribbons on the Home menu are grouped as project, code editor, bookmarks, find and replace, code folding and compile.

Area 3: Code Editor

The code editor has two (2) open tab, Main and Generated.

The Main tab is where to write the Arduino code. It has initial lines of codes which are necessary for the project.

The Generated tab is a read-only Arduino H file that are generated based on project contents and settings.

Area 4: Graphics Toolbar

The graphics toolbar provides buttons for managing widgets.

From left to right, the toolbar items are described in the table below.

Item	Description
Load Widget	Opens the Select Widget window.
Save Widget	Opens the Save Widget window.
Copy Widget	Copies the selected widget for pasting.
Cut Widget	Copies the selected widget for moving to another page.
Paste Widget	Pastes the recently copied widget.
Delete Widget	Deletes the selected widget.
Load Form	Opens the Load Form window.
Save Form	Opens the Save Form window.
Delete Form	Deletes the selected form.

Area 5: Visual Editor

The visual editor represents a What-You-See-Is-What-You-Get (WYSIWYG) area.

The active form is displayed and can be populated by objects from the object selection window.

Area 6: Object Properties

Object properties provides all the information of the selected object. Each object has their own properties that can be set on this area before pasting it on the code editor.

You can use the paste code button to paste the code of the selected object.

Area 7: Message Area

The message area displays errors, warnings and notices after the project was compiled and build.

Designing a Graphical Interface

The Workshop5 IDE provides a simple method for creating graphical user interfaces for 4D Systems display modules. It provides easy-to-use visual editor with support for multiple types of widgets including buttons, sliders, knobs and gauges.

Object Selection

Below are the steps in selecting and putting the objects into the visual editor.

1. To begin, click on the Widgets tab and select the object to open the Widget Selection window.

   

2. The widget selection window is open.

   

3. Navigate to each widgets pane to select an object. Then click the Confirm button to put the object into the Visual Editor.

   

   Note

   Widgets are filtered according to the selected processor.

4. The object will be shown on the top left of the visual editor.

   

Object Properties Configuration

Once the object was added to the visual editor, use the object properties to configure the object. Set the position, dimension, appearrance and other properties that neeeded for the project.

To add more objects, just repeat the steps in Object Selection and Object Properties Configuration.

Changing Between Object Properties

If there are multiple graphical objects on the screen, it may be necessary to change between object properties. Do this by using the dropdown box located at the top of the Object Inspector. Alternatively, each object can be edited by clicking on the object in the module display area.

Writing the Code

Once done in designing the graphical interface, let's now go to the code editor to write the code that we want for our program.

Main Tab

In the code edior Main tab contains initial code for including files, libraries and initial setup for the display orientation.

The SetupDisplay() function should be uncommented to initialize the display. This function is defined on the GeneratedConsts.h file and serves as a basic for Serial UART, display and media initialization.

Note

Advanced users can use their own custom Setup function or write directly in setup(). This may be useful when initializing custom TX and RX pins or SoftwareSerial in applicable Arduino modules.

Generated Tab

On the Generated tab, is a read-only file which is generated automatically during the designing of the user interface. This file defines all the widgets or object that is use on the graphical interface and functions needed on the main file.

This file GeneratedConsts.h is automatically included into the main file.

Generating Widget Code

Workshop5 is primarily designed for products powered by 4D graphics processors: PIXXI-44, PIXXI-28, DIABLO-16, and PICASO. It provides multiple environments for developers allowing different level of expertise, from no coding at all to writing code from scratch.

Workshop5's Serial (SPE) Extended environment provides the most versatility by allowing users to write their own Arduino code while providing a graphics editor. Furthermore, it provides a simple Paste Code utility that generates code for each widget used in the project with a click of a button.

This option generates code to update or show widgets at the current cursor position, or more appropriate location or multiple locations in the project.

The following is a list of common code snippets Workshop5 generate for a target Workshop5 object.

1. Enabling touch - the function Display.img_ClearAttributes() enable the widgets touch. This only needs to run once. This line s only available on widgets with touch capabilities.
2. Show widget initially - the function Display.img_Show() will show widgets with its initial value.
3. Update widget value - the function Display.img_SetWord() will update the value of the widget.
4. Show updated widget - the function Display.img_Show() will be called again to show the updated value of the widget.

Here is an example of a single form project containing a slider and a gauge.

The generated code is as shown.

#include "GeneratedConsts.h" // do not remove or edit this line

// routine to handle Serial errors
void user_callback(int ErrCode, unsigned char Errorbyte) {
#ifdef LOG_MESSAGES
    const char *Error4DText[] = { "OK\0", "Timeout\0", "NAK\0", "Length\0", "Invalid\0" };
    LOG_MESSAGES.print(F("Serial 4D Library reports error "));
    LOG_MESSAGES.print(Error4DText[ErrCode]);

    if (ErrCode == Err4D_NAK) {
        LOG_MESSAGES.print(F(" returned data= ")) ;
        LOG_MESSAGES.println(Errorbyte) ;
    } else {
        LOG_MESSAGES.println(F("")) ;
    }

    while (true); // you can return here, or you can loop
#endif
}

void setup() {

    SetupDisplay(); // generated helper function for basic initialization
    // Display.Callback4D = user_callback; // uncomment to use custom callback / error handler

    // set to enable touch, only need to do this once
    Display.img_ClearAttributes(hndl, iSliderA0, I_TOUCH_DISABLE);
    Display.img_Show(hndl, iSliderA0); // show SliderA0, only do this once

    Display.img_Show(hndl, iGaugeB0); // show GaugeB0, only do this once

    Display.touch_Set(TOUCH_ENABLE);

    // put your setup code here, to run once:
}

void loop () {

    // put your main code here, to run repeatedly:
    word state, n, x, y, posn;

    state = Display.touch_Get(TOUCH_STATUS);
    n = Display.img_Touched(hndl, -1);

    if (state == TOUCH_PRESSED) {
        x = Display.touch_Get(TOUCH_GETX);
        y = Display.touch_Get(TOUCH_GETY);
    }

    if (state == TOUCH_RELEASED) {
        x = Display.touch_Get(TOUCH_GETX);
        y = Display.touch_Get(TOUCH_GETY);
    }

    if (state == TOUCH_MOVING) { 
        x = Display.touch_Get(TOUCH_GETX);
        y = Display.touch_Get(TOUCH_GETY);

        if (n == iSliderA0) {
            // 'posn' and 'x' must be declared if not already
            // 'posn' - value of the widget
            // 'x' - horizontal touch position
            posn = x - 30;                        // x - left - offset
            if (posn < 0) {
                posn = 0;
            } else if (posn > 190) {                  // width - offset2
                posn = 100;                       // range
            } else {
                posn = 100 * posn / 190 ;          // range * posn / (width - offset2)
            }

            Display.img_SetWord(hndl, iSliderA0, IMAGE_INDEX, posn);
            Display.img_Show(hndl, iSliderA0); // where posn is 0 to 100

            Display.img_SetWord(hndl, iGaugeB0, IMAGE_INDEX, posn);
            Display.img_Show(hndl, iGaugeB0); // where value is 0 to 100
        }
    }
}

To learn more about the functions use for the above project, please refer to Diablo16 Serial (SPE) Command Set.

Programming the Display with Serial (SPE)

Before uploading the Extended project to an Arduino compatible module, it is required that the display is running SPE application.

Note

The SPE application comes pre-loaded out of the box which allows the display to be used without an IDE.

Connecting the Module

To connect the target display, please refer to the Workshop5 User Manual - Hardware Setup.

Once the target display is connected, the user can now go to the Display Tools tab to check if the target display is connected. The Blue lights indicates that the display is properly connected.

Refer to the Workshop5 User Manual - Connect the Module for other light colors.

Uploading SPE Application

After verifying that the display is connected, click the SPE Load button

Programing the Arduino-compatible Module

After completing the desired user interface and writing code. It is time to upload the project to the Arduino-compatible module.

Compile and Upload

Verify that the Arduino module is connected. The Arduino Tools provides similar layout to that of the Display Tools.

To scan the selected port, simply click the LED button.

Note

Some Arduino boards may not be identified and some may be identified as multiple possible boards. In both cases, it's up to the user to ensure that the COM port is correct.

After verifying that the Arduino module is connected, go back to Home tab and click the Compile & Upload button.

MicroSD Card

When prompted to copy files to microSD card, proceed with the copy for the first load or when new GCI widgets or fonts are added to the project, as well as when GCI widgets are moved across the WYSIWYG editor.

For PICASO, PIXXI28, PIXX44, and DIABLO16, the microSD card shall be FAT16-formatted. Partition can't exceed 4 GB.

To connect the micro-SD card, either

• Insert the micro-SD card into the USB adaptor and plug the USB adaptor into a USB port of the PC

Or

• Insert the micro-SD card into a micro-SD to SD card converter and plug the SD card converter into the SD card slot of the PC.

Check the micro-SD card is mounted, here as drive E:.

Testing the Serial (SPE) Application

To test a Serial (SPE) programmed display, Workshop5 provides the Serial Commander tool which provides a way to send commonly used SPE commands and the Terminal tool which allows sending of any hex string.

Select the Display Tools menu. This menu will provide both Serial Commander and Terminal tools.

Clicking the Serial Commander will open the window:

This tool provides common SPE commands related to 'gfx', 'txt', 'media' etc. as shown in the tabs.

Note

Pixxi28 and Pixxi44 processors share the same Serial Commander as Picaso.

Alternatively, you can use the Terminal tool to manually send commands or those that are not commonly used and not supported by the Serial Commander.

Note

See section Testing the Arduino Application regarding how to use this tool.

Testing the Arduino Application

To test a Arduino application, Workshop5 provides the Terminal tool which provides a way to send and receive data to the Arduino.

Select the Arduino Tools menu. This menu will provide the Terminal tool.

• Click Terminal connect 9600 to open the currently selected com port at 9600 baud in the Terminal program.
• Click Terminal connect 115200 to open the currently selected com port at 115200 baud in the Terminal program.

To send the commands on hexadecimal format, press

The commands sent by the Arduino and the messages sent by the screen are as shown. The white area on the right displays:

• In green the messages sent to the screen;
• And in red the messages received from the screen

Application Notes

For a more detailed presentation of the objects with examples, please refer to the Application Notes page.

Under Environments choose Serial (SPE)

All related application notes will now appear in the search results.

Note

Workshop5 Serial (SPE) Extended utilizes SPE and therefore application notes written for Workshop4 Serial, Arduino Basic and Arduino Extended Graphics environments is also applicable to Workshop5 with minor differences.

Revision History

Document Revision

Revision Number	Date	Content
1.0	06/02/2024	Initial Release