ArdWidgets - GUI Library for Arduino

ArdWidgets is a processing library that lets you make interactive dashboards that work with an Arduino. It's meant to be very accessible to both beginners with limited processing and arduino experience, as well as useful to advanced users.

You can create dashboards of buttons, sliders, time graphs and other Graphical User Interface (GUI) widgets with as little as one or two lines of processing code. Widgets can directly visualize and control both read and write pins that are either digital (buttons) or analog (sliders). Widgets can display their pins (valuable for debugging), values and ranges. The ArdWidgets library uses the Fermata library to establish the connections between Processing and Arduino.

It's also a relatively simple introduction to both object oriented and windows type UI coding and event handling (see what you think). I've kept the amount of code limited at the expense of tighter control of internal widget parameter access and behavior.

The current implementation is pretty lean graphically, partly in order to make the code legible, editable and instructive. It’s possible to edit the GUI style, colors, etc.

On the Arduino side, upload the StandardFermata library from the examples.
Download the ArdWidgets file and open in processing.

Download and open the ArdWidgets0_10_Basic.pde file and open in Processing.

As with all processing files, there are two key functions: setup() and draw(). You'll need to keep most of the code in the file as is (more on some settings later).

The code used to create the 4 GUIs is in setup():

////////////////////////////// Add Some Widgets //////////////////////////////
myWidgets.add(new ArdWidgetButton(50,50,50,50, INPUT, 12));  
myWidgets.add(new ArdWidgetButton(110,50,50,50, OUTPUT, 11));     
myWidgets.add(new ArdWidgetHSlider(50,150,100,50, INPUT, 0));    
myWidgets.add(new ArdWidgetHSlider(160,150,100,50, OUTPUT, 6));</p>

This code adds an INPUT button on pin 12, an OUTPUT button on pin 11,

a horizontal INPUT HSlider on A0, and another OUTPUT slider on pin ~6.

The basic circuit is as shown; remember to add 10K resistors between the switch pin connector and ground,

and 330 Ohm resistors between the LED ground pin and ground.

In this step we'll go over compound ArdWidgets. The most obvious compound widgets are arrays of similarly typed widgets:

• ArdWidgetButtonArray
• ArdWidgetHSliderArray
• ArdWidgetVSliderArray

In the ArdWidgets0_10_Basic sketch, comment out or delete the previous 4 widgets, and uncomment the lines that follow.

myWidgets.add(new ArdWidgetButtonArray(50, 50, 100, 120,  // the X, Y, Width and Height of the array
new int[] {INPUT, OUTPUT}, 	// the pattern of INPUTS and OUTPUTS
new int [] {5,13,4,12},  // the array of pins
new int[] {2,2}));  // the layout of widgets (#wide, #high)
myWidgets.add(new ArdWidgetHSliderArray(50, 250, 350, 120, 
new int[] {INPUT, OUTPUT}, 
new int [] {2,11,3,10}, 
new int[] {2,2}));

This generates a slightly more complicated panel with (4) buttons and (4) sliders.

Note that in most cases we are providing input parameters as integer arrays.

The number of widgets in a given array is driven by the number of pins provided.

We also need to give an array if INPUT and OUTPUT values, but the size of this array doesn't need to be the same as the number of pins. If the io length is less than the number of pins, the patter will simply repeat. For example, if you only wanted OUTPUT widgets in array, just use this as the ios: new int[] {OUTPUT},

There are a few basic settings for each widget:

• bgcolor - the background color of the widget
• lowcolor - the color for the low value of the widget
• highcolor - the color for the high value of the widget
• displayname - Show (true) or hide (false) the widget's pin
• displayvalue - Show (true) or hide (false) the widget's value
• displayscale - Show (true) or hide (false) the widget's scale (Sliders only)

There are a few ways to set these.

To set the overall defaults for all new widgets, edit the defaults near the beginning of the code:

// Some default behaviors, these MUST be defined, but can be overwritten on individual ArdWidgets. You can change these here:
color ArdDefaultLowColor = color(128,128,128);
color ArdDefaultHighColor = color(0,255,0);
color ArdDefaultINPUTBackgroundColor = color(210,210,210);
color ArdDefaultOUTPUTBackgroundColor = color(255,255,255);
boolean ArdDefaulDisplayname = true;
boolean ArdDefaulDisplayvalue = true;
boolean ArdDefaulDisplayscale = false;

If you want to set an individual widget's values, save the widget in a variable when you create it, then reference the widget's internal parameters:

// Make an INPUT Horizontal Slider on Pin 3
  ArdWidgetHSlider slider3 = new ArdWidgetHSlider (50, 150, 90, 40, INPUT, 0);
  slider3.highcolor = color(0,0,255); 
  slider3.displayscale = true; // add the scale text (show lowval and highval)
  myWidgets.add(slider3);

For widget arrays, it's maybe more convenient to set the global default before creating the widget:

ArdDefaultDisplayvalue = false;  // Turn off the display of the value
myWidgets.add(new ArdWidgetButtonArray(50, 50, 100, 120, new int[] {OUTPUT}, new int [] {13}, new int[] {1,1}));

Here's a sketch with all of the current widgets. You can simply comment out sections of the widget setup if you don't want to use them, or just leave them in (they won't be connected to any arduino behavior if the associated pins aren't wired up, but that's OK unless you want to use the pins for something else).

The full list of current ArdWidgets is:

ArdWidgetButton - creates a Digital INPUT or OUTPUT

ArdWidgetHSlider / ArdWidgetVSlider - creates and Analog INPUT or OUTPUT

(INPUT pins correspond to Analog input A0-A6)

ArdWidgetXY - takes an array of 2 Analog INPUT or OUTPUT pins

ArdWidgetGraph - takes an array of any number of Analog INPUT and OUTPUT pins,

and a corresponding io pattern array of INPUT and OUTPUT values.

The important setup() code that creates these widgets is:

/////////////////////////////// Add Some Widgets //////////////////////////////
  // Now add widgets to the ArdWidgetCollection. Basic signature is ( int x, int y, int w, int h, int anio, int apin):
  // Make an INPUT Button on Pin 2
  // Single line of code creates a new button Widget and adds to the collection.
  myWidgets.add(new ArdWidgetButton (50, 50, 40, 40, INPUT, 2)); 
 // Define an appropriate Widget variable in order to keep the reference and then change colors, display text, etc:
  // Make an OUTPUT Button on Pin 8  
  ArdWidgetButton button2 = new ArdWidgetButton  (100, 50, 40, 40, OUTPUT, 8);
  button2.lowcolor = color(255,0,0);   // set lowcolor to red
  button2.highcolor = color(0,255,0);  // set highcolor to green
  myWidgets.add(button2); 
  //Make an INPUT Horizontal Slider on Pin AO
  ArdWidgetHSlider slider3 = new ArdWidgetHSlider (50, 150, 90, 40, INPUT, 0);
  slider3.highcolor = color(0,0,255); 
  slider3.displayscale = true; // add the scale text (show lowval and highval)
  myWidgets.add(slider3);
  //Make an INPUT Vertical Slider on Pin 9
  // an INPUT widget's backround is grey by default; mouse interactions don't do anything
  ArdWidgetVSlider slider1 = new ArdWidgetVSlider(150, 50, 40, 140, OUTPUT, 9);
  slider1.lowcolor = color(255,0,0); // if lowcolor and highcolor are different, sliders will blend between them.
  slider1.highcolor = color(0,0,255); 
  slider1.displayname = false;  // Don't show the pin name
  myWidgets.add(slider1);
  
  // Note the ArdWidgetXY takes an array of 2 pins!
  ArdWidgetXY xy1 = new ArdWidgetXY (220, 50, 140, 140, OUTPUT, new int [] {10,11}); // Note how we pass the array of (2) pins
  xy1.highcolor = color(0,0,255); 
  xy1.displayscale = true;
  xy1.lowval[Y] = 0; xy1.highval[Y] = 64; // We can set the range to something other 
  // than the default 255 OUTPUT / 2013 INPUT
  myWidgets.add(xy1);
  // The ArdWidgetGraph - includes a dynamically created set of sliders and a time graph
  // Note we provide an array of ios and pins. The count of ios doesn't need to be the same as the pins
   ArdDefaultDisplayscale = true;
   myWidgets.add(new ArdWidgetGraph(50, 250, 310, 150, new int[] {OUTPUT, INPUT}, new int [] {3,2,5}));  
   ArdDefaultDisplayscale = false;
    
  /////////////////////////////////// Done Adding Widgets ////////////////////////////

Here are some overall instructions that can be also be found in the comments of the code:

////////////////////////////////////////////////////////////////////////// Instructions ///////////////////////////////////////////////////////////////////////////////
//
// This is a simple example processing script that allows users to easily create 
// Graphical User Interface (GUI) widgets with simple connections to an arduino.
// It uses the Fermata library to establish the connections between Processing and Arduino.
// It's also a simple introduction to both object oriented and windows type UI coding and event handling.
// The current implementation is pretty lean graphically, partly in order to make the code legible, editable and instructive.
// 
// To use: on the Arduino side upload the StandardFermata code found under Examples->Fermata in the Arduinoi development environment
//
// There are currently (5) types of ArdWidgets:
// - a pushbutton ArdWidgetButton
// - a horizontal and vertical slider ArdWidgetHSlider and ArdWidgetVSlider
// - a two dimensional ArdWidgetXY widget that can drive two arduino pins
// - an extensible ArdWidgetGraph that can take an arbitrary number of INPUTs and OUTPUTs and graph values over time
//
// The ArdWidgetButton is a Digital UI element that reads or drives digital arduino pins
// The ArdWidgetSliders, ArdWidgetXY and ArdWidgetGraph read or drive analog pins and produce analog (0-255 or 0-1023) values
//
// The basic signature of creating a widget is pretty consistent:
// ArdWidgetXXXXXX ( int x, int y, int w, int h, int anio, int apin)
// x, y, w, and h are standard for many processing elements, respectively the X and Y origin of the widget 
// and the Width and Height. 
// These define the rectangular region the widget will take on the canvas
//
// io is either INPUT or OUTPUT. These are the same meaning as for the Arduino
// OUTPUT widgets will write values to output pins (analog or digital). 
// They drive user interaction to phyical outputs on the Arduino 
// INPUT widgets will display the values read from analog or digital pins to Processing; 
// these display but do not respond to mouse interactions
// 
// Finally, apin is the pin number to be read or controlled by the widget. Note that:
//    Digital widgets (ArdWidgetButton) read or write one of the digital pins numbered 0 - 13.
//    Analog OUTPUT widgets must have one of the analog output pins specified, 
//    indicated on the arduino with a ~ (pins ~3,~5,~6,~9,~10,~11)
//    Analog INPUT widgets use the analog input pins, and accept inputs from 0-6. 0 corresponds to pin A0, etc.
//    the ArdWidgetXY and ArdWidgetGraph creation call is different from the others in that they require an array of pins, 
//    and the graphwidget takes an array of ios:
//    ArdWidgetXY ( int x, int y, int w, int h, int anio, int pin, int pin2)
//
// There is also a basic ArdWidgetsCollection class that ArdWidgets are added to and handles messaging, 
// mouse events, etc.
//
// The example setup() routine below shows how to create the different types of INPUT and OUTPUT widgets 
// and add them to Processing.
//
//  Send comments and feedback to dshelden@mit.edu