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.
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¶
#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:
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.DisplayOn()enables the supply, waits for it to settle and turns the panel on.- The drawing calls send short commands (a rectangle) or pixel data (a window of colours).
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
Configfield 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.