OLEDDisplay.h

00001 /**
00002  * The MIT License (MIT)
00003  *
00004  * Copyright (c) 2018 by ThingPulse, Daniel Eichhorn
00005  * Copyright (c) 2018 by Fabrice Weinberg
00006  * Copyright (c) 2019 by Helmut Tschemernjak - www.radioshuttle.de
00007  *
00008  * Permission is hereby granted, free of charge, to any person obtaining a copy
00009  * of this software and associated documentation files (the "Software"), to deal
00010  * in the Software without restriction, including without limitation the rights
00011  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00012  * copies of the Software, and to permit persons to whom the Software is
00013  * furnished to do so, subject to the following conditions:
00014  *
00015  * The above copyright notice and this permission notice shall be included in all
00016  * copies or substantial portions of the Software.
00017  *
00018  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00019  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00020  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00021  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00022  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00023  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00024  * SOFTWARE.
00025  *
00026  * ThingPulse invests considerable time and money to develop these open source libraries.
00027  * Please support us by buying our products (and not the clones) from
00028  * https://thingpulse.com
00029  *
00030  */
00031 
00032 #ifndef OLEDDISPLAY_h
00033 #define OLEDDISPLAY_h
00034 
00035 #ifdef ARDUINO
00036 #include <Arduino.h>
00037 #elif __MBED__
00038 #define pgm_read_byte(addr)   (*(const unsigned char *)(addr))
00039 
00040 #include <mbed.h>
00041 #define delay(x)    wait_ms(x)
00042 #define yield()     void()
00043 
00044 /*
00045  * This is a little Arduino String emulation to keep the OLEDDisplay
00046  * library code in common between Arduino and mbed-os
00047  */
00048 class String {
00049 public:
00050     String(const char *s) { _str = s; };
00051     int length() { return strlen(_str); };
00052     const char *c_str() { return _str; };
00053     void toCharArray(char *buf, unsigned int bufsize, unsigned int index = 0) const {
00054         memcpy(buf, _str + index,  std::min(bufsize, strlen(_str)));
00055     };
00056 private:
00057     const char *_str;
00058 };
00059 
00060 #else
00061 #error "Unkown operating system"
00062 #endif
00063 
00064 #include "OLEDDisplayFonts.h"
00065 
00066 //#define DEBUG_OLEDDISPLAY(...) Serial.printf( __VA_ARGS__ )
00067 //#define DEBUG_OLEDDISPLAY(...) dprintf("%s",  __VA_ARGS__ )
00068 
00069 #ifndef DEBUG_OLEDDISPLAY
00070 #define DEBUG_OLEDDISPLAY(...)
00071 #endif
00072 
00073 // Use DOUBLE BUFFERING by default
00074 #ifndef OLEDDISPLAY_REDUCE_MEMORY
00075 #define OLEDDISPLAY_DOUBLE_BUFFER
00076 #endif
00077 
00078 // Header Values
00079 #define JUMPTABLE_BYTES 4
00080 
00081 #define JUMPTABLE_LSB   1
00082 #define JUMPTABLE_SIZE  2
00083 #define JUMPTABLE_WIDTH 3
00084 #define JUMPTABLE_START 4
00085 
00086 #define WIDTH_POS 0
00087 #define HEIGHT_POS 1
00088 #define FIRST_CHAR_POS 2
00089 #define CHAR_NUM_POS 3
00090 
00091 
00092 // Display commands
00093 #define CHARGEPUMP 0x8D
00094 #define COLUMNADDR 0x21
00095 #define COMSCANDEC 0xC8
00096 #define COMSCANINC 0xC0
00097 #define DISPLAYALLON 0xA5
00098 #define DISPLAYALLON_RESUME 0xA4
00099 #define DISPLAYOFF 0xAE
00100 #define DISPLAYON 0xAF
00101 #define EXTERNALVCC 0x1
00102 #define INVERTDISPLAY 0xA7
00103 #define MEMORYMODE 0x20
00104 #define NORMALDISPLAY 0xA6
00105 #define PAGEADDR 0x22
00106 #define SEGREMAP 0xA0
00107 #define SETCOMPINS 0xDA
00108 #define SETCONTRAST 0x81
00109 #define SETDISPLAYCLOCKDIV 0xD5
00110 #define SETDISPLAYOFFSET 0xD3
00111 #define SETHIGHCOLUMN 0x10
00112 #define SETLOWCOLUMN 0x00
00113 #define SETMULTIPLEX 0xA8
00114 #define SETPRECHARGE 0xD9
00115 #define SETSEGMENTREMAP 0xA1
00116 #define SETSTARTLINE 0x40
00117 #define SETVCOMDETECT 0xDB
00118 #define SWITCHCAPVCC 0x2
00119 
00120 #ifndef _swap_int16_t
00121 #define _swap_int16_t(a, b) { int16_t t = a; a = b; b = t; }
00122 #endif
00123 
00124 enum OLEDDISPLAY_COLOR {
00125   BLACK = 0,
00126   WHITE = 1,
00127   INVERSE = 2
00128 };
00129 
00130 enum OLEDDISPLAY_TEXT_ALIGNMENT {
00131   TEXT_ALIGN_LEFT = 0,
00132   TEXT_ALIGN_RIGHT = 1,
00133   TEXT_ALIGN_CENTER = 2,
00134   TEXT_ALIGN_CENTER_BOTH = 3
00135 };
00136 
00137 
00138 enum OLEDDISPLAY_GEOMETRY {
00139   GEOMETRY_128_64   = 0,
00140   GEOMETRY_128_32,
00141   GEOMETRY_RAWMODE,
00142 };
00143 
00144 typedef char (*FontTableLookupFunction)(const uint8_t ch);
00145 char DefaultFontTableLookup(const uint8_t ch);
00146 
00147 
00148 #ifdef ARDUINO
00149 class OLEDDisplay : public Print  {
00150 #elif __MBED__
00151 class OLEDDisplay : public Stream {
00152 #else
00153 #error "Unkown operating system"
00154 #endif
00155 
00156   public:
00157     OLEDDisplay();
00158     virtual ~OLEDDisplay();
00159 
00160     uint16_t width(void) const { return displayWidth; };
00161     uint16_t height(void) const { return displayHeight; };
00162 
00163     // Initialize the display
00164     bool init();
00165 
00166     // Free the memory used by the display
00167     void end();
00168 
00169     // Cycle through the initialization
00170     void resetDisplay(void);
00171 
00172     /* Drawing functions */
00173     // Sets the color of all pixel operations
00174     void setColor(OLEDDISPLAY_COLOR color);
00175 
00176     // Returns the current color.
00177     OLEDDISPLAY_COLOR getColor();
00178 
00179     // Draw a pixel at given position
00180     void setPixel(int16_t x, int16_t y);
00181 
00182     // Clear a pixel at given position FIXME: INVERSE is untested with this function
00183     void clearPixel(int16_t x, int16_t y);
00184 
00185     // Draw a line from position 0 to position 1
00186     void drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1);
00187 
00188     // Draw the border of a rectangle at the given location
00189     void drawRect(int16_t x, int16_t y, int16_t width, int16_t height);
00190 
00191     // Fill the rectangle
00192     void fillRect(int16_t x, int16_t y, int16_t width, int16_t height);
00193 
00194     // Draw the border of a circle
00195     void drawCircle(int16_t x, int16_t y, int16_t radius);
00196 
00197     // Draw all Quadrants specified in the quads bit mask
00198     void drawCircleQuads(int16_t x0, int16_t y0, int16_t radius, uint8_t quads);
00199 
00200     // Fill circle
00201     void fillCircle(int16_t x, int16_t y, int16_t radius);
00202 
00203     // Draw a line horizontally
00204     void drawHorizontalLine(int16_t x, int16_t y, int16_t length);
00205 
00206     // Draw a line vertically
00207     void drawVerticalLine(int16_t x, int16_t y, int16_t length);
00208 
00209     // Draws a rounded progress bar with the outer dimensions given by width and height. Progress is
00210     // a unsigned byte value between 0 and 100
00211     void drawProgressBar(uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t progress);
00212 
00213     // Draw a bitmap in the internal image format
00214     void drawFastImage(int16_t x, int16_t y, int16_t width, int16_t height, const uint8_t *image);
00215 
00216     // Draw a XBM
00217     void drawXbm(int16_t x, int16_t y, int16_t width, int16_t height, const uint8_t *xbm);
00218 
00219     /* Text functions */
00220 
00221     // Draws a string at the given location
00222     void drawString(int16_t x, int16_t y, String text);
00223 
00224     // Draws a String with a maximum width at the given location.
00225     // If the given String is wider than the specified width
00226     // The text will be wrapped to the next line at a space or dash
00227     void drawStringMaxWidth(int16_t x, int16_t y, uint16_t maxLineWidth, String text);
00228 
00229     // Returns the width of the const char* with the current
00230     // font settings
00231     uint16_t getStringWidth(const char* text, uint16_t length);
00232 
00233     // Convencience method for the const char version
00234     uint16_t getStringWidth(String text);
00235 
00236     // Specifies relative to which anchor point
00237     // the text is rendered. Available constants:
00238     // TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT, TEXT_ALIGN_CENTER_BOTH
00239     void setTextAlignment(OLEDDISPLAY_TEXT_ALIGNMENT textAlignment);
00240 
00241     // Sets the current font. Available default fonts
00242     // ArialMT_Plain_10, ArialMT_Plain_16, ArialMT_Plain_24
00243     void setFont(const uint8_t *fontData);
00244 
00245     // Set the function that will convert utf-8 to font table index
00246     void setFontTableLookupFunction(FontTableLookupFunction function);
00247 
00248     /* Display functions */
00249 
00250     // Turn the display on
00251     void displayOn(void);
00252 
00253     // Turn the display offs
00254     void displayOff(void);
00255 
00256     // Inverted display mode
00257     void invertDisplay(void);
00258 
00259     // Normal display mode
00260     void normalDisplay(void);
00261 
00262     // Set display contrast
00263     // really low brightness & contrast: contrast = 10, precharge = 5, comdetect = 0
00264     // normal brightness & contrast:  contrast = 100
00265     void setContrast(uint8_t contrast, uint8_t precharge = 241, uint8_t comdetect = 64);
00266 
00267     // Convenience method to access 
00268     void setBrightness(uint8_t);
00269 
00270     // Reset display rotation or mirroring
00271     void resetOrientation();
00272 
00273     // Turn the display upside down
00274     void flipScreenVertically();
00275 
00276     // Mirror the display (to be used in a mirror or as a projector)
00277     void mirrorScreen();
00278 
00279     // Write the buffer to the display memory
00280     virtual void display(void) = 0;
00281 
00282     // Clear the local pixel buffer
00283     void clear(void);
00284 
00285     // Log buffer implementation
00286 
00287     // This will define the lines and characters you can
00288     // print to the screen. When you exeed the buffer size (lines * chars)
00289     // the output may be truncated due to the size constraint.
00290     bool setLogBuffer(uint16_t lines, uint16_t chars);
00291 
00292     // Draw the log buffer at position (x, y)
00293     void drawLogBuffer(uint16_t x, uint16_t y);
00294 
00295     // Get screen geometry
00296     uint16_t getWidth(void);
00297     uint16_t getHeight(void);
00298 
00299     // Implement needed function to be compatible with Print class
00300     size_t write(uint8_t c);
00301     size_t write(const char* s);
00302     
00303     // Implement needed function to be compatible with Stream class
00304 #ifdef __MBED__
00305     int _putc(int c);
00306     int _getc() { return -1; };
00307 #endif
00308 
00309 
00310     uint8_t            *buffer;
00311 
00312     #ifdef OLEDDISPLAY_DOUBLE_BUFFER
00313     uint8_t            *buffer_back;
00314     #endif
00315 
00316   protected:
00317 
00318     OLEDDISPLAY_GEOMETRY geometry;
00319 
00320     uint16_t  displayWidth;
00321     uint16_t  displayHeight;
00322     uint16_t  displayBufferSize;
00323 
00324     // Set the correct height, width and buffer for the geometry
00325     void setGeometry(OLEDDISPLAY_GEOMETRY g, uint16_t width = 0, uint16_t height = 0);
00326 
00327     OLEDDISPLAY_TEXT_ALIGNMENT   textAlignment;
00328     OLEDDISPLAY_COLOR            color;
00329 
00330     const uint8_t    *fontData;
00331 
00332     // State values for logBuffer
00333     uint16_t   logBufferSize;
00334     uint16_t   logBufferFilled;
00335     uint16_t   logBufferLine;
00336     uint16_t   logBufferMaxLines;
00337     char      *logBuffer;
00338 
00339 
00340     // the header size of the buffer used, e.g. for the SPI command header
00341     virtual int getBufferOffset(void) = 0;
00342     
00343     // Send a command to the display (low level function)
00344     virtual void sendCommand(uint8_t com) {(void)com;};
00345 
00346     // Connect to the display
00347     virtual bool connect() { return false; };
00348 
00349     // Send all the init commands
00350     void sendInitCommands();
00351 
00352     // converts utf8 characters to extended ascii
00353     char* utf8ascii(String s);
00354 
00355     void inline drawInternal(int16_t xMove, int16_t yMove, int16_t width, int16_t height, const uint8_t *data, uint16_t offset, uint16_t bytesInData) __attribute__((always_inline));
00356 
00357     void drawStringInternal(int16_t xMove, int16_t yMove, char* text, uint16_t textLength, uint16_t textWidth);
00358     
00359     FontTableLookupFunction fontTableLookupFunction;
00360 };
00361 
00362 #endif