Merge pull request #11 from ThingPulse/master

upstream changes

Author: caveman99

.github/workflows/main.yml

@@ -13,26 +13,26 @@ jobs:
         example: [examples/SSD1306UiDemo, examples/SSD1306SimpleDemo, examples/SSD1306DrawingDemo, examples/SSD1306OTADemo, examples/SSD1306ClockDemo, examples/SSD1306TwoScreenDemo]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Cache pip
-      uses: actions/cache@v2
+      uses: actions/cache@v3
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
         restore-keys: ${{ runner.os }}-pip-
     - name: Cache PlatformIO
-      uses: actions/cache@v2
+      uses: actions/cache@v3
       with:
         path: ~/.platformio
         key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
     - name: Install PlatformIO
       run: |
         python -m pip install --upgrade pip
         pip install --upgrade platformio
     - name: Install library dependencies
-      run: pio lib -g install "paulstoffregen/Time@^1.6"
+      run: pio pkg install -g -l "paulstoffregen/Time@^1.6"
     - name: Run PlatformIO
       run: pio ci --lib="." --board=nodemcuv2 --board=d1_mini --board=esp-wrover-kit --board=esp32doit-devkit-v1
       env:

README.md

@@ -1,8 +1,9 @@
-[![Build Status](https://github.com/ThingPulse/esp8266-oled-ssd1306/actions/workflows/main.yml/badge.svg)](https://github.com/ThingPulse/esp8266-oled-ssd1306/actions)
-
 # ThingPulse OLED SSD1306 (ESP8266/ESP32/Mbed-OS)
 
-This is a driver for SSD1306 128x64, 128x32, 64x48 and 64x32 OLED displays running on the Arduino/ESP8266 & ESP32 and mbed-os platforms.
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/thingpulse/library/ESP8266%20and%20ESP32%20OLED%20driver%20for%20SSD1306%20displays.svg)](https://registry.platformio.org/libraries/thingpulse/ESP8266%20and%20ESP32%20OLED%20driver%20for%20SSD1306%20displays)
+[![Build Status](https://github.com/ThingPulse/esp8266-oled-ssd1306/actions/workflows/main.yml/badge.svg)](https://github.com/ThingPulse/esp8266-oled-ssd1306/actions)
+
+This is a driver for SSD1306 and SH1106 128x64, 128x32, 64x48 and 64x32 OLED displays running on the Arduino/ESP8266 & ESP32 and mbed-os platforms.
 Can be used with either the I2C or SPI version of the display.
 
 This library drives the OLED display included in the [ThingPulse IoT starter kit](https://thingpulse.com/product/esp8266-iot-electronics-starter-kit-weatherstation-planespotter-worldclock/) aka classic kit aka weather station kit.
@@ -261,6 +262,27 @@ void setTextAlignment(OLEDDISPLAY_TEXT_ALIGNMENT textAlignment);
 void setFont(const uint8_t* fontData);
 ```
 
+## Arduino `Print` functionality
+
+Because this class has been "derived" from Arduino's `Print` class, you can use the functions it provides. In plain language, this means that you can use `print`, `println` and `printf` to the display. Internally, a buffer holds the text that was printed to the display previously (that would still fit on the display) and every time you print something, this buffer is put on the screen, using the functions from the previous section.
+
+What that means is that printing using `print` and "manually" putting things on the display are somewhat mutually exclusive: as soon as you print, everything that was on the display already is gone and only what you put there before with `print`, `println` or `printf` remains. Still, using `print` is a very simple way to put something on the display quickly.
+
+One extra function is provided: `cls()`
+```cpp
+// cls() will clear the display immediately and empty the logBuffer, meaning
+// the next print statement will print at the top of the display again.
+// cls() should not be confused with clear(), which only clears the internal
+// graphics buffer, which can then be shown on the display with display().
+void cls();
+
+> _Note that printing to the display, contrary to what you might expect, does not wrap your lines, so everything on a line that doesn't fit on the screen is cut off._
+```
+
+ 
+
+<hr>
+
 ## Ui Library (OLEDDisplayUi)
 
 The Ui Library is used to provide a basic set of user interface elements called `Frames` and `Overlays`. A `Frame` is used to provide
@@ -401,6 +423,33 @@ OLEDDisplayUiState* getUiState();
 int8_t update();
 ```
 
+## Creating and using XBM bitmaps
+
+If you want to display your own images with this library, the best way to do this is using a bitmap.
+
+There are two options to convert an image to a compatible bitmap:
+1. **Using Gimp.**
+   In this case exporting the bitmap in an 1-bit XBM format is sufficient.
+2. **Using a converter website.**
+   You could also use online converter services like e.g. [https://javl.github.io/image2cpp/](https://javl.github.io/image2cpp/). The uploaded image should have the same dimension as the screen (e.g. 128x64). The following output settings should be set:
+    - Draw Mode: Horizontal - 1 bit per pixel
+    - Swap bits in byte: swap checkbox should be checked.
+
+The resulting bitmap can be put into a header file:
+```C++
+const unsigned char epd_example [] PROGMEM = {
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, ... 
+    ...
+};
+```
+
+Subsequently, it can be used like this:
+```C++
+display.clear();
+display.drawXbm(0, 0, 128, 64, epd_example); // assuming your bitmap is 128x64
+display.display();
+```
+
 ## Example: SSD1306Demo
 
 ### Frame 1

examples/SSD1306DrawingDemo/SSD1306DrawingDemo.ino

@@ -171,10 +171,6 @@ void drawCircle(void) {
 }
 
 void printBuffer(void) {
-  // Initialize the log buffer
-  // allocate memory to store 8 lines of text and 30 chars per line.
-  display.setLogBuffer(5, 30);
-
   // Some test data
   const char* test[] = {
     "Hello",
@@ -189,15 +185,10 @@ void printBuffer(void) {
     "scrolling is",
     "working"
   };
-
+  display.clear();
   for (uint8_t i = 0; i < 11; i++) {
-    display.clear();
     // Print to the screen
     display.println(test[i]);
-    // Draw it to the internal screen buffer
-    display.drawLogBuffer(0, 0);
-    // Display it on the screen
-    display.display();
     delay(500);
   }
 }

library.json

@@ -1,6 +1,6 @@
 {
   "name": "ESP8266 and ESP32 OLED driver for SSD1306 displays",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "keywords": "ssd1306, oled, display, i2c",
   "description": "I2C display driver for SSD1306 OLED displays connected to ESP8266, ESP32, Mbed-OS",
   "license": "MIT",

library.properties

@@ -1,5 +1,5 @@
 name=ESP8266 and ESP32 OLED driver for SSD1306 displays
-version=4.3.0
+version=4.4.1
 author=ThingPulse, Fabrice Weinberg
 maintainer=ThingPulse <info@thingpulse.com>
 sentence=I2C display driver for SSD1306 OLED displays connected to ESP8266, ESP32, Mbed-OS