ISF15ACP4 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
isf15acp4::ISF15ACP4< Port > Class Template Reference

Driver for one ISF15ACP4 on a platform port. More...

#include <isf15acp4.hpp>

Public Member Functions

 ISF15ACP4 (Port &port, const Config &config={}) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail.
 
 ISF15ACP4 (const ISF15ACP4 &)=delete
 One driver object per module.
 
ISF15ACP4 & operator= (const ISF15ACP4 &)=delete
 One driver object per module.
 
Lifecycle
Result< void > EnsureInitialized () noexcept
 Power up to state 1: the controller is reset, configured and cleared, the supply is off.
 
bool IsInitialized () const noexcept
 
Result< void > Deinitialize () noexcept
 The power-down: command unlock, display off, supply off, wait vcc_off_ms. Never refused.
 
Result< void > Reinitialize () noexcept
 Power-down, then start again, then restore the display state that was on.
 
Display on and off
Result< void > DisplayOn () noexcept
 Turn the panel on at normal brightness (state 1 to 2): supply on, wait vcc_settle_ms, AFh, wait tAF (100 ms). From dim mode only AFh is sent.
 
Result< void > DisplayDim () noexcept
 Turn the panel on in dim mode (ACh; the ABh settings), as DisplayOn().
 
Result< void > DisplayOff () noexcept
 Turn the panel off and the supply off (state 2 to 1): unlock if locked, AEh, supply off.
 
Output GetOutput () const noexcept
 
bool IsSupplyEnabled () const noexcept
 
Configuration
Result< void > ApplyConfig (const Config &config) noexcept
 Change the whole configuration.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 
Geometry GetGeometry () const noexcept
 
Result< void > SetContrast (uint8_t a, uint8_t b, uint8_t c) noexcept
 Set the contrast of the three colours (81h, 82h, 83h).
 
Result< void > SetMasterCurrent (uint8_t step) noexcept
 Set the master current attenuation, 0 to 15 (87h).
 
Result< void > SetPrechargeSpeed (uint8_t a, uint8_t b, uint8_t c) noexcept
 Set the second pre-charge speed of the three colours; all six bytes go out together (8Ah to 8Ch). The values are stored and send_precharge_speeds is set, so a restart sends them again, also on the two smaller modules whose NKK tables leave them out.
 
Result< void > SetRemap (const Remap &remap) noexcept
 Set the remap and colour depth (A0h). Changes how pixels are sent: ColorDepth, vertical_increment.
 
Result< void > SetStartLine (uint8_t line) noexcept
 Set the display start line, 0 to 63 (A1h).
 
Result< void > SetDisplayOffset (uint8_t offset) noexcept
 Set the display offset, 0 to 63 (A2h).
 
Result< void > SetDisplayMode (DisplayMode mode) noexcept
 Set what the pixels show (A4h to A7h).
 
Result< void > SetMultiplexRatio (uint8_t rows) noexcept
 Set the multiplex ratio, 16 to 64 rows (A8h). Vertical scrolling needs 64. Not stored in Config: a restart (Reinitialize(), ApplyConfig()) goes back to the module's ratio.
 
Result< void > SetDimSettings (const DimSettings &dim) noexcept
 Set the dim mode parameters (ABh); they apply at the next DisplayDim().
 
Result< void > SetPowerSave (bool enable) noexcept
 Enable or disable the power save mode (B0h).
 
Result< void > SetPhasePeriods (uint8_t phase1, uint8_t phase2) noexcept
 Set phase 1 and phase 2 periods, 1 to 15 DCLK each (B1h).
 
Result< void > SetClock (uint8_t divide, uint8_t frequency) noexcept
 Set the clock divide ratio (this + 1) and oscillator frequency, 0 to 15 each (B3h).
 
Result< void > SetGrayScaleTable (std::span< const uint8_t, reg::kGrayScaleEntries > widths) noexcept
 Set the 32 gray scale pulse widths GS1, GS3 ... GS63, each 1 to 125 and rising (B8h). The table is not stored: a restart loads the start-up gray scale again (B9h when linear_gray_scale is set, NKK step 4.15).
 
Result< void > UseLinearGrayScale () noexcept
 Reload the built-in linear gray scale table (B9h).
 
Result< void > SetPrechargeLevel (uint8_t level) noexcept
 Set the pre-charge voltage level, 0 to 31 (0.10 to 0.50 x VCC) (BBh).
 
Result< void > SetVcomh (uint8_t level) noexcept
 Set the VCOMH level, 0 to 31 (0.44 to 0.83 x VCC) (BEh).
 
Result< void > SetCommandLock (bool lock) noexcept
 Lock or unlock the controller's command interface (FDh).
 
Result< void > Nop () noexcept
 Send a no-operation command (E3h).
 
Pixels (GDDRAM)
Result< void > Present (std::span< const Color > frame) noexcept
 Show a whole frame: GetGeometry().width * height colours, row by row.
 
Result< void > WriteWindow (uint8_t x, uint8_t y, uint8_t width, uint8_t height, std::span< const Color > pixels) noexcept
 Write a rectangle of colours into GDDRAM, row by row.
 
Result< void > WriteWindowRaw (uint8_t x, uint8_t y, uint8_t width, uint8_t height, std::span< const uint8_t > bytes) noexcept
 Write raw RAM bytes into a window: the caller has encoded them for the colour depth (2 bytes per pixel in 65k format 1). Sent in the order given.
 
Result< void > FillWindow (uint8_t x, uint8_t y, uint8_t width, uint8_t height, Color color) noexcept
 Fill a rectangle of GDDRAM with one colour by streaming data (no drawing engine).
 
Result< void > SetPixel (uint8_t x, uint8_t y, Color color) noexcept
 Set one pixel (a 1 x 1 window and its data).
 
Result< void > Clear (Color color=kBlack) noexcept
 Fill the whole visible area with one colour.
 
bool RamNeedsRewrite () const noexcept
 
Drawing engine
Result< void > DrawLine (uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, Color color) noexcept
 Draw a line with the controller's engine (21h), then wait engine_settle_us.
 
Result< void > DrawRectangle (uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, Color outline) noexcept
 Draw a rectangle outline (26h, 22h), then wait engine_settle_us.
 
Result< void > FillRectangle (uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, Color outline, Color fill) noexcept
 Draw a filled rectangle (26h, 22h) with an outline colour and a fill colour.
 
Result< void > CopyWindow (uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, Point dest, bool reverse=false) noexcept
 Copy a window to another place (26h, 23h); the destination must fit in the visible area.
 
Result< void > DimWindow (uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1) noexcept
 Dim a window (24h): gray levels from GS16 are reduced.
 
Result< void > ClearWindow (uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1) noexcept
 Set a window of GDDRAM to zero (25h).
 
Scrolling
Result< void > SetupScroll (const ScrollSetup &setup) noexcept
 Set the scroll parameters (27h). Not while scrolling is on.
 
Result< void > ActivateScroll () noexcept
 Start scrolling (2Fh).
 
Result< void > DeactivateScroll () noexcept
 Stop scrolling (2Eh); the RAM content must be rewritten afterwards (RamNeedsRewrite()).
 
bool IsScrolling () const noexcept
 
Switch
Result< ButtonUpdate > Poll () noexcept
 Sample the switch, debounce it and apply the idle timers.
 
Result< bool > ReadSwitchRaw () noexcept
 Read the switch pin once, as a logical level (true = closed, polarity applied).
 
Result< void > SetButtonConfig (const ButtonConfig &config) noexcept
 Change the switch configuration; the debouncer restarts.
 
bool IsButtonDown () const noexcept
 
uint32_t GetButtonPressCount () const noexcept
 
Result< void > NotifyActivity () noexcept
 Restart the idle timers from now.
 
Diagnostics
Result< void > TraceCommand (uint8_t opcode, std::span< const uint8_t > parameters) noexcept
 Send one command once: one transfer, no retry, no decoding of its effect (handbook KB-CPP-129).
 
uint8_t GetLastCommandOpcode () const noexcept
 
std::size_t GetLastTransferBytes () const noexcept
 
bool IsShadowInDoubt () const noexcept
 
bool IsLocked () const noexcept
 

Detailed Description

template<SpiPort Port>
class isf15acp4::ISF15ACP4< Port >

Driver for one ISF15ACP4 on a platform port.

Lifecycle (NKK sheet E7, states 0 to 2): construct with the configuration (no I/O); EnsureInitialized() resets the controller, sends the configuration and clears GDDRAM with the OLED supply still off (state 1); DisplayOn() enables the supply and turns the panel on (state 2); DisplayOff() turns it off and the supply off (state 1); Deinitialize() is the power-down and always runs. The supply is never enabled before the controller has been configured. Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded.

Optional port hooks, found at compile time:

Hook Used for Without it
bool ReadSwitch(bool& high) noexcept Poll(), ReadSwitchRaw(): the switch pin Those calls return Unsupported
uint32_t NowMs() noexcept Timestamps of the debouncer, the idle timers Poll() and NotifyActivity() return Unsupported
void Log(LogLevel, const char* message) noexcept One line per lifecycle event or failure Nothing is logged

A hook declared with the wrong signature is a compile error. Required: EnsureInitialized, Write, GpioSet, DelayUs.

Template Parameters
PortYour class derived from SpiInterface<Port>.

Constructor & Destructor Documentation

◆ ISF15ACP4()

template<SpiPort Port>
isf15acp4::ISF15ACP4< Port >::ISF15ACP4 ( Port &  port,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port and store the configuration. No I/O, cannot fail.

Parameters
portThe port; it must outlive the driver.
configWhat EnsureInitialized() will apply; checked there, before any I/O.

Member Function Documentation

◆ ActivateScroll()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::ActivateScroll ( )
noexcept

Start scrolling (2Fh).

Returns
Ok, NotInitialized, Locked, ScrollNotSet or Bus.

◆ ApplyConfig()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::ApplyConfig ( const Config &  config)
noexcept

Change the whole configuration.

Running: every configuration command is sent again (the panel stays as it is: no display off). Not started yet: config is only stored, with no I/O.

Parameters
configChecked with Validate() before any I/O.
Returns
Ok, InvalidArgument, Locked, ScrollActive (a running scroll: deactivate it first; the driver's own rule, not NKK's, which covers only the 27h parameters) or Bus. A configuration whose switch settings are unchanged keeps the debouncer's state. A failed transfer leaves the stored configuration as it was.

◆ Clear()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::Clear ( Color  color = kBlack)
noexcept

Fill the whole visible area with one colour.

Parameters
colorThe colour of every pixel; black by default.
Returns
As Present().

◆ ClearWindow()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::ClearWindow ( uint8_t  x0,
uint8_t  y0,
uint8_t  x1,
uint8_t  y1 
)
noexcept

Set a window of GDDRAM to zero (25h).

Parameters
x0Left column.
y0Top row.
x1Right column.
y1Bottom row.
Returns
As DrawLine().

◆ CopyWindow()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::CopyWindow ( uint8_t  x0,
uint8_t  y0,
uint8_t  x1,
uint8_t  y1,
Point  dest,
bool  reverse = false 
)
noexcept

Copy a window to another place (26h, 23h); the destination must fit in the visible area.

Parameters
x0Source left column.
y0Source top row.
x1Source right column.
y1Source bottom row.
destDestination top-left corner.
reversetrue to swap GS0 <-> GS63 in the copy.
Returns
As DrawLine().

◆ DeactivateScroll()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::DeactivateScroll ( )
noexcept

Stop scrolling (2Eh); the RAM content must be rewritten afterwards (RamNeedsRewrite()).

Returns
Ok, NotInitialized, Locked or Bus.

◆ Deinitialize()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::Deinitialize ( )
noexcept

The power-down: command unlock, display off, supply off, wait vcc_off_ms. Never refused.

It runs every step whatever the state (also on a driver that never started, also with the controller locked or scrolling) and whatever fails: the supply enable is driven off even when the display-off transfer failed. The driver is uninitialised afterwards. When it returns, the logic supply may be cut (SSD1331 section 7.9, tOFF).

Returns
Ok, or the first Bus of the steps.

◆ DimWindow()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::DimWindow ( uint8_t  x0,
uint8_t  y0,
uint8_t  x1,
uint8_t  y1 
)
noexcept

Dim a window (24h): gray levels from GS16 are reduced.

Parameters
x0Left column.
y0Top row.
x1Right column.
y1Bottom row.
Returns
As DrawLine().

◆ DisplayDim()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::DisplayDim ( )
noexcept

Turn the panel on in dim mode (ACh; the ABh settings), as DisplayOn().

Returns
As DisplayOn().

◆ DisplayOff()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::DisplayOff ( )
noexcept

Turn the panel off and the supply off (state 2 to 1): unlock if locked, AEh, supply off.

Never refused, also before the start and while locked or scrolling. It does not wait vcc_off_ms (the logic supply stays on); Deinitialize() waits.

Returns
Ok or Bus (the supply is driven off whatever failed).

◆ DisplayOn()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::DisplayOn ( )
noexcept

Turn the panel on at normal brightness (state 1 to 2): supply on, wait vcc_settle_ms, AFh, wait tAF (100 ms). From dim mode only AFh is sent.

Returns
Ok, NotInitialized, Locked, or Bus (the supply is switched off again).

◆ DrawLine()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::DrawLine ( uint8_t  x0,
uint8_t  y0,
uint8_t  x1,
uint8_t  y1,
Color  color 
)
noexcept

Draw a line with the controller's engine (21h), then wait engine_settle_us.

Parameters
x0Start column.
y0Start row.
x1End column.
y1End row.
colorThe line colour.
Returns
Ok, NotInitialized, InvalidArgument, Locked, ScrollActive or Bus.

◆ DrawRectangle()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::DrawRectangle ( uint8_t  x0,
uint8_t  y0,
uint8_t  x1,
uint8_t  y1,
Color  outline 
)
noexcept

Draw a rectangle outline (26h, 22h), then wait engine_settle_us.

Parameters
x0Left column.
y0Top row.
x1Right column, at least x0.
y1Bottom row, at least y0.
outlineThe outline colour.
Returns
As DrawLine().

◆ EnsureInitialized()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::EnsureInitialized ( )
noexcept

Power up to state 1: the controller is reset, configured and cleared, the supply is off.

Drives the VCC enable off, pulses RES# for kResetPulseMinUs, sends display off and every configuration command, clears GDDRAM (Config::clear_ram), and returns. Blocks for the SPI traffic (about 12 kB with the clear) and a few microseconds of waits. After it succeeds, later calls return Ok at once with no I/O. After it fails the driver stays uninitialised, the supply is off, and the next call starts again.

Returns
Ok, InvalidArgument (the stored configuration fails Validate(); no I/O) or Bus.

◆ FillRectangle()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::FillRectangle ( uint8_t  x0,
uint8_t  y0,
uint8_t  x1,
uint8_t  y1,
Color  outline,
Color  fill 
)
noexcept

Draw a filled rectangle (26h, 22h) with an outline colour and a fill colour.

Parameters
x0Left column.
y0Top row.
x1Right column.
y1Bottom row.
outlineThe outline colour.
fillThe fill colour.
Returns
As DrawLine().

◆ FillWindow()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::FillWindow ( uint8_t  x,
uint8_t  y,
uint8_t  width,
uint8_t  height,
Color  color 
)
noexcept

Fill a rectangle of GDDRAM with one colour by streaming data (no drawing engine).

Parameters
xColumn, 0-based in the visible area.
yRow, 0-based in the visible area.
widthColumns, at least 1.
heightRows, at least 1.
colorThe colour.
Returns
As Present().

◆ GetButtonPressCount()

template<SpiPort Port>
uint32_t isf15acp4::ISF15ACP4< Port >::GetButtonPressCount ( ) const
inlinenoexcept
Returns
Presses counted by the debouncer. No I/O.

◆ GetConfig()

template<SpiPort Port>
const Config & isf15acp4::ISF15ACP4< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration last applied or stored. No I/O.

◆ GetGeometry()

template<SpiPort Port>
Geometry isf15acp4::ISF15ACP4< Port >::GetGeometry ( ) const
inlinenoexcept
Returns
The visible area of the module. No I/O.

◆ GetLastCommandOpcode()

template<SpiPort Port>
uint8_t isf15acp4::ISF15ACP4< Port >::GetLastCommandOpcode ( ) const
inlinenoexcept
Returns
The opcode of the last command transfer; 0 before the first. No I/O.

◆ GetLastTransferBytes()

template<SpiPort Port>
std::size_t isf15acp4::ISF15ACP4< Port >::GetLastTransferBytes ( ) const
inlinenoexcept
Returns
The length in bytes of the last transfer, command or data; 0 before the first. No I/O.

◆ GetOutput()

template<SpiPort Port>
Output isf15acp4::ISF15ACP4< Port >::GetOutput ( ) const
inlinenoexcept
Returns
What the driver last sent: off, normal or dim. No I/O.

◆ IsButtonDown()

template<SpiPort Port>
bool isf15acp4::ISF15ACP4< Port >::IsButtonDown ( ) const
inlinenoexcept
Returns
The debounced level: true while the switch is down. No I/O.

◆ IsInitialized()

template<SpiPort Port>
bool isf15acp4::ISF15ACP4< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized() and before Deinitialize(). No I/O.

◆ IsLocked()

template<SpiPort Port>
bool isf15acp4::ISF15ACP4< Port >::IsLocked ( ) const
inlinenoexcept
Returns
true while the driver has the command interface locked. No I/O.

◆ IsScrolling()

template<SpiPort Port>
bool isf15acp4::ISF15ACP4< Port >::IsScrolling ( ) const
inlinenoexcept
Returns
true while the driver has scrolling on. No I/O.

◆ IsShadowInDoubt()

template<SpiPort Port>
bool isf15acp4::ISF15ACP4< Port >::IsShadowInDoubt ( ) const
inlinenoexcept
Returns
true after TraceCommand() or a failed transfer: the chip may differ from the shadow. No I/O.

◆ IsSupplyEnabled()

template<SpiPort Port>
bool isf15acp4::ISF15ACP4< Port >::IsSupplyEnabled ( ) const
inlinenoexcept
Returns
true while the driver has the supply enable on. No I/O.

◆ Nop()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::Nop ( )
noexcept

Send a no-operation command (E3h).

Returns
Ok, NotInitialized, Locked, Bus.

◆ NotifyActivity()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::NotifyActivity ( )
noexcept

Restart the idle timers from now.

Returns
Ok or Unsupported (no NowMs()).

◆ Poll()

template<SpiPort Port>
Result< ButtonUpdate > isf15acp4::ISF15ACP4< Port >::Poll ( )
noexcept

Sample the switch, debounce it and apply the idle timers.

Reads the pin, passes the level and the time to the debouncer and returns its event. When the display was lowered by the idle timers (dimmed or put to sleep by Poll() itself), a Pressed event wakes it (DisplayOn(), woke_display); a display that the application dimmed or switched off is not woken, and neither is a locked controller (the event is delivered and the display stays as the lock left it). If that DisplayOn() fails the call returns its error, the event is not delivered, and GetButtonPressCount() has already counted the press. When idle_dim_ms or idle_sleep_ms has passed since the last event, DisplayDim() or DisplayOff() runs. Call it at least twice per debounce time.

Returns
The update, or Unsupported (no ReadSwitch() or NowMs() hook), Bus (the switch read failed, or a transfer of the wake or the idle policy), or the errors of the display change.

◆ Present()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::Present ( std::span< const Color >  frame)
noexcept

Show a whole frame: GetGeometry().width * height colours, row by row.

Parameters
frameThe pixels; any other size is InvalidArgument (nothing sent).
Returns
Ok, NotInitialized, Locked, ScrollActive, InvalidArgument or Bus.

◆ RamNeedsRewrite()

template<SpiPort Port>
bool isf15acp4::ISF15ACP4< Port >::RamNeedsRewrite ( ) const
inlinenoexcept
Returns
true after a scroll was deactivated and before a full-area write: RAM must be rewritten. No I/O.

◆ ReadSwitchRaw()

template<SpiPort Port>
Result< bool > isf15acp4::ISF15ACP4< Port >::ReadSwitchRaw ( )
noexcept

Read the switch pin once, as a logical level (true = closed, polarity applied).

Returns
The level, Unsupported (no ReadSwitch() hook, or the display-only module) or Bus.

◆ Reinitialize()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::Reinitialize ( )
noexcept

Power-down, then start again, then restore the display state that was on.

Returns
InvalidArgument (the stored configuration fails Validate(): the driver never started, nothing is sent) or the errors of Deinitialize(), EnsureInitialized() and DisplayOn()/DisplayDim().

◆ SetButtonConfig()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetButtonConfig ( const ButtonConfig &  config)
noexcept

Change the switch configuration; the debouncer restarts.

Parameters
configThe configuration; checked with Validate() before any I/O.
Returns
Ok or InvalidArgument.

◆ SetClock()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetClock ( uint8_t  divide,
uint8_t  frequency 
)
noexcept

Set the clock divide ratio (this + 1) and oscillator frequency, 0 to 15 each (B3h).

Parameters
divideDivide ratio minus one, 0 to 15.
frequencyOscillator frequency setting, 0 to 15.
Returns
As above.

◆ SetCommandLock()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetCommandLock ( bool  lock)
noexcept

Lock or unlock the controller's command interface (FDh).

Parameters
locktrue to lock: every other call then returns Locked and sends nothing until unlocked.
Returns
Ok, NotInitialized or Bus.

◆ SetContrast()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetContrast ( uint8_t  a,
uint8_t  b,
uint8_t  c 
)
noexcept

Set the contrast of the three colours (81h, 82h, 83h).

Parameters
aValue for colour A (segment group A).
bValue for colour B.
cValue for colour C.
Returns
Ok, NotInitialized, InvalidArgument (a value below the dim contrast of its colour: ACh may not show more than the contrast; lower SetDimSettings() first), Locked, Bus.

NKK Note 1: values other than the module's table values may damage the OLED.

◆ SetDimSettings()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetDimSettings ( const DimSettings &  dim)
noexcept

Set the dim mode parameters (ABh); they apply at the next DisplayDim().

A dim contrast may not exceed the start-up contrast of its colour (NKK notes, ACh) nor the contrast now set, so the stored configuration stays valid for Reinitialize().

Parameters
dimThe dim-mode settings.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent), Locked, Bus.

◆ SetDisplayMode()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetDisplayMode ( DisplayMode  mode)
noexcept

Set what the pixels show (A4h to A7h).

Parameters
modeThe display mode.
Returns
As above.

◆ SetDisplayOffset()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetDisplayOffset ( uint8_t  offset)
noexcept

Set the display offset, 0 to 63 (A2h).

Parameters
offsetRows, 0 to 63.
Returns
As above.

◆ SetGrayScaleTable()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetGrayScaleTable ( std::span< const uint8_t, reg::kGrayScaleEntries >  widths)
noexcept

Set the 32 gray scale pulse widths GS1, GS3 ... GS63, each 1 to 125 and rising (B8h). The table is not stored: a restart loads the start-up gray scale again (B9h when linear_gray_scale is set, NKK step 4.15).

Parameters
widthsThe 32 gray-scale pulse widths.
Returns
As above.

◆ SetMasterCurrent()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetMasterCurrent ( uint8_t  step)
noexcept

Set the master current attenuation, 0 to 15 (87h).

Parameters
stepMaster current step, 0 to 15.
Returns
Ok, InvalidArgument, ...

◆ SetMultiplexRatio()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetMultiplexRatio ( uint8_t  rows)
noexcept

Set the multiplex ratio, 16 to 64 rows (A8h). Vertical scrolling needs 64. Not stored in Config: a restart (Reinitialize(), ApplyConfig()) goes back to the module's ratio.

Parameters
rowsRows scanned, 16 to 64.
Returns
As above.

◆ SetPhasePeriods()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetPhasePeriods ( uint8_t  phase1,
uint8_t  phase2 
)
noexcept

Set phase 1 and phase 2 periods, 1 to 15 DCLK each (B1h).

Parameters
phase1Phase 1 in DCLK, 1 to 15.
phase2Phase 2 in DCLK, 1 to 15.
Returns
As above.

◆ SetPixel()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetPixel ( uint8_t  x,
uint8_t  y,
Color  color 
)
noexcept

Set one pixel (a 1 x 1 window and its data).

Parameters
xColumn, 0-based in the visible area.
yRow, 0-based in the visible area.
colorThe colour.
Returns
As Present().

◆ SetPowerSave()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetPowerSave ( bool  enable)
noexcept

Enable or disable the power save mode (B0h).

Parameters
enabletrue to enable.
Returns
As above.

◆ SetPrechargeLevel()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetPrechargeLevel ( uint8_t  level)
noexcept

Set the pre-charge voltage level, 0 to 31 (0.10 to 0.50 x VCC) (BBh).

Parameters
levelLevel, 0 to 31.
Returns
As above.

◆ SetPrechargeSpeed()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetPrechargeSpeed ( uint8_t  a,
uint8_t  b,
uint8_t  c 
)
noexcept

Set the second pre-charge speed of the three colours; all six bytes go out together (8Ah to 8Ch). The values are stored and send_precharge_speeds is set, so a restart sends them again, also on the two smaller modules whose NKK tables leave them out.

Parameters
aValue for colour A (segment group A).
bValue for colour B.
cValue for colour C.
Returns
As above.

◆ SetRemap()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetRemap ( const Remap &  remap)
noexcept

Set the remap and colour depth (A0h). Changes how pixels are sent: ColorDepth, vertical_increment.

Parameters
remapThe remap and colour-depth settings.
Returns
As above.

◆ SetStartLine()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetStartLine ( uint8_t  line)
noexcept

Set the display start line, 0 to 63 (A1h).

Parameters
lineFirst displayed RAM row, 0 to 63.
Returns
As above.

◆ SetupScroll()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetupScroll ( const ScrollSetup &  setup)
noexcept

Set the scroll parameters (27h). Not while scrolling is on.

Parameters
setupThe parameters; both directions zero is InvalidArgument.
Returns
Ok, NotInitialized, InvalidArgument, Locked, ScrollActive or Bus.

◆ SetVcomh()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::SetVcomh ( uint8_t  level)
noexcept

Set the VCOMH level, 0 to 31 (0.44 to 0.83 x VCC) (BEh).

Parameters
levelLevel, 0 to 31.
Returns
As above.

◆ TraceCommand()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::TraceCommand ( uint8_t  opcode,
std::span< const uint8_t >  parameters 
)
noexcept

Send one command once: one transfer, no retry, no decoding of its effect (handbook KB-CPP-129).

For bring-up. The opcode and parameter count must match Table 10. The driver cannot track what a raw command changed: IsShadowInDoubt() is true afterwards. AFh and ACh need the supply on. The checks of the typed calls do not apply: A8h and 27h can break the rule that a vertical scroll needs 64 MUX, a raw AEh, AFh or ACh does not change GetOutput(), and a raw B8h is not checked for rising widths. FDh takes only 12h (unlock) or 16h (lock), so that IsLocked() follows it; ADh takes only 8Eh (A[0] must be 0); a raw 2Fh or 2Eh updates IsScrolling().

Parameters
opcodeA command of Table 10.
parametersExactly its parameter bytes.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent), SupplyOff, Locked or Bus.

◆ UseLinearGrayScale()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::UseLinearGrayScale ( )
noexcept

Reload the built-in linear gray scale table (B9h).

Returns
As above.

◆ WriteWindow()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::WriteWindow ( uint8_t  x,
uint8_t  y,
uint8_t  width,
uint8_t  height,
std::span< const Color >  pixels 
)
noexcept

Write a rectangle of colours into GDDRAM, row by row.

Sets the column and row window (15h, 75h), then streams the pixels as data in chunks of at most detail::kDataChunkBytes. With vertical_increment set the driver sends them column by column, so the picture is the same.

Parameters
xFirst column, 0-based in the visible area.
yFirst row.
widthColumns, at least 1; x + width within the visible width.
heightRows, at least 1; y + height within the visible height.
pixelswidth * height colours.
Returns
As Present().

◆ WriteWindowRaw()

template<SpiPort Port>
Result< void > isf15acp4::ISF15ACP4< Port >::WriteWindowRaw ( uint8_t  x,
uint8_t  y,
uint8_t  width,
uint8_t  height,
std::span< const uint8_t >  bytes 
)
noexcept

Write raw RAM bytes into a window: the caller has encoded them for the colour depth (2 bytes per pixel in 65k format 1). Sent in the order given.

Parameters
xFirst column.
yFirst row.
widthColumns.
heightRows.
bytesExactly width * height * bytes-per-pixel bytes.
Returns
As Present().

The documentation for this class was generated from the following file: