Skip to content

Commit 5903c54

Browse files
brainelectronicsbrainelectronics
committed
update docs after template
1 parent ed05502 commit 5903c54

File tree

7 files changed

+271
-65
lines changed

7 files changed

+271
-65
lines changed

‎docs/DOCUMENTATION.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Documentation is generated by using Sphinx and published on RTD
88

99
Documentation is automatically created on each merge to the development
1010
branch, as well as with each pull request and available
11-
[📚 here at Read the Docs][ref-rtd-micropython-package-template]
11+
[📚 here at Read the Docs][ref-rtd-micropython-i2c-lcd]
1212

1313
### Install required packages
1414

@@ -34,7 +34,7 @@ sphinx-build docs/ docs/build/linkcheck -d docs/build/docs_doctree/ --color -bli
3434
sphinx-build docs/ docs/build/html/ -d docs/build/docs_doctree/ --color -bhtml -j auto -W
3535
```
3636

37-
The created documentation can be found at [`docs/build/html`](docs/build/html).
37+
The created documentation can be found at `docs/build/html`.
3838

3939
<!-- Links -->
40-
[ref-rtd-micropython-package-template]: https://micropython-package-template.readthedocs.io/en/latest/
40+
[ref-rtd-micropython-i2c-lcd]: https://micropython-i2c-lcd.readthedocs.io/en/latest/

‎docs/EXAMPLES.md‎

Lines changed: 202 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,216 @@
11
# Examples
22

3-
Usage examples of this `micropython-package-template` library
3+
Usage examples of this `micropython-i2c-lcd` library
44

55
---------------
66

7-
## TBD
7+
## General
88

9-
Some text with *italic*, **bold** and `hightlighted` words.
9+
An example of all implemented functionalities can be found at the
10+
[MicroPython I2C LCD examples folder][ref-micropython-i2c-lcd-examples]
1011

11-
```{note}
12-
A reStructuredText highlighted note
12+
## Setup Display
13+
14+
```python
15+
from lcd_i2c import LCD
16+
from machine import I2C, Pin
17+
18+
I2C_ADDR = 0x27
19+
NUM_ROWS = 2
20+
NUM_COLS = 16
21+
22+
# define custom I2C interface, default is 'I2C(0)'
23+
# check the docs of your device for further details and pin infos
24+
i2c = I2C(1, scl=Pin(3), sda=Pin(2), freq=800_000)
25+
lcd = LCD(addr=I2C_ADDR, cols=NUM_COLS, rows=NUM_ROWS, i2c=i2c)
26+
27+
# get LCD infos/properties
28+
print("LCD is on I2C address {}".format(lcd.addr))
29+
print("LCD has {} columns and {} rows".format(lcd.cols, lcd.rows))
30+
print("LCD is used with a charsize of {}".format(lcd.charsize))
31+
print("Cursor position is {}".format(lcd.cursor_position))
32+
33+
# start LCD, not automatically called during init to be Arduino compatible
34+
lcd.begin()
35+
```
36+
37+
## Text
38+
39+
### Show Text
40+
41+
```python
42+
# LCD has already been setup, see section "Setup Display"
43+
44+
lcd.print("Hello World")
45+
```
46+
47+
### Clear Text
48+
49+
This command clears the text on the screen and sets the cursor position back
50+
to its home position at `(0, 0)`
51+
52+
```python
53+
# LCD has already been setup, see section "Setup Display"
54+
55+
lcd.clear()
56+
```
57+
58+
### Scroll Text
59+
60+
```python
61+
# LCD has already been setup, see section "Setup Display"
62+
from time import sleep
63+
64+
text = "Hello World"
65+
66+
# show text on LCD
67+
lcd.print(text)
68+
69+
# scroll text to the left
70+
for _ in text:
71+
lcd.scroll_display_left()
72+
sleep(0.5)
73+
74+
# scroll text to the right
75+
for _ in text:
76+
lcd.scroll_display_right()
77+
sleep(0.5)
78+
```
79+
80+
### Text Flow
81+
82+
```python
83+
# LCD has already been setup, see section "Setup Display"
84+
85+
# set text flow right to left
86+
lcd.right_to_left()
87+
lcd.print("Right to left")
88+
89+
# set text flow left to right
90+
lcd.left_to_right()
91+
lcd.print("Left to right")
92+
```
93+
94+
### Autoscroll
95+
96+
```python
97+
# LCD has already been setup, see section "Setup Display"
98+
99+
# activate autoscroll
100+
lcd.autoscroll()
101+
102+
# disable autoscroll
103+
lcd.no_autoscroll()
13104
```
14105

15-
```{eval-rst}
16-
.. warning::
17-
Some eval warning
106+
### Custom Characters
107+
108+
Custom characters can be defined for 8 CGRAM locations. The character has to
109+
be defined as binary of HEX list. In case you can't see the matrix, simply use
110+
the [LCD Character Creator page of Max Promer](https://maxpromer.github.io/LCD-Character-Creator/)
111+
112+
The following example defines a upright happy smiley `:-)` at the first (0)
113+
location in the displays CGRAM using 5x10 pixels. Maybe you can see it ...
114+
115+
```
116+
00000
117+
00000
118+
10001
119+
00100
120+
00100
121+
10001
122+
01110
123+
00000
124+
```
125+
126+
```python
127+
# LCD has already been setup, see section "Setup Display"
128+
129+
# custom char can be set for location 0 ... 7
130+
lcd.create_char(
131+
location=0,
132+
charmap=[0x00, 0x00, 0x11, 0x04, 0x04, 0x11, 0x0E, 0x00]
133+
)
134+
135+
# show custom char stored at location 0
136+
lcd.print(chr(0))
137+
```
138+
139+
## Backlight
140+
141+
The following functions can be used to control the LCD backlight
142+
143+
```python
144+
# LCD has already been setup, see section "Setup Display"
145+
146+
# turn LCD off
147+
lcd.no_backlight()
148+
149+
# turn LCD on
150+
lcd.backlight()
151+
152+
# turn LCD off
153+
lcd.set_backlight(False)
154+
155+
# turn LCD on
156+
lcd.set_backlight(True)
157+
158+
# get current backlight value
159+
print("Backlight value: {}".format(lcd.get_backlight()))
160+
161+
# get current backlight value via property
162+
print("Backlight value: {}".format(lcd.backlightval))
18163
```
19164

165+
## Cursor
166+
167+
The following functions can be used to control the cursor
168+
20169
```python
21-
def hello_world():
22-
print('Hello')
170+
# LCD has already been setup, see section "Setup Display"
171+
172+
# turn cursor on (show)
173+
lcd.cursor()
174+
175+
# turn cursor off (hide)
176+
lcd.no_cursor()
177+
178+
# turn cursor on (show)
179+
lcd.cursor_on()
180+
181+
# turn cursor off (hide)
182+
lcd.cursor_off()
183+
184+
# blink cursor
185+
lcd.blink()
186+
187+
# stop blinking cursor
188+
lcd.no_blink()
189+
190+
# set cursor to home position (0, 0)
191+
lcd.home()
192+
193+
# set cursor position to first line, third column
194+
lcd.set_cursor(col=3, row=0)
195+
196+
# set cursor position to second line, seventh column
197+
lcd.cursor_position = (7, 1)
198+
199+
# get current cursor position via property
200+
print("Cursor position: {}".format(lcd.cursor_position))
201+
```
202+
203+
## Display
204+
205+
```python
206+
# LCD has already been setup, see section "Setup Display"
207+
208+
# turn display off
209+
lcd.no_display()
210+
211+
# turn display on
212+
lcd.display()
23213
```
24214

25-
| Type | Individual | Prefered food |
26-
| ----- | ---------- | ------------- |
27-
| Car | E-Power | Electricity |
28-
| Animal | Cat | Mice |
215+
<!-- Links -->
216+
[ref-micropython-i2c-lcd-examples]: https://github.com/brainelectronics/micropython-i2c-lcd/tree/develop/examples

‎docs/be_upy_blink.rst‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎docs/conf.py‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,23 +14,31 @@
1414
here = Path(__file__).parent.resolve()
1515

1616
try:
17-
import be_upy_blink
18-
except ImportError:
19-
raise SystemExit("be_upy_blink has to be importable")
20-
else:
2117
# Inject mock modules so that we can build the
2218
# documentation without having the real stuff available
2319
from mock import Mock
2420

25-
sys.modules['micropython'] = Mock()
26-
print("Mocked 'micropython' module")
21+
to_be_mocked = [
22+
'micropython',
23+
'machine',
24+
'time.sleep_ms', 'time.sleep_us',
25+
]
26+
for module in to_be_mocked:
27+
sys.modules[module] = Mock()
28+
print("Mocked '{}' module".format(module))
29+
30+
from lcd_i2c import LCD
31+
except ImportError:
32+
raise SystemExit("lcd_i2c has to be importable")
33+
else:
34+
pass
2735

2836
# load elements of version.py
29-
exec(open(here / '..' / 'be_upy_blink' / 'version.py').read())
37+
exec(open(here / '..' / 'lcd_i2c' / 'version.py').read())
3038

3139
# -- Project information
3240

33-
project = 'micropython-package-template'
41+
project = 'micropython-i2c-lcd'
3442
copyright = '2023, brainelectronics'
3543
author = 'brainelectronics'
3644

@@ -72,10 +80,12 @@
7280
# A list of regular expressions that match URIs that should not be checked
7381
# when doing a linkcheck build.
7482
linkcheck_ignore = [
75-
# tag 0.4.0 did not exist during docs introduction
76-
'https://github.com/brainelectronics/micropython-package-template/tree/0.4.0',
83+
# tag 0.1.0 did not exist during docs introduction
84+
'https://github.com/brainelectronics/micropython-i2c-lcd/tree/0.1.0',
7785
# RTD page did not exist during docs introduction
78-
'https://micropython-package-template.readthedocs.io/en/latest/',
86+
'https://micropython-i2c-lcd.readthedocs.io/en/latest/',
87+
# examples folder did not exist during docs introduction
88+
'https://github.com/brainelectronics/micropython-i2c-lcd/tree/develop/examples',
7989
]
8090

8191
templates_path = ['_templates']

‎docs/index.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
MicroPython package template
2-
===================================
1+
Micropython package to control HD44780 LCD displays via I2C
2+
===========================================================
33

44
Contents
55
--------
@@ -11,7 +11,7 @@ Contents
1111
EXAMPLES
1212
DOCUMENTATION
1313
CONTRIBUTING
14-
be_upy_blink
14+
lcd_i2c
1515
changelog_link
1616

1717
Indices and tables

‎docs/lcd_i2c.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
API
2+
=======================
3+
4+
.. autosummary::
5+
:toctree: generated
6+
7+
LCD
8+
---------------------------------
9+
10+
.. automodule:: lcd_i2c.lcd_i2c
11+
:members:
12+
:private-members:
13+
:show-inheritance:
14+
15+
HD44780 Constants
16+
---------------------------------
17+
18+
.. automodule:: lcd_i2c.const
19+
:members:
20+
:private-members:
21+
:show-inheritance:

0 commit comments

Comments
 (0)