using an arduino host - 4d...

APPLIC

ATI

ON N

OTE

Application Note: 4D-AN-P4019

ViSi-Genie A Simple Digital Voltmeter Application using an Arduino Host

Document Date: July 31st, 2013

Document Revision: 1.0

4D SYSTEMS 4D-AN-P4019

© 2012 4D Systems of 35 www.4dsystems.com.au

Description

This application note explains how to use a 4D display module in displaying

voltage readings received from a host controller. The host is an AVR-

ATmega328-microcontroller-based Arduino Uno board. The host can also be

an Arduino Mega 2560. Ideally, the application described in this document

should work with any Arduino board that tolerates an analog input voltage

value from 0 to 5 volts and with at least one UART serial port. See

specifications of Aduino boards here.

NOTE: Some Arduino boards such as the Due operate at 3.3 volts and

tolerate analog input voltage levels from ground up to 3.3 V only. Applying

more than 3.3 V may damage the chip. If attempting to use 3.3V Arduino

boards for this application, make sure to limit the analog input voltage to

3.3 volts only and please read carefully your board’s datasheet.

Before getting started, the following are required:

Any of the following 4D Picaso display modules:

uLCD-24PTU

uLCD-28PTU

uLCD-32PTU

uLCD-32WPTU

uLCD-43(P/PT/PCT)

uVGA-III

other superseded modules which support the ViSi Genie

environment

4D Programming Cable or µUSB-PA5

micro-SD (µSD) memory card

Workshop 4 IDE (installed according to the installation

document)

Any 5-volt-tolerant Arduino board with a UART serial port

4D Arduino Adaptor Shield (optional) or connecting wires

Arduino IDE

10-kilo-ohm trimmer potentiometer

Breadboard

The user has completed the project described in 4D-AN-P4017-

ViSi-Genie Connecting a 4D Display to an Arduino Host or has an

understanding of how an Arduino host communicates with a 4D

display

http://arduino.cc/en/Products.Compare

http://arduino.cc/en/Products.Compare

http://www.4dsystems.com.au/product/1/7/4D_Intelligent_Display_Modules/uLCD_24PTU/



http://www.4dsystems.com.au/product/1/10/4D_Intelligent_Display_Modules/uLCD_32WPTU/

http://www.4dsystems.com.au/product/1/11/4D_Intelligent_Display_Modules/uLCD_43/

http://www.4dsystems.com.au/product/1/124/4D_Intelligent_Display_Modules/uVGA_III/

http://www.4dsystems.com.au/product/17/114/Accessories/4D-Programming-Cable/

http://www.4dsystems.com.au/product/17/115/Accessories/uUSB-PA5/

http://www.4dsystems.com.au/product/10/120/Development/4D_Workshop_4_IDE/

http://arduino.cc/en/Main/Software

http://www.4dsystems.com.au/appnotes/




Content

Description ............................................................................................. 2

Content................................................................................................... 3

Application Overview .............................................................................. 4

Setup Procedure ..................................................................................... 5

Load the Example ................................................................................... 5

Create a New Project ............................................................................... 6

Create a New Project ............................................................................. 6

Select ViSi Genie ..................................................................................... 8

Design the Application ............................................................................ 8

Create a LED Digits Object...................................................................... 9

Naming of Objects................................................................................ 11

Add a Static Text .................................................................................. 11

Add an Angular Meter .......................................................................... 12

Add a Rocker Switch ............................................................................. 14

Build and Upload the Project ................................................................. 15

How to Save the Program .................................................................... 15

Connect the Display Module ................................................................ 15

Insert the µSD Card to the PC ............................................................... 18

Program Destination ............................................................................ 19

Compile and Download ........................................................................ 19

Insert the µSD Card to the Display Module........................................... 20

Writing the Host Code ........................................................................... 21

Download and Install the ViSi-Genie-Arduino Library .......................... 21

Understanding the GenieTemperature Sketch Demo ........................... 22

Open a Serial Port and Set the Baud Rate 22

Reset the Arduino Host and the Display 24

The Main Loop - Writing Data to the Display 24

The Main Loop – Interrogating the Display 25

The Main Loop – Receiving Data from the Display 25

The User’s Event Handler 25

Set Up the Project ................................................................................. 27

Using the New 4D Arduino Adaptor Shield (Rev 2.00) .......................... 27

Using the Old 4D Arduino Adaptor Shield (Rev 1) ................................. 30

Connection Using Jumper Wires ........................................................... 30

Connect the Trimmer Potentiometer to the Arduino ............................ 31

The Complete Project ........................................................................... 32

Proprietary Information ........................................................................ 35

Disclaimer of Warranties & Limitation of Liability .................................. 35



Application Overview

The application developed in this document works in a manner illustrated in

the diagram shown to the right. First, the wiper of a trimmer potentiometer,

acting as a voltage divider, is connected to pin A0 of the Arduino Uno.

Thus, the voltage level at pin A0 can be of any value between 0 and 5 volts.

Thru ADC, an analog voltage level sampled by pin A0 is given a 10-bit binary

equivalent value. Given the reference voltage, which is 5 volts by default,

the digital voltage value can now be computed. The digital voltage reading

is then sent to the display module. Note that the default range of allowable

analog input voltage for the Uno and Mega 2560 is 0 to 5 volts only.

The Arduino host is programmed in the Arduino IDE to perform ADC and

send the voltage readings to the display module. The display module, on the

other hand, is programmed in Workshop (ViSi Genie environment) to display

the voltage readings.

This application note comes with a ViSi Genie program and an Arduino

sketch. The process of creating the ViSi Genie program is first shown. Then

the flow of the Arduino sketch is discussed. The sketch can be used to

develop more complex applications related to ADC. The last section shows

how the display module, Arduino host, and trimmer potentiometer are

connected.

Trimmer potentiometer

Arduino host

Genie objects

0 to 5 volts

Analog voltage

message

Trimmer

potentiometer acts

as a voltage divider

Digital voltage values are

computed and sent to the

display module

The display module

receives and displays the

voltage readings.

Analog voltage

levels are sampled

and given 10-bit

binary equivalent

values



Setup Procedure

Load the Example

Workshop 4 opens and displays the Recent page.

To load the existing project, click on Open.

A standard open window asks for a ViSi-Genie project.

Now, check the type of the screen module by selecting the Project menu.



If using a different display module, change the target display module by

clicking on the display button.

The Change Display window appears.

Select the screen on the drop-down list and define the orientation.

…and confirm by clicking on .

Create a New Project

Create a New Project

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.

These options update the main window with the selection of the screen.

Select the appropriate screen and preferred orientation. The screen used in this example is the uLCD-32PWTU (landscape reversed orientation).



Select ViSi Genie

Design the Application

Everything is now ready to start designing the project. Workshop 4 displays

an empty screen, called Form0. A form is like a page on the screen. The form

can contain widgets or objects, like sliders, displays or keyboards. Below is

an empty form.

At the end of this section, the user will able to create a form with four

objects. The final form will look like as shown below, with the labels

excluded.



Create a LED Digits Object

The LED digits object will display values received from the Arduino host. To

add a LED digits object, go to the Digits pane and select the first icon.

Click on the WYSIWYG (What-You-See-Is-What-You-Get) screen to place a

LED digits object. The WYSIWYG screen simulates the actual appearance of

the display module screen.

The object can be dragged to any desired location and resized to the desired

dimensions. The Object Inspector on the right part of the screen displays all

the properties of the newly created LED digits object named Leddigits0.

Static text

LED digits

Angular meter

Rocker

switch



Feel free to experiment with the different properties. To know more about

digital display objects, refer to 4D-AN-P4012-ViSi-Genie-Digital-Displays.

The LED digits object in this example has the following properties.

Apply the properties. The WYSIWYG screen is updated.

The object has four digits, three of which are to the left of the decimal

point. The object is positioned near the bottom of the screen.




Naming of Objects

Naming is important to differentiate between objects of the same kind. For

instance, suppose the user adds another LED digits object to the WYSIWYG

screen. This object will be given the name Leddigits1 – it being the second

LED digits in the program. The third LED digits object will be given the name

Leddigits2, and so on. An object’s name therefore identifies the object’s kind

and unique index number. It has an ID (or type) and an index.

Coolgauge0

It is important to take note of an object’s ID and index. When programming

in the Arduino IDE, an object’s status can be polled or changed if its ID and

index are known. The process of doing this will be shown later.

Add a Static Text

Static text objects are useful for labelling purposes. As the name implies, the

status of these objects cannot be changed when the program runs. To add

a static text, go to the Lables pane and click on the static text icon.

Click on the WYSIWYG screen to place the object.

In the Object Inspector, change the caption to volts, and increase the font

size. The static text object used in this example has the following properties.

Object index Object ID



When done, the WYSIWYG screen should look similar to the one shown

below.

Add an Angular Meter

To demonstrate the use of meters and to give the application an “analog

touch”, an angular meter will be added to the screen. Go to the gauges pane

and click on the angular meter icon.

Click on the WYSIWYG screen to add the object.



The object can be dragged to any desired location and resized to the desired

dimensions. The angular meter used in this example has the following

properties.

Take note of the decimals, maximum, and minimum values. When done,

the form will look like the image shown to the right.

To know more about meters and gauges, read 4D-AN-P4008-ViSi-Genie-

Gauges.





Add a Rocker Switch

To demonstrate the use of an input widget and to make the application

more interactive, a rocker switch will be added as a means to turn on and

off the voltmeter. When the rocker switch is off, the angular meter and LED

digits objects will display zero volts. This makes the application appear to be

turned off. To add a rocker switch, go to the inputs pane and click on the

rocker switch icon.

Click on the WYSIWYG screen to place the object.

The rocker switch used in this example has the following properties.

The user may need to move the static text object. The final form is shown

below.



To know more about inputs and switches, read 4D-AN-P4009-ViSi-Genie-

Inputs.

Build and Upload the Project

How to Save the Program

Save the program with the desired file name first.

Connect the Display Module

Connect the display module to the PC using a 4D USB Programming Cable or

a µUSB-PA5 programming adaptor.

Note: Before using the 4D Programming Cable or the µUSB-PA5 adaptor, the

drivers need to be installed first. Click any of the hyperlinks to go to the

product page. Follow the instructions on the page for installing the drivers.



http://www.4dsystems.com.au/product/17/114/Accessories/4D-Programming-Cable/

http://www.4dsystems.com.au/product/17/115/Accessories/uUSB-PA5/



Check the orientation.

4D USB Programming

Cable or a 5-way cable

connected to a µUSB-PA5



Setup using a µUSB-PA5:

Check the orientation.

Complete setup:

Go to the Comms menu to check if the module is detected.

Above the Comms section, the violet light mentions no module is currently

connected.

USB to miniUSB cable

connected to the PC

µUSB-PA5

programming

adaptor

5-way cable

going to the

display module



With the display module connected to the 4D USB programming cable (or

µUSB-PA5), plug the cable into the USB port. Click on the drop-down list and

select the COM port allocated to the cable. The product pages for the

programming cable and µUSB-PA5 have instructions on how to determine

the allocated COM port.

The light turns yellow while the connection is being established:

Finally, the light goes blue when the connection is established.

The light turns red when no module is attached to the selected port:

Insert the µSD Card to the PC

For Picaso display modules, a µSD card shall be FAT16-formatted, and

partition can't exceed 4 GB.

Insert the µSD card into the USB adaptor and plug the USB adaptor into a

USB port of the PC.

To PC

C



OR insert the µSD card into a µSD to SD card converter and plug the SD

card converter into the SD card slot of the PC.

Check if the µSD card is mounted, here it is mounted as drive E:

Program Destination

Choose how the project is going to be uploaded to the module. Select the

Project menu and click on Flash as the destination.

Compile and Download

After making sure that the device is detected, go to the Home menu and

click on the Comp n’Load button.

Workshop now builds and downloads the program to the display module.

Workshop will prompt the user for the µSD card. Select the drive on the

drop down list then click on OK.

To PC



A progress bar is displayed while the necessary files are being copied to the

µSD card. Workshop copies two files to the µSD card –the GCI and the DAT

files. The GCI file contains the graphics and the DAT file contains a list of the

objects inside the GCI file. These files will be accessed by the program when

the display module is turned on.

Now Workshop downloads the program to the flash memory of the display

module.

Finally, the message box displays the code size and confirms that the

download to the flash memory has been successful.

Insert the µSD Card to the Display Module

Properly disconnect the µSD card from the PC and plug it to the µSD Card

slot of the display module. The project now starts and runs on the screen.



Writing the Host Code

This section discusses how to program the Arduino host to make it work with

the display module. It is assumed that the user has a basic understanding of

how the Arduino host works and how to program in the Arduino IDE.

Inexperienced users may need to frequently refer to the Arduino website

for more information.

Download and Install the ViSi-Genie-Arduino Library

The ViSi-Genie-Arduino library files are located here:

https://github.com/4dsystems/ViSi-Genie-Arduino-Library

On the right side of the github page, click on the Download ZIP button. Save

the zip file and extract its contents to the folder where additional Arduino

libraries are saved.

Here is a link to a tutorial on installing additional libraries in the Arduino IDE.

http://arduino.cc/en/Guide/Libraries

In Windows for example, the library files will be saved here:

Remember to restart the Arduino IDE after installing the libraries. As a

quick test, the genieArduino demo sketch should be accessible under the

File – Examples menu.

C

https://github.com/4dsystems/ViSi-Genie-Arduino-Library

http://arduino.cc/en/Guide/Libraries



Understanding the GenieTemperature Sketch Demo

Open the genieArduinoVoltmeter sketch attached to this document. Note

that comments have been added to the code. Additional explanations are

now given below.

Open a Serial Port and Set the Baud Rate

In the setup () function a group of lines allows the user to choose the

serial port and the baud rate to be used in talking to the display.

By default, the first line is uncommented which means that the Arduino host

uses port Serial0 to communicate with the display module. The command

therefore, opens port Serial0 for communication with the 4D display module

at 9600 bps. Logically, the 4D display should also communicate with the

Arduino host at the same baud rate. To check the baud rate of the ViSi Genie

program go to the project menu in Workshop.

C



To change the baud rate of the ViSi Genie program, simply click on the drop

down arrow.

Choose the desired baud rate (115200 bps for instance) and download the

program to the display module again. Now change the baud rate of the

Arduino host as well.

For Arduino boards with four hardware serial ports (like the Mega 2560), the

user can choose another port to talk to the display by uncommenting the

corresponding line. To use Serial2 at 9600 bps for example:

N.B.: Again, remember that the baud rate of the display module should

match that of the Arduino host.



Reset the Arduino Host and the Display

It is sometimes necessary to reset the Arduino host and the display module.

To make resetting more convenient, the code below resets the display

module when the program is restarted.

If using the new 4D Arduino Adaptor Shield (Rev 2)

Note that the GPIO pin D4 of the Arduino host is used here for resetting the

display. When using the new 4D Arduino Adaptor Shield (Rev 2.00 written

on the PCB), simply connect RES to AR in jumper J1. See the section “Set Up

the Project”. If using the old 4D Arduino Adaptor Shield (Rev 1), simply

modify the code above. Use pin 2 instead of pin 4.

If using the old 4D Arduino Adaptor Shield (Rev 1)

If using jumper connecting wires, connect the RESET pin of the display

module to the D4 pin of the Arduino with a 1kohm series resistor in between

(see the section “Set Up the Project”), and modify the code as shown below.

If using jumper wires

Note that the logic state for resetting the display is now 0 instead of 1. This

is because the display module’s RESET pin is directly connected to D4 via a

1kohm resistor. If using a 4D Arduino Adaptor Shield, the display module’s

RESET pin is switched by the D4 pin via a transistor.

The Main Loop - Writing Data to the Display

This and the following sections discuss how the main loop and the user’s

event handler work. It is strongly recommended that the user opens and

analyses the accompanying Arduino sketch while reading this text.

In the main loop, the function below receives and queues the data received

from the display.

Initially, there is no data received from the display since none of the objects

were configured to report an event. The program now evaluates if the

voltmeter is turned on or off.



Since flag is initially set to 0, the following statements are executed.

These lines send or write the value 0 to Leddigits0 and Angularmeter0. The

voltmeter application is “off” in this case.

The Main Loop – Interrogating the Display

After writing the value zero to Leddigits0 and Angularmeter0, the program

executes the command

This command sends a message to the display inquiring for the status of

Rockerswitch0. The display will respond with the appropriate message,

which will be received at the next iteration of the loop. The program now

goes back to the start of the loop.

The Main Loop – Receiving Data from the Display

In the second execution of the main loop, data is received from the display

as a result of the statement

The data or message is received and queued by

Another function (to be written by the user) is needed to process the

received data. This function is the user’s event handler, which was arbitrarily

given the name myGenieEventHandler(). This function is called from

inside the function genieDoEvents().

The User’s Event Handler

The user’s event handler now takes out a message from the events queue

and evaluates it. Hence, the following lines:

C

C

C

C



The message is then tested if it is a REPORT_OBJ event from Rockerswitch0.

This is the expected response of the display to the interrogation message

sent earlier.

If the above condition is true, the value of the event is stored in

rockersw_val.

The value of an object event or message represents that object’s status. For

instance, the message for Rockerswitch0 will have a value of 0 when it is off,

a value of 1 when it is on. This concept is applicable to widgets or objects

having only two states such as the DIP switch (default mode), and the

Winbutton (toggle mode).

Suppose the user has turned on Rockerswitch0 by touch, the statement

below is executed.

The program exits the user’s event handler and goes back to the main loop.

There it processes the block

since flag has just been set to 1.

The line

performs the conversion below.

𝑣𝑜𝑙𝑡𝐿𝐸𝐷 = 𝑠𝑒𝑛𝑠𝑜𝑟𝑃𝑖𝑛 𝑙𝑒𝑣𝑒𝑙𝑠 𝑥 5 𝑣𝑜𝑙𝑡𝑠

1023 𝑙𝑒𝑣𝑒𝑙𝑠 𝑥 1000

The variable voltLED will hold a value between 0 and 5000, which will be sent to Leddigits0.

Remember that Leddigits0 has four digits so it can display 0000 to 5000. Now, since three of the four digits are to the right of the decimal point, it will display 0.000 to 5.000.

ADC resolution of

the Arduino Uno

C



Angularmeter0, on the other hand, is configured to display 0.0 to 5.0. For

more information on writing to Genie objects, refer to 4D-AN-P4018-ViSi-Genie Writing to Genie Objects Using an Arduino Host.

Set Up the Project

This section discusses how to connect the display module and the LM35

temperature sensor to the Arduino host. For the display-module-to-

Arduino-host connection, the user has the option of using a 4D Arduino

Adaptor Shield or simply connecting the Tx0, Rx0, RESET, and GND pins of

the display module to the corresponding pins of the Arduino host.

Using the New 4D Arduino Adaptor Shield (Rev 2.00)





To reset the display using the D4 pin of the Arduino and to power the display

from the Arduino host, set jumpers J1 and J2 as shown below.

By default, jumpers J3 and J4 are configured to connect RX (RX of display

module) to D0 (TX0 of the Arduino) and TX (TX of display module) to D1 (RX0

of the Arduino). To use the other serial ports of the Mega or Due, remove

the jumper connectors of J3 and J4 and connect the display TX and RX pins

to the desired serial port using jumper wires.

Below are images of a complete setup wherein the display module and the

Arduino host have a common power supply. Note that the power supply

must be able to provide enough current for both the display module and the

Arduino host. Refer to the display module’s datasheet for the specified

supply current.

Using the USB cable:

Using the jack:



To power the display using a 4D USB Programming Cable or a µUSB-PA5

Programming Adaptor, set J2 as shown below.

H2 is for the 4D USB Programming Cable or µUSB-PA5 and H1 is for the

display module. Note that the display module cannot be programmed in this

setup since H2 transfers power only. Always disconnect the display module

from the Arduino Adaptor Shield first before programming it. Always check

the orientation of the connectors.

Complete setup:



Using the Old 4D Arduino Adaptor Shield (Rev 1)

Connection Using Jumper Wires



Connect the Trimmer Potentiometer to the Arduino

Schematic for trimmer potentiometer-to-Arduino-Uno connection



Breadboard layout for trimpot- to-Arduino-Uno connection (made with Fritzing)

The Complete Project

The uUSB-PA5 programming adaptor is used here only to power the display.

Set jumper J2 of the new Arduino Adaptor Shield as described in page 29.

The uUSB-PA5

10k-ohm

trim pot



Adjusting the trimmer potentiometer.



Proprietary Information

The information contained in this document is the property of 4D Systems Pty. Ltd. and may be the subject of patents pending or granted, and must not be

copied or disclosed without prior written permission.

4D Systems endeavours to ensure that the information in this document is correct and fairly stated but does not accept liability for any error or omission. The

development of 4D Systems products and services is continuous and published information may not be up to date. It is important to check the current position

with 4D Systems.

All trademarks belong to their respective owners and are recognised and acknowledged.

Disclaimer of Warranties & Limitation of Liability

4D Systems makes no warranty, either expresses or implied with respect to any product, and specifically disclaims all other warranties, including, without

limitation, warranties for merchantability, non-infringement and fitness for any particular purpose.

Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates.

It is your responsibility to ensure that your application meets with your specifications.

In no event shall 4D Systems be liable to the buyer or to any third party for any indirect, incidental, special, consequential, punitive or exemplary damages

(including without limitation lost profits, lost savings, or loss of business opportunity) arising out of or relating to any product or service provided or to be

provided by 4D Systems, or the use or inability to use the same, even if 4D Systems has been advised of the possibility of such damages.

4D Systems products are not fault tolerant nor designed, manufactured or intended for use or resale as on line control equipment in hazardous environments

requiring fail – safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life

support machines or weapons systems in which the failure of the product could lead directly to death, personal injury or severe physical or environmental

damage (‘High Risk Activities’). 4D Systems and its suppliers specifically disclaim any expressed or implied warranty of fitness for High Risk Activities.

Use of 4D Systems’ products and devices in 'High Risk Activities' and in any other application is entirely at the buyer’s risk, and the buyer agrees to defend,

indemnify and hold harmless 4D Systems from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or

otherwise, under any 4D Systems intellectual property rights.

using an arduino host - 4d...

Documents