Skip to content

Commit 542756a

Browse files
gigapodgigapod
committed
initial setup for docs on github pages for this repo
1 parent e5748a1 commit 542756a

File tree

7 files changed

+468
-0
lines changed

7 files changed

+468
-0
lines changed

‎docs/api_device.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Device Operations
2+
3+
Methods to setup the device, get device information and change device options.
4+
5+
## Initialization
6+
7+
### begin()
8+
This method is called to initialize the TMF882X library and connect to the TMF882X device. This method should be called before accessing the device.
9+
10+
The I2C address of the is an optional argument. If not provided, the default address is used.
11+
12+
During the initialization process, the device is opened and the runtime firmware loaded onto the device. The TMF882X device is them placed into "APP" mode.
13+
14+
```c++
15+
bool begin(TwoWire &wirePort, uint8_t address)
16+
```
17+
18+
| Parameter | Type | Description |
19+
| :------------ | :---------- | :---------------------------------------------- |
20+
| `wirePort` | `TwoWire` | **optional**. The Wire port. If not provided, the default port is used|
21+
| `address` | `uint8_t` | **optional**. I2C Address. If not provided, the default address is used|
22+
| return value | `bool` | ```true``` on success, ```false``` on startup failure |
23+
24+
### loadFirmware()
25+
To operate the TMF882X device, runtime firmware must be loaded. At startup, this library loads a default firmware version on library initialization.
26+
27+
This method allows the library user to set the firmware version on the device if a newer version is available from AMS.
28+
29+
```C++
30+
bool loadFirmware(const unsigned char *firmwareBinImage, unsigned long length)
31+
```
32+
33+
| Parameter | Type | Description |
34+
| :------------ | :---------- | :---------------------------------------------- |
35+
| `firmwareBinImage` | `const unsigned char` | The firmware binary image |
36+
| `length` | `unsigned long` | The length of the image array |
37+
| return value | `bool` | ```true``` on success, ```false``` on failure |
38+
39+
### isConnected()
40+
Called to determine if a TMF882X device, at the provided i2c address is connected.
41+
42+
```C++
43+
bool isConnected()
44+
```
45+
46+
| Parameter | Type | Description |
47+
| :------------ | :---------- | :---------------------------------------------- |
48+
| return value | `bool` | ```true``` if connected, ```false``` if not |
49+
50+
### setI2CAddress()
51+
Called to change the I2C address of the connected device.
52+
53+
```C++
54+
bool setI2CAddress(uint8_t address)
55+
```
56+
57+
| Parameter | Type | Description |
58+
| :------------ | :---------- | :---------------------------------------------- |
59+
| return value | `bool` | ```true``` on success, ```false``` on failure |
60+
61+
### getApplicationVersion()
62+
Returns the version of the "Application" software running on the connected TMF882X device. See the TMF882X data sheet for more information regarding application software
63+
64+
```C++
65+
bool getApplicationVersion(char *Version, uint8_t vlen)
66+
```
67+
68+
| Parameter | Type | Description |
69+
| :------------ | :---------- | :---------------------------------------------- |
70+
| `Version` | `char*` | Pointer to a character array to receive the version data |
71+
| `vlen` | `uint8_t` | The length of the array pointed to by Version |
72+
| return value | `bool` | ```true``` on success, ```false``` on failure |
73+
74+
### getDeviceUniqueID()
75+
Returns the unique ID of the connected TMF882X.
76+
77+
!!! note
78+
This method uses a ID structure as defined by the AMS TMF882X SDK to
79+
store the ID value.
80+
81+
```C++
82+
bool getDeviceUniqueID(struct tmf882x_mode_app_dev_UID &devUID)
83+
```
84+
85+
| Parameter | Type | Description |
86+
| :------------ | :---------- | :---------------------------------------------- |
87+
| `deviceUID` | `struct tmf882x_mode_app_dev_UID` | The TMF882X UID structure to store the ID into. |
88+
| return value | `bool` | ```true``` on success, ```false``` on failure |
89+
90+
91+
## Debug and Development
92+
93+
### setDebug()
94+
Set the debug state fo the SDK. To use the full debug capabilities of the SDK, debug should be enabled before calling init/begin() on the library
95+
96+
```C++
97+
void setDebug(bool bEnable)
98+
```
99+
100+
| Parameter | Type | Description |
101+
| :------------ | :---------- | :---------------------------------------------- |
102+
| `bEnable` | `bool` | To enable or disable debug mode in the SDK|
103+
104+
### getDebug()
105+
Returns the current debug setting of the library
106+
107+
```C++
108+
bool getDebug(void)
109+
```
110+
111+
| Parameter | Type | Description |
112+
| :------------ | :---------- | :---------------------------------------------- |
113+
| return value | `bool` | ```true``` Debug mode enabled, ```false``` Debug Mode disabled |
114+
115+
### setInfoMessages()
116+
Enable/Disable the output of info messages from the AMS SDK.
117+
118+
```C++
119+
void setInfoMessages(bool bEnable)
120+
```
121+
122+
| Parameter | Type | Description |
123+
| :------------ | :---------- | :---------------------------------------------- |
124+
| `bEnable` | `bool` | To enable or disable info message output from the SDK|
125+
126+
### setMessageLevel()
127+
Used to set the message level of the system.
128+
129+
The value passed in should be one, or a combination of the following flags.
130+
131+
| FLAG | Description |
132+
| :------------ | :---------- |
133+
| TMF882X_MSG_INFO | Output Info messages|
134+
| TMF882X_MSG_DEBUG | Output Debug messages|
135+
| TMF882X_MSG_ERROR | Output Error messages|
136+
| TMF882X_MSG_ALL | Output all messages|
137+
| TMF882X_MSG_NONE | Disable all message output the output of info messages from the AMS SDK.|
138+
139+
```C++
140+
void setMessageLevel(uint8_t msg)
141+
```
142+
143+
| Parameter | Type | Description |
144+
| :------------ | :---------- | :---------------------------------------------- |
145+
| `msg` | `uint8_t` | Message type flag(s)|
146+
147+
### getMessageLevel()
148+
Return the current message settings. See setMessageLevel() description for possible values
149+
150+
```C++
151+
uint8_t getMessageLevel(void)
152+
```
153+
154+
| Parameter | Type | Description |
155+
| :------------ | :---------- | :---------------------------------------------- |
156+
| return value | `uint8_t` | The current message level settings|

‎docs/api_setup.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Arduino Print
2+
3+
Methods used to support Arduino Print functionality.
4+
5+
### setCursor()
6+
7+
This method is called set the "cursor" position in the device. The library supports the Arduino `Print` interface, enabling the use of a `print()` and `println()` methods. The set cursor position defines where to start text output for this functionality.
8+
9+
```c++
10+
void setCursor(uint8_t x, uint8_t y)
11+
```
12+
13+
| Parameter | Type | Description |
14+
| :--- | :--- | :--- |
15+
| x | `uint8_t` | The X coordinate of the cursor|
16+
| y | `uint8_t` | The Y coordinate of the cursor|
17+
18+
### setColor()
19+
20+
This method is called to set the current color of the system. This is used by the Arduino `Print` interface functionality
21+
22+
23+
```c++
24+
void setColor(uint8_t clr)
25+
```
26+
27+
| Parameter | Type | Description |
28+
| :--- | :--- | :--- |
29+
| `clr` | `uint8_t` | The color to set. 0 = black, > 0 = white|
30+
31+
### getColor()
32+
33+
This method is called to get the current color of the system. This is used by the Arduino `Print` interface functionality
34+
35+
36+
```c++
37+
uint8_t getColor(void)
38+
```
39+
40+
| Parameter | Type | Description |
41+
| :--- | :--- | :--- |
42+
| return value| `uint8_t` | The current color|

‎docs/api_tmf882x.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Arduino Print
2+
3+
Methods used to support Arduino Print functionality.
4+
5+
### setCursor()
6+
7+
This method is called set the "cursor" position in the device. The library supports the Arduino `Print` interface, enabling the use of a `print()` and `println()` methods. The set cursor position defines where to start text output for this functionality.
8+
9+
```c++
10+
void setCursor(uint8_t x, uint8_t y)
11+
```
12+
13+
| Parameter | Type | Description |
14+
| :--- | :--- | :--- |
15+
| x | `uint8_t` | The X coordinate of the cursor|
16+
| y | `uint8_t` | The Y coordinate of the cursor|
17+
18+
### setColor()
19+
20+
This method is called to set the current color of the system. This is used by the Arduino `Print` interface functionality
21+
22+
23+
```c++
24+
void setColor(uint8_t clr)
25+
```
26+
27+
| Parameter | Type | Description |
28+
| :--- | :--- | :--- |
29+
| `clr` | `uint8_t` | The color to set. 0 = black, > 0 = white|
30+
31+
### getColor()
32+
33+
This method is called to get the current color of the system. This is used by the Arduino `Print` interface functionality
34+
35+
36+
```c++
37+
uint8_t getColor(void)
38+
```
39+
40+
| Parameter | Type | Description |
41+
| :--- | :--- | :--- |
42+
| return value| `uint8_t` | The current color|

‎docs/index.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# The Qwiic OLED Arduino Library
2+
3+
![SparkFun Qwiic OLED Arduino Library](img/OLEDLibBanner.png "SparkFun Qwiic OLED Arduino Library")
4+
5+
The SparkFun Qwiic OLED Arduino Library is a single graphics module that supports all SparkFun OLED boards based on the SSD1306 from Solomon Systech. Prior to this library, three different libraries were used to support our four different OLED boards.
6+
7+
The SparkFun Qwiic OLED Library delivers a common implementation for all our Qwiic OLED products, delivering a unified, fast, and efficient solution that implements a familiar and easy to understand user experience.
8+
9+
### Key Features
10+
* Implements common graphics capabilities: pixel, line, rectangle, filled rectangle, circle, filled circle, bitmap, text and raster operators (i.e. XOR).
11+
* Smart data transfer to the device – only sends _dirty_ regions of the graphics buffer to the OLED device, not the entire buffer.
12+
* High performance – 2x faster than our previous OLED library, often much higher.
13+
* Efficient memory usage. No dynamic memory utilized. Static resources are loaded once, and only on explicit declaration.
14+
* Implements a familiar interface, making migration from older libraries straight forward
15+
16+
### Getting Started
17+
18+
The [Getting Started Page](software.md) outlines library installation and the general use of the qwiic OLED library.
19+
20+
Detailed examples are included as part of the library installation process and available in the Arduino IDE `File > Examples >` menu. A walk-thru of key examples is contained in the [Examples](sparkfun-qwiic-oled-arduino-library-examples/ex_01_hello/) section of this documentation set.
21+
22+
23+
A full [API Reference](api_device.md) is also provided for the library.
24+
25+
### Supported Products
26+
27+
The SparkFun Qwiic OLED Arduino Library supports the following SparFun Products
28+
29+
<table class="table table-hover table-striped table-bordered">
30+
<tr>
31+
<td width="120" pad=10 style="vertical-align: middle;">
32+
<a href="https://www.sparkfun.com/products/14532"><img src="https://cdn.sparkfun.com//assets/parts/1/2/6/2/1/14532-SparkFun_Micro_OLED_Breakout__Qwiic_-01.jpg"></a></td>
33+
<td style="text-align:left; vertical-align: middle; padding-left: 20px;font-weight: bold;">
34+
<a href="https://www.sparkfun.com/products/14532">SparkFun Micro OLED Breakout (Qwiic)</a>
35+
</td>
36+
</tr>
37+
<tr>
38+
<td width="120" pad=10 style="vertical-align: middle;">
39+
<a href="https://www.sparkfun.com/products/17153"><img src="https://cdn.sparkfun.com//assets/parts/1/6/1/3/5/17153-SparkFun_Qwiic_OLED_Display__0.91_in__128x32_-05.jpg"></a></td>
40+
<td style="text-align:left; vertical-align: middle; padding-left: 20px;font-weight: bold;">
41+
<a href="https://www.sparkfun.com/products/17153">SparkFun Qwiic OLED Display (0.91 in, 128x32)</a>
42+
</td>
43+
</tr>
44+
<tr>
45+
<td width="120" pad=10 style="vertical-align: middle;">
46+
<a href="https://www.sparkfun.com/products/15173"><img src="https://cdn.sparkfun.com//assets/parts/1/3/5/8/8/15173-SparkFun_Transparent_Graphical_OLED_Breakout__Qwiic_-01a.jpg"></a></td>
47+
<td style="text-align:left; vertical-align: middle; padding-left: 20px;font-weight: bold;">
48+
<a href="https://www.sparkfun.com/products/15173">SparkFun Transparent Graphical OLED Breakout (Qwiic)</a>
49+
</td>
50+
</tr>
51+
</table>
52+
53+
54+
55+
### Supported Microcontrollers - Arduino Environment
56+
57+
* [Artemis](https://www.sparkfun.com/products/15574)
58+
* [SAMD51](https://www.sparkfun.com/products/14713)
59+
* [ESP32](https://www.sparkfun.com/products/15663)
60+
* [STM32](https://www.sparkfun.com/products/17712)
61+
* [SAMD21](https://www.sparkfun.com/products/14812)
62+
* [nrf5280](https://www.sparkfun.com/products/15025)
63+
* [Teensy](https://www.sparkfun.com/products/16402)
64+
* [ATMega328](https://www.sparkfun.com/products/18158)
65+
66+
### License
67+
The SparkFun Qwiic OLED Arduino Library is licensed using the Open Source MIT License

‎docs/sfe_logo_sm.png‎

5.41 KB
Loading

‎docs/software.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Software Setup
2+
3+
4+
## Installation
5+
6+
The SparkFun Qwiic OLED Arduino Library is available within in the Arduino library manager, which is launched via the `Sketch > Include Libraries > Manage Libraries …` menu option in the Arduino IDE. Just search for ***SparkFun Qwiic OLED Library***
7+
8+
!!! note
9+
This guide assumes you are using the latest version of the Arduino IDE on your desktop. The following resources available at [SparkFun](https://www.sparkfun.com) provide the details on setting up and configuring Arduino to use this library.
10+
11+
- [Installing the Arduino IDE](https://learn.sparkfun.com/tutorials/installing-arduino-ide)
12+
- [Installing Board Definitions in the Arduino IDE](https://learn.sparkfun.com/tutorials/installing-board-definitions-in-the-arduino-ide)
13+
- [Installing an Arduino Library](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)
14+
15+
General Use Pattern
16+
---------
17+
After installing this library in your local Arduino environment, begin with a standard Arduino sketch, and include the header file for this library.
18+
```C++
19+
// Include the SparkFun qwiic OLED Library
20+
#include <SparkFun_Qwiic_OLED.h>
21+
```
22+
The next step is to declare the object for the SparkFun qwiic OLED device used. Like most Arduino sketches, this is done at a global scope (after the include file declaration), not within the ```setup()``` or ```loop()``` functions.
23+
24+
The user selects from one of the following classes:
25+
26+
| Class | Qwiic OLED Device |
27+
| :--- | :--- |
28+
| `QwiicMicroOLED` | [SparkFun Qwiic Micro OLED ]( https://www.sparkfun.com/products/14532)|
29+
| `QwiicNarrowOLED` | [SparkFun Qwiic OLED Display (128x32) ]( https://www.sparkfun.com/products/17153)|
30+
| `QwiicTransparentOLED` | [SparkFun Transparent Graphical OLED]( https://www.sparkfun.com/products/15173)|
31+
32+
For this example, the Qwiic Micro OLED is used.
33+
```C++
34+
QwiicMicroOLED myOLED;
35+
```
36+
In the ```setup()``` function of this sketch, like all of the SparkFun qwiic libraries, the device is initialized by calling the ```begin()``` method. This method returns a value of ```true``` on success, or ```false``` on failure.
37+
```C++
38+
int width, height; // global variables for use in the sketch
39+
void setup()
40+
{
41+
Serial.begin(115200);
42+
if(!myOLED.begin()){
43+
Serial.println("Device failed to initialize");
44+
while(1); // halt execution
45+
}
46+
Serial.println("Device is initialized");
47+
48+
}
49+
```
50+
Now that the library is initialized, the desired graphics are drawn. Here we erase the screen and draw simple series of lines that originate at the screen origin and fan out across the height of the display.
51+
52+
!!! note
53+
Graphics are not send to the OLED device when drawn. Updates are only sent to the device when the `display()` method is called. This minimizes data transfers to the OLED device, delivering a responsive display response.
54+
55+
```C++
56+
57+
myOLED.erase(); // Erase the screen
58+
myOLED.display(); // Send erase to device
59+
60+
delay(1000); // Slight pause
61+
62+
// Draw our lines from point (0,0) to (i, screen height)
63+
64+
for(int i=0; i < width; i+= 6){
65+
myOLED.line(0, 0, i, height-1); // draw the line
66+
myOLED.display(); // Send the new line to the device for display
67+
}
68+
```
69+
70+
71+
Library Provided Examples
72+
--------
73+
The SparkFun Qwiic OLED Arduino Library, includes a wide variety of examples. These are available from the Examples menu of the Arduino IDE, and in the [`examples`](https://github.com/sparkfun/SparkFun_Qwiic_OLED_Arduino_Library/blob/main/examples)folder of this repository.
74+
75+
For a detailed description of the examples, see the Examples section of the documentation.
76+
77+

0 commit comments

Comments
 (0)