Install openVFD for LCD display on recent (6.12) kernels - Tutorial

torz77 · 2025-09-25T01:27:33Z

This was originally meant as a reply to a user having problems enabling openVFD on a Tannix T3-Mini, a device I happen to own. I have recently been through this journey myself, and having searched the forums, I cannot find a recent topic on how to build this for Armbian, so have decided to make a new post that may be of use to some.

Hold on to your hat, because this is going to be long.

Caveats

These instructions are, specifically, for the Tannix TX3-Mini. However, with a bit of fiddling, the general approach should work for any supported TV Box. I have added notes where you will need to look to edit a different file for your specific device
There are many, many variants of the TX3-Mini out there. What works for me, may not work for you. Do not expect any help or support from me, I am just posting this as a courtesy for how I got this working... your mileage may vary. I am not going to troubleshoot anyone's issues
These instructions are quite verbose, as they may also help users of other TV Boxes to get their displays working. It also may not. Like I say, I am not here to be tech support, but we can all agree not having a display stuck on "boot" is a nice thing to have
As this is a kernel module it will most likely stop working after each kernel update. You will probably want to create a DKMS to rebuild the module whenever you download a new kernel. This is outside of scope here. Use Google.
At the end of this, if all goes well, you will have a display showing the current time. If you want to do more with the display then this is outside of scope and you will need to look elsewhere. However, this link is useful for how to trigger the icons: https://github.com/arthur-liberman/linux_openvfd/blob/master/led_control.txt (note: only items 1 to 6 are valid for the tx3-mini)
A lot of this can be done in a chroot, but the actual building of the kernel module itself must be done on the target device. To simplify things all of these instructions are to be executed on the device itself. If you want to do this in a chroot, then knock yourself out, but you are on your own.

My setup

At the time of writing, these instructions are confirmed working for the 7 Segment display and all icons on:

Tannix T3-Mini S905w with 2GB RAM
Armbian 25.11
Kernel 6.12.48-current-meson64
Debian stable (trixie) (13)

Instructions

Note: Every code block here is meant to be pasted and executed in one go, even the multi-line blocks

We will work from the home folder to keep things simple. Don't worry, there will be no clutter as we will remove files we no longer require as we go

cd ~

Device Tree Blob
The first thing we are going to want to do is enable kernel support for openvfd in our DTB. Normally I'd do this with an overlay, but this does not appear to be enabled on the aml-s9xx-box image, so we will apply an overlay to the DTB directly:

Install the device tree compiler:

sudo apt install -y device-tree-compiler --no-install-recommends

Back up the existing DTB (if anything goes wrong you can always just restore the backed up DTB) :
Note: If your device is not a Tanix T3-Mini, then you will want to amend the following to point to the actual DTB you are using (you can find this in '/boot/extlinux/extlinux.conf')
```
sudo cp /boot/dtb/amlogic/meson-gxl-s905w-tx3-mini.dtb /boot/dtb/amlogic/meson-gxl-s905w-tx3-mini.dtb.orig
```

Create the overlay source code:

cat << EOF > ~/openvfd.dts
/dts-v1/;
/plugin/;

/ {
    fragment@0 {
        target-path = "/";
        __overlay__ {
            openvfd {
                compatible = "open,vfd";
                dev_name = "openvfd";
                status = "okay";
            };
        };
    };
};
EOF

Compile the overlay:

dtc -@ -I dts -O dtb -o ~/openvfd.dtbo ~/openvfd.dts

Merge the overlay into your DTB:
Note: If your device is not a Tanix T3-Mini, then you will want to amend the following to point to the actual DTB you are using
```
sudo fdtoverlay -i /boot/dtb/amlogic/meson-gxl-s905w-tx3-mini.dtb -o /boot/dtb/amlogic/meson-gxl-s905w-tx3-mini.dtb ~/openvfd.dtbo
```
Delete the overlay source:
```
rm ~/openvfd.dts
```
[Optional] Delete the compiled overlay:
If your build is static (that is, you will never pull an updated DTB through apt) then you can also delete the compiled .dtbo overlay file. I prefer to keep this around, as you can just re-patch the new DTB with the "sudo fdtoverlay ..." command above. It is also possible to automate the update of a newly installed DTB file by creating a postinst.d script, but that is outside of the scope of this document. Google is your friend.
```
rm ~/openvfd.dtbo
```
Reboot so when we load the module later, our device knows what to do with it
```
sudo reboot now
```
Once your device has been rebooted, you can confirm that your change has been applied correctly with the following command:
```
dtc -I fs -O dts /proc/device-tree | grep -A3 openvfd
```
Again, this will generate a lot of warnings! This is normal. At the end of the warnings you should see the openvfd entry that you added to your DTS in the earlier step. If you do not, then you have not edited the file correctly, and you should go back and try again.

OpenVFD Config file

We need to create a configuration file which tells the OpenVFD module which GPIO pins are connected to the LCD display. We put this in the /etc folder as this is where we should be storing system configuration files for *deb based systems

The contents of this file were extracted from https://github.com/arthur-liberman/vfd-configurations so if you are using a different device, you must replace the following config with the relevant one from the link. If you are having issues with your config not working, direct them to the repo owner, not me. I do not know your device or what may be wrong.

Note: I remove the final functions='usb colon eth wifi' line as whilst the driver works fine with it included, it generates errors/warnings, which I would rather not see, and it appears to serve no purpose for Armbian

Execute the following to generate the config for the TX3-Mini
Note: If your device is not a Tanix T3-Mini do not execute the following. Instead, find your config at https://github.com/arthur-liberman/vfd-configurations and save it as /etc/openvfd.conf
```
sudo bash -c "cat << 'EOF' > /etc/openvfd.conf
vfd_gpio_clk='0,76,0'
vfd_gpio_dat='0,75,0'
vfd_gpio_stb='1,4,0'
vfd_chars='4,3,2,1,0'
vfd_dot_bits='0,1,3,2,4,5,6'
vfd_display_type='0x01,0x00,0x00,0x00'
EOF"
```

Build the Kernel Module

Now for the nitty gritty, we need to build the kernel module.

The first thing we need is the kernel headers.
Note: the headers version must match your installed kernel version exactly. Do not try installing the headers for a different kernel version. You will run into issues
If you are on a standard image, or your kernel has been upgraded since you built your image, this is straightforward:
```
sudo apt install linux-headers-$(uname -r)
```
However, if you have built the image yourself, and you have not upgraded your kernel, then most likely the version available from the apt repository will not be compatible and your build may fail or the driver may not work at all. In these instances, you will need to go back to your build system and add the following switch to your ./compile.sh command:
```
INSTALL_HEADERS=yes
```

Install the required build tools

sudo apt install -y git build-essential --no-install-recommends

Clone the openvfd repo.
At the time of writing the openvfd repo is not compatible with later Linux kernels. I have raised a PR against the repo to enable support, however it has not yet been accepted. If/when it is accepted I will be deleting my fork of the repo, but in the meantime, you can clone my fork with:
```
git clone https://github.com/torzdf/linux_openvfd.git ~/linux_openvfd
```
If the above does not work, it is because I have deleted my fork as the changes have been merged, and I am unable to come back and edit this post. If this is the case then run the following:
Note: DO NOT run the next line, if the above git clone worked
```
git clone https://github.com/arthur-liberman/linux_openvfd.git ~/linux_openvfd
```
Enter the driver folder of the cloned repo
```
cd ~/linux_openvfd/driver
```

Create a Makefile. The provided Makefile will not work, so we need to replace it with our own:

cat << 'EOF' > ./Makefile
ifeq ($(KERNELRELEASE),)
		PWD = $(shell pwd)
	        KERNELDIR = /lib/modules/`uname -r`/build
modules:
	        $(MAKE) -C $(KERNELDIR) M=$(PWD) modules
modules_install:
	        $(MAKE) -C $(KERNELDIR) M=$(PWD) modules_install
clean:
	        rm -rf  *.o *.ko .tmp_versions *.mod.c modules.order  Module.symvers ssd253x-ts.*
else
		obj-m := openvfd.o
		openvfd-objs += protocols/i2c_sw.o
		openvfd-objs += protocols/i2c_hw.o
		openvfd-objs += protocols/spi_sw.o
		openvfd-objs += controllers/dummy.o
		openvfd-objs += controllers/seg7_ctrl.o
		openvfd-objs += controllers/fd628.o
		openvfd-objs += controllers/fd650.o
		openvfd-objs += controllers/hd44780.o
		openvfd-objs += controllers/gfx_mono_ctrl.o
		openvfd-objs += controllers/ssd1306.o
		openvfd-objs += controllers/pcd8544.o
		openvfd-objs += controllers/il3829.o
		openvfd-objs += openvfd_drv.o
endif
EOF

Compile the kernel module:
```
make -j$(nproc)
```
Install the kernel module:
```
sudo make modules_install
```
Update the kernel modules:
```
sudo depmod -a
```

Create the helper service

Next we need to compile and install the helper service

Enter the folder that contains the source code for the helper service:
```
cd ~/linux_openvfd
```
Build the helper service:
```
make OpenVFDService
```
Make the helper service executable:
```
chmod +x OpenVFDService
```
Install the helper service:
```
sudo cp OpenVFDService /usr/bin/
```

Clean up

We have built everything we need from the OpenVFD repo, so we can get rid of the source code

Go back to our home folder and delete the source code
```
cd ~ && sudo rm -r linux_openvfd
```

systemd Service file

The final step. We need to create a service file that will load the kernel module, and launch the helper service, and enable it on boot

Create the systemd service file:
note: If you prefer a 12 hour clock rather than a 24 hour clock, edit the 'Environment="OPTS=-24h"' line to 'Environment="OPTS=-12h"'

sudo bash -c 'cat << '\''EOF'\'' > /etc/systemd/system/openvfd.service
[Unit]
Description=openvfd
Wants=network-online.target

[Service]
Type=simple
Environment="OPTS=-24h"
ExecStartPre=/usr/bin/sh -c ". /etc/openvfd.conf; /usr/sbin/modprobe openvfd vfd_gpio_clk=$vfd_gpio_clk vfd_gpio_dat=$vfd_gpio_dat vfd_gpio_stb=$vfd_gpio_stb vfd_chars=$vfd_chars vfd_dot_bits=$vfd_dot_bits vfd_display_type=$vfd_display_type;"
ExecStart=/usr/bin/OpenVFDService $OPTS &
ExecStop=/usr/bin/killall OpenVFDService
ExecStopPost=-/usr/sbin/rmmod openvfd

[Install]
WantedBy=multi-user.target
EOF'

Reload the systemd daemon:
```
sudo systemctl daemon-reload
```
Start the openvfd service:
```
sudo systemctl start openvfd.service
```
At this point your LCD should now be showing the time. If it is not, you can check for errors with:
```
sudo systemctl status openvfd.service
```
Enable the service at boot:
```
sudo systemctl enable openvfd.service
```

And that's it. If all has gone well, you now have a working LCD Display for your TV Box running a recent Armbian build

Edited 1 hour ago by torz77

SteeMan · 2025-09-25T13:22:13Z

Did you try doing this with a device tree overlay file instead of editing the device tree? That way on kernel upgrades you shouldn't need to redo the device tree edits each time.

SteeMan · 2025-09-25T13:24:00Z

Also, did you experiment with this alternative to openvfd?

torz77 · 2025-09-25T14:19:59Z

Quote

Did you try doing this with a device tree overlay file instead of editing the device tree? That way on kernel upgrades you shouldn't need to redo the device tree edits each time.

Sadly, Meson64 does not have DTB Overlays enabled. That would, of course, be my preference. I have, however, updated my instructions to create an overlay and apply it directly to the DTB (rather than manually editing the DTB) and pointed users in the direction of postint.d if they wish to automate this (out of scope to provide specific instructions here). It should now be easier to create an overlay rather than directly apply to DTB if the user's box supports this.

Quote

Also, did you experiment with this alternative to openvfd?

Unfortunately, I did not see this until I was well underway getting OpenVFD working. The box is now in production, so it is not straightforward taking it out and experimenting with it. However, having more than one way to achieve an end goal is no bad thing imho.

Sign In

Install openVFD for LCD display on recent (6.12) kernels - Tutorial

Recommended Posts

torz77

SteeMan

SteeMan

torz77

Join the conversation

Forums

My Activity Streams

Download

Store

Important Information