AXE133Y library for Arduino

by SmudgerD - May 2012 - www.stompville.co.uk

Functions

• writeByte()
• splash()
• displayShow()
• cursorShow()
• cursorBlink()
• clearScreen()
• cursorHome()
• cursorLeft()
• cursorRight()
• cursorPosition()
• printMessage()
• print()
• outputWrite()
• backspace()
• printFloat()

Navigation

• Introduction
• Hardware Requirements
• Display Architecture
• Download
• Installation
• Language Reference

Introduction

The AXE133Y is a 16x2 OLED dot-matrix display with 1-wire TTL serial interface. It is based on a Winstar OLED module (part number WEH001602ELPP5N00000) and a PICAXE piggyback board which converts the serial data to drive the OLED module.

The AXE133Y is available as a kit of parts from Tech Supplies. Reference info for the AXE133Y is available from picaxe.com

In addition to driving the OLED display, the PICAXE board has three digital output pins C0, C1 and C2 which may be used for auxiliary purposes.

Hardware Requirements

The AXE133Y board requires +5V, GND and Serial data. Power consumption varies according to how much of the display is on but two lines of text consume about 20mA so you can power the module from an Arduino pin if you need to. Pick up +5V and GND from the power pins if you can. The author picks up +5V and 0V from the ISP connector for the USB-serial chip on the Arduino.

The AXE133Y can be driven from any Arduino pin acting as a digital output.

As the AXE133Y module is designed for educational use, the PICAXE serial software protocol is quite simple and does have some limitations, such as the fact that you must write the status of the digital output pins together (i.e. they are not individually addressable).

Assuming the kit is built correctly and connected up to Arduino, The AXE133Y module powers-up and displays:

                       SERIAL  OLED
                      www.picaxe.com

Display Architecture

The display structure comprises 128 bytes of RAM memory-mapped to the display character cells.

• Line 1 (the upper line) of the display shows the contents of bytes 0~15 of the display memory
• Line 2 (the lower line) of the display shows the contents of bytes 65~80 of the display memory
• The library functions presented here allow for Line 2 to be addressed as 0~15 as well
• The display software automatically wraps (ring buffers) the display memory.
• If you send a long String to the display you may get unexpected results

For example, when the pangram "The quick brown fox jumps over the lazy dog" is sent to the beginning of line 1, the display will show:

                     The quick brown

However, "An inspired calligrapher can create pages of beauty using stick ink, quill, brush, pick-axe, buzz saw, or even strawberry jam." sent to the beginning of line 1, the display will show:

                     An inspired call
                     ink, quill, brus

and if we send "The quick brown fox jumps over the lazy dog, but an inspired calligrapher can create pages of beauty using stick ink, quill, brush, pick-axe, buzz saw, or even strawberry jam." to the beginning of line 1, the display will show:

                     sh, pick-axe, bu
                     ligrapher can cr

In the following functions there is no bounds-checking on the length of messages sent to the display.

Download

Download the latest version here: stompville.co.uk/AXE133Y-v001.zip

Installation

To install the AXE133Y library, navigate to the "libraries" folder in the installation directory for Arduino. Paste the file AXE133Y.zip into the "libraries" folder and unzip in place. This will result in a new folder in the "libraries" folder called "AXE133Y". Resart the Arduino software so that it reads the new library. Now (in Arduino) navigate to File|Examples|AXE133Y and click on AXE133Y, which will open the example sketch below:

Note: If you haven't updated to Arduino 1.0 or higher, you will need to rename the example sketch from AXE133Y.ino to AXE133Y.pde in order for pre 1.0 versions to see the sketch.

The above sketch is very straightforward and will display the following on the OLED display:

                      AXE133Y Vnnn
                      Hello World!

where nnn indicates the version of the library code.

Language Reference

writeByte()

• This function writes a single byte to the display
• The argument foo may have an integer value between zero and 255 (decimal)
• Values of foo between 0 and 20 (decimal, inclusive) are ignored
• Values of foo between 21 and 252 will cause the appropriate character from the Western European Character Font Table to be displayed
• A value of 253 tells the AXE133Y to display a predefined message (0~15)
• A value of 254 tells the AXE133Y that the next byte is a control byte
• A value of 255 tells the AXE133Y to set the auxiliary outputs
• Normally, this function is used to display special characters from the font table.

Example:

This is equivalent to:

splash()

• This function clears the display and shows the library version on the top line
• The second line displays the String object message with a length between 0 and 16 characters
• If message is longer than 16 characters, wrap-around may occur (see above)

Example (see example sketch above)

displayShow()

• This function blanks/hides and shows/reveals the display without changing the contents of the display memory
• The function can be used to flash the display to draw attention or to save energy as the power consumption of the display is related to the number of LED segments which are active at any given moment
• The function accepts the boolean argument show. If show is true the display is on (revealed) and if false the display is off (hidden)
• The default for the display is on

Example:

cursorShow()

• This function blanks/hides and shows/reveals the cursor in solid form
• The function accepts the boolean argument show. If show is true the cursor is on (revealed) and if false the cursor is off (hidden)
• The default for the cursor is off

Example:

cursorBlink()

• This function switches between solid and blinking cursor
• If the cursor is off, this function will turn it on
• The function accepts the boolean argument blink. If blink is true, the cursor will be switched on and made to blink
• If blink is false, the cursor will be switched on in solid form (i.e. same as OLED.cursorShow(true))
• If the cursor is off and you want a blinking cursor, you don't need to showCursor first

Example:

clearScreen()

• This function clears the display, homes the cursor to the beginning of the upper line (line 1) and switches the cursor off

Example:

cursorHome()

• This function moves the cursor to the beginning of a line
• The upper line is line 1 and the lower line is line 2

Example:

cursorLeft()

• This function moves the cursor left
• The function accepts the integer argument moves with a value between 0 and 255 (decimal)
• The cursor position moves through display memory and wraps automatically (see above)

Example:

cursorRight()

• This function moves the cursor right
• The function accepts the integer argument moves with a value between 0 and 255 (decimal)
• The cursor position moves through display memory and wraps automatically (see above)

Example:

cursorPosition()

• This function moves the cursor to an absolute position
• The position can be anywhere in the display memory
• The function accepts two integer arguments, line and position both with a value between 0 and 255 (decimal)
• If line is 1 then the cursor is moved to the upper line of the display
• If line is <>1 then the cursor is moved to the lower line of the display
• position will normally be in the range 0~15 (decimal) but the OLED module will wrap the value (see above)

Example:

printMessage()

• This function prints a predefined message stored in the Picaxe driver chip (in flash memory)
• You will have to reprogram the Picaxe chip firmware to change the messages
• The function accepts an integer argument messageNumber with a value between 0 and 15 (decimal)
• The message will be displayed starting at the current cursor position

Example:

print()

• This function prints a String object to the display starting at the current cursor position
• The function accepts an String argument message which should normally have a length between 0 and 16 characters
• The length of the String object message is not limited and the display will wrap long strings (see above)
• If you have a string in a character array, convert it to a string before sending using the String() function

Example:

outputWrite()

• This function sets/resets the auxiliary outputs C.2, C.1 and C.0
• These outputs are marked C2, C1 and C0 respectively on the pcb
• Unlike Arduino digitalWrite, the status of the outputs can not be read and all three outputs must be set at the same time
• The function accepts the integer argument state which sets the state of all three outputs at the same time
• If you want to set or reset one output whilst leaving the other outputs unchanged, you will need to keep a track of the desired status of all three outputs and use bitwise manipulations to change individual outputs
• It takes about 2.5ms to change the outputs so the maximum toggle frequency is less than 400Hz

Example:

The rules for bitwise manipulations are as follows:

bitwise AND function (&)

x AND 0 gives 0 //force to zero

x AND 1 gives x //leave unchanged

bitwise OR function (|)

x OR 0 gives x //leave unchanged

x OR 1 gives 1 //force to one

bitwise XOR function (^)

x XOR 0 gives x //leave unchanged

x XOR 1 gives ~x //i.e. not, toggle or invert x

backspace()

• This function deletes characters to the left of the current cursor position and moves the cursor correspondingly
• The function accepts the integer argument moves with a value between 0 and 255 (decimal)
• The backspace function will wrap through the display memory (see above)

Example:

printFloat()

• This function converts a floating point constant or variable to a String object and prints it to the display at the current cursor position
• The function accepts a float argument foo which is the float to be displayed
• The function accepts an integer argument minimumLength with a value between 0 and 255 (decimal)
• minimumLength represents the minimum length of the String object created. If necessary, the string object will be padded with leading whitespace
• The function accepts an integer argument decimalPlaces with a value between 0 and 255 (decimal)
• decimalPlaces represents the number of decimal places in the String object
• The buffer size is only 16 characters so you will get a buffer overflow if you try and create a string object in excess of 16 characters long
• The routine uses the C function dtostrf() which notionally works to eight significant figures

Example: