From b01f5e17312121b8c4347f18650955a5eaa33965 Mon Sep 17 00:00:00 2001 From: "Limor \"Ladyada\" Fried" Date: Sat, 16 May 2020 00:45:51 -0400 Subject: [PATCH] Generic mono oled support (#289) * initial monooled * i2c basic support * add dep * fix warnings * doxy * dirty rects if u pleeeze * reset *before* trying to connect to i2c * fix up SPI mode! * cllang * doxy --- Adafruit_MonoOLED.cpp | 398 ++++++++++++++++++++++++++++++++++++++++++ Adafruit_MonoOLED.h | 98 +++++++++++ library.properties | 2 +- 3 files changed, 497 insertions(+), 1 deletion(-) create mode 100644 Adafruit_MonoOLED.cpp create mode 100644 Adafruit_MonoOLED.h diff --git a/Adafruit_MonoOLED.cpp b/Adafruit_MonoOLED.cpp new file mode 100644 index 0000000..34ddf17 --- /dev/null +++ b/Adafruit_MonoOLED.cpp @@ -0,0 +1,398 @@ +/*! + * @file Adafruit_MonoOLED.cpp + * + * This is documentation for Adafruit's generic library for monochrome + * OLED displays: http://www.adafruit.com/category/63_98 + * + * These displays use I2C or SPI to communicate. I2C requires 2 pins + * (SCL+SDA) and optionally a RESET pin. SPI requires 4 pins (MOSI, SCK, + * select, data/command) and optionally a reset pin. Hardware SPI or + * 'bitbang' software SPI are both supported. + * + * Adafruit invests time and resources providing this open source code, + * please support Adafruit and open-source hardware by purchasing + * products from Adafruit! + * + */ + +#include "Adafruit_MonoOLED.h" +#include + +// SOME DEFINES AND STATIC VARIABLES USED INTERNALLY ----------------------- + +#define monooled_swap(a, b) \ + (((a) ^= (b)), ((b) ^= (a)), ((a) ^= (b))) ///< No-temp-var swap operation + +// CONSTRUCTORS, DESTRUCTOR ------------------------------------------------ + +/*! + @brief Constructor for I2C-interfaced OLED displays. + @param w + Display width in pixels + @param h + Display height in pixels + @param twi + Pointer to an existing TwoWire instance (e.g. &Wire, the + microcontroller's primary I2C bus). + @param rst_pin + Reset pin (using Arduino pin numbering), or -1 if not used + (some displays might be wired to share the microcontroller's + reset pin). + @param clkDuring + Speed (in Hz) for Wire transmissions in library calls. + Defaults to 400000 (400 KHz), a known 'safe' value for most + microcontrollers, and meets the OLED datasheet spec. + Some systems can operate I2C faster (800 KHz for ESP32, 1 MHz + for many other 32-bit MCUs), and some (perhaps not all) + Many OLED's can work with this -- so it's optionally be specified + here and is not a default behavior. (Ignored if using pre-1.5.7 + Arduino software, which operates I2C at a fixed 100 KHz.) + @param clkAfter + Speed (in Hz) for Wire transmissions following library + calls. Defaults to 100000 (100 KHz), the default Arduino Wire + speed. This is done rather than leaving it at the 'during' speed + because other devices on the I2C bus might not be compatible + with the faster rate. (Ignored if using pre-1.5.7 Arduino + software, which operates I2C at a fixed 100 KHz.) + @note Call the object's begin() function before use -- buffer + allocation is performed there! +*/ +Adafruit_MonoOLED::Adafruit_MonoOLED(uint16_t w, uint16_t h, TwoWire *twi, + int8_t rst_pin, uint32_t clkDuring, + uint32_t clkAfter) + : Adafruit_GFX(w, h), buffer(NULL), dcPin(-1), csPin(-1), rstPin(rst_pin), + i2c_preclk(clkDuring), i2c_postclk(clkAfter) { + i2c_dev = NULL; + _theWire = twi; +} + +/*! + @brief Constructor for SPI MonoOLED displays, using software (bitbang) + SPI. + @param w + Display width in pixels + @param h + Display height in pixels + @param mosi_pin + MOSI (master out, slave in) pin (using Arduino pin numbering). + This transfers serial data from microcontroller to display. + @param sclk_pin + SCLK (serial clock) pin (using Arduino pin numbering). + This clocks each bit from MOSI. + @param dc_pin + Data/command pin (using Arduino pin numbering), selects whether + display is receiving commands (low) or data (high). + @param rst_pin + Reset pin (using Arduino pin numbering), or -1 if not used + (some displays might be wired to share the microcontroller's + reset pin). + @param cs_pin + Chip-select pin (using Arduino pin numbering) for sharing the + bus with other devices. Active low. + @note Call the object's begin() function before use -- buffer + allocation is performed there! +*/ +Adafruit_MonoOLED::Adafruit_MonoOLED(uint16_t w, uint16_t h, int8_t mosi_pin, + int8_t sclk_pin, int8_t dc_pin, + int8_t rst_pin, int8_t cs_pin) + : Adafruit_GFX(w, h), dcPin(dc_pin), csPin(cs_pin), rstPin(rst_pin) { + + spi_dev = new Adafruit_SPIDevice(cs_pin, sclk_pin, -1, mosi_pin, 1000000); +} + +/*! + @brief Constructor for SPI MonoOLED displays, using native hardware SPI. + @param w + Display width in pixels + @param h + Display height in pixels + @param spi + Pointer to an existing SPIClass instance (e.g. &SPI, the + microcontroller's primary SPI bus). + @param dc_pin + Data/command pin (using Arduino pin numbering), selects whether + display is receiving commands (low) or data (high). + @param rst_pin + Reset pin (using Arduino pin numbering), or -1 if not used + (some displays might be wired to share the microcontroller's + reset pin). + @param cs_pin + Chip-select pin (using Arduino pin numbering) for sharing the + bus with other devices. Active low. + @param bitrate + SPI clock rate for transfers to this display. Default if + unspecified is 8000000UL (8 MHz). + @note Call the object's begin() function before use -- buffer + allocation is performed there! +*/ +Adafruit_MonoOLED::Adafruit_MonoOLED(uint16_t w, uint16_t h, SPIClass *spi, + int8_t dc_pin, int8_t rst_pin, + int8_t cs_pin, uint32_t bitrate) + : Adafruit_GFX(w, h), dcPin(dc_pin), csPin(cs_pin), rstPin(rst_pin) { + + spi_dev = new Adafruit_SPIDevice(cs_pin, bitrate, SPI_BITORDER_MSBFIRST, + SPI_MODE0, spi); +} + +/*! + @brief Destructor for Adafruit_MonoOLED object. +*/ +Adafruit_MonoOLED::~Adafruit_MonoOLED(void) { + if (buffer) { + free(buffer); + buffer = NULL; + } + if (spi_dev) + delete spi_dev; + if (i2c_dev) + delete i2c_dev; +} + +// LOW-LEVEL UTILS --------------------------------------------------------- + +/*! + @brief Issue single command byte to OLED, using I2C or hard/soft SPI as + needed. + @param c The single byte command +*/ +void Adafruit_MonoOLED::oled_command(uint8_t c) { + if (i2c_dev) { // I2C + uint8_t buf[2] = {0x00, c}; // Co = 0, D/C = 0 + i2c_dev->write(buf, 2); + } else { // SPI (hw or soft) -- transaction started in calling function + digitalWrite(dcPin, LOW); + spi_dev->write(&c, 1); + } +} + +// Issue list of commands to MonoOLED +/*! + @brief Issue multiple bytes of commands OLED, using I2C or hard/soft SPI as + needed. + @param c Pointer to the command array + @param n The number of bytes in the command array + @returns True for success on ability to write the data in I2C. +*/ + +bool Adafruit_MonoOLED::oled_commandList(const uint8_t *c, uint8_t n) { + if (i2c_dev) { // I2C + uint8_t dc_byte = 0x00; // Co = 0, D/C = 0 + if (!i2c_dev->write((uint8_t *)c, n, true, &dc_byte, 1)) { + return false; + } + } else { // SPI -- transaction started in calling function + digitalWrite(dcPin, LOW); + if (!spi_dev->write((uint8_t *)c, n)) { + return false; + } + } + return true; +} + +// ALLOCATE & INIT DISPLAY ------------------------------------------------- + +/*! + @brief Allocate RAM for image buffer, initialize peripherals and pins. + Note that subclasses must call this before other begin() init + @param addr + I2C address of corresponding oled display. + SPI displays (hardware or software) do not use addresses, but + this argument is still required. Default if unspecified is 0x3C. + @param reset + If true, and if the reset pin passed to the constructor is + valid, a hard reset will be performed before initializing the + display. If using multiple oled displays on the same bus, and + if they all share the same reset pin, you should only pass true + on the first display being initialized, false on all others, + else the already-initialized displays would be reset. Default if + unspecified is true. + @return true on successful allocation/init, false otherwise. + Well-behaved code should check the return value before + proceeding. + @note MUST call this function before any drawing or updates! +*/ +bool Adafruit_MonoOLED::_init(uint8_t addr, boolean reset) { + + // attempt to malloc the bitmap framebuffer + if ((!buffer) && !(buffer = (uint8_t *)malloc(WIDTH * ((HEIGHT + 7) / 8)))) { + return false; + } + + // Reset OLED if requested and reset pin specified in constructor + if (reset && (rstPin >= 0)) { + pinMode(rstPin, OUTPUT); + digitalWrite(rstPin, HIGH); + delay(10); // VDD goes high at start, pause + digitalWrite(rstPin, LOW); // Bring reset low + delay(10); // Wait 10 ms + digitalWrite(rstPin, HIGH); // Bring out of reset + delay(10); + } + + // Setup pin directions + if (_theWire) { // using I2C + i2c_dev = new Adafruit_I2CDevice(addr, _theWire); + // look for i2c address: + if (!i2c_dev || !i2c_dev->begin()) { + return false; + } + } else { // Using one of the SPI modes, either soft or hardware + if (!spi_dev || !spi_dev->begin()) { + return false; + } + pinMode(dcPin, OUTPUT); // Set data/command pin as output + } + + clearDisplay(); + + // set max dirty window + window_x1 = 0; + window_y1 = 0; + window_x2 = WIDTH - 1; + window_y2 = HEIGHT - 1; + + return true; // Success +} + +// DRAWING FUNCTIONS ------------------------------------------------------- + +/*! + @brief Set/clear/invert a single pixel. This is also invoked by the + Adafruit_GFX library in generating many higher-level graphics + primitives. + @param x + Column of display -- 0 at left to (screen width - 1) at right. + @param y + Row of display -- 0 at top to (screen height -1) at bottom. + @param color + Pixel color, one of: MONOOLED_BLACK, MONOOLED_WHITE or + MONOOLED_INVERT. + @return None (void). + @note Changes buffer contents only, no immediate effect on display. + Follow up with a call to display(), or with other graphics + commands as needed by one's own application. +*/ +void Adafruit_MonoOLED::drawPixel(int16_t x, int16_t y, uint16_t color) { + if ((x >= 0) && (x < width()) && (y >= 0) && (y < height())) { + // Pixel is in-bounds. Rotate coordinates if needed. + switch (getRotation()) { + case 1: + monooled_swap(x, y); + x = WIDTH - x - 1; + break; + case 2: + x = WIDTH - x - 1; + y = HEIGHT - y - 1; + break; + case 3: + monooled_swap(x, y); + y = HEIGHT - y - 1; + break; + } + + // adjust dirty window + window_x1 = min(window_x1, x); + window_y1 = min(window_y1, y); + window_x2 = max(window_x2, x); + window_y2 = max(window_y2, y); + + switch (color) { + case MONOOLED_WHITE: + buffer[x + (y / 8) * WIDTH] |= (1 << (y & 7)); + break; + case MONOOLED_BLACK: + buffer[x + (y / 8) * WIDTH] &= ~(1 << (y & 7)); + break; + case MONOOLED_INVERSE: + buffer[x + (y / 8) * WIDTH] ^= (1 << (y & 7)); + break; + } + } +} + +/*! + @brief Clear contents of display buffer (set all pixels to off). + @return None (void). + @note Changes buffer contents only, no immediate effect on display. + Follow up with a call to display(), or with other graphics + commands as needed by one's own application. +*/ +void Adafruit_MonoOLED::clearDisplay(void) { + memset(buffer, 0, WIDTH * ((HEIGHT + 7) / 8)); + // set max dirty window + window_x1 = 0; + window_y1 = 0; + window_x2 = WIDTH - 1; + window_y2 = HEIGHT - 1; +} + +/*! + @brief Return color of a single pixel in display buffer. + @param x + Column of display -- 0 at left to (screen width - 1) at right. + @param y + Row of display -- 0 at top to (screen height -1) at bottom. + @return true if pixel is set (usually MONOOLED_WHITE, unless display invert + mode is enabled), false if clear (MONOOLED_BLACK). + @note Reads from buffer contents; may not reflect current contents of + screen if display() has not been called. +*/ +boolean Adafruit_MonoOLED::getPixel(int16_t x, int16_t y) { + if ((x >= 0) && (x < width()) && (y >= 0) && (y < height())) { + // Pixel is in-bounds. Rotate coordinates if needed. + switch (getRotation()) { + case 1: + monooled_swap(x, y); + x = WIDTH - x - 1; + break; + case 2: + x = WIDTH - x - 1; + y = HEIGHT - y - 1; + break; + case 3: + monooled_swap(x, y); + y = HEIGHT - y - 1; + break; + } + return (buffer[x + (y / 8) * WIDTH] & (1 << (y & 7))); + } + return false; // Pixel out of bounds +} + +/*! + @brief Get base address of display buffer for direct reading or writing. + @return Pointer to an unsigned 8-bit array, column-major, columns padded + to full byte boundary if needed. +*/ +uint8_t *Adafruit_MonoOLED::getBuffer(void) { return buffer; } + +// OTHER HARDWARE SETTINGS ------------------------------------------------- + +/*! + @brief Enable or disable display invert mode (white-on-black vs + black-on-white). Handy for testing! + @param i + If true, switch to invert mode (black-on-white), else normal + mode (white-on-black). + @return None (void). + @note This has an immediate effect on the display, no need to call the + display() function -- buffer contents are not changed, rather a + different pixel mode of the display hardware is used. When + enabled, drawing MONOOLED_BLACK (value 0) pixels will actually draw + white, MONOOLED_WHITE (value 1) will draw black. +*/ +void Adafruit_MonoOLED::invertDisplay(boolean i) { + oled_command(i ? MONOOLED_INVERTDISPLAY : MONOOLED_NORMALDISPLAY); +} + +/*! + @brief Adjust the display contrast. + @param level The contrast level from 0 to 0x7F + @return None (void). + @note This has an immediate effect on the display, no need to call the + display() function -- buffer contents are not changed. +*/ +void Adafruit_MonoOLED::setContrast(uint8_t level) { + uint8_t cmd[] = {MONOOLED_SETCONTRAST, level}; + oled_commandList(cmd, 2); +} diff --git a/Adafruit_MonoOLED.h b/Adafruit_MonoOLED.h new file mode 100644 index 0000000..9c0e147 --- /dev/null +++ b/Adafruit_MonoOLED.h @@ -0,0 +1,98 @@ +/*! + * @file Adafruit_MonoOLED.h + * + * This is part of for Adafruit's GFX library, supplying generic support + * for monochrome OLED displays: http://www.adafruit.com/category/63_98 + * + * These displays use I2C or SPI to communicate. I2C requires 2 pins + * (SCL+SDA) and optionally a RESET pin. SPI requires 4 pins (MOSI, SCK, + * select, data/command) and optionally a reset pin. Hardware SPI or + * 'bitbang' software SPI are both supported. + * + * Adafruit invests time and resources providing this open source code, + * please support Adafruit and open-source hardware by purchasing + * products from Adafruit! + * + * Written by Limor Fried/Ladyada for Adafruit Industries, with + * contributions from the open source community. + * + * BSD license, all text above, and the splash screen header file, + * must be included in any redistribution. + * + */ + +#ifndef _Adafruit_MONOOLED_H_ +#define _Adafruit_MONOOLED_H_ + +#include +#include +#include +#include +#include + +#define MONOOLED_BLACK 0 ///< Draw 'off' pixels +#define MONOOLED_WHITE 1 ///< Draw 'on' pixels +#define MONOOLED_INVERSE 2 ///< Invert pixels + +/// These seem to be common commands for OLEDs +#define MONOOLED_SETCONTRAST 0x81 ///< See datasheet +#define MONOOLED_NORMALDISPLAY 0xA6 ///< See datasheet +#define MONOOLED_INVERTDISPLAY 0xA7 ///< See datasheet +#define MONOOLED_DISPLAYOFF 0xAE ///< See datasheet +#define MONOOLED_DISPLAYON 0xAF ///< See datasheet + +/*! + @brief Class that stores state and functions for interacting with + generic monochrome OLED displays. +*/ +class Adafruit_MonoOLED : public Adafruit_GFX { +public: + Adafruit_MonoOLED(uint16_t w, uint16_t h, TwoWire *twi = &Wire, + int8_t rst_pin = -1, uint32_t preclk = 400000, + uint32_t postclk = 100000); + Adafruit_MonoOLED(uint16_t w, uint16_t h, int8_t mosi_pin, int8_t sclk_pin, + int8_t dc_pin, int8_t rst_pin, int8_t cs_pin); + Adafruit_MonoOLED(uint16_t w, uint16_t h, SPIClass *spi, int8_t dc_pin, + int8_t rst_pin, int8_t cs_pin, + uint32_t bitrate = 8000000UL); + + ~Adafruit_MonoOLED(void); + + /** + @brief The function that sub-classes define that writes out the buffer to + the display over I2C or SPI + **/ + virtual void display(void) = 0; + void clearDisplay(void); + void invertDisplay(boolean i); + void setContrast(uint8_t contrastlevel); + void drawPixel(int16_t x, int16_t y, uint16_t color); + boolean getPixel(int16_t x, int16_t y); + uint8_t *getBuffer(void); + + void oled_command(uint8_t c); + bool oled_commandList(const uint8_t *c, uint8_t n); + +protected: + bool _init(uint8_t i2caddr = 0x3C, boolean reset = true); + + Adafruit_SPIDevice *spi_dev = NULL; ///< The SPI interface BusIO device + Adafruit_I2CDevice *i2c_dev = NULL; ///< The I2C interface BusIO device + int32_t i2c_preclk = 400000, ///< Configurable 'high speed' I2C rate + i2c_postclk = 100000; ///< Configurable 'low speed' I2C rate + uint8_t *buffer = NULL; ///< Internal 1:1 framebuffer of display mem + + int16_t window_x1, ///< Dirty tracking window minimum x + window_y1, ///< Dirty tracking window minimum y + window_x2, ///< Dirty tracking window maximum x + window_y2; ///< Dirty tracking window maximum y + + int dcPin, ///< The Arduino pin connected to D/C (for SPI) + csPin, ///< The Arduino pin connected to CS (for SPI) + rstPin; ///< The Arduino pin connected to reset (-1 if unused) + +private: + TwoWire *_theWire = NULL; ///< The underlying hardware I2C +}; + +#endif // _Adafruit_MonoOLED_H_ diff --git a/library.properties b/library.properties index eedafee..2bc8406 100644 --- a/library.properties +++ b/library.properties @@ -7,4 +7,4 @@ paragraph=Install this library in addition to the display library for your hardw category=Display url=https://github.com/adafruit/Adafruit-GFX-Library architectures=* -depends=Adafruit ILI9341 +depends=Adafruit ILI9341, Adafruit BusIO