Diff: ssd1306.h

Revision:

8:09b1578f93d9

Parent:

7:b0e7ccc9138b

Child:

9:57209a7e9cba

--- a/ssd1306.h	Wed Nov 01 16:54:57 2017 +0000
+++ b/ssd1306.h	Mon Nov 06 18:22:22 2017 +0000
@@ -65,6 +65,35 @@
 
 /**
  * SSD1306. A class for interacting with SSD1306 controlled 128x64 cheap OLED displays
+ * 
+ * Example of use:
+ * @code
+ * #include "mbed.h"
+ * #include "ssd1306.h"
+ * 
+ * SSD1306 lcd (I2C_SDA, I2C_SCL); // assumes default I2C address of 0x78
+ * AnalogIn knob (A0);             // potentiometer to analog pin A0
+ *
+ * int main()
+ * {
+ *   lcd.speed (SSD1306::Medium);  // set working frequency
+ *   lcd.init();                   // initialize SSD1306
+ *   lcd.cls();                    // clear frame buffer
+ *   lcd.locate (3,1);             // set text cursor to line 3, column 1
+ *   lcd.printf ("Hello, world!"); // print to frame buffer
+ *   lcd.line (  7, 23, 113, 23, SSD1306::Normal); //
+ *   lcd.line (113, 23, 113, 32, SSD1306::Normal); // Surrounds text with 
+ *   lcd.line (113, 32,   7, 32, SSD1306::Normal); // a rectangle
+ *   lcd.line (  7, 32,   7, 23, SSD1306::Normal); //
+ *   lcd.fill (0, 0);              // fills screen outside rectangle
+ *   lcd.redraw();                 // updates actual display transferring frame buffer over I2C bus
+ *   while (1) {
+ *     unsigned char level = 255*knob.read();  // reads pot. Scales to 0-255
+ *     lcd.set_contrast (level);               // set contrast
+ *     wait_ms (20);                           // waits a little to prevent excesive I2C traffic
+ *   }
+ * }
+ * @endcode
  */
 class SSD1306 {
 public:
@@ -73,9 +102,9 @@
      */
     enum PlotStyle
     {
-        Normal,
-        Inverse,
-        Xor
+        Normal,  /**< The point is set on the display */
+        Inverse, /**< The point is erased on the display */
+        Xor      /**< The point is erased on the display if it was already set, otherwise, it is set */
     };
     
     /**
@@ -83,9 +112,9 @@
      */
     enum I2CSpeed
     {
-        Slow,
-        Medium,
-        Fast
+        Slow,    /**< I2C frequency is set to 100 kHz */
+        Medium,  /**< I2C frequency is set to 400 kHz */
+        Fast     /**< I2C frequency is set to 1 MHz. Use it only with short connections to host */
     };
     
     /**
@@ -135,7 +164,7 @@
      * Prints a NUL terminated string
      *
      * @param s C-style string (NUL terminated) to print.
-     * @param refresh (optional) Force an actual screen redraw after scrolling
+     * @param refresh (optional) Force an actual screen redraw after the operation
      */
     void puts (char *s, bool refresh=false);
         
@@ -155,11 +184,16 @@
     void locate (char row, char column);
     
     /**
-     * Redraw the physical display, sending the content of the display memory to the SSD1306 controller using the I2C bus
+     * (Deprecated: use redraw instead) Redraws the physical display, sending the content of the display memory to the SSD1306 controller using the I2C bus.
      */
     void display (void);
     
     /**
+     * Redraws the physical display, sending the content of the display memory to the SSD1306 controller using the I2C bus
+     */
+    void redraw (void);    
+    
+    /**
      * Changes the contrast (actually, pixel brightness) of the screen
      *
      * @param v Contrast level (0-255)
@@ -170,7 +204,7 @@
      * Clear screen and optionally, fills it with a predefined picture (in 128x64 OLED format, see display datasheet). Also resets the text position.
      *
      * @param bkground If not NULL, should point to a 1024 byte buffer with the image to load to the display
-     * @param refresh (optional) Force an actual screen redraw after scrolling
+     * @param refresh (optional) Force an actual screen redraw after the operation
      */
     void cls (char *bkground=NULL, bool refresh=false);
     
@@ -180,7 +214,7 @@
      * @param x x-coordinate (0-127) of the pixel. X coordinates go left to right.
      * @param y y-coordinate (0-63) of the pixel. Y coordinates go up to down.
      * @param mode. Plot style mode: Normal (pixel is drawn), Inverse (pixel is erased), or Xor (pixel is erased if background position is already set, otherwise is drawn)
-     * @param refresh (optional) Force an actual screen redraw after scrolling
+     * @param refresh (optional) Force an actual screen redraw after plotting
      */
     void plot (char x, char y, PlotStyle mode, bool refresh=false);
     
@@ -201,7 +235,7 @@
      * @param x1 x-coordinate (0-127) of the ending point
      * @param y1 y-coordinate (0-63) of the ending point
      * @param mode. Plot style mode: Normal (pixel is drawn), Inverse (pixel is erased), or Xor (pixel is erased if background position is already set, otherwise is drawn)
-     * @param refresh (optional) Force an actual screen redraw after scrolling
+     * @param refresh (optional) Force an actual screen redraw after drawing the line
      */
     void line (char x0, char y0, char x1, char y1, PlotStyle mode, bool refresh=false);
     
@@ -212,10 +246,19 @@
      * @param y0 y-coordinate (0-63) of the center point
      * @param r radius of the circle
      * @param mode. Plot style mode: Normal (pixel is drawn), Inverse (pixel is erased), or Xor (pixel is erased if background position is already set, otherwise is drawn)
-     * @param refresh (optional) Force an actual screen redraw after scrolling
+     * @param refresh (optional) Force an actual screen redraw after drawing the shape
      */
     void circle (char x0, char y0, char r, PlotStyle mode, bool refresh=false);
     
+    /**
+     * Flood fills an area surrounded by the screen edge and/or a closed shape.
+     *
+     * @param x x-coordinate (0-127) of a point inside the area to fill, not plotted
+     * @param y y-coordinate (0-63) of a point inside the area to fill, not plotted
+     * @param refresh (optional) Force an actual screen redraw after the operation
+     */
+    void fill (char x, char y, bool refresh=false);
+    
     virtual ~SSD1306 () {
         if (!do_not_delete_bus)
             delete bus;