Skip to content

Commit 4f931b5

Browse files
tenbahttenbaht
committed
modified the oled ssd1306 library to use a more OO-like API and updated documentation
1 parent 597cfff commit 4f931b5

15 files changed

Lines changed: 495 additions & 254 deletions

File tree

‎docs/api/LiquidCrystal.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,6 @@ Arduino syntax |sduino syntax
103103

104104
## Possible improvements
105105

106-
107106
### Direct port access
108107
As long as the pin numberings are known at compile time it would be possible
109108
use direct port register access and the access pattern could be optimized if
@@ -117,3 +116,6 @@ assume 4-bit mode.
117116

118117
As init() is not called very frequently the possible advantage would be small
119118
compared to the downside of breaking the Arduino compatibility.
119+
120+
121+
[Back to the main page](../index.html)

‎docs/api/Mini_SSD1306.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Mini_SSD1306
2+
3+
This is a library for monochrome OLEDs based on SSD1306 drivers.
4+
5+
This library is a stripped-down version of the original
6+
[Adafruit_SSD1306 library](https://github.com/adafruit/Adafruit_SSD1306)
7+
v1.1.2.
8+
This version of the library does not depend on the Adafruit_GFX library and
9+
has a _much_ smaller memory footprint than the full version, but most of the
10+
graphical features are missing.
11+
12+
The Library only supports I2C communication.
13+
14+
15+
16+
## API
17+
18+
```c
19+
SSD1306(instancename, pin_reset);
20+
21+
void Mini_SSD1306_begin(uint8_t switchvcc, uint8_t i2caddr, bool reset);
22+
void Mini_SSD1306_clearDisplay(void);
23+
void Mini_SSD1306_invertDisplay(uint8_t i);
24+
void Mini_SSD1306_display();
25+
void Mini_SSD1306_startscrollright(uint8_t start, uint8_t stop);
26+
void Mini_SSD1306_startscrollleft(uint8_t start, uint8_t stop);
27+
void Mini_SSD1306_startscrolldiagright(uint8_t start, uint8_t stop);
28+
void Mini_SSD1306_startscrolldiagleft(uint8_t start, uint8_t stop);
29+
void Mini_SSD1306_stopscroll(void);
30+
void Mini_SSD1306_dim(boolean dim);
31+
void Mini_SSD1306_drawPixel(int16_t x, int16_t y, uint8_t color);
32+
```
33+
34+
35+
36+
## Example
37+
38+
The library initializes the display buffer with the Adafruit splash screen.
39+
Since it is not modified, `oled_display()` shows it. The loop draws a
40+
pattern of blinking pixels in an 8x8 grid:
41+
42+
```c
43+
#include "I2C.h"
44+
#include "Mini_SSD1306.h"
45+
46+
Mini_SSD1306(oled,-1); // -1 means no reset pin
47+
48+
#if (SSD1306_LCDHEIGHT != 64)
49+
#error("Height incorrect, please fix Mini_SSD1306.h!");
50+
#endif
51+
52+
void setup()
53+
{
54+
// Initialize with the I2C addr 0x3C. Some displays use 0x3D instead.
55+
oled_begin(SSD1306_SWITCHCAPVCC, 0x3C,0);
56+
}
57+
58+
void loop()
59+
{
60+
uint8_t x,y;
61+
62+
oled_display(); // show the display buffer
63+
delay (1000);
64+
65+
// draw some dots in an 8x8 pattern
66+
for (x=0; x<WIDTH; x+=8)
67+
{
68+
for (y=0; y<HEIGHT-8; y+=8) // don't alter the stack!
69+
{
70+
oled_drawPixel(x,y,INVERSE);
71+
}
72+
}
73+
}
74+
```
75+
76+
77+
## Hardware requirements
78+
79+
These tiny displays communicate usually via I2C, but SPI version do exist.
80+
My display uses the I2C address 0x3C, but there are similar displays out
81+
there configured to use the address 0x3D.
82+
83+
The display content has to be kept in memory as it is not possible to read
84+
the memory content of the physical display. For 128x64 pixel this requires
85+
1kB of RAM. For low-memory devices like the STM8S103 it means the display
86+
buffer overlaps with the stack. Notice the chaotic pattern in the lower part
87+
of the screen:
88+
89+
![My 0.96" OLED display](oled-ssd1306.jpg)
90+
91+
Technical data:
92+
* Driver chip SSD1306
93+
* Display resolution: 128x64
94+
* Power: 3.3V, approx. 20mA (5V possible)
95+
* Interface: I2C, some modules support SPI as well
96+
* I2C-Address: 0x3c, configurable to 0x3d by setting a solder bridge (on
97+
some modules)
98+
99+
Pin out of an I2C module:
100+
101+
Pin |Function|STM8S103 pin |sduino pin
102+
--- |-------|------------- |----------
103+
1 |GND | |
104+
2 |Vcc | |
105+
3 |SCL |PB4 |PIN_WIRE_SCL, SCL, 4
106+
4 |SDA |PB5 |PIN_WIRE_SDA, SDA, 3
107+
108+
109+
## Further reading
110+
111+
Technical information:
112+
* Adafruit tutorial: https://learn.adafruit.com/monochrome-oled-breakouts
113+
* SSD1306 datasheet: https://www.adafruit.com/datasheets/SSD1306.pdf
114+
115+
Other libraries:
116+
* Adafruit library: https://github.com/adafruit/Adafruit_SSD1306
117+
* Old Arduino library u8glib: https://github.com/olikraus/u8glib
118+
* newer library u8g2: https://github.com/olikraus/u8g2
119+
120+
121+
## Possible improvements
122+
123+
### Faster I2C transfer
124+
125+
Faster I2C transfer is supported by the [I2C.html](I2C library), but to use
126+
it you have to modify the source code for the Mini_SSD1306 library. Make
127+
this configurable in the instantiation function.
128+
129+
130+
131+
132+
[Back to the main page](../index.html)

‎docs/api/PCD8544.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,3 +149,5 @@ of this function.
149149
To make it easy to create custom symbols, there's a
150150
graphical glyph editor [available online](http://carlosefr.github.io/pcd8544/).
151151
152+
153+
[Back to the main page](../index.html)

‎docs/api/Servo.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,3 +158,4 @@ timer TIM1. Monitoring the repetion period might become a little complex, as
158158
it must be ensured that all servos on all channels have finshed before.
159159

160160

161+
[Back to the main page](../index.html)

‎docs/api/Stepper.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,3 +124,5 @@ void Stepper_step(Stepper this, int number_of_steps);
124124
// (not so) private:
125125
void Stepper_stepMotor(Stepper s, int this_step);
126126
```
127+
128+
[Back to the main page](../index.html)

‎docs/api/oled-ssd1306.jpg‎

80.7 KB
Loading

‎docs/hardware.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Supported hardware
2+
3+
No text yet. Check out these pages:
4+
5+
* [stm8blue: simple breakout board, STM8S103](hardware/stm8blue.html)
6+
* [ESP14: Wifi board, STM8S003](hardware/esp14.html)
7+
* [STM8S105Discovery: Evaluation board made my ST](hardware/stm8disco.html)

‎docs/index.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,12 +41,13 @@ http://www.aliexpress.com/ .
4141
with github pages and the preinstalled jekyll-themes?)
4242

4343
1. [Introduction and Overview](index.html)
44-
2. [API and migration guidelines](api.html)
44+
2. [API descriptions and migration guidelines](api.html)
4545
* [LiquidCrystal character LCD library](api/LiquidCrystal.html)
4646
* [PCD8544 libray for Nokia 5110-like graphical LCDs](api/PCD8544.html)
47+
* [Mini_SSD1306 library for monochrome OLED-displays](api/Mini_SSD1306.html)
4748
* [Stepper library](api/Stepper.html)
4849
* [Servo library](api/Servo.html)
49-
3. [Supported Boards]()
50+
3. [Supported Boards](hardware.html)
5051
* [stm8blue: simple breakout board, STM8S103](hardware/stm8blue.html)
5152
* [ESP14: Wifi board, STM8S003](hardware/esp14.html)
5253
* [STM8S105Discovery: Evaluation board made my ST](hardware/stm8disco.html)
@@ -299,12 +300,13 @@ Supports monochrome graphical LCD based on the PCD8544 controller like the
299300
popular Nokia N5110 display. Only SPI mode supported. The library is a very
300301
much simpified version of the Adafruit library optimized for a minimal memory
301302
footprint. Uses soft-SPI, does not need the SPI pins.
303+
[API description](api/PCD8544.html)
302304

303305

304-
#### ssd1306
306+
#### Mini_SSD1306
305307
Driver for SSD1306-based monochrome OLED display with 128x64
306-
pixels. I2C support only. Based on the Adafruit-libray.
307-
308+
pixels. I2C support only. Based on the Adafruit-libray Adafruit_SSD1306.
309+
[API description](api/Mini_SSD.html)
308310

309311

310312
### Motor

sduino/hardware/sduino/stm8/libraries/ssd1306/ssd1306.c renamed to sduino/hardware/sduino/stm8/libraries/Mini_SSD1306/Mini_SSD1306.c

Lines changed: 13 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,3 @@
1-
/*
2-
* This is an example for using the i2c library with a monochrome OLED
3-
* display based on SSD1306 drivers.
4-
*
5-
* The display has 128x64 pixel and uses only SCL and SDA for communication,
6-
* there is no reset pin.
7-
*
8-
* The framebuffer needs to be kept in RAM as reading the display is not
9-
* supported by the driver chips. Since the STM8S103F3 has only 1kB RAM
10-
* total, we will see the stack contents in the lower part of the display
11-
* as a wild bit pattern. Using drawPixel() on this memory would mess up
12-
* the stack contents and would result in an immediate crash. So don't
13-
* use the lower lines on low memory devices!
14-
*
15-
* This code is adopted from the Adafruit example code contained in the
16-
* Adafruit_SSD1306 library.
17-
*
18-
* modified 2017 by Michael Mayer
19-
*/
20-
21-
221
/*
232
* This is an example for using the i2c library with a monochrome OLED
243
* display based on SSD1306 drivers.
@@ -78,7 +57,7 @@ All text above, and the splash screen below must be included in any redistributi
7857
# define i2c_write(A,C,D) I2C_write_c(A,C,D)
7958
# define i2c_write_sn(A,C,B,N) I2C_write_sn(A,C,B,N)
8059
#endif
81-
#include "ssd1306.h"
60+
#include "Mini_SSD1306.h"
8261

8362
// private:
8463
static int8_t _i2caddr, _vccstate, sid, sclk, dc, rst, cs;
@@ -171,7 +150,7 @@ static void ssd1306_command(uint8_t c);
171150

172151

173152
// the most basic function, set a single pixel
174-
void drawPixel(int16_t x, int16_t y, uint8_t color) {
153+
void Mini_SSD1306_drawPixel(int16_t x, int16_t y, uint8_t color) {
175154
// if ((x < 0) || (x >= width()) || (y < 0) || (y >= height()))
176155
// return;
177156

@@ -202,13 +181,13 @@ void drawPixel(int16_t x, int16_t y, uint8_t color) {
202181
}
203182

204183
// initializer for I2C - we only indicate the reset pin!
205-
void display_init(int8_t reset) {
184+
void Mini_SSD1306_init(int8_t reset) {
206185
sclk = dc = cs = sid = -1;
207186
rst = reset;
208187
}
209188

210189
#if 1
211-
void display_begin(uint8_t vccstate, uint8_t i2caddr, bool reset) {
190+
void Mini_SSD1306_begin(uint8_t vccstate, uint8_t i2caddr, bool reset) {
212191
_vccstate = vccstate;
213192
_i2caddr = i2caddr;
214193

@@ -295,7 +274,7 @@ void display_begin(uint8_t vccstate, uint8_t i2caddr, bool reset) {
295274
}
296275
#endif
297276

298-
void display_invertDisplay(uint8_t i) {
277+
void Mini_SSD1306_invertDisplay(uint8_t i) {
299278
if (i) {
300279
ssd1306_command(SSD1306_INVERTDISPLAY);
301280
} else {
@@ -324,7 +303,7 @@ static void ssd1306_command(uint8_t c) {
324303
// Activate a right handed scroll for rows start through stop
325304
// Hint, the display is 16 rows tall. To scroll the whole display, run:
326305
// display.scrollright(0x00, 0x0F)
327-
void display_startscrollright(uint8_t start, uint8_t stop){
306+
void Mini_SSD1306_startscrollright(uint8_t start, uint8_t stop){
328307
ssd1306_command(SSD1306_RIGHT_HORIZONTAL_SCROLL);
329308
ssd1306_command(0X00);
330309
ssd1306_command(start);
@@ -339,7 +318,7 @@ void display_startscrollright(uint8_t start, uint8_t stop){
339318
// Activate a right handed scroll for rows start through stop
340319
// Hint, the display is 16 rows tall. To scroll the whole display, run:
341320
// display.scrollright(0x00, 0x0F)
342-
void display_startscrollleft(uint8_t start, uint8_t stop){
321+
void Mini_SSD1306_startscrollleft(uint8_t start, uint8_t stop){
343322
ssd1306_command(SSD1306_LEFT_HORIZONTAL_SCROLL);
344323
ssd1306_command(0X00);
345324
ssd1306_command(start);
@@ -354,7 +333,7 @@ void display_startscrollleft(uint8_t start, uint8_t stop){
354333
// Activate a diagonal scroll for rows start through stop
355334
// Hint, the display is 16 rows tall. To scroll the whole display, run:
356335
// display.scrollright(0x00, 0x0F)
357-
void display_startscrolldiagright(uint8_t start, uint8_t stop){
336+
void Mini_SSD1306_startscrolldiagright(uint8_t start, uint8_t stop){
358337
ssd1306_command(SSD1306_SET_VERTICAL_SCROLL_AREA);
359338
ssd1306_command(0X00);
360339
ssd1306_command(SSD1306_LCDHEIGHT);
@@ -371,7 +350,7 @@ void display_startscrolldiagright(uint8_t start, uint8_t stop){
371350
// Activate a diagonal scroll for rows start through stop
372351
// Hint, the display is 16 rows tall. To scroll the whole display, run:
373352
// display.scrollright(0x00, 0x0F)
374-
void display_startscrolldiagleft(uint8_t start, uint8_t stop){
353+
void Mini_SSD1306_startscrolldiagleft(uint8_t start, uint8_t stop){
375354
ssd1306_command(SSD1306_SET_VERTICAL_SCROLL_AREA);
376355
ssd1306_command(0X00);
377356
ssd1306_command(SSD1306_LCDHEIGHT);
@@ -384,14 +363,14 @@ void display_startscrolldiagleft(uint8_t start, uint8_t stop){
384363
ssd1306_command(SSD1306_ACTIVATE_SCROLL);
385364
}
386365

387-
void display_stopscroll(void){
366+
void Mini_SSD1306_stopscroll(void){
388367
ssd1306_command(SSD1306_DEACTIVATE_SCROLL);
389368
}
390369

391370
// Dim the display
392371
// dim = true: display is dimmed
393372
// dim = false: display is normal
394-
void display_dim(boolean dim) {
373+
void Mini_SSD1306_dim(boolean dim) {
395374
uint8_t contrast;
396375

397376
if (dim) {
@@ -410,7 +389,7 @@ void display_dim(boolean dim) {
410389
}
411390

412391

413-
void display_display(void) {
392+
void Mini_SSD1306_display(void) {
414393
ssd1306_command(SSD1306_COLUMNADDR);
415394
ssd1306_command(0); // Column start address (0 = reset)
416395
ssd1306_command(SSD1306_LCDWIDTH-1); // Column end address (127 = reset)
@@ -449,6 +428,6 @@ void display_display(void) {
449428
}
450429

451430
// clear everything
452-
void display_clearDisplay(void) {
431+
void Mini_SSD1306_clearDisplay(void) {
453432
memset(buffer, 0, (SSD1306_LCDWIDTH*SSD1306_LCDHEIGHT/8));
454433
}

0 commit comments

Comments
 (0)