241 lines
8.7 KiB
Python
241 lines
8.7 KiB
Python
"""Pure-Python tests for the SSD168x SPI decoder.
|
||
|
||
These tests are the **specification** for the future Velxio frontend
|
||
emulator. They walk the decoder through the exact byte sequences GxEPD2
|
||
and Adafruit_EPD emit and assert the resulting framebuffer is what a
|
||
real panel would have shown.
|
||
|
||
No QEMU, no DOM, no backend — just bytes in and pixels out.
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
from pathlib import Path
|
||
import sys
|
||
|
||
import pytest
|
||
|
||
_HERE = Path(__file__).parent
|
||
sys.path.insert(0, str(_HERE))
|
||
|
||
from ssd168x_decoder import ( # noqa: E402 (sys.path tweak above)
|
||
SSD168xDecoder,
|
||
Frame,
|
||
CMD_SW_RESET,
|
||
CMD_DRIVER_OUTPUT_CTRL,
|
||
CMD_DATA_ENTRY_MODE,
|
||
CMD_SET_RAMX_RANGE,
|
||
CMD_SET_RAMY_RANGE,
|
||
CMD_BORDER_WAVEFORM,
|
||
CMD_DISP_UPDATE_CTRL_1,
|
||
CMD_TEMP_SENSOR,
|
||
CMD_SET_RAMX_COUNTER,
|
||
CMD_SET_RAMY_COUNTER,
|
||
CMD_WRITE_BLACK_VRAM,
|
||
CMD_WRITE_RED_VRAM,
|
||
CMD_DISP_UPDATE_CTRL_2,
|
||
CMD_MASTER_ACTIVATION,
|
||
CMD_DEEP_SLEEP,
|
||
)
|
||
|
||
|
||
# ── Helpers ───────────────────────────────────────────────────────────────────
|
||
|
||
|
||
def cmd(c):
|
||
"""Return one (byte, dc=False) tuple — DC LOW means command."""
|
||
return [(c, False)]
|
||
|
||
|
||
def data(*bs):
|
||
"""Return n (byte, dc=True) tuples — DC HIGH means data."""
|
||
return [(b, True) for b in bs]
|
||
|
||
|
||
def feed_all(d, *streams):
|
||
"""Feed a flat sequence of (byte, dc) tuples into the decoder."""
|
||
for stream in streams:
|
||
for byte, dc_high in stream:
|
||
d.feed(byte, dc_high)
|
||
|
||
|
||
def gxepd2_init_154(d):
|
||
"""The init sequence GxEPD2 emits for the GxEPD2_154_D67 (200×200, SSD1681).
|
||
|
||
Lifted from GxEPD2's src/epd/GxEPD2_154_D67.cpp _InitDisplay() and
|
||
cross-checked against esp-bsp's esp_lcd_ssd1681_commands.h init.
|
||
"""
|
||
feed_all(
|
||
d,
|
||
cmd(CMD_SW_RESET),
|
||
cmd(CMD_DRIVER_OUTPUT_CTRL), data(0xC7, 0x00, 0x00),
|
||
cmd(CMD_DATA_ENTRY_MODE), data(0x03),
|
||
cmd(CMD_SET_RAMX_RANGE), data(0x00, 0x18),
|
||
cmd(CMD_SET_RAMY_RANGE), data(0x00, 0x00, 0xC7, 0x00),
|
||
cmd(CMD_BORDER_WAVEFORM), data(0x05),
|
||
cmd(CMD_DISP_UPDATE_CTRL_1), data(0x00, 0x80),
|
||
cmd(CMD_TEMP_SENSOR), data(0x80),
|
||
cmd(CMD_SET_RAMX_COUNTER), data(0x00),
|
||
cmd(CMD_SET_RAMY_COUNTER), data(0x00, 0x00),
|
||
)
|
||
|
||
|
||
# ── Tests ─────────────────────────────────────────────────────────────────────
|
||
|
||
|
||
class TestInitSequence:
|
||
"""The decoder must accept GxEPD2's init without complaint."""
|
||
|
||
def test_clean_init_for_154_panel(self):
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
gxepd2_init_154(d)
|
||
assert d.unknown_cmds == [], (
|
||
f"GxEPD2 init emitted unknown cmds: {d.unknown_cmds!r}"
|
||
)
|
||
assert d.refreshed_count == 0, "Init alone must NOT trigger a refresh"
|
||
assert not d.in_deep_sleep
|
||
|
||
def test_sw_reset_clears_state(self):
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
# Pollute the BW plane.
|
||
feed_all(d, cmd(CMD_WRITE_BLACK_VRAM), data(0x00, 0x00, 0x00))
|
||
assert any(b != 0xFF for b in d.bw_ram[:25])
|
||
# Reset.
|
||
feed_all(d, cmd(CMD_SW_RESET))
|
||
assert all(b == 0xFF for b in d.bw_ram[:25]), "SW reset must clear BW RAM"
|
||
|
||
|
||
class TestRamWindowing:
|
||
"""The X/Y range + entry-mode commands must steer pixel writes correctly."""
|
||
|
||
def test_ramx_ramy_range_sets_window(self):
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
feed_all(
|
||
d,
|
||
cmd(CMD_SET_RAMX_RANGE), data(0x00, 0x18), # full width (0..24)
|
||
cmd(CMD_SET_RAMY_RANGE), data(0x00, 0x00, 0xC7, 0x00), # full height (0..199)
|
||
)
|
||
assert d._xrange == (0x00, 0x18)
|
||
assert d._yrange == (0x0000, 0x00C7)
|
||
|
||
def test_set_counters_seek_position(self):
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
feed_all(
|
||
d,
|
||
cmd(CMD_SET_RAMX_COUNTER), data(0x05),
|
||
cmd(CMD_SET_RAMY_COUNTER), data(0x10, 0x00),
|
||
)
|
||
assert d._x_byte == 0x05
|
||
assert d._y == 0x0010
|
||
|
||
|
||
class TestPixelWriting:
|
||
"""Writing to the BW VRAM must land bytes in the right framebuffer position."""
|
||
|
||
def test_write_black_vram_increments_x(self):
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
gxepd2_init_154(d)
|
||
feed_all(d, cmd(CMD_WRITE_BLACK_VRAM), data(0x00, 0xFF, 0xAA))
|
||
assert d.bw_ram[0] == 0x00
|
||
assert d.bw_ram[1] == 0xFF
|
||
assert d.bw_ram[2] == 0xAA
|
||
assert d._x_byte == 3
|
||
assert d._y == 0
|
||
|
||
def test_write_wraps_to_next_row(self):
|
||
# Tiny window so we can hit the wrap fast (x range 0..1 = 2 bytes wide)
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
feed_all(
|
||
d,
|
||
cmd(CMD_DATA_ENTRY_MODE), data(0x03),
|
||
cmd(CMD_SET_RAMX_RANGE), data(0x00, 0x01),
|
||
cmd(CMD_SET_RAMX_COUNTER), data(0x00),
|
||
cmd(CMD_SET_RAMY_COUNTER), data(0x00, 0x00),
|
||
)
|
||
feed_all(d, cmd(CMD_WRITE_BLACK_VRAM), data(0xAA, 0xBB, 0xCC, 0xDD))
|
||
# First two bytes go to row 0; next two to row 1.
|
||
assert d.bw_ram[0] == 0xAA
|
||
assert d.bw_ram[1] == 0xBB
|
||
bpr = 25
|
||
assert d.bw_ram[bpr + 0] == 0xCC
|
||
assert d.bw_ram[bpr + 1] == 0xDD
|
||
|
||
|
||
class TestFrameLatchAndCompose:
|
||
"""0x20 ACTIVATE must trigger flush; red plane must win over black."""
|
||
|
||
def test_activate_calls_on_flush(self):
|
||
seen = []
|
||
d = SSD168xDecoder(width=200, height=200, on_flush=lambda f: seen.append(f))
|
||
gxepd2_init_154(d)
|
||
# White everywhere → all bits are already 0xFF (white).
|
||
feed_all(
|
||
d,
|
||
cmd(CMD_DISP_UPDATE_CTRL_2), data(0xF7),
|
||
cmd(CMD_MASTER_ACTIVATION),
|
||
)
|
||
assert len(seen) == 1
|
||
assert d.refreshed_count == 1
|
||
frame: Frame = seen[0]
|
||
assert frame.width == 200 and frame.height == 200
|
||
assert all(p == 1 for p in frame.pixels), (
|
||
"Default RAM is 0xFF (all bits=1) → all pixels must be white"
|
||
)
|
||
|
||
def test_red_plane_wins_over_black(self):
|
||
d = SSD168xDecoder(width=8, height=2) # tiny 1-byte-wide panel
|
||
# Black plane: row 0 all-black (0x00), row 1 all-white (0xFF)
|
||
feed_all(d, cmd(CMD_WRITE_BLACK_VRAM), data(0x00, 0xFF))
|
||
# Red plane: row 0 first 4 px red (0xF0), row 1 nothing (0x00)
|
||
feed_all(d, cmd(CMD_SET_RAMX_COUNTER), data(0x00))
|
||
feed_all(d, cmd(CMD_SET_RAMY_COUNTER), data(0x00, 0x00))
|
||
feed_all(d, cmd(CMD_WRITE_RED_VRAM), data(0xF0, 0x00))
|
||
frame = d.compose_frame()
|
||
# Row 0 cols 0..3: red (2). Cols 4..7: still black (0). Row 1 all white (1).
|
||
assert frame.pixels[0:4] == [2, 2, 2, 2]
|
||
assert frame.pixels[4:8] == [0, 0, 0, 0]
|
||
assert frame.pixels[8:16] == [1, 1, 1, 1, 1, 1, 1, 1]
|
||
|
||
|
||
class TestDeepSleepAndUnknownCmds:
|
||
"""Deep sleep + tolerance for vendor-specific quirks."""
|
||
|
||
def test_deep_sleep_flag_is_set(self):
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
feed_all(d, cmd(CMD_DEEP_SLEEP), data(0x01))
|
||
assert d.in_deep_sleep is True
|
||
|
||
def test_unknown_cmd_is_logged_not_raised(self):
|
||
"""Real panel firmware sometimes emits vendor-specific bytes;
|
||
the decoder logs them so we can audit later, but never raises."""
|
||
d = SSD168xDecoder(width=200, height=200)
|
||
feed_all(d, cmd(0xAB), data(0x01, 0x02)) # 0xAB is undefined
|
||
assert 0xAB in d.unknown_cmds
|
||
|
||
|
||
class TestEndToEndHelloWorld:
|
||
"""A canonical 'init → write white frame with one black pixel → activate'
|
||
flow reaches the on_flush callback with exactly one black pixel."""
|
||
|
||
def test_single_black_pixel_at_origin(self):
|
||
captured = []
|
||
d = SSD168xDecoder(width=200, height=200, on_flush=lambda f: captured.append(f))
|
||
gxepd2_init_154(d)
|
||
# Write the BW plane: byte 0 = 0x7F (top-left pixel = 0/black, others = 1/white)
|
||
feed_all(d, cmd(CMD_SET_RAMX_COUNTER), data(0x00))
|
||
feed_all(d, cmd(CMD_SET_RAMY_COUNTER), data(0x00, 0x00))
|
||
feed_all(d, cmd(CMD_WRITE_BLACK_VRAM), data(0x7F))
|
||
feed_all(
|
||
d,
|
||
cmd(CMD_DISP_UPDATE_CTRL_2), data(0xF7),
|
||
cmd(CMD_MASTER_ACTIVATION),
|
||
)
|
||
assert len(captured) == 1
|
||
frame = captured[0]
|
||
# Top-left pixel should be black (0); pixel (1, 0) should be white (1).
|
||
assert frame.pixels[0] == 0, "top-left expected black"
|
||
assert frame.pixels[1] == 1, "pixel (1,0) expected white"
|
||
|
||
|
||
if __name__ == "__main__":
|
||
pytest.main([__file__, "-v"])
|