microdot-phat-zig

A Zig port of the Pimoroni Micro Dot pHAT Python library.

Drives the Micro Dot pHAT — a Raspberry Pi add-on with six 5×7 LED dot-matrix displays driven by three IS31FL3730 chips over I²C.

Requirements

• Raspberry Pi (any model) with the Micro Dot pHAT attached
• Raspberry Pi OS (32-bit or 64-bit)
• Zig 0.16 — only needed on the build machine, not on the Pi

Building

On the Raspberry Pi itself

zig build -Doptimize=ReleaseSafe
sudo ./zig-out/bin/custom_clock

Cross-compiling from a Mac or Linux machine

32-bit Pi OS — works on every Pi model (Pi Zero, 1, 2, 3, 4, 5):

zig build pi-32bit
scp zig-out/pi-32bit/* pi@raspberrypi.local:~/

64-bit Pi OS — Pi 3, 4, and 5:

zig build pi-64bit
scp zig-out/pi-64bit/* pi@raspberrypi.local:~/

Binaries are self-contained (no external dependencies beyond standard libc) and ready to run.

Examples

Binary	Description
flash	Flash all pixels on and off repeatedly
scrolling_text	Scroll a message across the display (scrolling_text "Hello!")
scrolling_text_jp	Scroll Japanese and fullwidth ASCII text across the display
scrolling_word	Scroll one character at a time, 8 pixels per step
advanced_scrolling	Scroll multi-line text horizontally and vertically, then rewind diagonally
vertical_text	Scroll stacked lines of text vertically
sine_wave	Animate a scrolling sine wave across the display
graph	Show a scrolling random bar graph
fading_text	Fade brightness in and out while swapping strings
tiny_font	Display an IP address using the compact tiny number font
thermal	Display CPU temperature from thermal_zone0
clock	HHMMSS clock with blinking decimal-point separators
custom_clock	Live HH:MM clock with changed digits scrolling up in sync, rotated 180°

Run any example with sudo (I²C access requires it unless your user is in the i2c group):

sudo ./flash
sudo ./scrolling_text "Hello, world!"
sudo ./custom_clock

API

The library exposes a single MicroDotPhat struct. All display state is encapsulated — no globals.

const mdp = @import("microdotphat");

var display = try mdp.MicroDotPhat.init(allocator);
defer display.deinit();

// Write text (kerning=true for scrolling, kerning=false for one char per matrix)
_ = try display.writeString("Hello", 0, 0, true);

// Scroll, then push to hardware
display.scrollHorizontal(1);
try display.show();

Full API

Method	Description
init(allocator)	Initialise display and open I²C. Buffer starts at 45×7.
deinit()	Clear/show the display when enabled, then close I²C and free buffer.
isConnected()	Returns true if all three IS31FL3730 chips respond.
clear()	Clear buffer, reset scroll position, and restore the buffer to 45×7.
fill(c)	Fill entire buffer with 0 or 1.
setClearOnExit(bool)	Set whether deinit() should clear and show the display before closing.
setPixel(x, y, on)	Set a single pixel; buffer grows automatically.
setCol(x, col)	Set a full column from a 7-bit mask.
setDecimal(index, on)	Toggle the decimal point on display 0–5.
writeChar(codepoint, x, y)	Write one Unicode character to the buffer.
writeString(str, x, y, kerning)	Write a UTF-8 string; returns pixel width used.
drawTiny(display, digits)	Draw compact numbers (up to 3 digits per matrix).
scroll(dx, dy)	Scroll buffer by signed pixel amounts.
scrollTo(x, y)	Jump to an absolute scroll position.
scrollHorizontal(n)	Scroll horizontally by n pixels.
scrollVertical(n)	Scroll vertically by n pixels.
setBrightness(f)	Set brightness 0.0–1.0 for all matrices.
setRotate180(bool)	Rotate the display 180°.
setMirror(bool)	Mirror the display left-to-right.
show()	Push the current buffer to the hardware.

Font

The built-in 5×7 font covers:

• ASCII printable characters (32–126)
• Extended Latin (Ä, Å, Æ, Ç, É, Ö, Ø, ä, å, ö, ø, …)
• Arrows (← ↑ → ↓), box-drawing characters, geometric shapes, ★
• Hiragana, Katakana, fullwidth ASCII and punctuation

Glyph lookup: font.getGlyph(codepoint: u21) ?[5]u8

I²C permissions

By default I²C requires root. To run without sudo, add your user to the i2c group:

sudo usermod -aG i2c $USER
# log out and back in

Or enable the I²C interface without permission restrictions via raspi-config.

Project structure

src/
  root.zig          — public re-exports
  i2c.zig           — Linux I²C via ioctl + write syscalls
  matrix.zig        — IS31FL3730 driver (NanoMatrix)
  font.zig          — 5×7 glyph data (~400 characters)
  microdotphat.zig  — high-level display API
examples/
  advanced_scrolling.zig
  clock.zig
  custom_clock.zig
  fading_text.zig
  flash.zig
  graph.zig
  scrolling_text.zig
  scrolling_text_jp.zig
  scrolling_word.zig
  sine_wave.zig
  thermal.zig
  tiny_font.zig
  vertical_text.zig

Attribution

This is a Zig port of the pimoroni/microdot-phat Python library by Pimoroni Ltd. Font data, glyph bitmaps, and IS31FL3730 register layout are derived from that project.

License

MIT — see LICENSE.