Skip to content

Commit 4aa91eb

Browse files
malcolm-sparkfunmalcolm-sparkfun
committed
Add initial example documentation and CircuitPython/MicroPython installation instructions
1 parent b62b564 commit 4aa91eb

File tree

2 files changed

+137
-5
lines changed

2 files changed

+137
-5
lines changed

‎README.md

+23-5
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
![GitHub issues](https://img.shields.io/github/issues/sparkfun/Qwiic_SerLCD_Py)
77
![License](https://img.shields.io/github/license/sparkfun/Qwiic_SerLCD_Py)
88
![X](https://img.shields.io/twitter/follow/sparkfun)
9+
![API](https://img.shields.io/badge/API%20Reference-blue?link=https%3A%2F%2Fdocs.sparkfun.com%2Fqwiic_serlcd_py%2Fclassqwiic__serlcd_1_1_qwiic_serlcd.html)
910

1011
The line of SparkFun Qwiic SerLCD products provide a simple and cost effective solution for adding a "text based" LCD display to your project. Implementing a SparkFun Qwiic interface, a SerLCD is rapidly added to any board that is part of the SparkFun Qwiic ecosystem.
1112

@@ -17,7 +18,7 @@ This repository implements a Python package for the SparkFun Qwiic SerLCD series
1718
* [Getting Started](#getting-started)
1819
* [Installation](#installation)
1920
* [Supported Platforms](#supported-platforms)
20-
* [Documentation](https://docs.sparkfun.com/Qwiic_SerLCD_Py/)
21+
* [Documentation](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html)
2122
* [Examples](#examples)
2223

2324
## About the Package
@@ -90,16 +91,33 @@ cd dist
9091
pip install sparkfun_qwiic_serlcd-<version>.tar.gz
9192
```
9293

93-
### MicroPython
94+
#### MicroPython Installation
95+
If not already installed, follow the [instructions here](https://docs.micropython.org/en/latest/reference/mpremote.html) to install mpremote on your computer.
9496

95-
### CircuitPython
97+
Connect a device with MicroPython installed to your computer and then install the package directly to your device with mpremote mip.
98+
```sh
99+
mpremote mip install github:sparkfun/qwiic_serlcd_py
100+
```
101+
102+
#### CircuitPython Installation
103+
If not already installed, follow the [instructions here](https://docs.circuitpython.org/projects/circup/en/latest/#installation) to install CircUp on your computer.
104+
105+
Ensure that you have the latest version of the SparkFun Qwiic CircuitPython bundle.
106+
```sh
107+
circup bundle-add sparkfun/Qwiic_Py
108+
```
109+
110+
Finally, connect a device with CircuitPython installed to your computer and then install the package directly to your device with circup.
111+
```sh
112+
circup install --py qwiic_serlcd
113+
```
96114

97115
## Getting Started
98116

99117
## Examples
118+
Below is a quickstart program to print "Hello World!" to the Serial LCD.
100119

101-
102-
See the examples directory for more detailed use examples.
120+
See the examples directory for more detailed use examples and [examples/README.md](https://github.com/sparkfun/qwiic_serlcd_py/blob/main/examples/README.md) for a summary of the available examples.
103121

104122
```python
105123
from __future__ import print_function

‎examples/README.md

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Sparkfun SerLCD Examples Reference
2+
Below is a brief summary of each of the example programs included in this repository. To report a bug in any of these examples or to request a new feature or example [file an issue in our GitHub issues.](https://github.com/sparkfun/qwiic_serlcd_py/issues)
3+
4+
## Example 1: Hello World
5+
This example demonstrates basic bringup of the LCD to print "Hello World!".
6+
7+
It showcases the following methods:
8+
9+
- [setBacklight()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a81afb76ad0cc0b03b2def16c29ceaf06)
10+
- [setContrast()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a2dea2487f84df67519f61ff3004c7d12)
11+
- [clearScreen()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a35e73e1105f1db0be89372a5f4500714)
12+
- [print()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a30a4a9383c96b81763c6a32fa8b3f8dc)
13+
- [setCursor()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#ab62f2dd063749b4418373f3320f2a38a)
14+
15+
16+
## Example 2: Backlight
17+
This example shows how to change the color of the backlight by cycling through backlight colors and printing the name of the current backlight color to the display.
18+
19+
The key method showcased by this example is [setBacklight()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a81afb76ad0cc0b03b2def16c29ceaf06)
20+
21+
## Example 3: Set Cursor Position
22+
This example shows how to set the cursor to a specific column and row to print a character. It cycles through the lowercase letters of the alphabet (a-z) and prints each to a random row and column of the display.
23+
24+
The key method showcased by this example is [setCursor()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#ab62f2dd063749b4418373f3320f2a38a)
25+
26+
## Example 4: Move Cursor
27+
This example shows how to manually move the cursor left or right. It cycles between moving the cursor left three spaces and then moving it right three spaces.
28+
29+
The key methods showcased by this example are [moveCursorLeft()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#ac6dda0410878a153b193b05d4eeb62ee) and [moveCursorRight()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a7d8891c7fb78d2e684c7cdf38556b813)
30+
31+
## Example 5: Enable Cursor
32+
This example shows how to turn the cursor on and off. It prints "Hello World!" to the LCD and then cycles between turning the cursor on for a second and off for a second.
33+
34+
The key methods showcased by this example are [cursor()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#ab11b11f6eaca0dd22e7c14b816e10bed) and [noCursor()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#abafa73de35582185e9db2c74f91df116)
35+
36+
## Example 6: Blink Cursor
37+
This example shows how to turn blinking of the cursor on and off. It prints "Hello World!" to the LCD and then cycles between turning the blinking on for 5 seconds and off for 5 seconds.
38+
39+
The key methods showcased by this example are [blink()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a4c92d4fa2a89bbda03bcca43d82cd95a) and [noBlink()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#aae22aaee6f6d748c2921fc7b3008014b)
40+
41+
## Example 7: Scroll
42+
This example demonstrates the scrolling controls on the SerLCD. It prints "Hello World!" to the LCD and then cycles between scrolling it offscreen to the left, then offscreen to the right before finally centering it again.
43+
44+
The key methods showcased by this example are [scrollDisplayLeft()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a5770a90358b2bad368e67aa23f8d0148) and [scrollDisplayRight()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#abcb7784572d86a1ca3beec4b73481a6f)
45+
46+
## Example 8: Autoscroll Text
47+
This example demonstrates the autoscroll feature on the SerLCD. It cycles between printing the characters 0 to 9 and turning on and off autoscroll.
48+
49+
The key methods showcased by this example are:
50+
51+
- [leftToRight()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a3a1c4c6cf831084a78f09fb535fb69fc)
52+
- [autoScroll()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a1ed67c384ab25e363e8129bc4d5c37e8)
53+
- [noAutoScroll()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#abbbd2c0c047d37f88209b6dd27a34359)
54+
55+
56+
## Example 9: Custom Character
57+
This example demonstrates how to print custom characters to the LCD. It demonstrates printing a heart and a smiley face and then a little man waving his arms up and down.
58+
59+
The key methods showcased by this example are [createChar()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#af75050abc733dd3ada34e79bd9a3b21b) and [writeChar()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a1b7e9f17fd0f061eef860416ce846783)
60+
61+
## Example 10: Turn off Display
62+
This example prints "Hello World!" to the LCD and turns on and off
63+
the display for a second each.
64+
65+
The key methods showcased by this example are [display()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#acef2bfe9d6a0b2629150f0d18bf6849d) and [noDisplay()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#ae5db2e051be1530b742aacef0b4ccd3f)
66+
67+
## Example 11: Text Direction
68+
This example demonstrates how to change where the next character will be printed. It walks through the alphabet and cycles between printing characters from right to left then left to right.
69+
70+
The key methods showcased by this example are [rightToLeft()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#add5f1d9c4796f5f73d8944eb1e825575), [leftToRight()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a3a1c4c6cf831084a78f09fb535fb69fc) and [home()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a26bb593af77460f92a2dc1791096c294).
71+
72+
## Example 12: Console Input to Display
73+
This example demonstrates printing arbitrary strings to the LCD. It takes user input from the Python repl until the user presses "enter" and then prints it to the LCD.
74+
75+
The key method showcased by this example is [print()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a30a4a9383c96b81763c6a32fa8b3f8dc)
76+
77+
78+
## Example 13: Fast Backlight
79+
This example shows how to set the backlight fast. It is advantageous because using this method doesn't show any system messages and sends the values in one concatenated block of data (a single command for all 3 values). It alternates between turning the backlight red for a second an then orange for a second.
80+
81+
The key method showcased by this example is [setFastBacklight()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#afbc44537d3f324299f6a94433e338ef1)
82+
83+
## Example 14: Show Firmware Version
84+
This example shows how to get the devices firmware version. It repeatedly sends the command to display the firmware version.
85+
86+
The key method showcased by this example is [command()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#aed9378ca8da9030c62fe29ac96513cf4)
87+
88+
## Example 15: Message Enable
89+
This example demonstrates how to turn off the system messages displayed when
90+
the user changes a setting. For instance 'Contrast: 5' or 'Backlight: 100%' is
91+
no longer displayed. It first sets the backlight and contrast while system messages are enabled, and then disables them and repeatedly changes the backlight color to demonstrate that the system messages are no longer printed.
92+
93+
The key method showcased by this example is [disableSystemMessages()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a748362f1dfd4a4af65a19e1c07c6fbca)
94+
95+
## Example 16: Set Splash
96+
This example demonstrates how to create your own custom splash screen.
97+
98+
This is done by first writing the text you want as your splash to the display,
99+
then 'saving' it as a splash screen.
100+
101+
You can also disable or enable the displaying of the splash screen.
102+
103+
Note - The disableSplash() and enableSplash() commands
104+
are only supported on SerLCD v1.2 and above. But you can still use the
105+
toggle splash command (Ctrl+i) to enable/disable the splash.
106+
107+
The example sets the custom splash screen to "Tea-O-Matic".
108+
109+
The key methods showcased by this example are [saveSplash()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#ae80dc2c1c37bd22f8aba75336ea9cedb) and [enableSplash()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a4783eaf3f021b51e0c8b877d64742063)
110+
111+
## Example 17: Change I2C Address
112+
This example demonstrates how to change the I2C address on your LCD.
113+
114+
The key method showcased by this example is [setAddress()](https://docs.sparkfun.com/qwiic_serlcd_py/classqwiic__serlcd_1_1_qwiic_serlcd.html#a4783eaf3f021b51e0c8b877d64742063)

0 commit comments

Comments
 (0)