uOLED.h

00001 /* mbed 4D uOLED Library
00002  * Originally designed for use with uOLED-96-G1 (SGC)
00003  * serially controlled .96" screen.
00004  *
00005  * This is a modified library originally obtained from
00006  * Erik van Wijk's library code at:
00007  * http://mbed.org/users/evwijk/libraries/microOLED/li4nzn
00008  *
00009  * This library (uOLED) by Aaron Goselin.
00010  * 2010
00011  *
00012  * If you use and/or modify this library please keep credit lines intact.
00013  */
00014 
00015 #ifndef _MBED_UOLED_
00016 #define _MBED_UOLED_
00017 
00018 #include "mbed.h"
00019 
00020 #define     OLED_FONT5X7                    0x01
00021 #define     OLED_FONT8X8                    0x02
00022 #define     OLED_FONT8X12                   0x03
00023 
00024 #define     OLED_DISPLAYCONTROL_DISPLAY     0x01
00025 #define     OLED_DISPLAYCONTROL_CONTRAST    0x02
00026 #define     OLED_DISPLAYCONTROL_POWER       0x03
00027 
00028 
00029 /** uOLED control class using Serial
00030  * 
00031  * The serially controlled uOLEDs by 4D Systems are controlled
00032  * with only 3 pins:
00033  * - serialTX
00034  * - serialRX
00035  * - reset
00036  *
00037  * While the device includes many serial functions, it is faster to do things from a uSD card.
00038  * Consider learning the 4DSL scripting language.  You can then write your functions in 4DSL 
00039  * storing them on the uSD to later be triggered serially.
00040  *
00041  * Examples use SGC as the uOLED instance name.  SGC just happens to be the type of device that I have.
00042  * Of course, it doesn't matter what you call your instance(s).
00043  *
00044  * Examples use both decimal and hexadecimal numbers.  It does not matter which you use for most functions.
00045  *
00046  * Please post a comment on the library page if you spot an error.  I will try to fix it quickly.
00047  *
00048  * Example:
00049  * @code
00050  * // Draw text on the screen.
00051  * #include "mbed.h"
00052  * #include "uOLED.h"
00053  * 
00054  * uOLED SGC(p9, p10, p11);
00055  *
00056  * int main()
00057  * {    
00058  *     SGC.drawText(0, 0, 0, FF, FF, FF, "This is text");
00059  * }
00060  * @endcode
00061  */
00062 class uOLED {
00063 public:
00064 
00065     /** Create an instance of the uOLED class.
00066     * 
00067     * @param serialTX - mbed TX pin to be used
00068     * @param serialRX - mbed RX pin to be used
00069     * @param reset - mbed pin to control reset of the uOLED
00070     *
00071     * Example:
00072     * @code
00073     * // (serialTX, serialRX, reset)
00074     * uOLED SGC(p9, p10, p11);
00075     * @endcode
00076     */
00077     uOLED(PinName serialTX, PinName serialRX, PinName reset);
00078     
00079     /** Convert RGB value into the type of value that the uOLED wants.
00080     * 
00081     * @param red Red value.
00082     * @param green Green value.
00083     * @param blue Blue value.
00084     *
00085     * Example:
00086     * @code
00087     * // (red, green, blue)
00088     * SGC.getRGB(120, 255, 50);
00089     * @endcode
00090     */
00091     short getRGB(char red, char green, char blue);
00092 
00093     /** Add user defined bitmap character into internal memory.
00094     * 
00095     * @param character Character index to add to memory.  Range is 0-31 (0x00 to 0x1F).  32 8x8 characters.
00096     * @param data[8] 8 data bytes that make up the composition of the bitmap character.  8x8 composition is 1 byte wide (8 bits) by 8 bytes deep.
00097     *
00098     * Example:
00099     * @code
00100     * // Array containing data for 8x8 "O" character.
00101     * char data[8] = {0x18, 0x24, 0x42, 0x81, 0x81, 0x42, 0x24, 0x18};
00102     * // (characterIndex, characterData)
00103     * SGC.addBitmappedCharacter(0x01, data);
00104     * @endcode
00105     */
00106     bool addBitmappedCharacter(char character, char data[8]);
00107     
00108     /** Copy and paste a specified block of the screen.
00109     * 
00110     * @param sourceX Top left horizontal start position of screen area to be copied.
00111     * @param sourceY Top left vertical start position of screen area to be copied.
00112     * @param destinationX Top left horizontal start position of where copied area is to be pasted.
00113     * @param destinationY Top left vertical start position of where copied area is to be pasted.
00114     * @param width Width of screen area to be copied.
00115     * @param height Height of screen area to be copied.
00116     *
00117     * Example:
00118     * @code
00119     * // (sourceX, sourceY, destinationX, destinationY, width, height)
00120     * SGC.blockCopyPaste(0, 0, 25, 5, 10, 10);
00121     * @endcode
00122     */
00123     bool blockCopyPaste(char sourceX, char sourceY, char destinationX, char destinationY, char width, char height);
00124     
00125     /** Save a specified block of the screen to the uSD.
00126     * 
00127     * @param x Top left horizontal start position of screen area to be copied.
00128     * @param y Top left vertical start position of screen area to be copied.
00129     * @param width Width of screen area to be copied.
00130     * @param height Height of screen area to be copied.
00131     * @param sectorHi High sector address.
00132     * @param sectorMid Mid sector address.
00133     * @param sectorLow Low sector address.
00134     *
00135     * Example:
00136     * @code
00137     * // Save a block of the screen from (0x, 0y) to (20x, 20y) and save it on the uSD
00138     * // at (0x00, 0x10, 0x66)
00139     * // (x, y, width, height, sectorHi, sectorMid, sectorLow)
00140     * SGC.screenCopy(0, 0, 20, 20, 0x00, 0x10, 0x66);
00141     * @endcode
00142     */
00143     bool screenCopy(char x, char y, char width, char height, char sectorHi, char sectorMid, char sectorLow);
00144     
00145     
00146     /** Display control.
00147     * 
00148     * Display ON/OFF, set contrast, and PowerUp/Shutdown.
00149     *
00150     * @param mode Sets specified mode.
00151     * @param value Value option for mode.
00152     *
00153     * - Mode: 01 Display ON/OFF
00154     *   - Value: 00 OFF
00155     *   - Value: 01 ON
00156     * - Mode: 02 Contrast Adjust
00157     *   - Value range: 0x00 to 0x0F
00158     * - Mode: 03 Display PowerUp/Shutdown (low power mode)
00159     *   - Value 00 Shutdown
00160     *   - Value 01 Powerup
00161     *
00162     * Example:
00163     * @code
00164     * // Turn display ON.
00165     * SGC.displayControl(0x01, 0x01)
00166     * // Set contrast to medium.
00167     * SGC.displayControl(0x02, 0x08);
00168     * // Shutdown display.
00169     * SGC.displayControl(0x03, 0x00);
00170     * @endcode
00171     */
00172     bool displayControl(char mode, char value);
00173     
00174     /** Draw previously defined user bitmap character at specified location (and colour).
00175     * 
00176     * @param character Character index of previously defined bitmap character.  Range is 0 to 31 (0x00 to 0x1F).  32 8x8 characters.
00177     * @param x Horizontal display position of character.
00178     * @param y Vertical display position of character.
00179     * @param red Amount of red.
00180     * @param green Amount of green.
00181     * @param blue Amount of blue.
00182     *
00183     * Example:
00184     * @code
00185     * // Display bitmapped character stored in index 01, at location (0x,0y), and colour it red.
00186     * // (characterIndex, x, y, red, green, blue)
00187     * SGC.displayUserBitmappedCharacter(0x01, 0x00, 0x00, 0xFF, 0x00, 0x00);
00188     * @endcode
00189     */
00190     bool displayUserBitmappedCharacter(char character, char x, char y, short red, short green, short blue);
00191     
00192     /** Draw a circle.
00193     * 
00194     * @param x X position of circle center.
00195     * @param y Y position of circle center.
00196     * @param radius Radius of the circle.
00197     * @param red Amount of red.
00198     * @param green Amount of green.
00199     * @param blue Amount of blue.
00200     *
00201     * Example:
00202     * @code
00203     * // Draw a circle centered at (63x, 63y) with a radius of 34 and colour it green.
00204     * // (x, y, radius, red, green, blue)
00205     * SGC.drawCircle(0x3F, 0x3F, 0x22, 0x00, 0xFF, 0x00);
00206     * @endcode
00207     */
00208     bool drawCircle(char x, char y, char radius, short red, short green, short blue);
00209     
00210     /** Draw ASCII character (text format)
00211     * 
00212     * @param character Inbuilt standard ASCII character.  Range 32 to 127 (0x20 to 0x7F).
00213     * @param column Horizontal position of character.
00214     * - range: 0-20 for 5x7 font.
00215     * - range: 0-15 for 8x8 and 8x12 fonts.
00216     * @param row Vertical position of character.
00217     * @param red Amount of red.
00218     * @param green Amount of green.
00219     * @param blue Amount of blue.
00220     *
00221     * Example:
00222     * @code
00223     * // Draw character 'A' at column 0, row 0.  Colour it white.
00224     * // (character, column, row, red, green, blue)
00225     * SGC.drawCharacter(0x41, 0x00, 0x00, 0xFF, 0xFF, 0xFF);
00226     * @endcode
00227     */
00228     bool drawCharacter(char character, char column, char row, short red, short green, short blue);
00229     
00230     /** Display a bitmap image on the screen at specified location and size.
00231     * 
00232     * @param x Image horizontal start position (top left).
00233     * @param y Image vertical start position (top left).
00234     * @param width Horizontal size of the image.
00235     * @param height Vertical size of the image.
00236     * @param colorMode Colour mode to use for the image.
00237     * - 0x08 = 256 colour mode (8bits/1byte per pixel)
00238     * - 0x10 = 65K colour mode (16bits/2bytes per pixel)
00239     * @param *pixels Image pixel data.
00240     * - Colour Mode 0x08 (256 colour mode):  Number of pixels = width x height
00241     * - Colour Mode 0x10 (65K colour mode):  Number of pixels = 2 x width x height
00242     */
00243     bool drawImage(char x, char y, char width, char height, char colorMode, char *pixels);
00244     
00245     /** Load an image from the uSD and display on the screen at specified location and size.
00246     * 
00247     * @param x Image horizontal start position (top left).
00248     * @param y Image vertical start position (top left).
00249     * @param width Horizontal size of the image.
00250     * @param height Vertical size of the image.
00251     * @param colorMode Colour mode to use for the image.
00252     * - 0x08 = 256 colour mode (8bits/1byte per pixel)
00253     * - 0x10 = 65K colour mode (16bits/2bytes per pixel)
00254     * @param sectorHi High sector address.
00255     * @param sectorMid Mid sector address.
00256     * @param sectorLow Low sector address.
00257     */
00258     bool drawImageSD_16bit(char x, char y, char width, char height, char colourMode, char sectorHi, char sectorMid, char sectorLow);
00259     
00260     
00261     /** Draw a line.
00262     * 
00263     * @param x1 Top left horizontal start position.
00264     * @param y1 Top left vertical start position.
00265     * @param x2 Bottom right horizontal start position.
00266     * @param y2 Bottom right vertical end position.
00267     * @param red Amount of red.
00268     * @param green Amount of green.
00269     * @param blue Amount of blue.
00270     *
00271     * Example:
00272     * @code
00273     * // Draw a line starting at (0x, 0y) and ending at (43x, 43y).  Colour it blue.
00274     * // (x1, y1, x2, y2, red, green, blue)
00275     * SGC.drawLine(0x00, 0x00, 0x2B, 0x2B, 0x00, 0x00, 0xFF);
00276     * @endcode
00277     */
00278     bool drawLine(char x1, char y1, char x2, char y2, short red, short green, short blue);
00279     
00280     /** Draw a polygon (user defined shape) to the screen.
00281     * 
00282     * @param vertices Number of vertices from 3 to 7.
00283     * @param *x Array of vertices' X coordinates.
00284     * @param *y Array of vertices' Y coordinates.
00285     * @param red Amount of red.
00286     * @param green Amount of green.
00287     * @param blue Amount of blue.
00288     *
00289     * Example:
00290     * @code
00291     * char x[5] = {0, 18, 26, 44, 54};
00292     * char y[5] = {10, 25, 33, 22, 36};
00293     * // Draw a white polygon with 5 vertices located at:
00294     * // (0x, 10y), (18x, 25y), (26x, 33y), (44x, 22y), (54x, 36y)
00295     * // (vertices, *x, *y, red, green, blue)
00296     * SGC.drawPolygon(5, x, y, 255, 255, 255);
00297     * @endcode
00298     */
00299     bool drawPolygon(char vertices, char *x, char *y, short red, short green, short blue);
00300     
00301     /** Draw a rectangle.
00302     * 
00303     * @param x Top left horizontal start position.
00304     * @param y Top left vertical start position.
00305     * @param width Bottom right horizontal end position.
00306     * @param height Bottom right vertical end position.
00307     * @param red Amount of red.
00308     * @param green Amount of green.
00309     * @param blue Amount of blue.
00310     *
00311     * Example:
00312     * @code
00313     * // Draw rectangle starting at (0x, 0y) and ending at (40x, 40y).  Colour red.
00314     * // (x, y, width, height, red, green, blue)
00315     * SGC.drawRectangle(0, 0, 40, 40, 255, 0, 0);
00316     * @endcode
00317     */
00318     bool drawRectangle(char x, char y, char width, char height, short red, short green, short blue);
00319     
00320     /** Draw text to the screen.
00321     * 
00322     * @param column X coordinate for text placement.
00323     * @param row Y coordinate for text placement.
00324     * @param font Which font to use (Uses 0, 1, or 2).  More fonts can be added.
00325     * @param color Font colour to use.
00326     * @param *text Character array (string) to be displayed.
00327     *
00328     * Example:
00329     * @code
00330     * // Draw string "This is text" at (0, 0) with font set 0, coloured white.
00331     * // (column, row, font, red, green, blue, "text")
00332     * SGC.drawText(0, 0, 0, 0xFF, 0xFF, 0xFF, "This is text");
00333     * @endcode
00334     */
00335     bool drawText(char column, char row, char font, short red, short green, short blue, char *text);
00336     
00337     /** Draw unformated text to the screen.
00338     * The manual describes this as "graphics format".
00339     *
00340     * @param x X coordinate for text placement.
00341     * @param y Y coordinate for text placement.
00342     * @param font Which font to use (Uses 0, 1, or 2).  More fonts can be added.
00343     * @param red Amount of red in text colour RGB value.
00344     * @param green Amount of green in text colour RGB value.
00345     * @param blue Amount of blue in text colour RGB value.
00346     * @param width Text width.
00347     * @param height Text height.
00348     * @param *text Character array (string) to be displayed.
00349     *
00350     * Example:
00351     * @code
00352     * // Draw unformatted text string "This is text" at (0, 0) with font set 0, coloured white with zero (1x) magnification.
00353     * SGC.drawTextUF(0, 0, 0, 255, 255, 255, 1, 1, "This is text");
00354     * @endcode
00355     */
00356     bool drawTextUF(char x, char y, char font, short red, short green, short blue, char width, char height, char *text);
00357     
00358     /** Draw a triangle.
00359     *
00360     * Vertices must be defined counter clockwise.
00361     *
00362     * @param x1 Vertice 1 X coordinate.
00363     * @param y1 Vertice 1 Y coordinate.
00364     * @param x2 Vertice 2 X coordinate.
00365     * @param y2 Vertice 2 Y coordinate.
00366     * @param x3 Vertice 3 X coordinate.
00367     * @param y3 Vertice 3 Y coordinate.
00368     * @param red Amount of red.
00369     * @param blue Amount of blue.
00370     * @param green Amount of green.
00371     *
00372     * Example:
00373     * @code
00374     * // Draw a red triangle with vertices:
00375     * // (0x, 0y), (0x, 40y), (40x, 0y)
00376     * // (x1, y1, x2, y2, x3, y3, red, green, blue)
00377     * SGC.drawTriangle(0, 0, 0, 40, 40, 0, 255, 0, 0);
00378     * @endcode
00379     */
00380     bool drawTriangle(char x1, char y1, char x2, char y2, char x3, char y3, short red, short green, short blue);
00381     
00382     /** Clear the screen.
00383     * 
00384     * Remove everything except the background colour.
00385     *
00386     * @param returns success or failure.
00387     *
00388     * Example:
00389     * @code
00390     * // Do you really need an example? :)
00391     * SGC.eraseScreen();
00392     * @endcode
00393     */
00394     bool eraseScreen();
00395     
00396     /** Initialize the screen.  This must be completed before any other communication with the device.
00397     *
00398     * Timing allows for at least 500ms delay for initialization.
00399     *
00400     * @param returns bool indicating success or failure of initialization.
00401     *
00402     * Example:
00403     * @code
00404     * // Must be done before anything else
00405     * SGC.init();
00406     * @endcode
00407     */
00408     bool init();
00409     
00410     /** Set pen size.
00411     * 
00412     * Sets if objects should be drawn solid or wire frame.
00413     * Does not apply to polygon function.
00414     *
00415     * @param size Sets solid or wire frame.
00416     * - 0x00 = Solid
00417     * - 0x01 = Wire frame.
00418     *
00419     * Example:
00420     * @code
00421     * // Draw objects solid
00422     * SGC.penSize(0);
00423     * // Draw objects wire frame
00424     * SGC.penSize(1);
00425     * @endcode
00426     */
00427     bool penSize(char size);
00428     
00429     /** Draw a coloured pixel at designated position.
00430     * 
00431     * @param x Horizontal position of pixel.
00432     * @param y Vertical position of pixel.
00433     * @param red Amount of red.
00434     * @param green Amount of green.
00435     * @param blue Amount of blue.
00436     *
00437     * Example:
00438     * @code
00439     * // Draw a blue pixel at (10x, 10y).
00440     * // (x, y, red, green, blue)
00441     * SGC.putPixel(10, 10, 0, 0, 255);
00442     * @endcode
00443     */
00444     bool putPixel(char x, char y, short red, short green, short blue);
00445     
00446     /** Read the colour of a specified pixel.
00447     * 
00448     * @param x X coordinate.
00449     * @param y Y coordinate.
00450     * @param returns 2 byte pixel colour in RGB format.
00451     * - MSB: R4R3R2R1R0G5G4G3
00452     * - LSB: G2G1G0B4B3B2B1B0
00453     *
00454     * Example:
00455     * @code
00456     * // Read pixel colour at location (20x, 20y).
00457     * short pixelColour = SGC.readPixel(20, 20);
00458     * @endcode
00459     */
00460     short readPixel(char x, char y);
00461     
00462     /** Replaces the background colour with a new colour.
00463     * 
00464     * Most functions call this internally.
00465     *
00466     * @param red Red value (0 to 255).
00467     * @param green Green value (0 to 255).
00468     * @param blue Blue value (0 to 255).
00469     *
00470     * Example:
00471     * @code
00472     * // Set background colour to red.
00473     * // (red, green, blue)
00474     * SGC.setBackgroundColour(255, 0, 0);
00475     * @endcode
00476     */
00477     bool setBackgroundColour(char red, char green, char blue);
00478     
00479     /** Set font (for future text).
00480     *
00481     * 3 default fonts are supplied.  Further font sets can be added.
00482     * 
00483     * @param font Font selection.  Either a default or otherwise.
00484     * - DEFAULT: 0x00 = 5x7 small size font set
00485     * - DEFAULT: 0x01 = 8x8 medium size font set
00486     * - DEFAULT: 0x02 = 8x12 large size font set
00487     *
00488     * Example:
00489     * @code
00490     * // Use default 5x7 font set
00491     * SGC.setFont(0);
00492     * // Use default 8x12 font set
00493     * SGC.setFont(2);
00494     * @endcode
00495     */    
00496     bool setFont(char font);
00497     
00498     /** Draw a text button to the screen.
00499     * 
00500     * @param state Button down (0x00) or button up (0x01).
00501     * @param x Top left horizontal start position.
00502     * @param y Top left vertical start position.
00503     * @param red Amount of red (for button not text).
00504     * @param green Amount of green (for button not text).
00505     * @param blue Amount of blue (for button not text).
00506     * @param font Set which font set to use for the button.  3 default font sets are supplied and more can be added.
00507     * - DEFAULT: 0x00 = 5x7 small size font set
00508     * - DEFAULT: 0x01 = 8x8 medium size font set
00509     * - DEFAULT: 0x02 = 8x12 large size font set
00510     * @param textRed Amount of red for text.
00511     * @param textGreen Amount of green for text.
00512     * @param textBlue Amount of blue for text.
00513     * @param textWidth Width of characters (text).  Affect total width of string and button.
00514     * @param textHeight Height of characters (text).  Affects total height of string and button.
00515     * @param *text Character array (string) to display in the button.
00516     *
00517     * Example:
00518     * @code
00519     * // Draw a text button in the unpressed state starting at (0x, 0y).
00520     * // Button colour is red, text colour is white.  Text magnification is zero (1x).
00521     * // (state, x, y, red, green, blue, font, textRed, textGreen, textBlue, textWidth, textHeight, "Text");
00522     * SGC.textButton(1, 0, 0, 255, 0, 0, 0, 255, 255, 255, 1, 1, "Button text");
00523     * @endcode
00524     */
00525     bool textButton(char state, char x, char y, short red, short green, short blue, char font, short textRed, short textGreen, short textBlue, char textWidth, char textHeight, char *text);
00526     
00527     /** Set text mode (transparent or opaque).
00528     *
00529     * Opaque text has a rectangle drawn behind it (blocking out what is under it) and transparent text does not.
00530     * 
00531     * @param mode Set text to transparent (0x00) or opaque (0x01).
00532     *
00533     * Example:
00534     * @code
00535     * // Set text mode to transparent.
00536     * SGC.textMode(0);
00537     * @endcode
00538     */
00539     bool textMode(char mode);
00540     
00541     /** Retrieve current version info of the device.
00542     * 
00543     * Response:
00544     * 
00545     * device_type Indicates device type.
00546     * - 0x00 = micro-OLED
00547     * - 0x01 = micro-LCD
00548     * - 0x02 = micro-VGA
00549     *
00550     * hardware_rev Indicates device hardware version.
00551     *
00552     * firmware_rev Indicates device firmware version.
00553     *
00554     * horizontal_res Indicates the horizontal resolution of the display.
00555     * - 0x22 = 220 pixels
00556     * - 0x28 = 128 pixels
00557     * - 0x32 = 320 pixels
00558     * - 0x60 = 160 pixels
00559     * - 0x64 = 64 pixels
00560     * - 0x76 = 176 pixels
00561     * - 0x96 = 96 pixels
00562     *
00563     * vertical_res Indicates the vertical resolution of the display.
00564     * - See horizontal_res (identical).
00565     *
00566     * @param onScreen Set output option.
00567     * - 0x00 = Output to serial port only.
00568     * - 0x01 = Output to serial port and screen.
00569     * @param *info Character array to store results.
00570     *
00571     * Example:
00572     * @code
00573     * // Request version info, pass in character array to store results.
00574     * char info[5];
00575     * SGC.versionInfo(1, info);
00576     * printf("\n\nVersion info:\n\n");
00577     * for(int i = 0; i < 5; i++)
00578     * {
00579     *    printf("0x%X\n", info[i]);
00580     * }
00581     * @endcode
00582     */
00583     bool versionInfo(bool onScreen, char info[5]);
00584     
00585     
00586 protected:
00587     Serial      _oled;
00588     DigitalOut  _reset;
00589     
00590     void resetDisplay();
00591 };
00592 
00593 #endif