Skip to content

Commit 597cfff

Browse files
tenbahttenbaht
committed
change libray PCD8544 to a more OO-like API, add doc files
1 parent ecf7b30 commit 597cfff

9 files changed

Lines changed: 542 additions & 225 deletions

File tree

‎docs/api/LiquidCrystal.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# LiquidCrystal Library
2+
3+
This library is for character LCDs based on the HD44780 controller.
4+
Derived from the Arduino LiquidCrystal library v1.8.0.
5+
6+
7+
8+
## Example
9+
10+
Output some Text and count the time since the last reset. Mind the
11+
slightly different position of the opening parenthesis at the "class
12+
constructor" function LiquidCrystal_4bit_r compared to the C++ instatiation.
13+
14+
```c
15+
#include <Arduino.h>
16+
#include <LiquidCrystal.h>
17+
18+
// initialize the library with the numbers of the interface pins
19+
// The instance name "lcd" is _within_ the brackets
20+
LiquidCrystal_4bit_r (lcd,PA1,PA2, PA3,PD2,PD3,PD4);
21+
22+
void setup() {
23+
lcd_begin(16, 2);
24+
lcd_print_s("hello, world!");
25+
}
26+
27+
28+
void loop() {
29+
lcd_setCursor(0, 1);
30+
lcd_print_u(millis() / 1000);
31+
}
32+
```
33+
34+
35+
Original Arduino C++-Sytax:
36+
```c
37+
#include <LiquidCrystal.h>
38+
39+
// initialize the library with the numbers of the interface pins
40+
// The instance name "lcd" is _before_ the brackets
41+
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);
42+
43+
void setup() {
44+
lcd.begin(16, 2);
45+
lcd.print("hello, world!");
46+
}
47+
48+
void loop() {
49+
lcd.setCursor(0, 1);
50+
lcd.print(millis() / 1000);
51+
}
52+
```
53+
54+
55+
56+
## API
57+
58+
This library is a singleton library, it is not possible to use more than one
59+
instance per sketch.
60+
61+
The API syntax is very similar to the original C++ syntax, thanks to some
62+
[c preprocessor macro magic](macro.html).
63+
Apart from the usual name mangeling for polymorph functions replacing the
64+
dots in the method names for underscores and a small modification of the
65+
initializer code should be enough.
66+
67+
The polymorph instantiation method is split into for different macros. Only
68+
one can be used per sketch. The choice for one of them has to be made at
69+
compile time. Changing the LCD mode at run time can be done by calling the
70+
`lcd_init(...)` function.
71+
72+
73+
Arduino syntax |sduino syntax
74+
-------------------- |---------------------
75+
`LiquidCrystal lcd(rs,en,d0,d1,d2,d3)` |`LiquidCrystal_4bit_r (lcd,rs,en,d0,d1,d2,d3)`
76+
`LiquidCrystal lcd(rs,rw,en,d0,d1,d2,d3)` |`LiquidCrystal_4bit_rw (lcd,rs,rw,en,d0,d1,d2,d3)`
77+
`LiquidCrystal lcd(rs,en,d0,d1,d2,d3,d4,d5,d6,d7)` |`LiquidCrystal_8bit_r (lcd,rs,en,d0,d1,d2,d3,d4,d5,d6,d7)`
78+
`LiquidCrystal lcd(rs,rw,en,d0,d1,d2,d3,d4,d5,d6,d7)` |`LiquidCrystal_8bit_rw (lcd,rs,rw,en,d0,d1,d2,d3,d4,d5,d6,d7)`
79+
`lcd.init(rs,rw,en,d0,d1,d2,d3,d4,d5,d6,d7)`|`lcd_init(mode,rs,rw,en,d0,d1,d2,d3,d4,d5,d6,d7)`
80+
`lcd.begin(cols,lines)` |`lcd_begin(cols,lines)`
81+
`lcd.begin(cols,lines,charsize)` |`lcd_begin_charsize(cols,lines,charsize)`
82+
`lcd.clear()` |`lcd_clear()`
83+
`lcd.home()` |`lcd_home()`
84+
`lcd.noDisplay()` |`lcd_noDisplay()`
85+
`lcd.display()` |`lcd_display()`
86+
`lcd.noBlink()` |`lcd_noBlink()`
87+
`lcd.blink()` |`lcd_blink()`
88+
`lcd.noCursor()` |`lcd_noCursor()`
89+
`lcd.cursor()` |`lcd_cursor()`
90+
`lcd.scrollDisplayLeft()` |`lcd_scrollDisplayLeft()`
91+
`lcd.scrollDisplayRight()` |`lcd_scrollDisplayRight()`
92+
`lcd.leftToRight()` |`lcd_leftToRight()`
93+
`lcd.rightToLeft()` |`lcd_rightToLeft()`
94+
`lcd.noAutoscroll()` |`lcd_noAutoscroll()`
95+
`lcd.autoscroll()` |`lcd_autoscroll()`
96+
`lcd.setRowOffsets(row0,row1,row2,row3)`|`lcd_setRowOffsets(row0,row1,row2,row3)`
97+
`lcd.createChar(number, data[])` |`lcd_createChar(number, data[])`
98+
`lcd.setCursor(col,row)` |`lcd_setCursor(col,row)`
99+
`result = lcd.write(value)` |`result = lcd_write(value)`
100+
`lcd.command(value)` |`lcd_command(value)`
101+
102+
103+
104+
## Possible improvements
105+
106+
107+
### Direct port access
108+
As long as the pin numberings are known at compile time it would be possible
109+
use direct port register access and the access pattern could be optimized if
110+
all data pins are on the same port.
111+
112+
113+
### Auto-detect 4-bit mode
114+
The parameter `fourbitmode` of the init() function/method is not needed. It
115+
would be sufficient to check `d5` for a valid value. If it is not valid,
116+
assume 4-bit mode.
117+
118+
As init() is not called very frequently the possible advantage would be small
119+
compared to the downside of breaking the Arduino compatibility.

‎docs/api/PCD8544.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# PCD8544 Library
2+
3+
This library is for monochrome graphical LCD based on the Philips PCD8544
4+
controller
5+
([datasheet](https://github.com/carlosefr/pcd8544/blob/docs/docs/pcd8544.pdf?raw=true))
6+
or compatibles. These displays quite cheap and are commonly found on older monochrome mobile
7+
phones, such as the [Nokia 3310](http://en.wikipedia.org/wiki/Nokia_3310) or
8+
[5110](http://en.wikipedia.org/wiki/Nokia_5110).
9+
10+
This is a modified version of the
11+
[PCD8544 library](https://github.com/carlosefr/pcd8544) written by
12+
[Carlos Rodrigues](https://github.com/carlosefr). It is ported from C++ to C
13+
syntax and is meant to be used with the sduino environment for the STM8.
14+
15+
This library is meant to have a minimal memory footprint. If you need
16+
graphics and other features and can spare the resources, check out the
17+
[library](https://github.com/adafruit/Adafruit-PCD8544-Nokia-5110-LCD-library)
18+
from Adafruit (no sduino/STM8 port yet, though).
19+
20+
21+
## API
22+
23+
24+
Thanks to some [c preprocessor macro magic](macro.html) the API syntax is
25+
very similar to the original C++ syntax. Apart from the usual name mangeling
26+
for polymorph functions replacing the dots in the method names for
27+
underscores and a small modification of the initializer code should be
28+
enough. See below for an example.
29+
30+
The instantiation "method" can be called only one time per sketch as this
31+
library is a singleton library. It is not possible to use more than one
32+
instance per sketch.
33+
34+
35+
Arduino syntax |sduino syntax
36+
------------------------------ |---------------------
37+
`PCD8544 lcd` |no default pin mapping supported
38+
`PCD8544 lcd(sclk,sdin,dc,reset,sce)` |`PCD8544 (lcd,sclk,sdin,dc,reset,sce)`
39+
`lcd.begin()` |`lcd_begin()`
40+
`lcd.begin(width,height)` |`lcd_begin_wh(width,height)`
41+
`lcd.begin(width,height,chiptype)` |`lcd_begin_full(width,height,chiptype)`
42+
`lcd.stop()` |`lcd_stop()`
43+
`lcd.clear()` |`lcd_clear()`
44+
`lcd.clearLine()` |`lcd_clearLine()`
45+
`lcd.setPower(flag)` |`lcd_setPower(flag)`
46+
`lcd.display()` |`lcd_display()`
47+
`lcd.noDisplay()` |`lcd_noDisplay()`
48+
`lcd.setInverse(flag)` |`lcd_setInverse(flag)`
49+
`lcd.setContrast(level)` |`lcd_setContrast(level)`
50+
`lcd.home()` |`lcd_home()`
51+
`lcd.setCursor(col,line)` |`lcd_setCursor(col,line)`
52+
`result = lcd.write(value)` |`result = lcd_write(value)`
53+
`lcd.createChar(chr,glyph[])` |`lcd_createChar(chr,glyph)`
54+
`lcd.drawBitmap(data[],columns,lines)` |`lcd_drawBitmap(data[],columns,lines)`
55+
`lcd.drawColumn(lines, value)` |`lcd.drawColumn(lines, value)`
56+
57+
The default resolution of 84x48 fits the commons Nokia 5110 display.
58+
59+
60+
## Example
61+
62+
```c
63+
#include <PCD8544.h>
64+
65+
PCD8544(lcd, PC5, PC6, PC4, PC7, PD1); // sclk,sdin,dc,reset,sce
66+
67+
int counter = 0;
68+
69+
void setup() {
70+
lcd_begin(); // default resolution is 84x48
71+
}
72+
73+
74+
void loop() {
75+
// Write some text on the first line...
76+
lcd_setCursor(0, 0);
77+
lcd_print_s("Hello, World!");
78+
79+
// Write the counter on the second line...
80+
lcd_setCursor(0, 1);
81+
lcd_print_u(counter);
82+
83+
delay(200);
84+
counter++;
85+
}
86+
```
87+
88+
89+
90+
91+
## Hardware connections
92+
93+
To use this library, you must first connect your LCD to the proper pins on
94+
the STM8 board. This library uses bitbanging for the SPI data transfer, so
95+
you are not bound to the SPI pins for SCLK and MOSI.
96+
97+
For a Nokia 5510 display connected to a STM8S103 breakout board, the
98+
connections look like this:
99+
100+
Display Pin | STM8S breakout board
101+
----------------|------------
102+
Pin 1 (VCC) | +3.3V (marked by a square around the pin on the silkscreen)
103+
Pin 2 (GND) | Ground
104+
Pin 3 (SCE) | STM8S103 pin PD1 (sduino digital pin 10)
105+
Pin 4 (RST) | STM8S103 pin PC7 (sduino digital pin 9)
106+
Pin 5 (D/C) | STM8S103 pin PC4 (sduino digital pin 6)
107+
Pin 6 (MOSI) | STM8S103 pin PC6 (sduino digital pin 8)
108+
Pin 7 (SCLK) | STM8S103 pin PC5 (sduino digital pin 7)
109+
Pin 8 (LED) | 82 Ohm resistor to 3.3V or 330 Ohm to 5V
110+
111+
Since the STM8S works on 3.3V you can connect the data lines directly to
112+
port lines. If you are using this display with a 5V CPU (like on most
113+
Arduino boards), you have to add extra components to connect it to the
114+
digital pins of the Arduino (not necessary if you are using a 3.3V
115+
variant of the Arduino, such as Sparkfun's Arduino Pro).
116+
117+
The background LEDs need only 2.8V/6mA. If you connect them to a port pin,
118+
prefer a HS (High sink) pin (see CPU datasheet, all pins except the
119+
oscillator and the I2C pin PA1/PA2 and PB4/PB5). PWM pins are the best
120+
choice.
121+
122+
when soldering the pin connectors, keep in mind that the upside of the
123+
display is the thicker part of the metal frame.
124+
125+
126+
For a Nokia 3310 display the connections would be the following:
127+
128+
Display Pin | Arduino Pin
129+
------------------|------------
130+
Pin 1 | +3.3V Pin
131+
Pin 2 (SCLK) | PC5, digital Pin 7
132+
Pin 3 (SDIN/MOSI) | PC6, digital Pin 8
133+
Pin 4 (D/C) | PC4, digital Pin 6
134+
Pin 5 (SCE) | PD1, digital Pin 10
135+
Pin 6 | Ground Pin
136+
Pin 7 | 10uF capacitor to Ground Pin
137+
Pin 8 (RST) | PC7, digital Pin 9
138+
139+
For this display model, "Pin 1" is the leftmost pin when facing the back of
140+
the display with the connector on top.
141+
142+
143+
## Custom Symbols
144+
145+
The library allows the use of custom bitmap symbols (5x8), defined by an
146+
array of five bytes. Checkout the examples in the library folder for usage
147+
of this function.
148+
149+
To make it easy to create custom symbols, there's a
150+
graphical glyph editor [available online](http://carlosefr.github.io/pcd8544/).
151+

‎docs/hardware/stm8disco.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# STM8S105Discovery board
2+
3+
Widespread evaluation board made by ST. No support yet, but it is on my
4+
list.

0 commit comments

Comments
 (0)