locator_receiver/SSD1306Ascii.h

   1 /* Arduino SSD1306Ascii Library
   2  * Copyright (C) 2015 by William Greiman
   3  *
   4  * This file is part of the Arduino SSD1306Ascii Library
   5  *
   6  * This Library is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This Library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with the Arduino SSD1306Ascii Library.  If not, see
  18  * <http://www.gnu.org/licenses/>.
  19  */
  20 /**
  21  * @file SSD1306Ascii.h
  22  * @brief Base class for ssd1306 displays.
  23  */
  24 #ifndef SSD1306Ascii_h
  25 #define SSD1306Ascii_h
  26 #include "Arduino.h"
  27 #include "SSD1306init.h"
  28 #include "fonts/allFonts.h"
  29 //------------------------------------------------------------------------------
  30 /** SSD1306Ascii version */
  31 #define SDD1306_ASCII_VERSION 1.2.2
  32 //------------------------------------------------------------------------------
  33 // Configuration options.
  34 /** Set Scrolling mode for newline.
  35  *
  36  * If INCLUDE_SCROLLING is defined to be zero, newline will not scroll
  37  * the display and code for scrolling will not be included.  This option
  38  * will save some code space and three bytes of RAM.
  39  *
  40  * If INCLUDE_SCROLLING is nonzero, the scroll feature will included.
  41  */
  42 #define INCLUDE_SCROLLING 0
  43
  44 /** Initial scroll mode, SCROLL_MODE_OFF,
  45     SCROLL_MODE_AUTO, or SCROLL_MODE_APP. */
  46 #define INITIAL_SCROLL_MODE SCROLL_MODE_OFF
  47
  48 /** Use larger faster I2C code. */
  49 #define OPTIMIZE_I2C 1
  50
  51 /** AvrI2c uses 400 kHz fast mode if AVRI2C_FASTMODE is nonzero else 100 kHz. */
  52 #define AVRI2C_FASTMODE 1
  53 //------------------------------------------------------------------------------
  54 // Values for setScrolMode(uint8_t mode)
  55 /** Newline will not scroll the display or RAM window. */
  56 #define SCROLL_MODE_OFF  0
  57 /** Newline will scroll both the display and RAM windows. */
  58 #define SCROLL_MODE_AUTO 1
  59 /** Newline scrolls the RAM window. The app scrolls the display window. */
  60 #define SCROLL_MODE_APP  2
  61 //------------------------------------------------------------------------------
  62 // Values for writeDisplay() mode parameter.
  63 /** Write to Command register. */
  64 #define SSD1306_MODE_CMD     0
  65 /** Write one byte to display RAM. */
  66 #define SSD1306_MODE_RAM     1
  67 /** Write to display RAM with possible buffering. */
  68 #define SSD1306_MODE_RAM_BUF 2
  69 //-----------------------------------------------------------------------------
  70 /**
  71  * @brief Reset the display controller.
  72  *
  73  * @param[in] rst Reset pin number.
  74  */
  75 inline void oledReset(uint8_t rst) {
  76   pinMode(rst, OUTPUT);
  77   digitalWrite(rst, LOW);
  78   delay(10);
  79   digitalWrite(rst, HIGH);
  80   delay(10);
  81 }
  82 //------------------------------------------------------------------------------
  83 /**
  84  * @class SSD1306Ascii
  85  * @brief SSD1306 base class
  86  */
  87 class SSD1306Ascii : public Print {
  88  public:
  89   using Print::write;
  90   SSD1306Ascii() {}
  91 #if INCLUDE_SCROLLING
  92 //------------------------------------------------------------------------------
  93   /**
  94    * @return the RAM page for top of the RAM window.
  95    */
  96   uint8_t pageOffset() const {return m_pageOffset;}
  97   /**
  98    * @return the display line for pageOffset.
  99    */
 100   uint8_t pageOffsetLine() const {return 8*m_pageOffset;}
 101   /**
 102    * @brief Scroll the Display window.
 103    *
 104    * @param[in] lines Number of lines to scroll the window.
 105    */
 106   void scrollDisplay(int8_t lines) {setStartLine(m_startLine + lines);}
 107   /**
 108    * @brief Scroll the RAM window.
 109    *
 110    * @param[in] rows Number of rows to scroll the window.
 111    */
 112   void scrollMemory(int8_t rows) {setPageOffset(m_pageOffset + rows);}
 113   /**
 114    * @return true if the first display line is equal to the
 115    *         start of the RAM window.
 116    */
 117   bool scrollIsSynced() const {return startLine() == pageOffsetLine();}
 118   /**
 119    * @brief Set page offset.
 120    *
 121    * @param[in] page the RAM page for start of the RAM window
 122    */
 123   void setPageOffset(uint8_t page);
 124   /**
 125    * @brief Enable or disable scroll mode. Deprecated use setScrollMode().
 126    *
 127    * @param[in] enable true enable scroll on newline false disable scroll.
 128    */
 129   void setScroll(bool enable) __attribute__((deprecated("use setScrollMode"))) {
 130     setScrollMode(enable ? SCROLL_MODE_AUTO : SCROLL_MODE_OFF);
 131   }
 132   /**
 133    * @brief Set scroll mode.
 134    *
 135    * @param[in] mode One of the following.
 136    *
 137    * SCROLL_MODE_OFF - newline will not scroll the display or RAM window.
 138    *
 139    * SCROLL_MODE_AUTO - newline will scroll both the display and RAM windows.
 140    *
 141    * SCROLL_MODE_APP - newline scrolls the RAM window.
 142    *                   The app scrolls the display window.
 143    */
 144   void setScrollMode(uint8_t mode) {m_scrollMode = mode;}
 145   /**
 146    * @brief Set the display start line register.
 147    *
 148    * @param[in] line RAM line to be mapped to first display line.
 149    */
 150   void setStartLine(uint8_t line);
 151   /**
 152    * @return the display startline.
 153    */
 154   uint8_t startLine() const {return m_startLine;}
 155 #endif  // INCLUDE_SCROLLING
 156   //----------------------------------------------------------------------------
 157   /**
 158    * @brief Determine the width of a character.
 159    *
 160    * @param[in] c Character code.
 161    * @return Width of the character in pixels.
 162    */
 163   uint8_t charWidth(uint8_t c) const;
 164   /**
 165    * @brief Clear the display and set the cursor to (0, 0).
 166    */
 167   void clear();
 168   /**
 169    * @brief Clear a region of the display.
 170    *
 171    * @param[in] c0 Starting column.
 172    * @param[in] c1 Ending column.
 173    * @param[in] r0 Starting row;
 174    * @param[in] r1 Ending row;
 175    * @note The final cursor position will be (c0, r0).
 176    */
 177   void clear(uint8_t c0, uint8_t c1, uint8_t r0, uint8_t r1);
 178   /**
 179    * @brief Clear a field of n fieldWidth() characters.
 180    *
 181    * @param[in] col Field start column.
 182    *
 183    * @param[in] row Field start row.
 184    *
 185    * @param[in] n Number of characters in the field.
 186    *
 187    */
 188   void clearField(uint8_t col, uint8_t row, uint8_t n);
 189   /**
 190    * @brief Clear the display to the end of the current line.
 191    * @note The number of rows cleared will be determined by the height
 192    *       of the current font.
 193    * @note The cursor will be returned to the original position.
 194    */
 195   void clearToEOL();
 196   /**
 197    * @return The current column in pixels.
 198    */
 199   uint8_t col() const {return m_col;}
 200   /**
 201    * @return The display hight in pixels.
 202    */
 203   uint8_t displayHeight() const {return m_displayHeight;}
 204   /**
 205    * @brief Set display to normal or 180 degree remap mode.
 206    *
 207    * @param[in] mode true for normal mode, false for remap mode.
 208    *
 209    * @note Adafruit and many ebay displays use remap mode.
 210    *       Use normal mode to rotate these displays 180 degrees.
 211    */
 212   void displayRemap(bool mode);
 213   /**
 214    * @return The display height in rows with eight pixels to a row.
 215    */
 216   uint8_t displayRows() const {return m_displayHeight/8;}
 217   /**
 218    * @return The display width in pixels.
 219    */
 220   uint8_t displayWidth() const {return m_displayWidth;}
 221   /**
 222    * @brief Width of a field in pixels.
 223    *
 224    * @param[in] n Number of characters in the field.
 225    *
 226    * @return Width of the field.
 227    */
 228   size_t fieldWidth(uint8_t n);
 229   /**
 230    * @return The current font pointer.
 231    */
 232   const uint8_t* font() const {return m_font;}
 233   /**
 234    * @return The count of characters in a font.
 235    */
 236   uint8_t fontCharCount() const;
 237   /**
 238    * @return The first character in a font.
 239    */
 240   char fontFirstChar() const;
 241   /**
 242    * @return The current font height in pixels.
 243    */
 244   uint8_t fontHeight() const;
 245   /**
 246    * @return The number of eight pixel rows required to display a character
 247    *    in the current font.
 248    */
 249   uint8_t fontRows() const;
 250   /**
 251    * @return The maximum width of characters in the current font.
 252    */
 253   uint8_t fontWidth() const;
 254   /**
 255    * @brief Set the cursor position to (0, 0).
 256    */
 257   void home() {setCursor(0, 0);}
 258   /**
 259    * @brief Initialize the display controller.
 260    *
 261    * @param[in] dev A display initialization structure.
 262    */
 263   void init(const DevType* dev);
 264   /**
 265    * @brief Set pixel mode for for entire display.
 266    *
 267    * @param[in] invert Inverted display if true or normal display if false.
 268    */
 269   void invertDisplay(bool invert);
 270   /**
 271    * @return invert mode.
 272    */
 273   bool invertMode() const {return !!m_invertMask;}
 274   /**
 275    * @brief Set invert mode for write/print.
 276    *
 277    * @param[in] mode Invert pixels if true and use normal mode if false.
 278    */
 279   void setInvertMode(bool mode) {m_invertMask = mode ? 0XFF : 0;}
 280   /**
 281    * @return letter-spacing in pixels with magnification factor.
 282    */
 283   uint8_t letterSpacing() const {return m_magFactor*m_letterSpacing;}
 284   /**
 285    * @return The character magnification factor.
 286    */
 287   uint8_t magFactor() const {return m_magFactor;}
 288   /**
 289    * @return the current row number with eight pixels to a row.
 290    */
 291   uint8_t row() const {return m_row;}
 292   /**
 293    * @brief Set the character magnification factor to one.
 294    */
 295   void set1X() {m_magFactor = 1;}
 296   /**
 297    * @brief Set the character magnification factor to two.
 298    */
 299   void set2X() {m_magFactor = 2;}
 300   /**
 301    * @brief Set the current column number.
 302    *
 303    * @param[in] col The desired column number in pixels.
 304    */
 305   void setCol(uint8_t col);
 306   /**
 307    * @brief Set the display contrast.
 308    *
 309    * @param[in] value The contrast level in th range 0 to 255.
 310    */
 311   void setContrast(uint8_t value);
 312   /**
 313    * @brief Set the cursor position.
 314    *
 315    * @param[in] col The column number in pixels.
 316    * @param[in] row the row number in eight pixel rows.
 317    */
 318   void setCursor(uint8_t col, uint8_t row);
 319   /**
 320    * @brief Set the current font.
 321    *
 322    * @param[in] font Pointer to a font table.
 323    */
 324   void setFont(const uint8_t* font);
 325   /**
 326    * @brief Set letter-spacing.  setFont() will restore default letter-spacing.
 327    *
 328    * @param[in] pixels letter-spacing in pixels before magnification.
 329    */
 330   void setLetterSpacing(uint8_t pixels) {m_letterSpacing = pixels;}
 331   /**
 332    * @brief Set the current row number.
 333    *
 334    * @param[in] row the row number in eight pixel rows.
 335    */
 336   void setRow(uint8_t row);
 337   /**
 338    * @brief Write a command byte to the display controller.
 339    *
 340    * @param[in] c The command byte.
 341    * @note The byte will immediately be sent to the controller.
 342    */
 343   void ssd1306WriteCmd(uint8_t c) {writeDisplay(c, SSD1306_MODE_CMD);}
 344   /**
 345    * @brief Write a byte to RAM in the display controller.
 346    *
 347    * @param[in] c The data byte.
 348    * @note The byte will immediately be sent to the controller.
 349    */
 350   void ssd1306WriteRam(uint8_t c);
 351   /**
 352    * @brief Write a byte to RAM in the display controller.
 353    *
 354    * @param[in] c The data byte.
 355    * @note The byte may be buffered until a call to ssd1306WriteCmd
 356    *       or ssd1306WriteRam.
 357    */
 358   void ssd1306WriteRamBuf(uint8_t c);
 359   /**
 360    * @param[in] str The pointer to string.
 361    * @return the width of the string in pixels.
 362    */
 363   size_t strWidth(const char* str) const;
 364   /**
 365    * @brief Display a character.
 366    *
 367    * @param[in] c The character to display.
 368    * @return the value one.
 369    */
 370   size_t write(uint8_t c);
 371
 372  protected:
 373   uint16_t fontSize() const;
 374   virtual void writeDisplay(uint8_t b, uint8_t mode) = 0;
 375   uint8_t m_col;            // Cursor column.
 376   uint8_t m_row;            // Cursor RAM row.
 377   uint8_t m_displayWidth;   // Display width.
 378   uint8_t m_displayHeight;  // Display height.
 379   uint8_t m_colOffset;      // Column offset RAM to SEG.
 380   uint8_t m_letterSpacing;  // Letter-spacing in pixels.
 381 #if INCLUDE_SCROLLING
 382   uint8_t m_startLine;      // Top line of display
 383   uint8_t m_pageOffset;     // Top page of RAM window.
 384   uint8_t m_scrollMode = INITIAL_SCROLL_MODE;  // Scroll mode for newline.
 385 #endif  // INCLUDE_SCROLLING
 386   const uint8_t* m_font = nullptr;  // Current font.
 387   uint8_t m_invertMask = 0;  // font invert mask
 388   uint8_t m_magFactor = 1;   // Magnification factor.
 389 };
 390 #endif  // SSD1306Ascii_h