# LCD - LCD Display for Devices

> Configure LCD displays on VyOS hardware appliances with LCDPROC - show system metrics, interface status, and routing information right on the device

Source: https://opennix.org/en/docs/vyos/system/vyos-lcd/


## 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

**Physical hardware only**: The LCD display functionality is intended exclusively for bare-metal VyOS installations on physical hardware. This feature does not apply to virtual machines or cloud deployments.

**Limited model support**: VyOS supports a limited set of LCD displays out of the box. If your model is not supported, file a request to add the functionality through the VyOS issue tracker.

## 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:**

```bash
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:**

```bash
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):**

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

**Configuration (Serial):**

```bash
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:**

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

### Matrix Orbital

**Extended support**: Although the official VyOS documentation only mentions CrystalFontz models, LCDPROC supports a wide range of Matrix Orbital displays. Using these models may require manual LCDPROC configuration or a request to add support.

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:

```bash
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:

```bash
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:

```bash
lsusb
```

Example output:

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

Verify that the device was created:

```bash
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:

```bash
dmesg | grep ttyS
```

### Selecting the Display Model

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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
show configuration commands | grep lcd
```

Output:

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

### Checking LCDPROC Status

Check the running LCDd process:

```bash
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:

```bash
journalctl -u lcdproc.service
```

Or:

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

### Testing the Connection

Check device availability:

```bash
ls -la /dev/ttyUSB0
```

Check access permissions:

```bash
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

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
sudo vi /etc/LCDd.conf
```

Example of an extended configuration for the CFA-635:

```ini
[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:

```ini
[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:

```ini
[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:

```ini
[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:

```bash
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:

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

### 4. Monitoring the Display Status

Create a script for periodic checks:

```bash
#!/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:

```bash
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`:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
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

| Model | Size | Interface | Buttons | Backlight | Use Case |
|--------|--------|-----------|--------|-----------|------------|
| CFA-533 | 16x2 | USB | 4 | Single-color | Basic, compact |
| CFA-631 | 20x2 | USB | 6 | RGB | Advanced, color |
| CFA-633 | 16x2 | USB/Serial | 4 | Single-color | Versatile |
| CFA-635 | 20x4 | USB/Serial | 6 | RGB | Professional |

### 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.