# ChipKIT™ Basic I/O Shield™

## Introduction

This project will be introducing the chipKIT Basic I/O Shield, and how to use the organic LED (or OLED) display screen on the shield. If you are unfamiliar with chipKIT (or Arduino™) shields, they are simply accessory boards that are designed to mount onto your chipKIT board and contain many peripheral components (you should be aware that chipKIT shields come separately from the chipKIT Starter Kit). While for this project we will be solely focusing on the OLED component, the Basic I/O Shield does contain several buttons, switches, LEDS, FET drivers (for connecting motors/high current devices), a digital thermometer, and an onboard EPROM.

We will be writing a “Hello chipKIT World!!!” message to the OLED display, along with a simple animation of cascading square boxes.

##### Before you begin, you should:
• Be able to load a library into MPIDE.
##### After you're done, you should:
• Be able to initialize an OLED.
• Be able to write characters and simple graphics to an OLED.

## Inventory:

Qty Description Typical Image
1 ChipKIT Basic I/O Shield.

## Basic Theory

OLED displays are very convenient, power efficient devices that are commonly used in mobile applications. As you can probably imagine, an LED display uses individual LED elements to represent pixels on the screen. These devices are termed “Organic” because they are constructed from layers of organic semi-conducting polymers, as opposed traditional LEDs which are made from silicon or germanium.

Normally, communication with the OLED controller can be somewhat involved, but for our project we will be using a pre-built library to make communication very easy and straightforward. To download a zipped package of libraries for the Basic I/O Shield (there are libraries for using the EPROM and temperature sensor, but we will only use the OLED library), follow the red tab to the right.

If you are unfamiliar or forget how to install a library, you can refer back to the “Debouncing via Bounce Library” project as a refresher (orange tab on the right).

You can find a reference pdf for the I/O Shield OLED library contained in the zip file, or by clicking on the yellow tab to the right.

### Drawing Characters

The OLED can be used to display strings (i.e., characters) or for writing graphics. Both modes can be used interchangeably but work slightly different. In order to display a string of characters once the OLED is setup, it is simply a matter of calling:

              IOShieldOled.setCursor(0,0);
IOShieldOled.putString("String to display");

This will start writing characters to the top left corner of the OLED (likewise, setCursor will set the row and column that the string starts from). The OLED display consists of 4 rows, and 16 columns per row. When calling the “putstring” method, the cursor will automatically increment, and even jump to a new line if you exceed the characters per row (it is also important to remember that all row and column indexes start at 0).

### Drawing Graphics

The second mode is for displaying graphics. The OLED library has simple functions for drawing basic lines and shapes, and for this project we will simply be drawing squares onto our display.

One of the main differences between character mode and drawing mode is that in drawing mode exact pixel locations are used (and not cursor locations). The Basic I/O Shield has a display space of 128*32 pixels.

For example, to draw a box in the upper left hand corner of the screen you could use the following code:

            IOShieldOled.moveTo(0,0);
IOShieldOled.drawRect(8, 8);  // int x , int y


The “moveTo” function sets a reference location (since the screen is 128*32 pixels, the x value range is from 0 to 127, and y value range is from 0 to 31). The “drawRect” function will then draw a rectangle to the frame buffer with the top left corner starting at the reference location (the frame buffer is simply a location in chipKIT memory that stores the values that will be printed to the screen). The X and Y parameters specify the location of the bottom right corner of the rectangle (the difference between the reference point and the drawRect method parameters being the length and width of the rectangle).

To actually display the graphic, call (i.e., write the frame buffer to the screen):

IOShieldOled.updateDisplay();

For this project we will be using the drawFillRect() method in the OLED library, which first requires you to set a fill pattern. To set the fill pattern to white, simply declare a byte pointer (more on that below), and call the following functions in your setup function:

 byte* fillWhite
setup(){
fillWhite = IOShieldOled.getStdPattern(1);
IOShieldOled.setFillPattern(fillWhite);

}


The getStdPattern() method returns a “pointer” to an array of 8 bytes. A pointer is a programming object that references data stored in a different location in memory. Using the above code as an example, no data is stored in the pointer fillWhite, instead the pointer stores the location of where the data can be found. Essentially, getSTdPattern returns the memory location where a fill pattern is located. The setFillPattern() does what one would expect and sets pattern so that it will be used the next time a drawFillRect() method is called.

There are seven patterns from the getStdPattern() method (0 having no pixels on, and 1 having all pixels on), feel free to experiment.

## Step 1: Setting up the Hardware

Setting up the hardware for this project will be relatively easy. Simply place the Basic I/O Shield onto the chipKIT board so that the pins on the underside of the I/O shield insert into the chipKIT board headers (the name labels on the I/O shield should match the chipKIT board). If this is unclear simply watch the video provided below.

## Step 2: Initializing the OLED (Through Software)

Like most digital components, before they can be used they have to be setup. The OLED display controller will require six functions to be called in the setup() function before it can be used.

• IOShieldOled.begin()
• This will turn on power to the display and initializes the device. (Note: this will also take control of SPI1 on the chipKIT board, so be aware).
• IOShieldOled.displayOn()
• This will enable the display.
• IOShieldOled.clear()
• The IOSheildOled library uses a data buffer to keep track of characters and graphics before they are visible on the OLED. So for graphics, you will need to write to the buffer and then call the update command before the graphics are visible (for just writing characters the putString command will automatically update the buffer). The clear function then, like its name implies, will clear this data buffer. (When initializing any data register, it is always good practice to set it to a known value at startup).
• IOShieldOled.setDrawMode(modeSet)
• setDrawMode method changes how data will be placed into the data buffer. The four options are:
• modeSet = when drawing a graphic will set the data location with the line and fill color, regardless of frame buffer content.
• modeOr = will logically “Or” the new drawn graphic with whatever was in the frame buffer at the particular location.
• modeAnd = will logically “And” the new graphic with previous frame buffer content.
• modeXor = will logically “Xor” the new graphic with previous frame buffer content.

• IOShieldOled.setCursor(0,0)
• The set cursor function simply tells the display where to start putting characters on the OLED screen. Setting the cursor location to 0,0 homes the cursor to the top left corner of the screen.

Below is an example of the global variables, setup, and include portion of a sketch to initialize an OLED.

#include <IOShieldOled.h>

byte* fillWhite

void setup() {

IOShieldOled.begin();
IOShieldOled.displayOn();
IOShieldOled.clear();
IOShieldOled.setCursor(0,0);
IOShieldOled.setDrawMode(modeSet)

fillWhite = IOShieldOled.getStdPattern(1);
IOShieldOled.setFillPattern(fillWhite);

}


## Step 3: Writing and Drawing

The main body of our sketch will simply write the string “Hello chipKIT World” and draw a 4x4 grid of boxes on the right side of the screen.

    #include <IOShieldOled.h>

int z;
int Size;
byte* fillWhite;

const int xoffset = 90;
const int yoffset = 0;

void setup() {

IOShieldOled.begin();
IOShieldOled.displayOn();
IOShieldOled.clear();
IOShieldOled.setCursor(0,0);

IOShieldOled.setDrawMode(modeAnd);

fillWhite = IOShieldOled.getStdPattern(1);
IOShieldOled.setFillPattern(fillWhite);

z = 0;

Size = 6;

}

void loop() {

// Hello chipKIT World"
IOShieldOled.setCursor(0,1);// sets the cursor to row 2
IOShieldOled.putString("Hello");
IOShieldOled.setCursor(0,2);// sets the cursor to row 3
IOShieldOled.putString("chipKIT");
IOShieldOled.setCursor(0,3);// sets the cursor to row 4
IOShieldOled.putString("World");
// square graphics

int x = 8*(z % 4) + xoffset; //sets the column position for the rectangle
int y = 8*(z/4) + yoffset;   //sets the row position for the rectangle
IOShieldOled.moveTo(x,y);

IOShieldOled.drawFillRect(x+ Size, y + Size);

z++;
if (z == 16){
z = 0;
}
IOShieldOled.updateDisplay();// update the frame buffer

delay(150);

}