Skip to content

Quickstart

Run the driver on your PC first, with no hardware; then wire the module, write a small port class and call four driver functions.

Datasheet sections this page relies on

From NKK Switches ISF15ACP4_FramelessOLED (sheets E4 to E9, no number printed) none printed:

  • Module pins, switch contacts and block diagram: Block diagram and pin configurations (sheet E6), p. 3

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

Try it on your PC

examples/host/ runs the real driver against a simulated controller, through a host port. From the repository root, with CMake and a C++20 compiler:

cmake -S examples/host -B build-example
cmake --build build-example
./build-example/isf15acp4_host_example
ISF15ACP4 driver 0.1.0 on the host
isf15acp4: initialised, supply off
isf15acp4: supply on
  event 1 at 1235 ms
  event 3 at 2035 ms
  event 2, held 1000 ms
isf15acp4: display and supply off
3 button events; panel lit: yes; power-down clean: yes

The calls in main.cpp are the ones below; only the port differs on an MCU. CI builds and runs this example on every pull request.

1. Wire it

MCU Module pin Notes
SPI SCLK 7 SCK Mode 0, up to 6.6 MHz; 1 to 4 MHz is a good start
SPI MOSI 8 SDI There is no data out: do not connect MISO
GPIO chip select 4 SS Low for the whole transfer
GPIO 6 D/C Low for a command, high for pixel data
GPIO 5 RES Idles high
GPIO enable of the 15 V supply Active high; must idle low through reset and boot (pull-down)
3.3 V 3 VDD 2.4 V to 3.5 V
15 V supply 9 VCC 14 V to 16 V (ISC15ANP4, ISC01P: 15 V to 17 V), current 11 mA typical with all pixels on
GPIO input with pull-up 1 SW The switch to ground on pin 2; closed reads low
GND 10 GND, 2 SW

The 15 V OLED supply is not part of the module: it is yours, with an enable the driver controls. Hardware draws the circuit.

2. Write the port

The port is the only platform code: it brings the bus and the pins up at their idle levels, moves bytes with D/C# set for the kind of transfer, and waits. Replace the platform_* calls with your SDK's.

my_port.hpp
class MyPort : public isf15acp4::SpiInterface<MyPort> {
public:
  // Bring the bus and the pins up once, each at its idle level (supply off, RES# high, CS# high);
  // later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_vcc(false) && platform_res(true) && platform_spi_init();
    }
    return ready_;
  }

  // One write-only transfer, CS low for all `len` bytes. There is no read.
  bool Write(isf15acp4::DataKind kind, const uint8_t* data, std::size_t len) noexcept {
    return platform_dc(kind == isf15acp4::DataKind::Data) && platform_spi_write(data, len);
  }

  // RES# is active low and the supply enable active high; the port maps the logical level.
  bool GpioSet(isf15acp4::CtrlPin pin, isf15acp4::GpioSignal signal) noexcept {
    const bool active = (signal == isf15acp4::GpioSignal::ACTIVE);
    if (pin == isf15acp4::CtrlPin::Reset) {
      return platform_res(!active);
    }
    return platform_vcc(active);
  }

  // Wait at least `us` microseconds: the reset and the supply waits depend on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Porting explains each hook and the optional ones (switch, clock, log).

3. Show something

main.cpp
#include "isf15acp4.hpp"

int show_hello(MyPort& port) {
  isf15acp4::ISF15ACP4<MyPort> panel(port); // no I/O yet

  if (auto r = panel.EnsureInitialized();
      !r) {                           // 1. reset, configure, clear: the supply is still off
    return static_cast<int>(r.error); //    Bus or InvalidArgument: check wiring and Config
  }
  if (auto r = panel.DisplayOn(); !r) { // 2. only now is the 15 V supply enabled and the panel on
    return static_cast<int>(r.error);
  }
  if (auto r = panel.DrawRectangle(0, 0, 95, 63, isf15acp4::kWhite); !r) { // 3. draw
    return static_cast<int>(r.error);
  }
  static_cast<void>(panel.Deinitialize()); // 4. display off, supply off, wait: always runs
  return 0;
}

What each step does:

  1. EnsureInitialized() brings your bus up, drives the supply enable off, resets the controller, sends the whole configuration and clears the display RAM. The panel stays dark and the 15 V supply stays off.
  2. DisplayOn() enables the supply, waits for it to settle and turns the panel on.
  3. The drawing calls send short commands (a rectangle) or pixel data (a window of colours).
  4. Deinitialize() turns the panel off, switches the supply off and waits. It always runs.

Reading the switch is one more call, Poll(), described in the API guide.

If it does not work

The bus is write only, so a wrong wire never gives an error. A dark panel is the symptom for most faults.

Symptom First thing to check
EnsureInitialized() returns Bus Your port's EnsureInitialized(), or a pin that cannot be driven
EnsureInitialized() returns InvalidArgument The Config fails Validate(): nothing was sent
Panel dark, no error 15 V rail present and enabled? D/C#, RES#, SS# wired? Troubleshooting
Colours swapped Config::red_on_segment_a or Remap::reverse_colour_order (Ambiguities)
Poll() returns Unsupported Your port has no ReadSwitch() or NowMs() hook

Next

  • API guide: pixels, the drawing engine, scrolling, the button, errors.
  • Configuration: every Config field and the variant presets.
  • Examples: the host example and the ESP-IDF example.
  • Limitations: what the write-only bus and the missing hardware test mean for you.