tm16xx-display

Linux kernel driver for auxiliary displays based on led controllers such as tm16xx family and alike

Supported Android TV box

See Device Table

Compatible Controllers

Other similar controllers may already be compatible using one of these identifiers.

• Shenzhen Titan Micro Electronics Co., Ltd.
  • titanmec,tm1618 (datasheet)
  • titanmec,tm1620 (datasheet)
  • titanmec,tm1628 (datasheet)
  • titanmec,tm1638 (datasheet)
  • titanmec,tm1650 (datasheet)
• Fuzhou Fuda Hisi Microelectronics Co., Ltd.
  • fdhisi,fd620 (datasheet)
  • fdhisi,fd628 (datasheet)
  • fdhisi,fd650 (datasheet)
  • fdhisi,fd655 (datasheet)
  • fdhisi,fd6551 (datasheet)
• Wuxi i-Core Electronics Co., Ltd.
  • wxicore,aip650 (datasheet)
  • wxicore,aip1618 (datasheet)
  • wxicore,aip1628 (datasheet)
• Princeton Technology Corporation
  • princeton,pt6964 (datasheet)
• Shenzhen Winrise Technology Co., Ltd.
  • winrise,hbs658 (datasheet)

Overview

graph TD;
    subgraph "User Space"
        A["display-service - systemd service"]
    end
    subgraph "Kernel Space"
        B["tm16xx - Kernel Driver Module"]
    end
    subgraph "Hardware"
        C["display-controller - tm16xx Chip"]
    end

    A -->|leds class sysfs interface| B
    B -->|Device Tree Node - I2C or SPI| C

Loading

Explanation:

• User Space:

  • display-service: A systemd service running in user space, interacting with the kernel driver via the sysfs interface.

• Kernel Space:

  • tm16xx: The kernel driver module that exposes control interfaces through sysfs, allowing user-space applications to control the display hardware.

• Hardware:

  • display-controller: The actual tm16xx chip that manages the display.

Interaction Flow:

1. User Space to Kernel Space:

   • The display-service interacts with the tm16xx kernel driver via the sysfs LEDs class interface, typically found under /sys/class/leds/.

2. Kernel Space to Hardware:

   • The tm16xx driver relies on the device tree node (which defines hardware properties) to communicate with the display controller, using either I2C or SPI.

Installation Instructions

Prerequisites

Building the driver

Linux kernel headers installed

armbian-config

Then go to Software -> Headers

tm16xx module

See Kconfig for kernel configuration.

Display service

Depending on the icons configured for the auxiliary display, additional led triggers modules are required by display-service:

Usage	LEDs	Trigger	Module	Config
Time seperator blink	colon	timer	ledtrig_timer	CONFIG_LEDS_TRIGGER_TIMER=y or m
Network activity	lan, wlan, bluetooth	netdev	ledtrig_netdev	CONFIG_LEDS_TRIGGER_NETDEV=y or m
USB activity	usb	usbport	ledtrig-usbport	CONFIG_USB_LEDS_TRIGGER_USBPORT=y or m
SD/MMC activity	sd	mmc0	mmc_core	CONFIG_MMC=y or m

Download

git clone https://github.com/jefflessard/tm16xx-display.git

Configure the device tree

⚠️ KEEP A BACKUP OF YOUR CUREENT DTB

1. Find your device in the Device Table

2. Update your dtb

Option 1: Use device tree overlay, if supported

• Build overlay

# This will create the overlay in release/{YOUR_DEVICE_NAME}.dtbo
make {YOUR_DEVICE_NAME}.dtbo 

• Copy dtbo in /boot/overlay-user/

cp release/{YOUR_DEVICE_NAME}.dtbo /boot/overlay-user/tm16xx.dtbo

• Edit /boot/armbianEnv.txt to load the overlay

user_overlays=tm16xx

Option 2: Create an updated dtb

• Copy your current dtb file to original.dtb:

# run this command only once.
# we must always start from the
# original dtb when merging overlay
make extract-dtb ORIGINAL_DTB=original.dtb

• Merge the display dtb overlay with your current dtb

# This will create the dtb in release/{YOUR_DEVICE_NAME}.dtb
make {YOUR_DEVICE_NAME}.dtb ORIGINAL_DTB=original.dtb

# Replace your current dtb with the new dtb, for example:
#cp release/{YOUR_DEVICE_NAME}.dtb /boot/dtb/{YOUR_DTB_PATH}.dtb

3. Reboot to apply changes

reboot

Kernel module and display service

Option 1: build and install in a single command

Builds then installs module and service

make install

Option 2: step by step commands

make module
make module-install
make service-install

Check your display configuration

display-service -c

3 phase display check

1. Check that all leds are ON
2. Check the order of digits and segment mapping (you should see "1234")
3. Check each led name (ex: LAN icon is ON while "LAN" text is shown on the digits)

Advanced Device Configuration

Convert existing OpenVFD vfd.conf

Existing compatible OpenVFD vfd-configurations are already converted. Find them in the Device Table

Convert a single vfd.conf

./vfdconf-convert {path_to_your_vfd.conf_file} devices/{your_device_name}.dtso

Convert multiple vfd.conf

./vfdconf-convert -r {path_to_vfd-configurations_directory} devices

Create your own configuration

See device tree bindings documentation: titanmec,tm16xx.yaml.

Usage

Service basics

Start:

systemctl start display

Stop:

systemctl stop display

Restart:

systemctl restart display

Show scrolling text on the display

display-service -t "{your_message}"

Customize display service

Just edit the shell script at /usr/sbin/display-service

Customize display from shell

# turn on display
cat /sys/class/leds/display/max_brightness > /sys/class/leds/display/brightness

# dim brightness display
# value between 1 and max_brightness (usually 8)
echo 1 > /sys/class/leds/display/brightness

# turn off display
echo 0 > /sys/class/leds/display/brightness

# write text on the display (supports 7-segment ascii mapping)
echo "boot" > /sys/class/leds/display/value

# clear the display text
echo > /sys/class/leds/display/value

# list available leds/symbols
ls /sys/class/leds/display\:\:*

# turn on a specific led/symbol
echo 1 > /sys/class/leds/display\:\:lan/brightness

# turn off a specific led/symbol
echo 0 > /sys/class/leds/display\:\:lan/brightness

# automatically turn on/off usb led when usb device is connected on a specific port
echo usbport > /sys/class/leds/display::usb/trigger
echo 1 > /sys/class/leds/display::usb/ports/usb1-port1

# turn on led on wifi connect + blink on activity (requires ledtrig-netdev module)
echo netdev > /sys/class/leds/display::wlan/trigger
echo wlan0 > /sys/class/leds/display::wlan/device_name
echo 1 > /sys/class/leds/display::wlan/link
echo 1 > /sys/class/leds/display::wlan/rx
echo 1 > /sys/class/leds/display::wlan/tx