display.oled.ssd1322.spin

{
----------------------------------------------------------------------------------------------------
    Filename:       display.oled.ssd1322.spin
    Description:    Driver for SSD1322 OLED displays
    Author:         Jesse Burt
    Started:        Jul 17, 2023
    Updated:        Mar 7, 2025
    Copyright (c) 2025 - See end of file for terms of use.
----------------------------------------------------------------------------------------------------
}

#define MEMMV_NATIVE bytemove

CON

' -- Default I/O configuration (can be overridden by parent object)
    WIDTH       = 256
    HEIGHT      = 64

    CS          = 0
    SCK         = 1
    MOSI        = 2
    DC          = 3
    RST         = -1
    SPI_FREQ    = 1_000_000                     ' not currently used
'--

    BPP         = 4                             ' bits per pixel/color depth of the display
    BYTESPERPX  = 1 #> (BPP/8)                  ' limit to minimum of 1
    BPPDIV      = BYTESPERPX #> (8 / BPP)       ' limit to range BYTESPERPX .. (8/BPP)
    BUFF_SZ     = (WIDTH * HEIGHT) / BPPDIV
    MAX_COLOR   = (1 << BPP)-1
    XMAX        = WIDTH-1
    YMAX        = HEIGHT-1
    CENTERX     = WIDTH/2
    CENTERY     = HEIGHT/2

    CMD         = 0
    DATA        = 1


OBJ

    core:   "core.con.ssd1322"                  ' hardware-specific constants
    spi:    "com.spi.20mhz"                     ' SPI engine
    time:   "time"                              ' timekeeping methods


VAR

    word _offs_x, _offs_y                       ' display panel-specific offsets
    word _xaddr_max                             ' display internal X-max address
    byte _framebuffer[BUFF_SZ]                  ' display/framebuffer
    byte _CS, _DC, _RST

    ' shadow registers
    byte _remap[2]                              ' set re-map and dual COM line mode
    byte _clkdiv                                ' clock divider and oscillator freq
    byte _gpio_state                            ' gpio 0, 1 state
    byte _disp_enh_a[2]                         ' ext/int VSL, enhanced low GS disp quality
    byte _phase_len                             ' phase 1, 2 period
    byte _seg_per_pix                           ' SEGments per pixel


PUB start(): s
' Start the driver using default I/O settings and internal framebuffer
    return startx(CS, SCK, MOSI, DC, RST, SPI_FREQ, WIDTH, HEIGHT, @_framebuffer)


PUB startx(CS_PIN, SCK_PIN, MOSI_PIN, DC_PIN, RES_PIN, SCK_FREQ, DISP_WID, DISP_HT, p_fb=0): s
' Start the driver using custom I/O settings and (optionally) external framebuffer
'   CS_PIN:             Chip Select, 0..31
'   SCK_PIN:            Serial Clock, 0..31
'   MOSI_PIN:           Master-Out/Slave-In, 0..31
'   DC_PIN:             Data/Command (sometimes known as RS or Register Select), 0..31
'   RES_PIN:            Reset (set to -1 if not used), 0..31
'   SCK_FREQ:           SPI bus speed (not currently used)
'   DISP_WID, DISP_HT:  display dimensions, in pixels
'   p_fb:               (optional) pointer to display buffer (leave blank or set to 0 to use
'                           the driver's internal framebuffer)
   if ( s := spi.init(SCK_PIN, MOSI_PIN, -1, core.SPI_MODE) )
        time.usleep(core.T_POR)
        outa[CS_PIN] := 1
        outa[DC_PIN] := 1
        dira[CS_PIN] := 1
        dira[DC_PIN] := 1
        _CS := CS_PIN
        _DC := DC_PIN
        _RST := RES_PIN
        set_dims(DISP_WID, DISP_HT)
        set_address(p_fb)
        return s
    return FALSE


PUB stop()
' Stop the driver and reclaim/clear memory used
    bytefill(@_framebuffer, 0, BUFF_SZ)
    bytefill(@_CS, 0, 3)
    spi.deinit()


PUB defaults()
' Factory default settings
    _remap := $00
    _seg_per_pix := 1
    _xaddr_max := _disp_xmax/4
    command(core.SET_CMD_LOCK, 1, $12)
    powered(false)
    clk_freq(1876)
    clk_div(1)
    disp_lines(64)
    command(core.SET_DISP_OFFS, 1, $00)
    disp_start_line(0)
    mirror_h(false)
    mirror_v(false)
    nibble_remap(false)
    command(core.SET_GPIO, 1, $00)
    gpio_state(0, GPIO_HIZ_INP_DIS)
    gpio_state(1, GPIO_HIZ_INP_DIS)
    vdd_regulator(1)
    vsl_reference(0)
    lowgs_quality(0)
    contrast(127)
    segment_current_scale(16)
    greyscale_table_default_linear()
    phase1_period(9)
    phase2_period(7)
    precharge_lvl(497)
    precharge_period(-1, 8)
    vcomh_voltage(0_800)
    visibility(NORMAL)
    disp_part_area(-1, -1)
    clear()
    powered(true)


PUB preset_newhaven_2p7_128x64()
' Preset settings: Newhaven NHD-2.7-12864WDx3M (with or without -CTP)
'   128x64
'   Panel offsets: 28, 0
    _remap[0] := 1 << 3
    _remap[1] := $01
    _seg_per_pix := 2
    disp_offset(28, 0)
    _xaddr_max := _offs_x + (_disp_xmax / _seg_per_pix)

    reset()
    powered(false)
    nibble_remap(true)
    mirror_h(true)
    mirror_v(true)
    disp_lines(64)
    precharge_lvl(600)
    vcomh_voltage(0_860)
    clk_freq(1750)
    clk_div(1)
    phase1_period(5)
    phase2_period(14)
    gpio_state(0, 0)
    gpio_state(1, 0)
    powered(true)


PUB preset_newhaven_3p12_256x64()
' Preset settings: Newhaven NHD-3.12-25664UCW2
'   256x64
'   Panel offsets: 28, 0
    _remap[0] := (1 << core.COM_REMAP) | (1 << core.NIBB_REMAP)
    _remap[1] := $01
    _seg_per_pix := 1
    disp_offset(28, 0)
    _xaddr_max := _offs_x + (_disp_xmax / 4 / _seg_per_pix)

    powered(false)
    nibble_remap(true)
    mirror_h(false)
    mirror_v(true)
    disp_lines(64)
    precharge_lvl(600)
    vcomh_voltage(0_860)
    clk_freq(1750)
    clk_div(1)
    phase1_period(5)
    phase2_period(14)
    gpio_state(0, 0)
    gpio_state(1, 0)
    powered(true)


PUB clear() | y, x'xxx need GFX_DIRECT case
' Clear the display
    bytefill(@_framebuffer, 0, _buff_sz)


PUB clk_div(d)
' Set clock frequency divider used by the display controller
'   Valid values: 1..16 (clamped to range)
    _clkdiv := ( (_clkdiv & core.CLK_DIV_CLR) | ( (1 #> d <# 16)-1) )
    command(core.SET_CLKDIV_OSCFREQ, 1, _clkdiv)


PUB clk_freq(f)
' Set display internal oscillator frequency, in kHz
'   Valid values: 1750..2130 (clamped to range; POR: 1876)
'   NOTE: Range is interpolated, based on the datasheet min/max values and
'   number of steps, so actual clock frequency may not be accurate.
'   Value set will be rounded to the nearest 25.33kHz
    f := ( ( ( ( (1750 #> f <# 2130) - 1750) * 100) / 25_33) << core.FOSCFREQ)
    _clkdiv := ( (_clkdiv & core.FOSCFREQ_CLR) | f)
    command(core.SET_CLKDIV_OSCFREQ, 1, _clkdiv)


PUB contrast(c)
' Set display contrast
'   c:  0..255
    command(core.SET_CONTR_CURR, 1, c)


PUB disp_lines(l)
' Set total number of display lines
'   l:  16..128 (clamped to range)
    command(core.SET_MUX_RATIO, 1, 15 #> (l-1) <# 127)


PUB disp_offset(x, y)
' Set display panel-specific offset
'   x, y:   offset in pixels
    _offs_x := x
    _offs_y := y


PUB disp_part_area(sy, ey)
' Enable partial-display mode and define visible area (rows) of display
'   sy:     starting row of displayed area, 0..127
'   ey:     ending row of displayed area, sy..127
'   NOTE: If either (or both) sy or ey are negative numbers, partial area mode will be disabled.
    if ( (sy < 0) or (ey < 0) )
        command(core.DIS_PARTIAL_DISP)
        return

    sy := 0 #> sy <# 127
    ey := sy #> ey <# 127                       ' ending row must be >= sy

    command(core.ENA_PARTIAL_DISP, 2, sy, ey)


PUB disp_start_line(l)
' Set display start line
'   Valid values: 0..127 (clamped to range; POR: 0)
    command(core.SET_DISP_ST_LINE, 1, 0 #> l <# 127)


PUB draw_area(sx, sy, ex, ey)
' Set display position for next drawing operation
    if ( _seg_per_pix == 1 )
        command(core.SET_COL_ADDR, 2, (_offs_x+sx), (_offs_x+(ex/4) ) )
    elseif ( _seg_per_pix == 2 )
        command(core.SET_COL_ADDR, 2, (_offs_x+sx), (_offs_x+(ex/2) ) )
    command(core.SET_ROW_ADDR, 2, (_offs_y+sy), ey)

CON

    GPIO_HIZ_INP_DIS    = 0
    GPIO_HIZ_INP_ENA    = 1
    GPIO_OUT_LOW        = 2
    GPIO_OUT_HIGH       = 3


PUB gpio_state(p, s)
' Set GPIO pin state
'   p:  GPIO pin # (0..1)
'   s:  state
'       0: HiZ, input disabled
'       1: HiZ, input enabled
'       2: output, low (default)
'       3: output, high
    if ( p == 0 )
        _gpio_state := (_gpio_state & core.GPIO0_CLR) | (s & core.GPIO0_BITS)
    elseif ( p == 1 )
        _gpio_state := (_gpio_state & core.GPIO1_CLR) | (s & core.GPIO1_BITS)
    else
        return

    command(core.SET_GPIO, 2, _gpio_state)


PUB greyscale_table_default_linear()
' Select default linear grey scale table
    command(core.DEF_LINEAR_GRAY)


PUB lowgs_quality(q)
' Set low greyscale quality
'   q:
'       non-zero values:    enhanced quality
'       zero:               normal (default)
    _disp_enh_a[1] :=   (_disp_enh_a[1] & core.LOWGS_MASK) | ...
                        ( (q <> 0) ? core.ENH_LOWGS : core.NORM_LOWGS)

    command(core.DISP_ENH_A, 2, _disp_enh_a)


PUB mirror_h(m)
' Mirror the display horizontally
'   m:
'       non-zero values:    enable
'       zero:               disable
    _remap[0] := (_remap[0] & core.SEGREMAP_CLR) | ( (m <> 0) & 1) << core.SEG_REMAP
    command(core.SET_REMAP, 2, _remap[0], _remap[1])


PUB mirror_v(m)
' Mirror the display vertically
'   m:
'       non-zero values:    enable
'       zero:               disable
    _remap[0] := (_remap[0] & core.COMREMAP_CLR) | ( (m <> 0) & 1) << core.COM_REMAP
    command(core.SET_REMAP, 2, _remap[0], _remap[1])


PUB nibble_remap(r)
' Remap pixel data nibbles (swap upper/lower 4 bits)
'   r:
'       non-zero values:    enable
'       zero:               disable (default)
    _remap[0] := (_remap[0] & core.NIBB_REMAP_CLR) | ( (r <> 0) & 1) << core.NIBB_REMAP
    command(core.SET_REMAP, 2, _remap[0], _remap[1])


PUB phase1_period(c)
' Set phase 1 period (reset phase length)
'   c:  5..31 (clamped to range; default: 9)
    _phase_len := (_phase_len & core.PHASE1_CLR) | ( ( (5 #> c <# 31)-1) / 2)
    command(core.SET_PHASE_LEN, 1, _phase_len)


PUB phase2_period(c)
' Set phase 2 period (first precharge phase length)
'   c:  3..15 (clamped to range; default: 7)
    _phase_len := (_phase_len & core.PHASE2_CLR) | ( (3 #> c <# 15) << core.PHASE2)
    command(core.SET_PHASE_LEN, 1, _phase_len)


PUB plot(x, y, c) | mask, p, b1
' Draw a single pixel
'   (x, y): screen coordinates
'   c:      color
    if ( (x < 0) or (x > _disp_xmax) or (y < 0) or (y > _disp_ymax) )
        return

    if ( x.[0] )                                ' for odd-numbered columns,
        mask := c                               '   put the color data into the lower nibble
    else                                        ' for even-numbered columns,
        mask := (c << 4)                        '   put the color data into the upper nibble

    ' find offset in framebuffer
    p := @_framebuffer + ( (x >> 1) + (y * _bytesperln) )
    b1 := byte[p] & ( (x.[0]) ? $f0 : $0f )     ' grab pixel data from the upper or lower nibble,
                                                '   depending on whether x is even or odd

    byte[p] := b1 | mask


#ifndef GFX_DIRECT
PUB point(x, y): c
' Get the currently set color of a pixel
'   (x, y): screen coordinates
'   Returns: 4-bit color
    if ( (x < 0) or (x > _disp_xmax) or (y < 0) or (y > _disp_ymax) )
        return
    { find pixel address within framebuffer }
    c := byte[ @_framebuffer+( (x >> 1) + (y * _bytesperln ) ) ]
    if ( x.[0] )                                ' for odd-numbered columns,
        c &= $0f                                '   get the lower nibble
    else                                        ' for even-numbered columns,
        c >>= 4                                 '   get the upper nibble
#endif


PUB powered(p)
' Enable display power
'   p:
'       non-zero values:    on
'       false (0):          off
    if ( p )
        command(core.SLEEP_OFF)
    else
        command(core.SLEEP_ON)


PUB precharge_lvl(l)
' Set first pre-charge voltage level (phase 2) of segment pins, in millivolts
'   l:  200..600 (clamped to range; default: 497)
    l := ( ( (200 #> l <# 600) * 10 ) / 12_9) - 16
    command(core.SET_PRECHG_VOLT, 1, l)


PUB precharge_period(p1, p2) | tmp
' Set display refresh pre-charge period
'   p1: ignored (for API compatibility with other drivers)
'   p2: 0..15 display clocks (clamped to range; default: 8)
    command(core.SET_SEC_PRECHG_PER, 1, 0 #> p2 <# 15)


PUB reset()
' Reset the device
    if ( lookdown(_RST: 0..31) )
        outa[_RST] := 1
        dira[_RST] := 1
        outa[_RST] := 0
#ifdef __OUTPUT_ASM__
        time.usleep(core.T_RES)
#endif
        outa[_RST] := 1


PUB segment_current_scale(v)
' Scale segment output current
'   v:  scaling factor (1..16)
'       1..15:  reduce output current to v/16
'       16:     no change (default)
    command(core.MAST_CURR_CTRL, 1, (1 #> v <# 16)-1)


PUB set_gamma_table(p_tbl) | i
' Set gamma table
'   p_tbl:  pointer to 15-byte gamma/greyscale table
    command(core.SET_GRAYSCALE_TBL)
    outa[_DC] := 1
    outa[_CS] := 0
    repeat i from 0 to 14
        spi.wr_byte( byte[p_tbl][i] )           ' 0..180 each
    outa[_CS] := 1
    command(core.ENA_GRAYSCALE_TBL)


CON LINEBUFF_SZ = 128
PUB show() | tmp, y, x, p, b, row_buff[LINEBUFF_SZ/4], w, o
' Show the display buffer on the display
    tmp.byte[0] := _offs_x
    tmp.byte[1] := _xaddr_max
    command(core.SET_COL_ADDR, 2, tmp.byte[0], tmp.byte[1])

    tmp.byte[0] := _offs_y
    tmp.byte[1] := _disp_ymax
    command(core.SET_ROW_ADDR, 2, tmp.byte[0], tmp.byte[1])

    command(core.WR_RAM)

    if ( _seg_per_pix == 1 )
        outa[_DC] := DATA
        outa[_CS] := 0
            spi.wrblock_lsbf(@_framebuffer, _buff_sz)
        outa[_CS] := 1
    elseif ( _seg_per_pix == 2 )
        ' pixel-doubled (x-axis) displays: these use two display SEGments to drive each pixel
        '   so the pixel data has to be sent twice for each to get the pixel to display
        outa[_DC] := DATA
        outa[_CS] := 0
        ' buffer a line of display data and send it out at once to avoid the (severe) penalty
        '   of writing individual bytes at a time
        repeat y from 0 to _disp_ymax
            o := 0
            repeat x from 0 to (_disp_xmax >> 1)
                p := byte[@_framebuffer + ( x + (y * _bytesperln))]
                ' write the upper nibble, then the lower nibble (SEG pairs mapped to single pixel)
                w := 	( (p.[3..0] << 4) | p.[3..0] ) << 8 | ...'SEG0, SEG1...
                        ( (p.[7..4] << 4) | p.[7..4] )			 'SEG2, SEG3...
                row_buff.word[o++] := w
            spi.wrblock_lsbf(@row_buff, LINEBUFF_SZ)
        outa[_CS] := 1


PUB vcomh_voltage(l)
' Set Vcom output voltage
'   l:  0_720..0_860 millivolts (clamped to range; default: 0_800)
    command(core.SET_VCOMH, 1, ( (0_720 #> l <# 0_860) - 0_720) )


PUB vdd_regulator(r)
' Set Vdd regulator
'   0:                  external regulator
'   non-zero values:    internal regulator (default)
    command(core.FUNC_SEL, 1, (r <> 0) & 1)


CON

    #0, ALL_OFF, ALL_ON, NORMAL, INVERTED

PUB visibility(mode)
' Set display visibility
'   m:
'       ALL_OFF (0):    Turns off all pixels
'       ALL_ON (1):     Turns on all pixels (white)
'       NORMAL (2):     Normal display (display graphics RAM contents)
'       INVERTED (3):   Like NORMAL, but with inverted colors
'   NOTE: This setting doesn't affect the contents of graphics RAM,
'       only how they are displayed
    mode := ( (ALL_OFF #> mode <# INVERTED) + core.SET_DISP_MODE_OFF)
    command(mode)


PUB vsl_reference(r)
' Set Vsl reference
'   0:                  external
'   non-zero values:    internal (default)
    _disp_enh_a[0] := (_disp_enh_a & core.VSL_MASK) | ( (r <> 0) ? core.VSL_INTERNAL : $00 )
    command(core.DISP_ENH_A, 2, _disp_enh_a[0], _disp_enh_a[1])


PRI command(c, l=0, v1=0, v2=0)
' Issue simple command, no parameters
    outa[_DC] := CMD
    outa[_CS] := 0
        spi.wr_byte(c)
        if ( l )
            outa[_DC] := DATA
            spi.wrblock_lsbf(@v1, 1)
            if ( l == 2 )
                spi.wrblock_lsbf(@v2, 1)
    outa[_CS] := 1


#ifndef GFX_DIRECT
PRI memfill(xs, ys, val, count)
' Fill region of display buffer memory
'   xs, ys: Start of region
'   val: Color
'   count: Number of consecutive memory locations to write
    bytefill(   _ptr_drawbuffer + (xs >> 1) + (ys * _bytesperln), ...
                val | (val << 4), ...
                count / BPPDIV )
#endif

#include "graphics.common.spinh"

DAT
{
Copyright 2025 Jesse Burt

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}