Note: This article is out of date but archived here for future reference.
You can find the current version here.

Today we present a basic-function Arduino library for Peggy 2.0.

This brings Peggy 2.0 up to the level of having useful compatibility with the Arduino software environment: you can use high-level commands to control what shows up on the Peggy display. For example, the type of high-level command might be something of the form “Peggy_SetPoint(x, y)” which would turn on the LED located at position (x,y) in the grid.

As we have discussed earlier, Peggy 2.0 is Arduino compatible in the sense that supports programming through a USB-TTL cable, using the popular Arduino software environment.

Note 1: You can also program Peggy 2.0 in the Arduino environment without the USB-TTL cable if you have an AVR ISP compatible programmer like the USBtinyISP. See this note on how to make that work.

Note 2: Peggy also still supports programming with an AVR ISP interface using the GNU AVR toolchain; please see the original article about programming Peggy 2.0 if you are using that approach.

First things first: This is not (by any stretch) intended as a full Arduino tutorial; there are plenty of very good examples out there already, and other lists of resources to point you in the right direction. Still, if you have done some programming, this may well be enough of a guide to get you up and running.

Let’s get started.

Hardware:

1. A Peggy 2.0, built and working, with at least some LEDs in it.

• A USB-TTL cable. (Or other compatible programmer– see note above.)Software:
  1. Download the Arduino Software from this page.
  2. Download the Peggy2 library here (18 kB .ZIP file)

  First, install the Arduino software if you don’t already have it. Uncompress the Peggy2 library, and place it in the hard/ware/library/ directory where your Arduino software is installed. (If you’ve put it in the right place, it will be amongst a few other libraries in similar folders there, with names like “EEPROM” and “Wire.”)

  Now open up the Arduino program itself. From the menu, select File>Sketchbook>Examples>Library-Peggy2>peggy2_firstdemo. Click the “Verify” button to compile the program. (It’s the one with the “play” symbol at the upper left of the window.) In a few moments, it should indicate that it’s done compiling.

  Now, to hook up to the Peggy. If using the USB-TTL cable, it hooks up to your computer and to the connector (J3) on the left side of the Peggy, by the chips. Note that the wires on the cable are color-coded: the end where the green wire goes is marked “green” on the circuit board.

  Next, we’ll actually send the demo program to the board. From the menu, make sure that Tools>Board>Arduino Diecimila is selected. (Peggy 2.0 is not a Diecimila, but the architecture is compatible.)
  Then, to actually program the board, press the “Upload to I/O Board” button at the top of the Arduino program window (it’s the other “right arrow” button). If it works, you may see Peggy do some erratic things while the program is being uploaded, typically about 15 seconds, and then it will start to run the program. If it does not work, make sure that Peggy has power and is turned on. You may also wish to play with the serial port selection under the Tools menu.
   

  ---

  Example programs

  There are four demo programs included with the library:

  peggy2_firstdemo

  Light up pixels at the four corners of the screen and demonstrate very simple “live” animation– programming where the dots go in real time.

  peggy2_FrameAnim

  Generates four (very simple) frame buffers and slowly switches between them to animate. In our example, we’re just drawing four rectangular stripes and switching between them. However, there’s no reason that you couldn’t use this to switch between multiple full-frame images for simple animation within the constraints of available memory.

  peggy2_FrameGray

  This uses the same four frame buffers as peggy2_FrameAnim, but switches quickly between them, spending a variable amount of time at each– which produces four-bit gray scale stripes. (See the picture at the top of this article.)

  peggy2_minimal

  Not quite as minimal as it could be, this example is a great place to start playing. We initialize a single frame buffer array, fill it with dots, and display it. This is pretty similar to the default firmware that ships on the Peggy, but now written with the Peggy2 Arduino library.
   

  ---

  Gory Details::Working with the library

  The easiest way to get started is to take one or more of the above examples and bend it to your will. However, we will also here go over what the different functions are and how to use them.

  Importing the library

  Before you get started using any of the Peggy2 functions or data structures, you need to include the library in your Arduino “sketch” by adding the following line at the top:

  #include <Peggy2.h>You can add this line semi-automatically by selecting it from the menu: Sketch>Import Library>Peggy2

  Creating a frame buffer

  A frame buffer is an object in memory (RAM) that holds one monochrome image that can be displayed on the Peggy. In order to display things on the Peggy, you need to allocate at least one frame buffer. (Internally, the data in a frame buffer–four bytes per row– is arranged as an array of 25 long integers. However, you don’t actually need to know that in order to use them.)

  If we’re doing an animation that has four frames that we switch between, we might want to use four frame buffers. Or, if we’re drawing live on the screen, we might only want one frame buffer, which we could keep drawing in. In any case, you can have one or several different frame buffers (limited by the amount of available RAM), each of which needs to have a different name. Normally, frame buffers are declared (created) at the beginning of the program, right after the #includes.

  A new frame buffer is declared by using the keyword “Peggy2.” To make a new frame buffer named Fred, we would call

  Peggy2 Fred; If you wanted four frame buffers (named frame1, frame2, frame3, and frame4), you could create them like so:

  Peggy2 frame1;

  Peggy2 frame2;

  Peggy2 frame3;

  Peggy2 frame4;

  Hardware initialization

  Separately from creating the frame buffer, we also have to make sure that the Peggy hardware is ready for us. Do this by putting the command XXXX.Peggy_HardwareInit(); (where XXXX is the name of any one of your frame buffers) within your setup() section.

  The setup() section is a part of the Arduino Sketch that’s only run once at the beginning; the other half– the loop()section that comes after it is repeated forever.

  Your setup() section might look like this, for example:

  
void setup()

  {

  frame1.Peggy_HardwareInit();

  }
That’s it for initialization: make (at least) one frame buffer and do the hardware initialization. What remains are functions and procedures that can be executed at your discretion later in the setup()section or in the loop() section.

  Peggy_RefreshAll

  In order to draw the contents of a frame buffer on the Peggy, you can issue a command of the form

  FrameBufferName.Peggy_RefreshAll(unsigned int refreshNum),

  which takes an (unsigned) integer argument that says how many times to draw it on the screen. For a fast, single update of your frame buffer named Fred, you might put the following in your loop() section:

  
Fred.Peggy_RefreshAll(1);
while for a more complex arrangement, you might have

  
frame1.Peggy_RefreshAll(2);

  frame2.Peggy_RefreshAll(8);
which would draw both frames frame1 and frame2 on the Peggy. By the persistence of vision effect, you would see both frames frame1 and frame2 at the same time, drawn on top of each other. And, since frame2 is drawn for longer, (with the same brightness) it would appear brighter than the image in frame1.

  Peggy_Clear();

  You can completely zero out an existing frame buffer named Fred by issuing the command
  Fred.Peggy_Clear();

  Example usage:

  
if (n > 100)

  frame2.Peggy_Clear();
Peggy_SetPoint

  The Peggy_SetPoint function is used to turn on a given pixel of a given frame buffer. The syntax is
  FrameBufferName.Peggy_SetPoint(unsigned short x, unsigned short y).

  As before, this function acts on a specific frame buffer. The (x,y) coordinates are the usual type for computer graphics: origin in the upper left corner, with column/row location given by the ordered pair of unsigned integers, which should in this case be in the range 0-24.

  Example usage, to turn on pixel located at (x,y) = (4, 10), in a frame buffer named Ginger:

  
Ginger.Peggy_SetPoint(4,10);
See the code examples for additional usage demonstrations, particularly peggy2_firstdemo.

  Peggy_ClearPoint

  The Peggy_ClearPoint function is used to turn off a given pixel of a given frame buffer. The syntax is
  FrameBufferName. Peggy_ClearPoint(unsigned short x, unsigned short y).

  Very much like Peggy_SetPoint, above.
  Example usage, to turn off pixel located at (x,y) = (4, 10), in a frame buffer named Ginger:

  
Ginger.Peggy_ClearPoint(4,10);
See the code examples for additional usage demonstrations.

   

   

  ---

  Caveats

  While this library does make it easier to control Peggy, it is far from perfect, not particularly fast or efficient, and you can probably write a better one. If you do have upgrades, improvements, code, bugs, or suggestions to contribute, we’re listening. We’ll also be working on some expanded features and new code of our own; You can expect this library to evolve over time.