1/*
2MIT License
3
4Copyright (c) 2021 David Schramm
5
6Permission is hereby granted, free of charge, to any person obtaining a copy
7of this software and associated documentation files (the "Software"), to deal
8in the Software without restriction, including without limitation the rights
9to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10copies of the Software, and to permit persons to whom the Software is
11furnished to do so, subject to the following conditions:
12
13The above copyright notice and this permission notice shall be included in all
14copies or substantial portions of the Software.
15
16THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22SOFTWARE.
23*/
24
25/**
26* @file ssd1306.h
27*
28* simple driver for ssd1306 displays
29*/
30
31#ifndef _inc_ssd1306
32#define _inc_ssd1306
33#include <pico/stdlib.h>
34#include <hardware/i2c.h>
35
36/**
37* @brief defines commands used in ssd1306
38*/
39typedef enum {
40 SET_CONTRAST = 0x81,
41 SET_ENTIRE_ON = 0xA4,
42 SET_NORM_INV = 0xA6,
43 SET_DISP = 0xAE,
44 SET_MEM_ADDR = 0x20,
45 SET_COL_ADDR = 0x21,
46 SET_PAGE_ADDR = 0x22,
47 SET_DISP_START_LINE = 0x40,
48 SET_SEG_REMAP = 0xA0,
49 SET_MUX_RATIO = 0xA8,
50 SET_COM_OUT_DIR = 0xC0,
51 SET_DISP_OFFSET = 0xD3,
52 SET_COM_PIN_CFG = 0xDA,
53 SET_DISP_CLK_DIV = 0xD5,
54 SET_PRECHARGE = 0xD9,
55 SET_VCOM_DESEL = 0xDB,
56 SET_CHARGE_PUMP = 0x8D
57} ssd1306_command_t;
58
59/**
60* @brief holds the configuration
61*/
62typedef struct {
63 uint8_t width; /**< width of display */
64 uint8_t height; /**< height of display */
65 uint8_t pages; /**< stores pages of display (calculated on initialization*/
66 uint8_t address; /**< i2c address of display*/
67 i2c_inst_t *i2c_i; /**< i2c connection instance */
68 bool external_vcc; /**< whether display uses external vcc */
69 uint8_t *buffer; /**< display buffer */
70 size_t bufsize; /**< buffer size */
71} ssd1306_t;
72
73/**
74* @brief initialize display
75*
76* @param[in] p : pointer to instance of ssd1306_t
77* @param[in] width : width of display
78* @param[in] height : heigth of display
79* @param[in] address : i2c address of display
80* @param[in] i2c_instance : instance of i2c connection
81*
82* @return bool.
83* @retval true for Success
84* @retval false if initialization failed
85*/
86bool ssd1306_init(ssd1306_t *p, uint16_t width, uint16_t height, uint8_t address, i2c_inst_t *i2c_instance);
87
88/**
89* @brief turn off display
90*
91* @param[in] p : instance of display
92*
93*/
94void ssd1306_poweroff(ssd1306_t *p);
95
96/**
97 @brief turn on display
98
99 @param[in] p : instance of display
100
101*/
102void ssd1306_poweron(ssd1306_t *p);
103
104/**
105 @brief set contrast of display
106
107 @param[in] p : instance of display
108 @param[in] val : contrast
109
110*/
111void ssd1306_contrast(ssd1306_t *p, uint8_t val);
112
113/**
114 @brief set invert display
115
116 @param[in] p : instance of display
117 @param[in] inv : inv==0: disable inverting, inv!=0: invert
118
119*/
120void ssd1306_invert(ssd1306_t *p, uint8_t inv);
121
122/**
123 @brief display buffer, should be called on change
124
125 @param[in] p : instance of display
126
127*/
128void ssd1306_show(ssd1306_t *p);
129
130/**
131 @brief clear display buffer
132
133 @param[in] p : instance of display
134
135*/
136void ssd1306_clear(ssd1306_t *p);
137
138/**
139 @brief draw pixel on buffer
140
141 @param[in] p : instance of display
142 @param[in] x : x position
143 @param[in] y : y position
144*/
145void ssd1306_draw_pixel(ssd1306_t *p, uint32_t x, uint32_t y);
146
147/**
148 @brief draw pixel on buffer
149
150 @param[in] p : instance of display
151 @param[in] x1 : x position of starting point
152 @param[in] y1 : y position of starting point
153 @param[in] x2 : x position of end point
154 @param[in] y2 : y position of end point
155*/
156void ssd1306_draw_line(ssd1306_t *p, int32_t x1, int32_t y1, int32_t x2, int32_t y2);
157
158/**
159 @brief draw filled square at given position with given size
160
161 @param[in] p : instance of display
162 @param[in] x : x position of starting point
163 @param[in] y : y position of starting point
164 @param[in] width : width of square
165 @param[in] height : height of square
166*/
167void ssd1306_draw_square(ssd1306_t *p, uint32_t x, uint32_t y, uint32_t width, uint32_t height);
168
169/**
170 @brief draw empty square at given position with given size
171
172 @param[in] p : instance of display
173 @param[in] x : x position of starting point
174 @param[in] y : y position of starting point
175 @param[in] width : width of square
176 @param[in] height : height of square
177*/
178void ssd13606_draw_empty_square(ssd1306_t *p, uint32_t x, uint32_t y, uint32_t width, uint32_t height);
179
180/**
181 @brief draw monochrome bitmap with offset
182
183 @param[in] p : instance of display
184 @param[in] data : image data (whole file)
185 @param[in] size : size of image data in bytes
186 @param[in] x_offset : offset of horizontal coordinate
187 @param[in] y_offset : offset of vertical coordinate
188*/
189void ssd1306_bmp_show_image_with_offset(ssd1306_t *p, const uint8_t *data, const long size, uint32_t x_offset, uint32_t y_offset);
190
191/**
192 @brief draw monochrome bitmap
193
194 @param[in] p : instance of display
195 @param[in] data : image data (whole file)
196 @param[in] size : size of image data in bytes
197*/
198void ssd1306_bmp_show_image(ssd1306_t *p, const uint8_t *data, const long size);
199
200/**
201 @brief draw char with given font
202
203 @param[in] p : instance of display
204 @param[in] x : x starting position of char
205 @param[in] y : y starting position of char
206 @param[in] scale : scale font to n times of original size (default should be 1)
207 @param[in] font : pointer to font
208 @param[in] c : character to draw
209*/
210void ssd1306_draw_char_with_font(ssd1306_t *p, uint32_t x, uint32_t y, uint32_t scale, const uint8_t *font, char c);
211
212/**
213 @brief draw char with builtin font
214
215 @param[in] p : instance of display
216 @param[in] x : x starting position of char
217 @param[in] y : y starting position of char
218 @param[in] scale : scale font to n times of original size (default should be 1)
219 @param[in] c : character to draw
220*/
221void ssd1306_draw_char(ssd1306_t *p, uint32_t x, uint32_t y, uint32_t scale, char c);
222
223/**
224 @brief draw string with given font
225
226 @param[in] p : instance of display
227 @param[in] x : x starting position of text
228 @param[in] y : y starting position of text
229 @param[in] scale : scale font to n times of original size (default should be 1)
230 @param[in] font : pointer to font
231 @param[in] s : text to draw
232*/
233void ssd1306_draw_string_with_font(ssd1306_t *p, uint32_t x, uint32_t y, uint32_t scale, const uint8_t *font, char *s );
234
235/**
236 @brief draw string with builtin font
237
238 @param[in] p : instance of display
239 @param[in] x : x starting position of text
240 @param[in] y : y starting position of text
241 @param[in] scale : scale font to n times of original size (default should be 1)
242 @param[in] s : text to draw
243*/
244void ssd1306_draw_string(ssd1306_t *p, uint32_t x, uint32_t y, uint32_t scale, char *s);
245
246#endif