17#ifndef ISF15ACP4_TYPES_HPP
18#define ISF15ACP4_TYPES_HPP
24#include "isf15acp4_version.h"
41enum class [[nodiscard]]
Error : uint8_t {
71 return "NotInitialized";
73 return "InvalidArgument";
79 return "DeviceIdMismatch";
89 return "ScrollActive";
91 return "ScrollNotSet";
115 [[nodiscard]]
constexpr bool ok() const noexcept {
116 return error == Error::Ok;
119 constexpr explicit operator bool() const noexcept {
129 return {v, Error::Ok};
147 [[nodiscard]]
constexpr bool ok() const noexcept {
148 return error == Error::Ok;
151 constexpr explicit operator bool() const noexcept {
265 return Geometry{.
width = 96, .height = 64, .column_origin = 0, .multiplex = 64};
267 return Geometry{.
width = 64, .height = 48, .column_origin = 16, .multiplex = 48};
269 return Geometry{.
width = 52, .height = 36, .column_origin = 22, .multiplex = 36};
273 return Geometry{.
width = 96, .height = 64, .column_origin = 0, .multiplex = 64};
301 return (a.active_low == b.active_low) && (a.debounce_ms == b.debounce_ms) &&
302 (a.long_press_ms == b.long_press_ms) && (a.repeat_interval_ms == b.repeat_interval_ms) &&
303 (a.repeat_delay_ms == b.repeat_delay_ms);
368 c.remap.com_left_right_swap =
false;
369 c.remap.com_scan_reverse =
true;
373 c.precharge_level = 9;
374 c.precharge_bit0 =
false;
375 c.send_precharge_speeds =
false;
380 c.display_offset = 0x10;
381 c.clock_frequency = 10;
389 c.display_offset = 0x1C;
390 c.clock_frequency = 3;
395 c.precharge_speed_a = c.contrast_a;
396 c.precharge_speed_b = c.contrast_b;
397 c.precharge_speed_c = c.contrast_c;
432 if ((b.debounce_ms == 0U) || (b.debounce_ms > 1000U)) {
435 if ((b.long_press_ms <= b.debounce_ms) || (b.long_press_ms >
kButtonTimeMaxMs)) {
438 if (b.repeat_interval_ms != 0U) {
439 if ((b.repeat_interval_ms < 10U) || (b.repeat_interval_ms > 10000U)) {
452constexpr bool DisplayFieldsValid(
const Config& config)
noexcept {
454 IsEnumerator(config.variant) && IsEnumerator(config.remap.depth) && IsEnumerator(config.mode);
456 const bool dim_ok = (config.dim.contrast_a <= config.contrast_a) &&
457 (config.dim.contrast_b <= config.contrast_b) &&
458 (config.dim.contrast_c <= config.contrast_c);
463 return enums && rows && levels;
467constexpr bool ClockFieldsValid(
const Config& config)
noexcept {
468 const bool phases = (config.phase1 != 0U) && (config.phase1 <=
reg::kPhaseMax) &&
470 return phases && (config.clock_divide <= 15U) && (config.clock_frequency <= 15U);
474constexpr bool TimeKnobsValid(
const Config& config)
noexcept {
475 const bool waits = (config.vcc_settle_ms != 0U) && (config.vcc_settle_ms <=
kWaitMaxMs) &&
480 const bool ordered = (config.idle_dim_ms == 0U) || (config.idle_sleep_ms == 0U) ||
481 (config.idle_sleep_ms > config.idle_dim_ms);
482 return waits && idle && ordered;
498 if (!detail::DisplayFieldsValid(config) || !detail::ClockFieldsValid(config) ||
499 !detail::TimeKnobsValid(config)) {
540 [[nodiscard]]
constexpr const Config&
Get() const& noexcept {
544 void Get() const&& = delete;
566 const uint32_t word = ((
static_cast<uint32_t
>(r) >> 3U) << 11U) |
567 ((
static_cast<uint32_t
>(g) >> 2U) << 5U) | (
static_cast<uint32_t
>(b) >> 3U);
568 return Color{
static_cast<uint16_t
>(word)};
595 const uint32_t w = c.rgb565;
596 return Channels{.
red =
static_cast<uint8_t
>((w >> 11U) & 0x1FU),
597 .green =
static_cast<uint8_t
>((w >> 5U) & 0x3FU),
598 .blue =
static_cast<uint8_t
>(w & 0x1FU)};
607 return ISF15ACP4_VERSION_STRING;
611 return ISF15ACP4_VERSION_MAJOR;
615 return ISF15ACP4_VERSION_MINOR;
619 return ISF15ACP4_VERSION_PATCH;
A configuration proven valid at build time.
Definition isf15acp4_types.hpp:528
void Get() const &&=delete
Not on a temporary: the reference would dangle (KB-CPP20-044).
consteval CheckedConfig(const Config &config) noexcept
Check config at build time.
Definition isf15acp4_types.hpp:534
constexpr const Config & Get() const &noexcept
Definition isf15acp4_types.hpp:540
constexpr uint32_t kVccOffTypicalMs
VCC off to VDD off, minimum 0 and typical 100 ms (section 7.9, tOFF).
Definition isf15acp4_registers.hpp:166
constexpr uint8_t kPhaseMax
B1h: 1 to 15 DCLK per phase.
Definition isf15acp4_registers.hpp:102
constexpr uint8_t kRamColumns
GDDRAM width: columns 0 to 95 (section 7.5.1).
Definition isf15acp4_registers.hpp:96
constexpr uint8_t kRamRows
GDDRAM height: rows 0 to 63.
Definition isf15acp4_registers.hpp:97
constexpr uint8_t kMasterCurrentMax
87h: 1/16 to 16/16 (steps 0 to 15).
Definition isf15acp4_registers.hpp:100
constexpr uint8_t kPrechargeSteps
BBh, BEh, ABh E: A[5:1] 0 to 31.
Definition isf15acp4_registers.hpp:101
constexpr Color MakeColor(uint8_t r, uint8_t g, uint8_t b) noexcept
An RGB565 colour from 8-bit channels (the low bits are dropped, not rounded).
Definition isf15acp4_types.hpp:565
constexpr Color kBlack
Black.
Definition isf15acp4_types.hpp:572
constexpr uint32_t kWaitMaxMs
Longest wait the driver accepts for the supply and engine times, in milliseconds.
Definition isf15acp4_types.hpp:309
constexpr Color kRed
Pure red.
Definition isf15acp4_types.hpp:576
constexpr Error Validate(const ButtonConfig &b) noexcept
Check the switch configuration without touching the chip.
Definition isf15acp4_types.hpp:431
constexpr uint32_t GetDriverVersionMinor() noexcept
Definition isf15acp4_types.hpp:614
ButtonEvent
What a switch poll can report.
Definition isf15acp4_types.hpp:215
DisplayMode
What the pixels show (A4h to A7h).
Definition isf15acp4_types.hpp:192
constexpr uint32_t GetDriverVersionMajor() noexcept
Definition isf15acp4_types.hpp:610
constexpr const char * ToString(Error error) noexcept
The name of an error, for logs.
Definition isf15acp4_types.hpp:66
LogLevel
Severity passed to the optional Log() hook.
Definition isf15acp4_types.hpp:170
constexpr Config PresetFor(Variant variant) noexcept
The working set of a module.
Definition isf15acp4_types.hpp:362
ColorDepth
The pixel format of GDDRAM (A0h A[7:6]).
Definition isf15acp4_types.hpp:185
constexpr bool SameButtonConfig(const ButtonConfig &a, const ButtonConfig &b) noexcept
Whether two switch configurations are the same, field by field.
Definition isf15acp4_types.hpp:300
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition isf15acp4_types.hpp:41
constexpr Channels Split(Color c) noexcept
Split an RGB565 colour.
Definition isf15acp4_types.hpp:594
constexpr uint32_t GetDriverVersionPatch() noexcept
Definition isf15acp4_types.hpp:618
constexpr const char * GetDriverVersion() noexcept
Definition isf15acp4_types.hpp:606
constexpr uint32_t kButtonTimeMaxMs
Longest button time the driver accepts, in milliseconds (keeps every difference below 2^31).
Definition isf15acp4_types.hpp:307
ScrollInterval
The time between two scroll steps (27h E).
Definition isf15acp4_types.hpp:207
Output
What the panel is doing, as far as the driver knows.
Definition isf15acp4_types.hpp:200
void ConfigIsInvalid() noexcept
Reached only when a CheckedConfig is built from an invalid configuration: it is never defined,...
constexpr uint32_t kEngineSettleMaxUs
Longest engine settle time, in microseconds.
Definition isf15acp4_types.hpp:311
constexpr Geometry GeometryOf(Variant variant) noexcept
The geometry of a module (NKK sheets: pixel format; the column origin of the smaller panels is the ce...
Definition isf15acp4_types.hpp:262
constexpr Color kWhite
White.
Definition isf15acp4_types.hpp:574
constexpr Color kBlue
Pure blue.
Definition isf15acp4_types.hpp:580
constexpr bool HasSwitch(Variant variant) noexcept
Whether a module has the pushbutton (the ISC01P is a display only).
Definition isf15acp4_types.hpp:281
constexpr Color kGreen
Pure green.
Definition isf15acp4_types.hpp:578
Variant
The three modules of the family; they share the controller and differ in the panel.
Definition isf15acp4_types.hpp:178
@ LongPress
Held for long_press_ms; once per press.
@ Repeat
Held on: one per repeat_interval_ms after repeat_delay_ms.
@ Pressed
The switch closed and stayed closed for the debounce time.
@ Released
The switch opened and stayed open for the debounce time.
@ Normal
The RAM content (A4h).
@ Inverse
Gray levels swapped, GS0 <-> GS63 (A7h).
@ AllOff
Every pixel at GS0 (A6h).
@ AllOn
Every pixel at GS63 (A5h).
@ Warning
Something unexpected that the driver recovered from.
@ Info
Lifecycle events: initialised, supply on or off.
@ Debug
Detail for bring-up.
@ Colors65k
2 bytes per pixel, format 1: C[4:0] B[5:0] A[4:0]. Reset value.
@ Colors256
1 byte per pixel: C[4:2] B[5:3] A[4:3].
@ Colors65kFormat2
3 bytes per pixel, format 2: six bits per byte (Table 9).
@ InvalidArgument
An argument or a Config field is out of range; nothing was sent.
@ SupplyOff
The call needs the OLED supply on (raw display-on).
@ DeviceIdMismatch
Not returned by this driver: the controller has no ID and cannot answer.
@ Crc
Not returned by this driver: the serial interface has no checksum.
@ ScrollActive
A RAM, drawing or setup call while scrolling is on (Deactivate first).
@ Bus
A port hook returned false (a transfer or a pin write).
@ DeviceFault
Not returned by this driver: the controller reports no fault.
@ NotInitialized
EnsureInitialized() has not succeeded, or Deinitialize() ran since.
@ Timeout
Not returned by this driver: nothing the driver waits for is observable.
@ Locked
The controller is command-locked by SetCommandLock(true).
@ Busy
Not returned by this driver: every wait blocks until it has elapsed.
@ ScrollNotSet
ActivateScroll() before SetupScroll() succeeded.
@ Dim
Display on in dim mode (ACh).
@ Off
Sleep (AEh): segments and commons are high impedance.
@ Isc15anp4
64 x 48 pixels, pushbutton (NKK sheet ISC15ANP4).
@ Isc01p
52 x 36 pixels, display only (NKK sheet ISC01P): no switch.
@ Isf15acp4
96 x 64 pixels, frameless pushbutton (NKK sheet E4 to E7).
Compile-time helpers of the ISF15ACP4 driver: typed integer literals, exact hook matching,...
SSD1331 command set: opcodes, parameter fields, limits and timing (SSD1331 datasheet Rev 1....
The ISF15ACP4 driver: everything it declares lives here; internals in detail.
Definition isf15acp4.hpp:31
The red, green and blue fields of a colour (5, 6 and 5 bits).
Definition isf15acp4_types.hpp:583
uint8_t red
0 to 31.
Definition isf15acp4_types.hpp:584
uint8_t green
0 to 63.
Definition isf15acp4_types.hpp:585
uint8_t blue
0 to 31.
Definition isf15acp4_types.hpp:586
A colour as the RGB565 word every call takes: red in bits 15..11, green 10..5, blue 4....
Definition isf15acp4_types.hpp:554
uint16_t rgb565
The word.
Definition isf15acp4_types.hpp:555
Everything the driver sends at start-up, and its own time knobs.
Definition isf15acp4_types.hpp:322
uint8_t precharge_speed_a
8Ah: second pre-charge speed, colour A.
Definition isf15acp4_types.hpp:328
uint32_t vcc_off_ms
VCC off to the end of power-down (tOFF typical).
Definition isf15acp4_types.hpp:350
bool precharge_bit0
BBh bit 0 (reserved): NKK Table 3 sends 1Dh, Tables 1/2 12h.
Definition isf15acp4_types.hpp:342
bool send_precharge_speeds
8Ah to 8Ch: only the ISF15ACP4 table (Table 3) has them.
Definition isf15acp4_types.hpp:343
bool linear_gray_scale
B9h at start-up (false: the reset table stays).
Definition isf15acp4_types.hpp:345
uint8_t contrast_b
82h.
Definition isf15acp4_types.hpp:326
uint8_t start_line
A1h, 0 to 63.
Definition isf15acp4_types.hpp:332
DisplayMode mode
A4h to A7h.
Definition isf15acp4_types.hpp:334
uint32_t vcc_settle_ms
VCC enable to AFh; the datasheet says only "stable".
Definition isf15acp4_types.hpp:349
uint8_t precharge_speed_b
8Bh.
Definition isf15acp4_types.hpp:329
ButtonConfig button
The switch.
Definition isf15acp4_types.hpp:354
uint32_t idle_sleep_ms
Poll(): sleep after this idle time; 0 = never.
Definition isf15acp4_types.hpp:353
Remap remap
A0h.
Definition isf15acp4_types.hpp:324
uint8_t vcomh_level
BEh A[5:1], 0 to 31.
Definition isf15acp4_types.hpp:344
uint8_t display_offset
A2h, 0 to 63.
Definition isf15acp4_types.hpp:333
uint32_t idle_dim_ms
Poll(): dim after this idle time; 0 = never.
Definition isf15acp4_types.hpp:352
uint8_t master_current
87h, 0 to 15 (1/16 to 16/16).
Definition isf15acp4_types.hpp:331
bool writes_while_scrolling
Allow RAM writes while scrolling (datasheet is silent).
Definition isf15acp4_types.hpp:348
uint8_t precharge_level
BBh A[5:1], 0 to 31.
Definition isf15acp4_types.hpp:341
uint32_t engine_settle_us
Wait after a drawing command; not in the datasheet.
Definition isf15acp4_types.hpp:351
uint8_t precharge_speed_c
8Ch.
Definition isf15acp4_types.hpp:330
uint8_t phase1
B1h phase 1, 1 to 15 DCLK.
Definition isf15acp4_types.hpp:337
uint8_t clock_divide
B3h A[3:0]: ratio is this + 1.
Definition isf15acp4_types.hpp:339
Variant variant
Which module; sets the geometry.
Definition isf15acp4_types.hpp:323
uint8_t phase2
B1h phase 2, 1 to 15 DCLK.
Definition isf15acp4_types.hpp:338
uint8_t clock_frequency
B3h A[7:4].
Definition isf15acp4_types.hpp:340
bool power_save
B0h: false = disabled (reset value: enabled).
Definition isf15acp4_types.hpp:336
DimSettings dim
ABh.
Definition isf15acp4_types.hpp:335
uint8_t contrast_a
81h. Reset value 0x80.
Definition isf15acp4_types.hpp:325
uint8_t contrast_c
83h.
Definition isf15acp4_types.hpp:327
bool clear_ram
Zero GDDRAM before the supply is enabled.
Definition isf15acp4_types.hpp:346
bool red_on_segment_a
Panel wiring: segment group A carries red.
Definition isf15acp4_types.hpp:347
Dim mode parameters (ABh): used when the display is on in dim mode (ACh).
Definition isf15acp4_types.hpp:241
uint8_t precharge
Pre-charge level in dim mode, 0 to 31 (0.10 to 0.50 x VCC).
Definition isf15acp4_types.hpp:245
uint8_t contrast_a
Contrast of colour A in dim mode.
Definition isf15acp4_types.hpp:242
uint8_t contrast_b
Contrast of colour B in dim mode.
Definition isf15acp4_types.hpp:243
uint8_t contrast_c
Contrast of colour C in dim mode.
Definition isf15acp4_types.hpp:244
Geometry of a module: its visible pixels inside the 96 x 64 RAM.
Definition isf15acp4_types.hpp:249
uint8_t multiplex
Rows scanned (A8h: N + 1).
Definition isf15acp4_types.hpp:253
uint8_t height
Visible rows.
Definition isf15acp4_types.hpp:251
uint8_t width
Visible columns.
Definition isf15acp4_types.hpp:250
uint8_t column_origin
RAM column of the first visible column.
Definition isf15acp4_types.hpp:252
A position in the visible area.
Definition isf15acp4_types.hpp:235
uint8_t y
Row.
Definition isf15acp4_types.hpp:237
uint8_t x
Column.
Definition isf15acp4_types.hpp:236
The controller settings that depend on the wiring of the panel (Remap, A0h).
Definition isf15acp4_types.hpp:224
bool column_reverse
A[1]: RAM column 0 drives SEG95 (mirror).
Definition isf15acp4_types.hpp:226
bool reverse_colour_order
A[2]: segment order SC, SB, SA.
Definition isf15acp4_types.hpp:227
bool com_scan_reverse
A[4]: scan COM[N-1] to COM0.
Definition isf15acp4_types.hpp:229
bool com_split_odd_even
A[5]: odd-even split of the COM pins.
Definition isf15acp4_types.hpp:230
ColorDepth depth
A[7:6].
Definition isf15acp4_types.hpp:231
bool com_left_right_swap
A[3]: left-right swap on COM.
Definition isf15acp4_types.hpp:228
bool vertical_increment
A[0]: the RAM address runs down a column first.
Definition isf15acp4_types.hpp:225
constexpr bool ok() const noexcept
Definition isf15acp4_types.hpp:147
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition isf15acp4_types.hpp:164
static constexpr Result Success() noexcept
Definition isf15acp4_types.hpp:156
The value of a call, or why there is none.
Definition isf15acp4_types.hpp:110
static constexpr Result Success(T v) noexcept
A successful result.
Definition isf15acp4_types.hpp:128
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition isf15acp4_types.hpp:136
constexpr bool ok() const noexcept
Definition isf15acp4_types.hpp:115