|
ISF15ACP4 Driver 0.1.0
API 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 |
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.
| Port | Your class derived from SpiInterface<Port>. |
|
inlineexplicitnoexcept |
Bind the driver to a port and store the configuration. No I/O, cannot fail.
| port | The port; it must outlive the driver. |
| config | What EnsureInitialized() will apply; checked there, before any I/O. |
|
noexcept |
Start scrolling (2Fh).
Ok, NotInitialized, Locked, ScrollNotSet or Bus.
|
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.
| config | Checked with Validate() before any I/O. |
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.
|
noexcept |
Fill the whole visible area with one colour.
| color | The colour of every pixel; black by default. |
Present().
|
noexcept |
Set a window of GDDRAM to zero (25h).
| x0 | Left column. |
| y0 | Top row. |
| x1 | Right column. |
| y1 | Bottom row. |
DrawLine().
|
noexcept |
Copy a window to another place (26h, 23h); the destination must fit in the visible area.
| x0 | Source left column. |
| y0 | Source top row. |
| x1 | Source right column. |
| y1 | Source bottom row. |
| dest | Destination top-left corner. |
| reverse | true to swap GS0 <-> GS63 in the copy. |
DrawLine().
|
noexcept |
Stop scrolling (2Eh); the RAM content must be rewritten afterwards (RamNeedsRewrite()).
Ok, NotInitialized, Locked or Bus.
|
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).
Ok, or the first Bus of the steps.
|
noexcept |
Dim a window (24h): gray levels from GS16 are reduced.
| x0 | Left column. |
| y0 | Top row. |
| x1 | Right column. |
| y1 | Bottom row. |
DrawLine().
|
noexcept |
Turn the panel on in dim mode (ACh; the ABh settings), as DisplayOn().
DisplayOn().
|
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.
Ok or Bus (the supply is driven off whatever failed).
|
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.
Ok, NotInitialized, Locked, or Bus (the supply is switched off again).
|
noexcept |
Draw a line with the controller's engine (21h), then wait engine_settle_us.
| x0 | Start column. |
| y0 | Start row. |
| x1 | End column. |
| y1 | End row. |
| color | The line colour. |
Ok, NotInitialized, InvalidArgument, Locked, ScrollActive or Bus.
|
noexcept |
Draw a rectangle outline (26h, 22h), then wait engine_settle_us.
| x0 | Left column. |
| y0 | Top row. |
| x1 | Right column, at least x0. |
| y1 | Bottom row, at least y0. |
| outline | The outline colour. |
DrawLine().
|
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.
Ok, InvalidArgument (the stored configuration fails Validate(); no I/O) or Bus.
|
noexcept |
Draw a filled rectangle (26h, 22h) with an outline colour and a fill colour.
| x0 | Left column. |
| y0 | Top row. |
| x1 | Right column. |
| y1 | Bottom row. |
| outline | The outline colour. |
| fill | The fill colour. |
DrawLine().
|
noexcept |
Fill a rectangle of GDDRAM with one colour by streaming data (no drawing engine).
| x | Column, 0-based in the visible area. |
| y | Row, 0-based in the visible area. |
| width | Columns, at least 1. |
| height | Rows, at least 1. |
| color | The colour. |
Present().
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
EnsureInitialized() and before Deinitialize(). No I/O.
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
TraceCommand() or a failed transfer: the chip may differ from the shadow. No I/O.
|
inlinenoexcept |
|
noexcept |
Send a no-operation command (E3h).
Ok, NotInitialized, Locked, Bus.
|
noexcept |
Restart the idle timers from now.
Ok or Unsupported (no NowMs()).
|
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.
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.
|
noexcept |
Show a whole frame: GetGeometry().width * height colours, row by row.
| frame | The pixels; any other size is InvalidArgument (nothing sent). |
Ok, NotInitialized, Locked, ScrollActive, InvalidArgument or Bus.
|
inlinenoexcept |
|
noexcept |
Read the switch pin once, as a logical level (true = closed, polarity applied).
Unsupported (no ReadSwitch() hook, or the display-only module) or Bus.
|
noexcept |
Power-down, then start again, then restore the display state that was on.
InvalidArgument (the stored configuration fails Validate(): the driver never started, nothing is sent) or the errors of Deinitialize(), EnsureInitialized() and DisplayOn()/DisplayDim().
|
noexcept |
Change the switch configuration; the debouncer restarts.
| config | The configuration; checked with Validate() before any I/O. |
Ok or InvalidArgument.
|
noexcept |
Set the clock divide ratio (this + 1) and oscillator frequency, 0 to 15 each (B3h).
| divide | Divide ratio minus one, 0 to 15. |
| frequency | Oscillator frequency setting, 0 to 15. |
|
noexcept |
Lock or unlock the controller's command interface (FDh).
| lock | true to lock: every other call then returns Locked and sends nothing until unlocked. |
Ok, NotInitialized or Bus.
|
noexcept |
Set the contrast of the three colours (81h, 82h, 83h).
| a | Value for colour A (segment group A). |
| b | Value for colour B. |
| c | Value for colour C. |
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.
|
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().
| dim | The dim-mode settings. |
Ok, NotInitialized, InvalidArgument (nothing sent), Locked, Bus.
|
noexcept |
Set what the pixels show (A4h to A7h).
| mode | The display mode. |
|
noexcept |
Set the display offset, 0 to 63 (A2h).
| offset | Rows, 0 to 63. |
|
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).
| widths | The 32 gray-scale pulse widths. |
|
noexcept |
Set the master current attenuation, 0 to 15 (87h).
| step | Master current step, 0 to 15. |
Ok, InvalidArgument, ...
|
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.
| rows | Rows scanned, 16 to 64. |
|
noexcept |
Set phase 1 and phase 2 periods, 1 to 15 DCLK each (B1h).
| phase1 | Phase 1 in DCLK, 1 to 15. |
| phase2 | Phase 2 in DCLK, 1 to 15. |
|
noexcept |
Set one pixel (a 1 x 1 window and its data).
| x | Column, 0-based in the visible area. |
| y | Row, 0-based in the visible area. |
| color | The colour. |
Present().
|
noexcept |
Enable or disable the power save mode (B0h).
| enable | true to enable. |
|
noexcept |
Set the pre-charge voltage level, 0 to 31 (0.10 to 0.50 x VCC) (BBh).
| level | Level, 0 to 31. |
|
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.
| a | Value for colour A (segment group A). |
| b | Value for colour B. |
| c | Value for colour C. |
|
noexcept |
Set the remap and colour depth (A0h). Changes how pixels are sent: ColorDepth, vertical_increment.
| remap | The remap and colour-depth settings. |
|
noexcept |
Set the display start line, 0 to 63 (A1h).
| line | First displayed RAM row, 0 to 63. |
|
noexcept |
Set the scroll parameters (27h). Not while scrolling is on.
| setup | The parameters; both directions zero is InvalidArgument. |
Ok, NotInitialized, InvalidArgument, Locked, ScrollActive or Bus.
|
noexcept |
Set the VCOMH level, 0 to 31 (0.44 to 0.83 x VCC) (BEh).
| level | Level, 0 to 31. |
|
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().
| opcode | A command of Table 10. |
| parameters | Exactly its parameter bytes. |
Ok, NotInitialized, InvalidArgument (nothing sent), SupplyOff, Locked or Bus.
|
noexcept |
Reload the built-in linear gray scale table (B9h).
|
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.
| x | First column, 0-based in the visible area. |
| y | First row. |
| width | Columns, at least 1; x + width within the visible width. |
| height | Rows, at least 1; y + height within the visible height. |
| pixels | width * height colours. |
Present().
|
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.
| x | First column. |
| y | First row. |
| width | Columns. |
| height | Rows. |
| bytes | Exactly width * height * bytes-per-pixel bytes. |
Present().