LCD - LCD Display for Devices

LCD - LCD Display for Devices

Overview

VyOS supports the configuration and management of LCD displays for hardware appliances, such as 19-inch rack servers or dedicated network devices. LCD displays make it possible to show real-time system status information directly on the physical device, without the need to connect a monitor or use remote access.

Key Capabilities

• System information display: CPU load, memory usage, network interfaces
• Network status: IP addresses, interface statistics, connection information
• Custom messages: Configurable text for device identification
• LCDPROC support: Uses the powerful LCDPROC daemon to drive the displays
• Multiple connection types: USB, serial port, parallel port

Important Notes

LCDPROC Architecture

VyOS uses LCDPROC - a client-server architecture for managing LCD displays:

• LCDd (daemon): The server process that communicates directly with the display hardware
• Clients: Programs that connect to LCDd to display information
• Drivers: Hardware-specific modules for the various display models

Benefits of LCDPROC

1. Modularity: Separation of display logic from hardware control
2. Multiple clients: Several programs can use a single display
3. Broad hardware support: An extensive driver base
4. Network transparency: The ability to manage the display remotely

Supported Display Models

CrystalFontz

VyOS officially supports the following CrystalFontz models:

CFA-533

Model: cfa533
Type: LCD text display
Size: 16x2 characters
Interface: USB
Features:
  - 4 directional navigation buttons
  - Backlight with adjustable brightness
  - Contrast adjustable in software

Configuration:

set system lcd device ttyUSB0
set system lcd model cfa533
commit
save

CFA-631

Model: cfa631
Type: LCD text display
Size: 20x2 characters
Interface: USB
Features:
  - Larger display size
  - 4 directional buttons + 2 additional
  - RGB backlight
  - Built-in temperature sensor

Configuration:

set system lcd device ttyUSB0
set system lcd model cfa631
commit
save

CFA-633

Model: cfa633
Type: LCD text display
Size: 16x2 characters
Interface: USB / Serial
Features:
  - Flexible connection (USB or RS-232)
  - 4 directional buttons
  - Adjustable backlight
  - Compatible with a 5.25" bay

Configuration (USB):

set system lcd device ttyUSB0
set system lcd model cfa633
commit
save

Configuration (Serial):

set system lcd device ttyS0
set system lcd model cfa633
commit
save

CFA-635

Model: cfa635
Type: LCD text display
Size: 20x4 characters
Interface: USB / Serial
Features:
  - Large 20x4 display
  - 6 directional buttons
  - RGB backlight
  - Up to 4 fans with control
  - Temperature sensors (up to 32)
  - DOW reader

Configuration:

set system lcd device ttyUSB0
set system lcd model cfa635
commit
save

Matrix Orbital

Popular Matrix Orbital models:

• GLK12232-25-USB: 122x32 graphic display
• GLK19264-7T-1U: 192x64 graphic display
• LK162-12: 16x2 text display
• LK204-25: 20x4 text display

Other Manufacturers

LCDPROC supports displays from:

• Hitachi HD44780: A basic LCD controller (many manufacturers)
• Noritake: VFD displays
• SureElec: USB LCD displays
• Tyan: Built-in server displays
• Shuttle: Displays for PC cases

Configuration

Basic Setup

A minimal configuration requires specifying the display device and model:

configure
set system lcd device <device_path>
set system lcd model <model_name>
commit
save

Identifying the Device

Automatic Detection of USB Devices

VyOS supports tab-completion for the available serial interfaces:

configure
set system lcd device <TAB>

Output:

Possible completions:
  ttyS0        Serial port 0
  ttyS1        Serial port 1
  ttyUSB0      USB serial device 0
  ttyUSB1      USB serial device 1

Identifying a USB LCD Manually

To identify a connected USB LCD display:

lsusb

Example output:

Bus 001 Device 003: ID 0403:fc0d Future Technology Devices International, Ltd

Verify that the device was created:

ls -la /dev/ttyUSB*

Output:

crw-rw---- 1 root dialout 188, 0 Oct 15 10:23 /dev/ttyUSB0

Serial Ports

Standard serial ports:

• ttyS0: COM1 (IRQ 4, IO 0x3F8)
• ttyS1: COM2 (IRQ 3, IO 0x2F8)
• ttyS2: COM3 (IRQ 4, IO 0x3E8)
• ttyS3: COM4 (IRQ 3, IO 0x2E8)

Check port availability:

dmesg | grep ttyS

Selecting the Display Model

A list of supported models can be obtained through tab-completion:

configure
set system lcd model <TAB>

Output:

Possible completions:
  cfa533       Crystalfontz CFA-533
  cfa631       Crystalfontz CFA-631
  cfa633       Crystalfontz CFA-633
  cfa635       Crystalfontz CFA-635

Complete Configuration Example

Example 1: CFA-633 over USB

configure

# Configure the LCD display
set system lcd device ttyUSB0
set system lcd model cfa633

# Apply the configuration
commit

# Save the configuration
save

exit

Example 2: CFA-635 over Serial

configure

# Configure the LCD display
set system lcd device ttyS0
set system lcd model cfa635

# Apply the configuration
commit

# Save the configuration
save

exit

Example 3: CFA-533 for a Rack Server

configure

# LCD display for identification in the rack
set system lcd device ttyUSB0
set system lcd model cfa533

# Configure the hostname for display
set system host-name rack-router-01

# Apply and save
commit
save

exit

Displayed Information

System Screens

LCDPROC automatically cycles through the following information:

Screen 1: System Information

VyOS 1.5.0-rc
Uptime: 5d 3h 42m

Displays:

• The VyOS version
• System uptime

Screen 2: Processor and Memory

CPU: 45% [||||    ]
MEM: 2.3G/8.0G 28%

Displays:

• CPU load as a percentage and graphically
• Memory usage (used/total)

Screen 3: Network Interfaces

eth0: 192.168.1.1
UP 1000Mb/s Full

Displays:

• The IP address of the primary interface
• Link status and connection speed

Screen 4: Network Statistics

RX: 1.2TB 45Mb/s
TX: 834GB 12Mb/s

Displays:

• Received data (total and current rate)
• Transmitted data (total and current rate)

Screen 5: Hostname

rack-router-01
Ready

Displays:

• The system hostname
• Readiness status

Refresh Interval

The information on the display is refreshed:

• System information: Every 5 seconds
• CPU/Memory: Every second
• Network statistics: Every 2 seconds
• Screen switching: Every 4-6 seconds

Verifying the Configuration

Viewing the Active Configuration

show configuration commands | grep lcd

Output:

set system lcd device 'ttyUSB0'
set system lcd model 'cfa633'

Checking LCDPROC Status

Check the running LCDd process:

ps aux | grep LCDd

Output:

root      1234  0.1  0.2  12345  6789 ?        Ss   10:23   0:01 /usr/sbin/LCDd

Checking the Logs

View the LCDPROC logs for diagnostics:

journalctl -u lcdproc.service

Or:

cat /var/log/syslog | grep -i lcdproc

Testing the Connection

Check device availability:

ls -la /dev/ttyUSB0

Check access permissions:

stat /dev/ttyUSB0

Troubleshooting

Problem: The Display Does Not Initialize

Symptoms: The display stays blank after configuration.

Solution 1: Verify that the device is correct

# List USB devices
lsusb

# List serial devices
ls -la /dev/ttyUSB* /dev/ttyS*

# Verify that the device was created
dmesg | tail -50

Solution 2: Check access permissions

# Add the user to the dialout group
sudo usermod -a -G dialout root

# Check permissions on the device
ls -la /dev/ttyUSB0

# It should be: crw-rw---- 1 root dialout

Solution 3: Restart the LCDPROC service

sudo systemctl restart lcdproc
sudo systemctl status lcdproc

Problem: Incorrect Display Model

Symptoms: The display shows garbled characters or flickers.

Solution: Make sure the model is correct

configure

# Remove the old configuration
delete system lcd model

# Set the correct model
set system lcd model <correct_model>

commit
save

Problem: The USB Device Disconnects

Symptoms: The display disappears intermittently.

Solution 1: Disable USB autosuspend

# Find the USB device
lsusb -t

# Disable autosuspend for the specific device
echo -1 > /sys/bus/usb/devices/1-1/power/autosuspend_delay_ms

Solution 2: Check USB power

# Check power limits
lsusb -v | grep -i maxpower

# Make sure the USB port provides sufficient power

Problem: Serial Port Conflict

Symptoms: A “Device is busy” error during configuration.

Solution: Check whether the port is used by another process

# Check the processes using the device
lsof /dev/ttyUSB0

# Or via fuser
fuser /dev/ttyUSB0

# Stop the conflicting process
kill <PID>

Problem: The Display Shows Stale Information

Symptoms: The information on the display does not update.

Solution: Restart LCDPROC with a cleanup

# Stop the service
sudo systemctl stop lcdproc

# Clear any possible locks
sudo rm -f /var/run/LCDd.pid

# Start it again
sudo systemctl start lcdproc

# Check the status
sudo systemctl status lcdproc

Problem: Unsupported Model

Symptoms: The model you need does not appear in tab-completion.

Solution: Request that support be added

1. Check for support in LCDPROC directly
2. Create a feature request in VyOS Phabricator:
   • URL: https://vyos.dev/
   • Specify the display model
   • Specify the manufacturer and specifications
   • Attach the display documentation

Workaround: Manual LCDPROC configuration

# Edit the LCDPROC configuration file directly
sudo vi /etc/LCDd.conf

# Add a section for your driver
[your_driver]
Device=/dev/ttyUSB0
Size=20x4

# Restart the service
sudo systemctl restart lcdproc

Advanced Configuration

Manual LCDPROC Setup

For advanced settings, you can edit the LCDPROC configuration file directly:

sudo vi /etc/LCDd.conf

Example of an extended configuration for the CFA-635:

[server]
Driver=CFontz635
Bind=127.0.0.1
Port=13666
ReportLevel=3
ReportToSyslog=yes

[CFontz635]
Device=/dev/ttyUSB0
Size=20x4
Contrast=560
Brightness=1000
OffBrightness=0
Speed=115200
NewFirmware=yes
Reboot=no

Adjusting Contrast and Brightness

For models with software adjustment:

[CFontz633]
Device=/dev/ttyUSB0
Size=16x2
# Contrast (0-1000)
Contrast=500
# Brightness (0-1000)
Brightness=800
# Brightness when idle (0-1000)
OffBrightness=100

Configuring the Port Speed

For serial connections:

[CFontz633]
Device=/dev/ttyS0
# Transfer rate (baud rate)
Speed=19200
# Possible values: 1200, 2400, 9600, 19200, 38400, 57600, 115200

Configuring the Buttons

For models with buttons:

[menu]
# Enable the button menu
MenuKey=Enter
# Button assignments
UpKey=Up
DownKey=Down
LeftKey=Left
RightKey=Right

Best Practices

1. Choosing the Device

• USB is preferable: USB connections are more versatile and simpler to set up
• Serial for critical systems: Serial ports are more reliable in harsh conditions
• Avoid long USB cables: Use cables no longer than 3 meters

2. Identification in the Data Center

Use meaningful hostnames to make identification easier:

set system host-name dc1-edge-router-01
set system domain-name example.com

The display will show:

dc1-edge-router-01
.example.com

3. Documenting the Configuration

Add a system description:

set system description "Edge Router - Rack 15, Position 23"

4. Monitoring the Display Status

Create a script for periodic checks:

#!/bin/bash
# /config/scripts/check_lcd.sh

if ! pgrep -x "LCDd" > /dev/null; then
    logger "LCD daemon not running, restarting..."
    systemctl restart lcdproc
fi

Add it to the scheduler:

set system task-scheduler task check-lcd interval 5m
set system task-scheduler task check-lcd executable path /config/scripts/check_lcd.sh

5. Backing Up the Configuration

The LCD configuration is stored in /config/config.boot:

# Backup copy
sudo cp /config/config.boot /config/config.boot.backup

# Or via a VyOS command
save /config/config.boot.backup

6. Powering USB Devices

To prevent power issues:

• Use USB 3.0 ports (more power)
• Consider using a powered USB hub
• Check consumption: lsusb -v | grep MaxPower

7. Compatibility with Server Hardware

When installing into a server chassis:

• Check the display dimensions (5.25" or 3.5" bay)
• Make sure the mounting is compatible
• Check the availability of USB/Serial ports from inside the chassis

8. Testing After an Upgrade

After upgrading VyOS:

# Check the LCD configuration
show configuration commands | grep lcd

# Check the service status
systemctl status lcdproc

# Check the logs
journalctl -u lcdproc.service -n 50

Integration with Monitoring

SNMP Monitoring of the Display

You can monitor the LCD status via SNMP:

configure

# Enable SNMP
set service snmp community public authorization ro
set service snmp community public network 192.168.1.0/24

commit
save

Check from a remote host:

snmpwalk -v2c -c public <router-ip> .1.3.6.1.4.1.2021.11

Integration with System Events

You can extend the functionality to display critical events on the display through custom scripts and LCDPROC clients.

Usage Examples

Example 1: Edge Router in a Rack

configure

# Basic system configuration
set system host-name border-router-dc1-r15
set system domain-name corp.example.com
set system description "Border Router - DC1, Rack 15"

# LCD display
set system lcd device ttyUSB0
set system lcd model cfa635

# Time and NTP
set system time-zone UTC
set system ntp server 0.pool.ntp.org
set system ntp server 1.pool.ntp.org

commit
save

Example 2: Firewall with a Serial Display

configure

# System configuration
set system host-name fw-dmz-01
set system description "DMZ Firewall"

# LCD over the serial port
set system lcd device ttyS0
set system lcd model cfa633

# Interface configuration for display
set interfaces ethernet eth0 description "WAN"
set interfaces ethernet eth1 description "DMZ"
set interfaces ethernet eth2 description "LAN"

commit
save

Example 3: VPN Concentrator

configure

# System configuration
set system host-name vpn-concentrator-01
set system description "VPN Gateway - Branch Office"

# LCD display
set system lcd device ttyUSB0
set system lcd model cfa631

# The VPN configuration will be visible on the display
set vpn ipsec site-to-site peer 203.0.113.1 description "HQ"

commit
save

Model Comparison

Selection Recommendations

CFA-533:

• Budget option
• Basic functionality
• Compact devices

CFA-631:

• Mid-range segment
• More information (20 characters)
• RGB backlight for color-coded indication

CFA-633:

• Versatile choice
• Connection flexibility
• Compatible with a 5.25" bay

CFA-635:

• Professional level
• Maximum information (20x4)
• Additional functionality (fans, sensors)
• Server use

Conclusion

LCD displays in VyOS provide a convenient way to monitor system status directly on the physical device. This is especially useful for:

• Data centers: Quick identification of devices in the rack
• Remote locations: Local diagnostics without remote access
• Critical systems: Monitoring without dependence on the network
• Industrial applications: Reliable display in harsh conditions

Key Takeaways

1. Bare-metal only: The feature does not work in virtual environments
2. Limited support: Check the compatibility of your model
3. Simple configuration: Just two commands for the basic setup
4. Automatic management: LCDPROC automatically cycles through the information
5. Extensibility: The ability to configure LCDPROC manually for advanced scenarios

Next Steps

• Check the compatibility of your LCD display
• Determine the connection type (USB or Serial)
• Apply the basic configuration
• Verify that the information is displayed
• Configure the advanced parameters if needed

Additional Resources

• VyOS Documentation: https://docs.vyos.io/en/latest/configuration/system/lcd.html
• LCDPROC Project: http://lcdproc.org/
• CrystalFontz Support: https://www.crystalfontz.com/support/
• VyOS Community: https://forum.vyos.io/
• VyOS Bug Tracker: https://vyos.dev/

Note: This documentation is current for VyOS 1.4 (Sagitta) and VyOS 1.5 (Circinus). The LCD display functionality is stable and does not change significantly between versions.