ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
ht16k33_char.cpp
Go to the documentation of this file.
1#include "ht16k33_char.h"
2
4#include "esphome/core/hal.h"
5#include "esphome/core/log.h"
6
7#include <algorithm>
8#include <cstdarg>
9#include <cstring>
10
12
13ESPHOME_LOG_TAG(TAG, "display.ht16k33_char");
14
15// Commands; the low bits carry the argument
16static constexpr uint8_t COMMAND_DISPLAY_DATA = 0x00;
17static constexpr uint8_t COMMAND_SYSTEM_SETUP = 0x20; // bit 0 runs the oscillator
18static constexpr uint8_t COMMAND_DISPLAY_SETUP = 0x80; // bit 0 turns the display on, bits 1 and 2 pick the blink rate
19static constexpr uint8_t BLINK_MASK = 0x06;
20static constexpr uint8_t DISPLAY_SETUP_MASK = 0x07;
21static constexpr uint8_t STANDBY_FLAG = 0x80; // kept in display_setup_, not sent
22static constexpr uint8_t COMMAND_DIMMING = 0xE0; // bits 0 to 3 are the duty cycle, 1/16 to 16/16
23static constexpr uint8_t OSCILLATOR_ON = 0x01;
24static constexpr uint8_t DISPLAY_ON = 0x01;
25static constexpr uint8_t MAX_BLINK = 3;
26static constexpr uint8_t MAX_INTENSITY = 15;
27
28// MAX_BUFFER_LENGTH in display.py plus the terminator
29static constexpr size_t FORMAT_BUFFER_SIZE = 64 + 1;
30
31// A frame is the data address followed by the 16 bytes of display memory
32static constexpr uint8_t DISPLAY_RAM_SIZE = 16;
33static constexpr uint8_t FRAME_SIZE = DISPLAY_RAM_SIZE + 1;
34
35// Adafruit 0.56" backpack: digits in bytes 0, 2, 6 and 8, colon in byte 4
36static constexpr uint8_t DIGITS_PER_CHIP = 4;
37static constexpr uint8_t DIGIT_RAM_OFFSET[DIGITS_PER_CHIP] PROGMEM = {0, 2, 6, 8};
38static constexpr uint8_t COLON_RAM_OFFSET = 4;
39static constexpr uint8_t COLON_BIT = 0x02;
40static constexpr uint8_t COLON_DIGIT = 2; // the colon sits between the second and third digit
41static constexpr uint8_t DECIMAL_POINT_BIT = 0x80;
42
43// ASCII 0x20 to 0x7E; 0 is a dark digit
44//
45// A
46// ---
47// F | | B
48// -G-
49// E | | C
50// ---
51// D
52// bit 0 is A, bit 6 is G
53static constexpr uint8_t FONT[] PROGMEM = {
54 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // space ! " # $ % & '
55 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x00, 0x00, // ( ) * + , - . /
56 0x3F, 0x06, 0x5B, 0x4F, 0x66, 0x6D, 0x7D, 0x07, // 0 1 2 3 4 5 6 7
57 0x7F, 0x6F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // 8 9 : ; < = > ?
58 0x00, 0x77, 0x00, 0x39, 0x00, 0x79, 0x71, 0x3D, // @ A B C D E F G
59 0x76, 0x30, 0x0E, 0x00, 0x38, 0x00, 0x37, 0x3F, // H I J K L M N O
60 0x73, 0x00, 0x00, 0x6D, 0x00, 0x3E, 0x00, 0x00, // P Q R S T U V W
61 0x00, 0x6E, 0x00, 0x00, 0x00, 0x00, 0x00, 0x08, // X Y Z [ \ ] ^ _
62 0x00, 0x00, 0x7C, 0x58, 0x5E, 0x00, 0x00, 0x00, // ` a b c d e f g
63 0x74, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x5C, // h i j k l m n o
64 0x00, 0x00, 0x50, 0x00, 0x78, 0x1C, 0x00, 0x00, // p q r s t u v w
65 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // x y z { | } ~
66};
67
69 // Cleared before the display turns on, so a message from before an MCU-only reboot never shows
70 if (!this->write_all_(this->system_setup_()) || !this->write_frames_(0) ||
71 !this->write_all_(this->display_setup_command_()) || !this->write_all_(COMMAND_DIMMING | this->intensity_)) {
72 this->mark_failed(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
73 }
74}
75
77 if (this->writer_.has_value()) {
78 this->clear();
79 (*this->writer_)(*this);
80 }
81 this->status_comm_result(this->write_frames_(this->length_));
82}
83
85 ESP_LOGCONFIG(TAG,
86 "HT16K33 Character Display:\n"
87 " Message buffer: %u bytes\n"
88 " Intensity: %u",
89 this->capacity_, this->intensity_);
90 LOG_I2C_DEVICE(this);
91#ifdef HT16K33_CHAR_SECONDARY_COUNT
92 for (uint8_t address : this->secondary_addresses_) {
93 ESP_LOGCONFIG(TAG, " Secondary address: 0x%02X", address);
94 }
95#endif
96 LOG_UPDATE_INTERVAL(this);
97}
98
100 return COMMAND_SYSTEM_SETUP | ((this->display_setup_ & STANDBY_FLAG) ? 0 : OSCILLATOR_ON);
101}
102
104 return COMMAND_DISPLAY_SETUP | (this->display_setup_ & DISPLAY_SETUP_MASK);
105}
106
107bool HT16K33CharDisplay::write_all_(uint8_t command) {
108 bool ok = true;
109 this->for_each_chip_([&](uint8_t address) {
110 if (this->bus_->write(address, &command, 1) != i2c::ERROR_OK)
111 ok = false;
112 });
113 return ok;
114}
115
116void HT16K33CharDisplay::send_(uint8_t command) {
117 if (this->is_ready())
118 this->status_comm_result(this->write_all_(command));
119}
120
122#ifdef USE_HT16K33_CHAR_GLYPH_OVERRIDES
123 // The define is global; a display without add_characters has no table
124 if (this->glyph_overrides_ != nullptr) {
125 for (const uint32_t *entry = this->glyph_overrides_; *entry != 0; entry++) {
126 if ((*entry & 0xFFFF) == codepoint)
127 return *entry >> 16;
128 }
129 }
130#endif
131 if (codepoint < ' ' || codepoint > '~')
132 return 0;
133 return progmem_read_byte(&FONT[codepoint - ' ']);
134}
135
136// A decimal point lights on the digit before it and a colon only in its place; neither takes a digit
138 uint8_t pos = 0;
139 bool ok = true;
140 this->for_each_chip_([&](uint8_t address) {
141 uint8_t frame[FRAME_SIZE] = {COMMAND_DISPLAY_DATA};
142 uint8_t *ram = frame + 1;
143 uint8_t digit = 0;
144 while (pos < length) {
145 size_t consumed;
146 uint32_t codepoint = unicode::extract_unicode_codepoint(this->message_ + pos, &consumed);
147 if (consumed == 0) {
148 consumed = 1;
149 codepoint = 0;
150 }
151 if (codepoint == '.') {
152 if (digit > 0)
153 ram[progmem_read_byte(&DIGIT_RAM_OFFSET[digit - 1])] |= DECIMAL_POINT_BIT;
154 } else if (codepoint == ':') {
155 if (digit == COLON_DIGIT)
156 ram[COLON_RAM_OFFSET] |= COLON_BIT;
157 } else {
158 if (digit == DIGITS_PER_CHIP)
159 break; // the next chip takes this character
160 ram[progmem_read_byte(&DIGIT_RAM_OFFSET[digit++])] = this->find_segments_(codepoint);
161 }
162 pos += consumed;
163 }
164 if (this->bus_->write(address, frame, FRAME_SIZE) != i2c::ERROR_OK)
165 ok = false;
166 });
167 return ok;
168}
169
170uint8_t HT16K33CharDisplay::print(uint8_t pos, const char *str) {
171 if (pos >= this->capacity_)
172 return 0;
173 if (pos > this->length_)
174 memset(this->message_ + this->length_, ' ', pos - this->length_);
175 uint8_t len = std::min<size_t>(strlen(str), this->capacity_ - pos);
176 // Do not cut a multi-byte character; continuation bytes are 10xxxxxx
177 while (len > 0 && (str[len] & 0xC0) == 0x80)
178 len--;
179 memcpy(this->message_ + pos, str, len);
180 this->length_ = std::max<uint8_t>(this->length_, pos + len);
181 this->message_[this->length_] = '\0';
182 return len;
183}
184
185uint8_t HT16K33CharDisplay::vprintf_(uint8_t pos, const char *format, va_list arg) {
186 char buffer[FORMAT_BUFFER_SIZE];
187 if (vsnprintf(buffer, sizeof(buffer), format, arg) <= 0)
188 return 0;
189 return this->print(pos, buffer);
190}
191
192uint8_t HT16K33CharDisplay::printf(uint8_t pos, const char *format, ...) {
193 va_list arg;
194 va_start(arg, format);
195 const uint8_t written = this->vprintf_(pos, format, arg);
196 va_end(arg);
197 return written;
198}
199
200uint8_t HT16K33CharDisplay::printf(const char *format, ...) {
201 va_list arg;
202 va_start(arg, format);
203 const uint8_t written = this->vprintf_(0, format, arg);
204 va_end(arg);
205 return written;
206}
207
208uint8_t HT16K33CharDisplay::strftime(uint8_t pos, const char *format, ESPTime time) {
209 char buffer[FORMAT_BUFFER_SIZE];
210 if (time.strftime(buffer, sizeof(buffer), format) == 0)
211 return 0;
212 return this->print(pos, buffer);
213}
214
215uint8_t HT16K33CharDisplay::clock_display(uint8_t pos, bool show_leading_zero, bool use_ampm, ESPTime time) {
216 char buffer[6];
217 if (time.strftime(buffer, sizeof(buffer), use_ampm ? "%I:%M" : "%H:%M") == 0)
218 return 0;
219 if (!show_leading_zero && buffer[0] == '0')
220 buffer[0] = ' ';
221 return this->print(pos, buffer);
222}
223
224void HT16K33CharDisplay::set_intensity(uint8_t intensity) {
225 this->intensity_ = std::min(intensity, MAX_INTENSITY);
226 this->send_(COMMAND_DIMMING | this->intensity_);
227}
228
229void HT16K33CharDisplay::set_blink(uint8_t blink) {
230 if (blink > MAX_BLINK)
231 blink = 0;
232 this->display_setup_ = (this->display_setup_ & ~BLINK_MASK) | (blink << 1);
233 this->send_(this->display_setup_command_());
234}
235
236void HT16K33CharDisplay::display_power(bool power_status) {
237 assign_bits(this->display_setup_, DISPLAY_ON, power_status);
238 this->send_(this->display_setup_command_());
239}
240
242 assign_bits(this->display_setup_, STANDBY_FLAG, standby);
243 this->send_(this->system_setup_());
244}
245
247 if (this->is_ready())
248 this->status_comm_result(this->write_frames_(0));
249}
250
251} // namespace esphome::ht16k33_char
void mark_failed()
Mark this component as failed.
bool status_comm_result(bool ok)
Clears the warning when ok, else sets it with message (default "Communication failed"); returns ok.
bool is_ready() const
uint8_t print(uint8_t pos, const char *str)
Write str at byte offset pos, where a .
void set_intensity(uint8_t intensity)
0 (dimmest) to 15, clamped
uint8_t printf(uint8_t pos, const char *format,...) __attribute__((format(printf
void send_(uint8_t command)
Send a command to every chip once set up, and report the result.
uint8_t uint8_t uint8_t strftime(uint8_t pos, const char *format, ESPTime time) __attribute__((format(strftime
uint8_t display_setup_
Display setup register: on bit and blink rate; bit 7 remembers standby, which the register does not u...
void clear()
For printing from automations; the lambda starts from an empty message.
bool write_frames_(uint8_t length)
Draw the first length bytes of the message; the chips it does not reach are cleared.
void display_power(bool power_status)
Turn the display on or off.
StaticVector< uint8_t, HT16K33_CHAR_SECONDARY_COUNT > secondary_addresses_
uint8_t vprintf_(uint8_t pos, const char *format, va_list arg)
void set_blink(uint8_t blink)
0 steady, 1 at 2 Hz, 2 at 1 Hz, 3 at 0.5 Hz; before setup only the value is kept
uint8_t find_segments_(uint32_t codepoint) const
void display_standby(bool standby)
Stop the oscillator, the lowest power state; before setup only the value is kept.
void blank()
Clear the display memory; the next update redraws the message.
uint8_t uint8_t uint8_t uint8_t uint8_t clock_display(uint8_t pos, bool show_leading_zero, bool use_ampm, ESPTime time)
HH:MM, or H:MM without the leading zero; 12-hour when use_ampm.
ErrorCode write(uint8_t address, const uint8_t *buffer, size_t len, bool stop=true)
Definition i2c_bus.h:53
I2CBus * bus_
pointer to I2CBus instance
Definition i2c.h:325
uint32_t buffer
Definition gif.cpp:50
const char * format
ESPHOME_LOG_TAG(TAG, "display.ht16k33_char")
@ ERROR_OK
No error found during execution of method.
Definition i2c_bus.h:15
uint32_t extract_unicode_codepoint(const char *utf8_str, size_t *length)
Attempt to extract a 32 bit Unicode codepoint from a UTF-8 string.
Definition unicode.cpp:19
ESPHOME_ALWAYS_INLINE constexpr void assign_bits(T &value, std::type_identity_t< T > mask, bool on)
Set the bits of mask in value when on is true, clear them otherwise.
Definition helpers.h:1150
va_end(args)
const void size_t len
Definition hal.h:68
size_t size_t pos
Definition helpers.h:1333
size_t size_t const char va_start(args, fmt)
int written
Definition helpers.h:1340
uint8_t progmem_read_byte(const uint8_t *addr)
Definition hal.h:51
static void uint32_t
A more user-friendly version of struct tm from time.h.
Definition time.h:23
size_t strftime(char *buffer, size_t buffer_len, const char *format)
Convert this ESPTime struct to a null-terminated c string buffer as specified by the format argument.
Definition time.cpp:20
std::string print()
uint16_t length
Definition tt21100.cpp:0