Skip to content

Porting

Write the port for your MCU's SDK: a class with a few small methods that moves bytes and drives pins.

Datasheet sections this page relies on
  • Serial interface framing, D/C# and chip select: Solomon Systech (copy from the Adafruit mirror) SSD1331 1.2, 7.1.3 Serial Interface, p. 17
  • Serial interface timing: Solomon Systech (copy from the Adafruit mirror) SSD1331 1.2, 12 AC Characteristics, Table 21, p. 57
  • Communication, SCK frequency and chip select: NKK Switches OLED application notes none printed (web page), Design Considerations 2 and 5, p. 1

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

The driver never calls your SDK. It calls hooks on a class you derive from isf15acp4::SpiInterface<Self> (in inc/isf15acp4_spi_interface.hpp). The base uses CRTP and declares no hook itself; the driver template is constrained by the isf15acp4::SpiPort concept, so calls are resolved at compile time (no virtual functions, nothing to allocate) and a missing or misdeclared hook is a compile error at the point of use.

What you implement

Method Required Contract
bool EnsureInitialized() noexcept yes Bring the bus and the pins up, each at its idle level, on the first call; true at once afterwards. false makes the driver's EnsureInitialized() return Bus
bool Write(DataKind, const uint8_t* data, std::size_t len) noexcept yes One write-only transfer of 1 to 96 bytes (33 for a command; a bus limited to fewer bytes, such as ESP-IDF's SPI without DMA at 64, needs DMA or its own splitting): D/C# low for Command, high for Data, CS# low for all bytes, CS# high at the end. false on any bus error
bool GpioSet(CtrlPin, GpioSignal) noexcept yes Drive RES# or the supply enable; false if the pin write failed
void DelayUs(uint32_t us) noexcept yes Wait at least us microseconds
bool ReadSwitch(bool& high) noexcept no The switch pin's physical level; false on a read failure
uint32_t NowMs() noexcept no A free-running millisecond counter, may wrap
void Log(LogLevel, const char* message) noexcept no Print one line; message is plain text, never a format string

There is no read hook: the bus is write only.

The port

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;
};

Rules the transfer must follow:

  • One call, one transfer. Keep CS# low for all len bytes. A command and its parameters are one transfer: the controller takes the parameters as the bytes that follow the opcode while D/C# stays low, and splitting them is not allowed.
  • D/C# before CS#. Set D/C# for the kind first; it must be stable before the first clock (tAS 40 ns) and held after the last (tAH 40 ns).
  • The bus requirements below: mode 0 (mode 3 also works), MSB first, up to kMaxClockHz. Start at 1 MHz on jumper wires.
  • Raw bytes only. Do not interpret, retry or reorder bytes.
  • Return false for a bus error. The driver turns it into Error::Bus and never ignores it. Return true only when the bytes were clocked out: it does not mean the controller received them, and the driver does not claim that.
  • Bounded time-outs. A stuck bus fails the call; it does not block forever.

Bus requirements

The driver states what the controller needs from the bus as constexpr values in inc/isf15acp4_spi_interface.hpp (handbook KB-CPP-123). Check your port's settings against them with static_assert, as both example ports do, so a port that clocks too fast or in the wrong mode does not compile:

Constant Value Meaning (SSD1331 section 7.1.3, Table 21)
kSpiMode 0 CPOL 0, CPHA 0; mode 3 also works
kMsbFirst true Most significant bit first
kMaxClockHz 6'600'000 SCK cycle 150 ns minimum
kMinCsHighNs 150 CS# high between two transfers: assumed, the table gives none
kCsSetupNs, kCsHoldNs 75, 60 CS# low to the first SCK edge, last SCK edge to CS# high
kDcSetupNs, kDcHoldNs 40, 40 D/C# valid before and after the byte
kContinuousWord false Idle SCK time between the bytes of one transfer is allowed
kWriteOnly true There is no MISO

Control pins

Each control pin has a defined idle level, and the port drives it there before it enables the pin's output and before the driver's first transfer (handbook KB-HW-018). Configuring a pin as an output first and setting its level afterwards gives the module a pulse it did not ask for: a reset, or worse, the 15 V supply on.

CtrlPin Module pin Polarity Idle (INACTIVE) level Before the first transfer
Reset 5 RES active low high Set high, then enable the output
VccEnable enable of the 15 V supply active high low (supply off) Set low, then enable the output

GpioSignal::ACTIVE always means "function asserted"; the port maps it to the electrical level (RES# ACTIVE is low, the enable ACTIVE is the supply on, inverted for a low-side or P-channel switch). The supply enable must also be off while the MCU resets and boots: use a pull-down on the regulator's enable, because the port's code does not run then. D/C# is set inside Write().

The bytes passed to Write() live in the driver object (command_, data_). A port that uses DMA must be given a driver object in memory the DMA engine can read (internal RAM on an ESP32, not flash or PSRAM): declare it static or on the heap with DMA-capable capabilities, not in a section the engine cannot reach.

Optional hooks

The driver finds the optional hooks at compile time with named concepts in isf15acp4::detail. A missing hook falls back in a documented, safe way; a misdeclared one is a static_assert that names it; neither skips a step silently.

Hook Used for Without it
ReadSwitch() Poll(), ReadSwitchRaw() Those calls return Unsupported; the display works
NowMs() Poll() timestamps and idle timers, NotifyActivity() Poll() and NotifyActivity() return Unsupported
Log() One line per lifecycle event or failure Nothing is logged

A port with every hook:

class FullPort : public isf15acp4::SpiInterface<FullPort> {
public:
  bool EnsureInitialized() noexcept {
    return platform_gpio_write(kVccGpio, false) && platform_gpio_write(kResGpio, true) &&
           platform_spi_init();
  }
  bool Write(isf15acp4::DataKind kind, const uint8_t* data, std::size_t len) noexcept {
    return platform_gpio_write(kDcGpio, kind == isf15acp4::DataKind::Data) &&
           platform_spi_write(data, len);
  }
  bool GpioSet(isf15acp4::CtrlPin pin, isf15acp4::GpioSignal signal) noexcept {
    const bool active = (signal == isf15acp4::GpioSignal::ACTIVE);
    return (pin == isf15acp4::CtrlPin::Reset) ? platform_gpio_write(kResGpio, !active)
                                              : platform_gpio_write(kVccGpio, active);
  }
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

  // Optional: the switch pin's physical level. The driver applies the polarity.
  bool ReadSwitch(bool& high) noexcept {
    high = platform_gpio_read(kSwitchGpio);
    return true;
  }
  // Optional: a free-running millisecond counter; it may wrap.
  uint32_t NowMs() noexcept {
    return platform_millis();
  }
  // Optional: one line per lifecycle event or failure. The driver never formats; the port does.
  void Log(isf15acp4::LogLevel level, const char* message) noexcept {
    if (level > isf15acp4::LogLevel::Warning) {
      return;
    }
    platform_log(message); // plain text: never use it as a format string
  }

private:
  static constexpr int kDcGpio = 3;
  static constexpr int kVccGpio = 4;
  static constexpr int kSwitchGpio = 5;
  static constexpr int kResGpio = 11;
};
isf15acp4::Error RecoverFromDarkPanel(isf15acp4::ISF15ACP4<FullPort>& panel) {
  // The bus is write only: a brown-out of the logic supply cannot be detected, only repaired. This
  // runs the power-down, the start-up and the display-on again.
  return panel.Reinitialize().error;
}

A GpioSet() that returns void is a compile error: the driver must see a failed pin write, because it drives the supply with it. The compile-fail tests check that rule and the signatures of every hook.

Reference implementations

Every port lives with its example, in examples/<platform>/; the driver has none. Platforms lists them and how to add one.

Check your port

  1. Build it: the ports on this page are compiled by the host CI from tests/docs/, with the driver instantiated over them.
  2. Scope the supply enable: it must stay low through EnsureInitialized() and rise only in DisplayOn().
  3. Draw a rectangle and a diagonal (Quickstart). A dark panel with no error means a wire, the 15 V rail or the supply enable: the bus gives no other answer.

Threads

The driver is not thread-safe. Give each driver object one owner task, or guard every call with one mutex. When several devices share a bus, the port must also serialise the bus. See Contract.

Editor setup

The clang-format and clang-tidy configuration is in _config/, and the repository root has no copy of it. Tools that take a path use it directly; CI does the same:

Tool Setting
Command line clang-format --style=file:_config/.clang-format, clang-tidy --config-file=_config/.clang-tidy -p build
VS Code (C/C++ extension) "C_Cpp.clang_format_style": "file:${workspaceFolder}/_config/.clang-format" and "C_Cpp.codeAnalysis.clangTidy.args": ["--config-file=${workspaceFolder}/_config/.clang-tidy"]
clangd (VS Code clangd, Neovim, Emacs), CLion These find .clang-format and .clang-tidy only by name, from the file upwards: copy both to the root once (cp _config/.clang-format _config/.clang-tidy .). .gitignore lists the copies, so they never reach a commit; copy again after _config/ changes

Configure with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON (clangd: --compile-commands-dir=build) so the editor sees the same flags as the build.