Gitzian

This package is a runtime client for Gitzian display hardware for supported Raspberry Pi devices.

The client receives the display stream over the network, drives the connected display, handles backlight and touch hardware, and forwards local input events.

Changelog

0.1.4

• Added automatic display config selection via the installed display manifest.
• Read out FPGA firmware ID at startup and resolve matching display profiles from firmware project, decoder board, version, and build ID.
• Print the selected display INI before display, backlight, and touch initialization.
• Added a display runtime layer for panel init, backlight init, touch init, and touch IRQ handling.
• Added support for optional touch and backlight sections in display profiles.
• Added TL021WVC02CT-B1323B display support
• Added TL032FWV01CT-I1440A display support
• Added Server Misconfiguration Detection

Supported displays

Display	Resolution	Backlight	Touch
TL021WVC02CT-B1323B	480x480	LM3630A	CST826
TL032FWV01CT-I1440A	320x820	LM3630A	FT6336U
TL040HDS30CT1-B1620A	720x720	LM3630A	FT6336
TL040HDS20CT-B1502A	720x720	LM3630A	FT6336

Supported Raspberry Pi models

Gitzian is intended to run on Raspberry Pi hardware with I2C and SPI enabled.

Recommended models:

• Raspberry Pi Zero 2 W
• Raspberry Pi 2
• Raspberry Pi 3, tested with Model B
• Raspberry Pi 4, tested with Model B
• Raspberry Pi 5

Raspberry Pi Zero v1.1 is supported, but not recommended for displays larger than 360×360 because of weaker Wi-Fi performance. It is still usable for static or lower-bandwidth use, but not recommended for gaming or fluid video streaming.

Actual streaming quality depends on Wi-Fi quality, network latency, and available bandwidth.

Raspberry Pi setup

Enable I2C and SPI:

sudo raspi-config

Install basic build requirements:

sudo apt update
sudo apt install -y python3-dev build-essential

Raspberry Pi 5 GPCLK0 support

Raspberry Pi 5 requires the Gitzian GPCLK0 overlay package for proper display clock output.

sudo apt update
sudo apt install -y curl

curl -fsSL https://apt.gitzian.com/gitzian-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/gitzian-archive-keyring.gpg >/dev/null

sudo tee /etc/apt/sources.list.d/gitzian.sources >/dev/null <<'EOF'
Types: deb
URIs: https://apt.gitzian.com
Suites: trixie
Components: main
Architectures: arm64
Signed-By: /usr/share/keyrings/gitzian-archive-keyring.gpg
EOF

sudo apt update
sudo apt install -y gitzian-rp1-gpclk0-dkms

Install

pip install gitzian

First run

Create the default configuration:

gitzian-pi --init-config

Edit the config file:

~/.config/gitzian/client/default.ini

At minimum, set the network target for your Gitzian streaming server:

[network]
enabled = true
server_host = 10.77.0.4
server_port = 55556

Start the client:

gitzian-pi

Equivalent module form:

python -m gitzian

Use a custom config file:

gitzian-pi --config ./default.ini

Runtime commands

Runtime commands are typed into the terminal while Gitzian is running.

Command	Description
help	Show available runtime commands.
brightness	Show the current brightness percentage.
brightness 0	Turn the display backlight off.
brightness 75	Set backlight brightness to 75%.
brightness off	Turn the display backlight off.
brightness max	Set backlight brightness to 100%.

When runtime debug tools are enabled in the config, these commands are also available:

Command	Description
fps	Show current frame-rate statistics.
fps run	Print frame-rate statistics periodically.
fps stop	Stop periodic frame-rate output.
input list	List detected input devices.
input reload	Reload input devices.

Configuration

The main config selects the display profile. The default mode is automatic:

[display]
config = auto

In automatic mode, Gitzian reads the FPGA firmware ID and resolves the display profile through the installed display manifest. Startup output shows the resolved display INI before display, backlight, and touch hardware are initialized.

Manual selection is also supported:

[display]
config = TL040HDS30CT1-B1620A.ini

A custom absolute INI path can be used for local development or unsupported hardware:

[display]
config = /home/gitzi/my_custom_display.ini

The display profile contains display-specific reset, panel init, I2C, backlight, and touch settings. Touch and backlight sections are optional for displays that do not provide them.

Network notes

Gitzian is a streaming client. Network connectivity to the configured Gitzian streaming server is required.

For secure use over the internet, use a private tunnel such as WireGuard.

Support

Website:

https://gitzian.com

For help, questions, or special requirements, contact:

marco [at] gitzian.com

There are no stupid questions. If you are unsure whether your setup is supported, ask.

License

This Python package is released under the MIT License.

See LICENSE for details.

Trademark notice

Raspberry Pi is a trademark of Raspberry Pi Ltd. This project is not affiliated with or endorsed by Raspberry Pi Ltd.