Skip to content

README.md

Latest commit

 

History

History
221 lines (143 loc) · 3.88 KB

README.md

File metadata and controls

221 lines (143 loc) · 3.88 KB

STeaMi Screen

High-level UI library for STeaMi displays.

Provides a device-agnostic abstraction layer on top of display drivers (SSD1327, GC9A01) with a simple API to draw UI elements: text layouts, widgets, menus, icons.

Features

  • Display abstraction (works with any FrameBuffer-based backend)
  • Automatic layout for round screens (cardinal positioning, safe margins)
  • Text rendering with alignment and scaling
  • Drawing primitives (pixel, line, rect, circle)
  • 10 widgets: title, subtitle, value, bar, gauge, graph, menu, compass, watch, face

Basic Usage

import ssd1327
from machine import SPI, Pin
from steami_screen import Screen, SSD1327Display

spi = SPI(1)
dc = Pin("DATA_COMMAND_DISPLAY")
res = Pin("RST_DISPLAY")
cs = Pin("CS_DISPLAY")

raw = ssd1327.WS_OLED_128X128_SPI(spi, dc, res, cs)
display = SSD1327Display(raw)
screen = Screen(display)

screen.clear()
screen.title("STeaMi")
screen.value(42, label="Temp", unit="C")
screen.show()

API Reference

Initialization

screen = Screen(display)

display must expose fill(), pixel(), line(), rect(), fill_rect(), text(), show(). Width and height are auto-detected from the display backend.

Drawing Primitives

screen.pixel(x, y, color)
screen.line(x1, y1, x2, y2, color)
screen.rect(x, y, w, h, color, fill=False)
screen.circle(x, y, r, color, fill=False)

Text

screen.text("Hello", at="CENTER")
screen.text("Top", at="N")
screen.text("Custom", at=(10, 20))
screen.text("Big", at="CENTER", scale=2)

Cardinal positions: "N", "NE", "E", "SE", "S", "SW", "W", "NW", "CENTER".

Note: scale > 1 produces a true pixel-scale zoom on SSD1327 displays via pixel-by-pixel framebuf rendering. Other backends can implement draw_scaled_text() for native scaling support. Backends without it fall back to a bold offset effect.

Widgets

Title

screen.title("STeaMi")

Draws text centered at the top (N position).

Subtitle

screen.subtitle("Line 1", "Line 2")

Draws text centered at the bottom (S position). Accepts multiple lines.

Value

screen.value(23.5, label="Temp", unit="C")

Displays a large centered value with optional label above and unit below.

Progress Bar

screen.bar(75, max_val=100)

Gauge

screen.gauge(60, min_val=0, max_val=100)

Draws a 270-degree arc gauge near the screen border.

Graph

screen.graph([10, 20, 15, 30], min_val=0, max_val=100)

Draws a scrolling line graph with the last value displayed above.

Menu

screen.menu(["Item 1", "Item 2", "Item 3"], selected=1)

Compass

screen.compass(heading=45)

Draws a compass with cardinal labels and a rotating needle.

Watch

screen.watch(hours=10, minutes=30, seconds=15)

Draws an analog clock face.

Face

screen.face("happy")

Draws a pixel-art expression. Available: "happy", "sad", "surprised", "sleeping", "angry", "love".

Control

screen.clear()
screen.show()

Properties

screen.center      # (64, 64) for 128x128
screen.radius      # 64 for 128x128
screen.max_chars   # 16 for 128px width

Color Constants

from steami_screen import BLACK, DARK, GRAY, LIGHT, WHITE
from steami_screen import RED, GREEN, BLUE, YELLOW

Colors are RGB tuples. On SSD1327 they degrade to greyscale automatically.

Color Utilities

from steami_screen import rgb_to_gray4, rgb_to_rgb565, rgb_to_rgb8
Function Output
rgb_to_gray4(color) 4-bit greyscale (0-15) for SSD1327
rgb_to_rgb565(color) 16-bit RGB565 for GC9A01
rgb_to_rgb8(color) RGB tuple pass-through

All accept int values for backward compatibility.