Extracting HW specific code to a driver class

Adafruit_SSD1306.h

@@ -24,35 +24,39 @@
 #ifndef _Adafruit_SSD1306_H_
 #define _Adafruit_SSD1306_H_
 
-// ONE of the following three lines must be #defined:
-//#define SSD1306_128_64 ///< DEPRECTAED: old way to specify 128x64 screen
-#define SSD1306_128_32   ///< DEPRECATED: old way to specify 128x32 screen
-//#define SSD1306_96_16  ///< DEPRECATED: old way to specify 96x16 screen
-// This establishes the screen dimensions in old Adafruit_SSD1306 sketches
-// (NEW CODE SHOULD IGNORE THIS, USE THE CONSTRUCTORS THAT ACCEPT WIDTH
-// AND HEIGHT ARGUMENTS).
-
-#if defined(ARDUINO_STM32_FEATHER)
-  typedef class HardwareSPI SPIClass;
-#endif
-
-#include <Wire.h>
-#include <SPI.h>
-#include <Adafruit_GFX.h>
+/*=========================================================================
+    SSD1306 Displays
+    -------------------------------------------------------------------
+    SSD1306 display support communication over SPI and I2C interfaces.
+    In order to avoid bringing both SPI and I2C code to user firmware at the
+    same time (and therefore increasing firmware size and memory consumptuin)
+    hardware interaction is extracted to a driver. User can select which
+    driver to use according to hardware display connection. Moreover this 
+    simplifies porintg of the library code to other platforms - it just 
+    requires creation of a new driver, rather than patching the library.
+
+    Classes responsibilities:
+    - Adafruit_SSD1306 knows how to draw pixels (over Adafruit_GFX), knows
+      which commands shall be sent to the display, but the actual communication
+      is delegated to the driver. Adafruit_SSD1306 class does not have any
+      hardware specific code
+    - Driver knows how to initialize and then transfer data to the hardware
+
+    The library comes with a few drivers:
+    - SSD1306_I2C_Driver - for communication via hardware I2C
+    - SSD1306_SPI_Driver - for communication via hardware SPI
+    - SSD1306_SW_SPI_Driver - SPI interface software emulation (bitbanging)
+
+    Usage:
+        SSD1306_I2C_Driver i2c_driver(0x3C);
+        Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &i2c_driver);
+
+        display.begin();
+        display.draw...
+        display.display();
+  =========================================================================*/
 
-#if defined(__AVR__)
-  typedef volatile uint8_t  PortReg;
-  typedef uint8_t           PortMask;
-  #define HAVE_PORTREG
-#elif defined(__SAM3X8E__)
-  typedef volatile RwReg    PortReg;
-  typedef uint32_t          PortMask;
-  #define HAVE_PORTREG
-#elif defined(__arm__) || defined(ARDUINO_FEATHER52)
-  typedef volatile uint32_t PortReg;
-  typedef uint32_t          PortMask;
-  #define HAVE_PORTREG
-#endif
+#include <Adafruit_GFX.h>
 
 #define BLACK                          0 ///< Draw 'off' pixels
 #define WHITE                          1 ///< Draw 'on' pixels
@@ -94,45 +98,94 @@
 #define SSD1306_ACTIVATE_SCROLL                      0x2F ///< Start scroll
 #define SSD1306_SET_VERTICAL_SCROLL_AREA             0xA3 ///< Set scroll range
 
-// Deprecated size stuff for backwards compatibility with old sketches
-#if defined SSD1306_128_64
- #define SSD1306_LCDWIDTH  128 ///< DEPRECATED: width w/SSD1306_128_64 defined
- #define SSD1306_LCDHEIGHT  64 ///< DEPRECATED: height w/SSD1306_128_64 defined
-#endif
-#if defined SSD1306_128_32
- #define SSD1306_LCDWIDTH  128 ///< DEPRECATED: width w/SSD1306_128_32 defined
- #define SSD1306_LCDHEIGHT  32 ///< DEPRECATED: height w/SSD1306_128_32 defined
-#endif
-#if defined SSD1306_96_16
- #define SSD1306_LCDWIDTH   96 ///< DEPRECATED: width w/SSD1306_96_16 defined
- #define SSD1306_LCDHEIGHT  16 ///< DEPRECATED: height w/SSD1306_96_16 defined
-#endif
 
 /*! 
-    @brief  Class that stores state and functions for interacting with
-            SSD1306 OLED displays.
+    @brief  Hardware driver Interface 
+
+    The Adafruit_SSD1306 does not work directly with the hardware
+    All the communcation requests are forwarded to the driver which
+    actually communicate with the hardware. 
+*/
+class ISSD1306Driver
+{
+public:
+  /*!
+    @brief  Initialize display driver and hardware underneath
+
+    Adafruit_SSD1306 calls this method during its begin() method            
+  */
+  virtual void begin() = 0;
+
+  /*!
+    @brief  Prepare hardware for a communication transaction
+
+    Driver implementation may perform some communication preparations here, e.g.
+    set up a communication channel, prepare target device for the data transfer.
+  */
+  virtual void startTransaction() = 0;
+
+  /*!
+    @brief  Send a single command to the display
+
+    @param  cmd - A command to send    
+
+    @note   Because command calls are often grouped, a transaction and chip selection
+            must be started/ended using startTransaction()/endTransaction() functions
+            for efficiency.
+  */
+  virtual void sendCommand(uint8_t cmd) = 0;
+
+  /*!
+    @brief  Send multiple commands to the display
+
+    @param  cmds - Pointer to the commands list to send
+    @param  size - number of commands to send
+
+    @note   cmds is a pointer in program memory, not RAM. Implementation must 
+            read commands using pgm_read_byte
+    @note   Because command calls are often grouped, a transaction and chip selection
+            must be started/ended using startTransaction()/endTransaction() functions
+            for efficiency.
+  */
+  virtual void sendCommands(const uint8_t *cmds, size_t size) = 0;
+
+  /*!
+    @brief  Send data to the display
+
+    @param  data - Pointer to the data buffer to send
+    @param  size - number of commands to send
+
+    @note   c is a pointer RAM, not program memory.
+    @note   Because command calls are often grouped, a transaction and chip selection
+            must be started/ended using startTransaction()/endTransaction() functions
+            for efficiency.
+  */
+  virtual void sendData(const uint8_t * data, size_t size) = 0;
+
+  /*!
+    @brief Finalize communication transaction
+
+    Driver implementation may perform some communication finalization here, e.g.
+    deactivate communication channel, restore channel settings.
+  */
+  virtual void endTransaction() = 0;
+};
+
+
+/*! 
+    @brief  Class that holds a state and contains functions for interacting with
+            SSD1306 OLED displays over the supplied driver.
+
+    The Adafruit_SSD1306 class itself is hardware and platform independent. This class
+    implements communication logic with SSD1306 displays, while actuall communication with
+    the hardware is performed by the driver. 
 */
 class Adafruit_SSD1306 : public Adafruit_GFX {
  public:
-  // NEW CONSTRUCTORS -- recommended for new projects
-  Adafruit_SSD1306(uint8_t w, uint8_t h, TwoWire *twi=&Wire, int8_t rst_pin=-1,
-    uint32_t clkDuring=400000UL, uint32_t clkAfter=100000UL);
-  Adafruit_SSD1306(uint8_t w, uint8_t h, int8_t mosi_pin, int8_t sclk_pin,
-    int8_t dc_pin, int8_t rst_pin, int8_t cs_pin);
-  Adafruit_SSD1306(uint8_t w, uint8_t h, SPIClass *spi,
-    int8_t dc_pin, int8_t rst_pin, int8_t cs_pin, uint32_t bitrate=8000000UL);
-
-  // DEPRECATED CONSTRUCTORS - for back compatibility, avoid in new projects
-  Adafruit_SSD1306(int8_t mosi_pin, int8_t sclk_pin, int8_t dc_pin,
-    int8_t rst_pin, int8_t cs_pin);
-  Adafruit_SSD1306(int8_t dc_pin, int8_t rst_pin, int8_t cs_pin);
-  Adafruit_SSD1306(int8_t rst_pin = -1);
-
+  Adafruit_SSD1306(uint8_t w, uint8_t h, ISSD1306Driver * drv, uint8_t switchvcc=SSD1306_SWITCHCAPVCC);
   ~Adafruit_SSD1306(void);
 
-  boolean      begin(uint8_t switchvcc=SSD1306_SWITCHCAPVCC,
-                 uint8_t i2caddr=0, boolean reset=true,
-                 boolean periphBegin=true);
+  boolean      begin();
   void         display(void);
   void         clearDisplay(void);
   void         invertDisplay(boolean i);
@@ -150,30 +203,16 @@ class Adafruit_SSD1306 : public Adafruit_GFX {
   uint8_t     *getBuffer(void);
 
  private:
-  inline void  SPIwrite(uint8_t d) __attribute__((always_inline));
   void         drawFastHLineInternal(int16_t x, int16_t y, int16_t w,
                  uint16_t color);
   void         drawFastVLineInternal(int16_t x, int16_t y, int16_t h,
                  uint16_t color);
   void         ssd1306_command1(uint8_t c);
   void         ssd1306_commandList(const uint8_t *c, uint8_t n);
 
-  SPIClass    *spi;
-  TwoWire     *wire;
+  ISSD1306Driver * driver;
   uint8_t     *buffer;
-  int8_t       i2caddr, vccstate, page_end;
-  int8_t       mosiPin    ,  clkPin    ,  dcPin    ,  csPin, rstPin;
-#ifdef HAVE_PORTREG
-  PortReg     *mosiPort   , *clkPort   , *dcPort   , *csPort;
-  PortMask     mosiPinMask,  clkPinMask,  dcPinMask,  csPinMask;
-#endif
-#if defined(SPI_HAS_TRANSACTION)
-  SPISettings  spiSettings;
-#endif
-#if ARDUINO >= 157
-  uint32_t     wireClk;    // Wire speed for SSD1306 transfers
-  uint32_t     restoreClk; // Wire speed following SSD1306 transfers
-#endif
+  int8_t       vccstate;
 };
 
 #endif // _Adafruit_SSD1306_H_

README.md

@@ -26,6 +26,32 @@ Version 1.2 (November 2018) introduces some significant changes:
   * SPI transactions are used and SPI bitrate can be specified (both require Arduino 1.6 or later).
   * SPI and Wire (I2C) interfaces other than the defaults are supported.
 
+Version 1.10 (2019) introduces another significant changes:
+
+  * All hadrware communication moved to a driver class, while main Adafruit_SSD1306 class focuses on the display logic. This significantly improves internal library architecture, and reduces memory footprint as unused interfaces do not compile. 
+    Thus if the display is connected via SPI, the I2C related code is not even compiled into the program. 
+  * The change requires minor adjustments in the user sketch as follows
+
+Prior the change:
+```
+Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
+...
+display.begin(SSD1306_SWITCHCAPVCC, 0x3D)
+```
+
+Now:
+```
+#include <ssd1306_i2c_driver.h>
+SSD1306_I2C_Driver i2c_driver(0x3D, OLED_RESET); // initialize with the I2C addr 0x3D (for the 128x64)
+Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &i2c_driver);
+...
+display.begin(SSD1306_SWITCHCAPVCC)
+
+```
+
+See examples and header files for more details
+
+
 <!-- START COMPATIBILITY TABLE -->
 
 ## Compatibility
@@ -42,6 +68,8 @@ ATSAM21D    |      X     |            |          |
 Intel Curie |      X     |            |          |
 WICED       |      X     |            |          | No hardware SPI - bitbang only
 ATtiny85    |            |      X     |          |
+STM32F1     |      X     |            |          | Tested with STM32GENERIC and stm32duino
+
 
   * ATmega328 : Arduino UNO, Adafruit Pro Trinket, Adafruit Metro 328, Adafruit Metro Mini
   * ATmega32u4 : Arduino Leonardo, Arduino Micro, Arduino Yun, Teensy 2.0, Adafruit Flora, Bluefruit Micro
@@ -50,5 +78,6 @@ ATtiny85    |            |      X     |          |
   * ATSAM3X8E : Arduino Due
   * ATSAM21D : Arduino Zero, M0 Pro, Adafruit Metro Express, Feather M0
   * ATtiny85 : Adafruit Gemma, Arduino Gemma, Adafruit Trinket
+  * STM32F1: Blue Pill board (STM32F103C8)
 
 <!-- END COMPATIBILITY TABLE -->

examples/OLED_featherwing/OLED_featherwing.ino

@@ -2,8 +2,10 @@
 #include <Wire.h>
 #include <Adafruit_GFX.h>
 #include <Adafruit_SSD1306.h>
+#include <ssd1306_i2c_driver.h>
 
-Adafruit_SSD1306 display = Adafruit_SSD1306(128, 32, &Wire);
+SSD1306_I2C_Driver i2c_driver(0x3C);  // Address 0x3C for 128x32
+Adafruit_SSD1306 display = Adafruit_SSD1306(128, 32, &i2c_driver);
 
 // OLED FeatherWing buttons map to different pins depending on board:
 #if defined(ESP8266)
@@ -36,8 +38,8 @@ void setup() {
   Serial.begin(9600);
 
   Serial.println("OLED FeatherWing test");
-  // SSD1306_SWITCHCAPVCC = generate display voltage from 3.3V internally
-  display.begin(SSD1306_SWITCHCAPVCC, 0x3C); // Address 0x3C for 128x32
+
+  display.begin();
 
   Serial.println("OLED begun");
 

examples/ssd1306_128x32_i2c/ssd1306_128x32_i2c.ino

@@ -18,17 +18,19 @@
  included in any redistribution.
  **************************************************************************/
 
-#include <SPI.h>
 #include <Wire.h>
 #include <Adafruit_GFX.h>
 #include <Adafruit_SSD1306.h>
+#include <ssd1306_i2c_driver.h>
 
 #define SCREEN_WIDTH 128 // OLED display width, in pixels
 #define SCREEN_HEIGHT 32 // OLED display height, in pixels
 
+
 // Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)
 #define OLED_RESET     4 // Reset pin # (or -1 if sharing Arduino reset pin)
-Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
+SSD1306_I2C_Driver i2c_driver(0x3C, OLED_RESET); // initialize with the I2C addr 0x3C (for the 128x32)
+Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &i2c_driver);
 
 #define NUMFLAKES     10 // Number of snowflakes in the animation example
 
@@ -55,8 +57,7 @@ static const unsigned char PROGMEM logo_bmp[] =
 void setup() {
   Serial.begin(9600);
 
-  // SSD1306_SWITCHCAPVCC = generate display voltage from 3.3V internally
-  if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { // Address 0x3C for 128x32
+  if(!display.begin()) {
     Serial.println(F("SSD1306 allocation failed"));
     for(;;); // Don't proceed, loop forever
   }

examples/ssd1306_128x32_spi/ssd1306_128x32_spi.ino

@@ -4,7 +4,7 @@
  Pick one up today in the adafruit shop!
  ------> http://www.adafruit.com/category/63_98
 
- This example is for a 128x32 pixel display using SPI to communicate
+ This example is for a 128x64 pixel display using SPI to communicate
  4 or 5 pins are required to interface.
 
  Adafruit invests time and resources providing this open
@@ -24,25 +24,29 @@
 #include <Adafruit_SSD1306.h>
 
 #define SCREEN_WIDTH 128 // OLED display width, in pixels
-#define SCREEN_HEIGHT 32 // OLED display height, in pixels
+#define SCREEN_HEIGHT 64 // OLED display height, in pixels
 
+#include <ssd1306_sw_spi_driver.h>
 // Declaration for SSD1306 display connected using software SPI (default case):
 #define OLED_MOSI   9
 #define OLED_CLK   10
 #define OLED_DC    11
 #define OLED_CS    12
 #define OLED_RESET 13
-Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT,
-  OLED_MOSI, OLED_CLK, OLED_DC, OLED_RESET, OLED_CS);
+SSD1306_SW_SPI_Driver spi_driver(OLED_MOSI, OLED_CLK, OLED_DC, OLED_CS, OLED_RESET);
+Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &spi_driver);
 
-/* Comment out above, uncomment this block to use hardware SPI
+/*
+#include <ssd1306_spi_driver.h>
+// Alternatively you may use hardware SPI which is much faster
 #define OLED_DC     6
 #define OLED_CS     7
 #define OLED_RESET  8
-Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT,
-  &SPI, OLED_DC, OLED_RESET, OLED_CS);
+SSD1306_SPI_Driver spi_driver(OLED_DC, OLED_CS, OLED_RESET);
+Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &spi_driver);
 */
 
+
 #define NUMFLAKES     10 // Number of snowflakes in the animation example
 
 #define LOGO_HEIGHT   16
@@ -68,12 +72,12 @@ static const unsigned char PROGMEM logo_bmp[] =
 void setup() {
   Serial.begin(9600);
 
-  // SSD1306_SWITCHCAPVCC = generate display voltage from 3.3V internally
-  if(!display.begin(SSD1306_SWITCHCAPVCC)) {
+  if(!display.begin()) {
     Serial.println(F("SSD1306 allocation failed"));
     for(;;); // Don't proceed, loop forever
   }
 
+
   // Show initial display buffer contents on the screen --
   // the library initializes this with an Adafruit splash screen.
   display.display();