ISF15ACP4 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, configuration, geometry and colours. More...

Classes

struct  isf15acp4::Result< T >
 The value of a call, or why there is none. More...
 
struct  isf15acp4::Result< void >
 The result of a call that returns no value. More...
 
struct  isf15acp4::Remap
 The controller settings that depend on the wiring of the panel (Remap, A0h). More...
 
struct  isf15acp4::Point
 A position in the visible area. More...
 
struct  isf15acp4::DimSettings
 Dim mode parameters (ABh): used when the display is on in dim mode (ACh). More...
 
struct  isf15acp4::Geometry
 Geometry of a module: its visible pixels inside the 96 x 64 RAM. More...
 
struct  isf15acp4::ButtonConfig
 Switch handling: polarity, debounce, long press and repeat. More...
 
struct  isf15acp4::Config
 Everything the driver sends at start-up, and its own time knobs. More...
 
class  isf15acp4::CheckedConfig
 A configuration proven valid at build time. More...
 
struct  isf15acp4::Color
 A colour as the RGB565 word every call takes: red in bits 15..11, green 10..5, blue 4..0. A strong type, so a panel word or a byte count cannot be passed by mistake (KB-CPP20-030). More...
 
struct  isf15acp4::Channels
 The red, green and blue fields of a colour (5, 6 and 5 bits). More...
 

Enumerations

enum class  isf15acp4::Error : uint8_t {
  isf15acp4::Error::Ok = 0 , isf15acp4::Error::NotInitialized = 1 , isf15acp4::Error::InvalidArgument = 2 , isf15acp4::Error::Bus = 3 ,
  isf15acp4::Error::Timeout = 4 , isf15acp4::Error::DeviceIdMismatch , isf15acp4::Error::Crc = 6 , isf15acp4::Error::Busy = 7 ,
  isf15acp4::Error::DeviceFault = 8 , isf15acp4::Error::Unsupported = 9 , isf15acp4::Error::ScrollActive = 16 , isf15acp4::Error::ScrollNotSet = 17 ,
  isf15acp4::Error::SupplyOff = 18 , isf15acp4::Error::Locked = 19
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  isf15acp4::LogLevel : uint8_t { isf15acp4::LogLevel::Error = 0 , isf15acp4::LogLevel::Warning , isf15acp4::LogLevel::Info , isf15acp4::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  isf15acp4::Variant : uint8_t { isf15acp4::Variant::Isf15acp4 = 0 , isf15acp4::Variant::Isc15anp4 = 1 , isf15acp4::Variant::Isc01p = 2 }
 The three modules of the family; they share the controller and differ in the panel. More...
 
enum class  isf15acp4::ColorDepth : uint8_t { isf15acp4::ColorDepth::Colors256 = 0 , isf15acp4::ColorDepth::Colors65k = 1 , isf15acp4::ColorDepth::Colors65kFormat2 = 2 }
 The pixel format of GDDRAM (A0h A[7:6]). More...
 
enum class  isf15acp4::DisplayMode : uint8_t { isf15acp4::DisplayMode::Normal = 0 , isf15acp4::DisplayMode::AllOn = 1 , isf15acp4::DisplayMode::AllOff = 2 , isf15acp4::DisplayMode::Inverse = 3 }
 What the pixels show (A4h to A7h). More...
 
enum class  isf15acp4::Output : uint8_t { isf15acp4::Output::Off = 0 , isf15acp4::Output::Normal = 1 , isf15acp4::Output::Dim = 2 }
 What the panel is doing, as far as the driver knows. More...
 
enum class  isf15acp4::ScrollInterval : uint8_t { isf15acp4::ScrollInterval::Frames6 = 0 , isf15acp4::ScrollInterval::Frames10 = 1 , isf15acp4::ScrollInterval::Frames100 = 2 , isf15acp4::ScrollInterval::Frames200 = 3 }
 The time between two scroll steps (27h E). More...
 
enum class  isf15acp4::ButtonEvent : uint8_t {
  isf15acp4::ButtonEvent::None = 0 , isf15acp4::ButtonEvent::Pressed = 1 , isf15acp4::ButtonEvent::Released = 2 , isf15acp4::ButtonEvent::LongPress = 3 ,
  isf15acp4::ButtonEvent::Repeat = 4
}
 What a switch poll can report. More...
 

Functions

constexpr const char * isf15acp4::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Geometry isf15acp4::GeometryOf (Variant variant) noexcept
 The geometry of a module (NKK sheets: pixel format; the column origin of the smaller panels is the centred one and not given by any NKK document: not verified on hardware).
 
constexpr bool isf15acp4::HasSwitch (Variant variant) noexcept
 Whether a module has the pushbutton (the ISC01P is a display only).
 
constexpr bool isf15acp4::SameButtonConfig (const ButtonConfig &a, const ButtonConfig &b) noexcept
 Whether two switch configurations are the same, field by field.
 
constexpr Config isf15acp4::PresetFor (Variant variant) noexcept
 The working set of a module.
 
constexpr Error isf15acp4::Validate (const ButtonConfig &b) noexcept
 Check the switch configuration without touching the chip.
 
constexpr Error isf15acp4::Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
void isf15acp4::ConfigIsInvalid () noexcept
 Reached only when a CheckedConfig is built from an invalid configuration: it is never defined, so the build fails and names it (KB-CPP20-013).
 
constexpr Color isf15acp4::MakeColor (uint8_t r, uint8_t g, uint8_t b) noexcept
 An RGB565 colour from 8-bit channels (the low bits are dropped, not rounded).
 
constexpr Channels isf15acp4::Split (Color c) noexcept
 Split an RGB565 colour.
 
constexpr const char * isf15acp4::GetDriverVersion () noexcept
 
constexpr uint32_t isf15acp4::GetDriverVersionMajor () noexcept
 
constexpr uint32_t isf15acp4::GetDriverVersionMinor () noexcept
 
constexpr uint32_t isf15acp4::GetDriverVersionPatch () noexcept
 

Variables

constexpr uint32_t isf15acp4::kButtonTimeMaxMs = 60000
 Longest button time the driver accepts, in milliseconds (keeps every difference below 2^31).
 
constexpr uint32_t isf15acp4::kWaitMaxMs = 1000
 Longest wait the driver accepts for the supply and engine times, in milliseconds.
 
constexpr uint32_t isf15acp4::kEngineSettleMaxUs = 100000
 Longest engine settle time, in microseconds.
 
constexpr Color isf15acp4::kBlack {0x0000}
 Black.
 
constexpr Color isf15acp4::kWhite {0xFFFF}
 White.
 
constexpr Color isf15acp4::kRed {0xF800}
 Pure red.
 
constexpr Color isf15acp4::kGreen {0x07E0}
 Pure green.
 
constexpr Color isf15acp4::kBlue {0x001F}
 Pure blue.
 

Detailed Description

Errors, results, configuration, geometry and colours.

Enumeration Type Documentation

◆ ButtonEvent

enum class isf15acp4::ButtonEvent : uint8_t
strong

What a switch poll can report.

Enumerator
None 

Nothing happened.

Pressed 

The switch closed and stayed closed for the debounce time.

Released 

The switch opened and stayed open for the debounce time.

LongPress 

Held for long_press_ms; once per press.

Repeat 

Held on: one per repeat_interval_ms after repeat_delay_ms.

◆ ColorDepth

enum class isf15acp4::ColorDepth : uint8_t
strong

The pixel format of GDDRAM (A0h A[7:6]).

Enumerator
Colors256 

1 byte per pixel: C[4:2] B[5:3] A[4:3].

Colors65k 

2 bytes per pixel, format 1: C[4:0] B[5:0] A[4:0]. Reset value.

Colors65kFormat2 

3 bytes per pixel, format 2: six bits per byte (Table 9).

◆ DisplayMode

enum class isf15acp4::DisplayMode : uint8_t
strong

What the pixels show (A4h to A7h).

Enumerator
Normal 

The RAM content (A4h).

AllOn 

Every pixel at GS63 (A5h).

AllOff 

Every pixel at GS0 (A6h).

Inverse 

Gray levels swapped, GS0 <-> GS63 (A7h).

◆ Error

enum class isf15acp4::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; chip-specific values start at 16. [[nodiscard]] on the type: a function that returns a bare Error cannot have it ignored either (KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize() ran since.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

A port hook returned false (a transfer or a pin write).

Timeout 

Not returned by this driver: nothing the driver waits for is observable.

DeviceIdMismatch 

Not returned by this driver: the controller has no ID and cannot answer.

Crc 

Not returned by this driver: the serial interface has no checksum.

Busy 

Not returned by this driver: every wait blocks until it has elapsed.

DeviceFault 

Not returned by this driver: the controller reports no fault.

Unsupported 

The port lacks the optional hook this call needs (switch, clock) or the pixel format does not allow the call.

ScrollActive 

A RAM, drawing or setup call while scrolling is on (Deactivate first).

ScrollNotSet 

ActivateScroll() before SetupScroll() succeeded.

SupplyOff 

The call needs the OLED supply on (raw display-on).

Locked 

The controller is command-locked by SetCommandLock(true).

◆ LogLevel

enum class isf15acp4::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events: initialised, supply on or off.

Debug 

Detail for bring-up.

◆ Output

enum class isf15acp4::Output : uint8_t
strong

What the panel is doing, as far as the driver knows.

Enumerator
Off 

Sleep (AEh): segments and commons are high impedance.

Normal 

Display on at normal brightness (AFh).

Dim 

Display on in dim mode (ACh).

◆ ScrollInterval

enum class isf15acp4::ScrollInterval : uint8_t
strong

The time between two scroll steps (27h E).

Enumerator
Frames6 

6 frames.

Frames10 

10 frames.

Frames100 

100 frames.

Frames200 

200 frames.

◆ Variant

enum class isf15acp4::Variant : uint8_t
strong

The three modules of the family; they share the controller and differ in the panel.

Enumerator
Isf15acp4 

96 x 64 pixels, frameless pushbutton (NKK sheet E4 to E7).

Isc15anp4 

64 x 48 pixels, pushbutton (NKK sheet ISC15ANP4).

Isc01p 

52 x 36 pixels, display only (NKK sheet ISC01P): no switch.

Function Documentation

◆ GeometryOf()

constexpr Geometry isf15acp4::GeometryOf ( Variant  variant)
constexprnoexcept

The geometry of a module (NKK sheets: pixel format; the column origin of the smaller panels is the centred one and not given by any NKK document: not verified on hardware).

Parameters
variantThe module.
Returns
Its geometry.

◆ GetDriverVersion()

constexpr const char * isf15acp4::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0", from the generated isf15acp4_version.h. No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t isf15acp4::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t isf15acp4::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t isf15acp4::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ HasSwitch()

constexpr bool isf15acp4::HasSwitch ( Variant  variant)
constexprnoexcept

Whether a module has the pushbutton (the ISC01P is a display only).

Parameters
variantThe module.
Returns
true when the module has the switch.

◆ MakeColor()

constexpr Color isf15acp4::MakeColor ( uint8_t  r,
uint8_t  g,
uint8_t  b 
)
constexprnoexcept

An RGB565 colour from 8-bit channels (the low bits are dropped, not rounded).

Parameters
rRed, 0 to 255.
gGreen, 0 to 255.
bBlue, 0 to 255.
Returns
The colour.

◆ PresetFor()

constexpr Config isf15acp4::PresetFor ( Variant  variant)
constexprnoexcept

The working set of a module.

Parameters
variantThe module.
Returns
Config{} for the ISF15ACP4; the settings of the smaller panels otherwise.

◆ SameButtonConfig()

constexpr bool isf15acp4::SameButtonConfig ( const ButtonConfig &  a,
const ButtonConfig &  b 
)
constexprnoexcept

Whether two switch configurations are the same, field by field.

Parameters
aOne configuration.
bThe other.
Returns
true when all five fields are equal.

◆ Split()

constexpr Channels isf15acp4::Split ( Color  c)
constexprnoexcept

Split an RGB565 colour.

Parameters
cThe colour.
Returns
Its channels.

◆ ToString()

constexpr const char * isf15acp4::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Bus"; "Unknown" for a value that is not an enumerator.

◆ Validate() [1/2]

constexpr Error isf15acp4::Validate ( const ButtonConfig &  b)
constexprnoexcept

Check the switch configuration without touching the chip.

Parameters
bThe configuration.
Returns
Ok, or InvalidArgument: debounce outside 1 to 1000 ms, long press not above the debounce time or above kButtonTimeMaxMs, a repeat interval that is not 0 or 10 to 10000 ms, a repeat delay above kButtonTimeMaxMs.

◆ Validate() [2/2]

constexpr Error isf15acp4::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the chip.

Fails when an enum holds a value that is not an enumerator, a level is out of its range, the contrast-independent fields leave their field, a time knob is above its limit, the sleep time is not above the dim time, or the switch configuration fails.

Parameters
configThe configuration.
Returns
Error::Ok or Error::InvalidArgument.