Skip to content

Configuration

isf15acp4::Config holds every setting. Config{} is the ISF15ACP4's configuration; PresetFor() gives the other modules'.

Datasheet sections this page relies on
  • Switch circuit and contact data: NKK Switches ISF15ACP4_FramelessOLED (sheets E4 to E9, no number printed) none printed, Switch specifications (sheet E5), p. 2
  • Gray scale decoder: Solomon Systech (copy from the Adafruit mirror) SSD1331 1.2, 7.6 Gray Scale Decoder, p. 21
  • Contrast, master current and second pre-charge speed: Solomon Systech (copy from the Adafruit mirror) SSD1331 1.2, 9.1.3 to 9.1.5, p. 36
  • Re-map and data format: Solomon Systech (copy from the Adafruit mirror) SSD1331 1.2, 9.1.6 Set Re-map and Data Format (A0h), p. 37
  • Display start line, offset, mode and multiplex ratio: Solomon Systech (copy from the Adafruit mirror) SSD1331 1.2, 9.1.7 to 9.1.10, p. 42
  • Power save, phase periods, clock and pre-charge: Solomon Systech (copy from the Adafruit mirror) SSD1331 1.2, 9.1.14 to 9.1.20, p. 46
  • Variant geometry and column offsets: NKK Switches ISC15ANP4 (sheets E4 to E9, no number printed) none printed, Block diagram and pin configurations (sheet E6), p. 3
  • Display-only variant: NKK Switches ISC01P (sheets E4 to E9, no number printed) none printed, Switch and OLED specifications (sheets E5, E6), p. 2
  • Start-up values of each module: NKK Switches OLED application notes none printed (web page), Initialization, Tables 1 to 3, steps 4.1 to 4.18 (Note 1, Note 2), p. 1

All of them, with the driver API for each: Datasheet map.

Fields

The defaults are the ISF15ACP4's table (NKK application notes, Table 3, steps 4.1 to 4.18); PresetFor() gives Tables 1 and 2. NKK Note 1: changing the set-up values (contrast, display offset, multiplex ratio, phase periods, clock, linear gray scale, pre-charge level, VCOMH) may damage the OLED module.

Field Default Valid Command
variant Isf15acp4 the three modules geometry
remap see below A0h
contrast_a, _b, _c 0x1C, 0x2E, 0x2C 0 to 255 81h, 82h, 83h
precharge_speed_a, _b, _c 0x4F, 0x74, 0x88 0 to 255 8Ah, 8Bh, 8Ch (one transfer)
send_precharge_speeds true (false for the two smaller modules) whether 8Ah to 8Ch are sent: only Table 3 has them
master_current 15 (full) 0 to 15 87h
start_line, display_offset 0, 0 0 to 63 A1h, A2h
mode Normal normal, all on, all off, inverse A4h to A7h
dim 0x0E, 0x17, 0x16, pre-charge 0x12 contrast at most the colour's contrast_*, pre-charge 0 to 31 ABh
power_save false B0h
phase1, phase2 7, 1 1 to 15 B1h
clock_divide, clock_frequency 0, 15 0 to 15 B3h
precharge_level, vcomh_level 14, 16 0 to 31 BBh, BEh
precharge_bit0 true (false for the two smaller modules) bit 0 of BBh: Table 3 sends 1Dh, Tables 1 and 2 send 12h
linear_gray_scale true B9h
clear_ram true RAM zeroed before the supply can light it
red_on_segment_a true panel wiring (Ambiguities)
writes_while_scrolling false allow RAM writes during a scroll
vcc_settle_ms 50 1 to 1000 wait after the supply enable
vcc_off_ms 100 0 to 1000 wait after the supply goes off
engine_settle_us 3000 0 to 100 000 wait after a drawing command
idle_dim_ms, idle_sleep_ms 0, 0 (never) up to 6 000 000; sleep above dim Poll() policy
button see below the switch

Remap: horizontal RAM increment, no column mirror, colour order A-B-C, COM left-right swap on, COM scan normal, odd-even split on, 65k colour format 1.

ButtonConfig: active low (pull-up, closed reads low), debounce_ms 20 (1 to 1000), long_press_ms 800 (above the debounce time, to 60 000), repeat_interval_ms 0 (none; else 10 to 10 000), repeat_delay_ms 500.

The defaults after the first three rows of timing are the module's initialisation values, not the SSD1331's reset values: Ambiguities says where they come from.

Presets

Preset Module What differs from Config{}
PresetFor(Variant::Isf15acp4) 96 x 64, switch none
PresetFor(Variant::Isc15anp4) 64 x 48, switch geometry (column offset 16, 48 rows), COM scan reversed, contrast, offset, clock, pre-charge, VCOMH
PresetFor(Variant::Isc01p) 52 x 36, display only geometry (column offset 22, 36 rows), as above; Poll() returns Unsupported
isf15acp4::Config DimmerConfig() {
  isf15acp4::Config c = isf15acp4::PresetFor(isf15acp4::Variant::Isf15acp4);
  c.master_current = 8;          // half the segment current: less heat, longer life
  c.idle_dim_ms = 30'000;        // Poll() dims after 30 s without a press
  c.idle_sleep_ms = 120'000;     // and turns the display off after 2 min; a press wakes it
  c.button.long_press_ms = 1000; // the long-press event
  return c;                      // isf15acp4::Validate(c) checks it without the chip
}

isf15acp4::Error Start(MyPort& port) {
  static isf15acp4::ISF15ACP4<MyPort> panel(port, DimmerConfig()); // stored, no I/O
  return panel.EnsureInitialized().error; // InvalidArgument if the config is out of range
}

Validation

isf15acp4::Validate(config) checks a configuration without touching the module, and EnsureInitialized(), Reinitialize() and ApplyConfig() call it before any I/O. It returns InvalidArgument when an enum holds a value that is not an enumerator, a level or time is outside its range, a dim contrast is above the contrast of its colour (NKK: ACh may not exceed the start-up contrasts), the sleep time is not above the dim time, or the switch configuration fails. CheckedConfig runs the same check at compile time:

// A configuration that Validate() rejects does not compile.
constexpr isf15acp4::CheckedConfig kBoard{isf15acp4::Config{.master_current = 12}};

const isf15acp4::Config& BoardConfig() {
  return kBoard.Get();
}

Kconfig

Under ESP-IDF, idf.py menuconfig shows ISF15ACP4 OLED pushbutton when the driver is a component of the project (Installation); the menu is _config/Kconfig. The options reach the code only through inc/isf15acp4_kconfig.hpp, never through a driver signature:

isf15acp4::Error StartFromMenuconfig(MyPort& port) {
  static isf15acp4::ISF15ACP4<MyPort> panel(port, isf15acp4::KconfigDefaults());
  return panel.EnsureInitialized().error;
}
Option Default Config field
CONFIG_ISF15ACP4_VARIANT_* ISF15ACP4 variant and its preset
CONFIG_ISF15ACP4_MASTER_CURRENT 15 master_current
CONFIG_ISF15ACP4_RED_ON_SEGMENT_A y red_on_segment_a
CONFIG_ISF15ACP4_BUTTON_ACTIVE_LOW y button.active_low
CONFIG_ISF15ACP4_BUTTON_DEBOUNCE_MS 20 button.debounce_ms
CONFIG_ISF15ACP4_BUTTON_LONG_PRESS_MS 800 button.long_press_ms
CONFIG_ISF15ACP4_IDLE_DIM_MS 0 idle_dim_ms
CONFIG_ISF15ACP4_IDLE_SLEEP_MS 0 idle_sleep_ms

Without Kconfig (plain CMake, other platforms) KconfigDefaults() returns Config{}. Both cases are host tests.

Next: Porting.