ESPHome 2026.8.0-dev
Loading...
Searching...
No Matches
it8951_defs.h
Go to the documentation of this file.
1#pragma once
2
3#include <cstdint>
4
5namespace esphome::it8951 {
6
7struct DevInfo {
8 uint16_t panel_width{0};
9 uint16_t panel_height{0};
10 uint16_t img_buf_addr_l{0};
11 uint16_t img_buf_addr_h{0};
12 uint16_t fw_version[8]{};
13 uint16_t lut_version[8]{};
14};
15
16// --- IT8951 SPI packet preambles ---
17static constexpr uint16_t PACKET_TYPE_CMD = 0x6000;
18static constexpr uint16_t PACKET_TYPE_WRITE = 0x0000;
19static constexpr uint16_t PACKET_TYPE_READ = 0x1000;
20
21// --- Built-in I80 commands ---
22static constexpr uint16_t TCON_SYS_RUN = 0x0001;
23static constexpr uint16_t TCON_STANDBY = 0x0002;
24static constexpr uint16_t TCON_SLEEP = 0x0003;
25static constexpr uint16_t TCON_REG_RD = 0x0010;
26static constexpr uint16_t TCON_REG_WR = 0x0011;
27
28static constexpr uint16_t TCON_LD_IMG = 0x0020;
29static constexpr uint16_t TCON_LD_IMG_AREA = 0x0021;
30static constexpr uint16_t TCON_LD_IMG_END = 0x0022;
31
32// --- I80 user-defined commands ---
33static constexpr uint16_t I80_CMD_DPY_AREA = 0x0034;
34static constexpr uint16_t I80_CMD_GET_DEV_INFO = 0x0302;
35static constexpr uint16_t I80_CMD_DPY_BUF_AREA = 0x0037;
36static constexpr uint16_t I80_CMD_VCOM = 0x0039;
37static constexpr uint16_t I80_CMD_VCOM_READ = 0x0000;
38// VCOM write selectors. Different IT8951-driven panels accept different
39// selector values for the VCOM SET sub-command. Most panels (m5stack-m5paper,
40// generic dev kits) accept 0x0001. Some panels — notably the Seeed
41// reTerminal E1003 — only respond to selector 0x0002 and silently ignore
42// 0x0001, leaving VCOM at its default and making grayscale waveforms
43// (GC16/GL16) ineffective even though INIT still works.
44static constexpr uint16_t I80_CMD_VCOM_WRITE = 0x0001;
45static constexpr uint16_t I80_CMD_VCOM_WRITE_ALT = 0x0002;
46
47// Force temperature command. The IT8951 selects waveform LUTs based on
48// panel temperature; if it is left at the controller default, panels with
49// auto-temperature disabled (notably the Seeed reTerminal E1003) will
50// run waveforms against a mismatched LUT, leaving pixels visually
51// unchanged even though the LUT engine completes a full cycle. The
52// selector word selects the operation (0x0001 = write); the value word
53// is the temperature in degrees Celsius.
54static constexpr uint16_t I80_CMD_FORCE_TEMP = 0x0040;
55static constexpr uint16_t I80_CMD_FORCE_TEMP_WRITE = 0x0001;
56static constexpr int16_t DEFAULT_FORCE_TEMP_C = 25;
57
58// --- Pixel mode (bits per pixel encoding) ---
59static constexpr uint8_t PIXEL_2BPP = 0;
60static constexpr uint8_t PIXEL_3BPP = 1;
61static constexpr uint8_t PIXEL_4BPP = 2;
62static constexpr uint8_t PIXEL_8BPP = 3;
63
64// --- Endian flags for LD_IMG_AREA ---
65static constexpr uint8_t LDIMG_L_ENDIAN = 0;
66static constexpr uint8_t LDIMG_B_ENDIAN = 1;
67
68// --- SPI probe frequency used for initial controller handshake ---
69static constexpr uint32_t SPI_PROBE_FREQUENCY = 1'000'000;
70
71// --- Refresh modes ---
72/*
73 INIT The initialization (INIT) mode is
74 used to completely erase the display and leave it in the white state. It is
75 useful for situations where the display information in memory is not a faithful
76 representation of the optical state of the display, for example, after the
77 device receives power after it has been fully powered down. This waveform
78 switches the display several times and leaves it in the white state.
79
80 DU
81 The direct update (DU) is a very fast, non-flashy update. This mode supports
82 transitions from any graytone to black or white only. It cannot be used to
83 update to any graytone other than black or white. The fast update time for this
84 mode makes it useful for response to touch sensor or pen input or menu selection
85 indictors.
86
87 GC16
88 The grayscale clearing (GC16) mode is used to update the full display and
89 provide a high image quality. When GC16 is used with Full Display Update the
90 entire display will update as the new image is written. If a Partial Update
91 command is used the only pixels with changing graytone values will update. The
92 GC16 mode has 16 unique gray levels.
93
94 GL16
95 The GL16 waveform is primarily used to update sparse content on a white
96 background, such as a page of anti-aliased text, with reduced flash. The
97 GL16 waveform has 16 unique gray levels.
98
99 GLR16
100 The GLR16 mode is used in conjunction with an image preprocessing algorithm to
101 update sparse content on a white background with reduced flash and reduced image
102 artifacts. The GLR16 mode supports 16 graytones. If only the even pixel states
103 are used (0, 2, 4, … 30), the mode will behave exactly as a traditional GL16
104 waveform mode. If a separately-supplied image preprocessing algorithm is used,
105 the transitions invoked by the pixel states 29 and 31 are used to improve
106 display quality. For the AF waveform, it is assured that the GLR16 waveform data
107 will point to the same voltage lists as the GL16 data and does not need to be
108 stored in a separate memory.
109
110 GLD16
111 The GLD16 mode is used in conjunction with an image preprocessing algorithm to
112 update sparse content on a white background with reduced flash and reduced image
113 artifacts. It is recommended to be used only with the full display update. The
114 GLD16 mode supports 16 graytones. If only the even pixel states are used (0, 2,
115 4, … 30), the mode will behave exactly as a traditional GL16 waveform mode. If a
116 separately-supplied image preprocessing algorithm is used, the transitions
117 invoked by the pixel states 29 and 31 are used to refresh the background with a
118 lighter flash compared to GC16 mode following a predetermined pixel map as
119 encoded in the waveform file, and reduce image artifacts even more compared to
120 the GLR16 mode. For the AF waveform, it is assured that the GLD16 waveform data
121 will point to the same voltage lists as the GL16 data and does not need to be
122 stored in a separate memory.
123
124 DU4
125 The DU4 is a fast update time (similar to DU), non-flashy waveform. This mode
126 supports transitions from any gray tone to gray tones 1,6,11,16 represented by
127 pixel states [0 10 20 30]. The combination of fast update time and four gray
128 tones make it useful for anti-aliased text in menus. There is a moderate
129 increase in ghosting compared with GC16.
130
131 A2
132 The A2 mode is a fast, non-flash update mode designed for fast paging turning or
133 simple black/white animation. This mode supports transitions from and to black
134 or white only. It cannot be used to update to any graytone other than black or
135 white. The recommended update sequence to transition into repeated A2 updates is
136 shown in Figure 1. The use of a white image in the transition from 4-bit to
137 1-bit images will reduce ghosting and improve image quality for A2 updates.
138 */
150
151// --- Registers ---
152static constexpr uint16_t DISPLAY_REG_BASE = 0x1000;
153static constexpr uint16_t UP1SR = DISPLAY_REG_BASE + 0x138;
154static constexpr uint16_t LUTAFSR = DISPLAY_REG_BASE + 0x224;
155static constexpr uint16_t BGVR = DISPLAY_REG_BASE + 0x250;
156
157static constexpr uint16_t I80CPCR = 0x0004;
158
159static constexpr uint16_t MCSR_BASE_ADDR = 0x0200;
160static constexpr uint16_t LISAR = MCSR_BASE_ADDR + 0x0008;
161
162// Display orientation flags
163static constexpr uint8_t TRANSFORM_NONE = 0;
164static constexpr uint8_t TRANSFORM_MIRROR_X = 1;
165static constexpr uint8_t TRANSFORM_MIRROR_Y = 2;
166static constexpr uint8_t TRANSFORM_SWAP_XY = 4;
167
168} // namespace esphome::it8951
uint32_t
static void uint32_t
Definition crash_handler.cpp:141
Generated by doxygen 1.12.0