Lenovo BIOS Boot Logo Customization for NixOS

A complete NixOS module for automating Lenovo BIOS boot logo customization on supported devices.

Overview

This project provides comprehensive BIOS boot logo customization for Lenovo devices, supporting both modern UEFI-based methods and legacy BIOS tool approaches:

1. UEFI Direct Method: Uses built-in BootX64.efi logo commands (safer, no BIOS modification)
2. Legacy BIOS Method: Uses compress.efi and chgLogo.efi tools (for older devices)

Supported Devices

Primary Support

• ThinkPad X1 Yoga 4th (Product Name: 20QGS4AE00) - UEFI Direct Method
• ThinkCentre M720q (Product Name: 10TAS0FT00) - Legacy BIOS Method

Additional Support

• ThinkCentre M720t/M720s - Legacy BIOS Method
• ThinkCentre M920t/M920s/M920q - Legacy BIOS Method
• ThinkStation P330 Tiny - Legacy BIOS Method

Features

Core Functionality

• Dual Method Support: Automatic selection between UEFI Direct and Legacy BIOS methods
• UEFI Shell Automation: Automated script execution for logo updates
• Device Detection: Automatic identification of Lenovo device types and appropriate method
• ESP Integration: Proper deployment to EFI System Partition with safety features
• Legacy BIOS Tools: Python reimplementation of compress.efi and chgLogo.efi

Stylix Integration

• Automatic Logo Processing: Converts Stylix wallpapers for BIOS use
• Real-time Updates: Automatically updates BIOS logo when wallpaper changes
• Image Optimization: Resizes and compresses for BIOS constraints
• Fallback Support: Handles processing failures gracefully

Tooling

• EFI Tools Extractor: Extracts compress.efi and chgLogo.efi from Lenovo BIOS packages
• Deployment Script: Automates ESP partition setup and BootNext configuration
• Device Detection: Identifies hardware using DMI information

Quick Start

1. Get the Correct BIOS Tools

For UEFI Direct Method (ThinkPad X1 Yoga 4th)

# Download the BIOS Update (Bootable CD) ISO from Lenovo support
# Extract the required tools
./tools/extract-efi-tools.sh extract lenovo-bios.iso thinkpad-x1-yoga-4th

For Legacy BIOS Method (ThinkCentre M720q, etc.)

# Download the BIOS Update ISO for your device from Lenovo support
# Extract compress.efi and chgLogo.efi tools
./tools/extract-efi-tools.sh extract lenovo-bios.iso thinkcentre-m720q

Note: You must download the BIOS update package for your specific device model from Lenovo's official support website. The extraction tool will pull required EFI tools from the official package.

Note: You must download the BIOS update package for your specific device model from Lenovo's official support website. The extraction tool will pull the required EFI tools from the official package.

For Legacy BIOS Method (ThinkCentre M720q, etc.)

# Download the BIOS Update ISO for your device from Lenovo support
# Extract compress.efi and chgLogo.efi tools
./tools/extract-efi-tools.sh extract lenovo-bios.iso thinkcentre-m720q

2. Configure NixOS

# configuration.nix
{
  services.lenovo-bios-logo = {
    enable = true;
    model = "ThinkPad X1 Yoga 4th"; # or "ThinkCentre M720q" or "ThinkPad X250"
    logoFile = ./my-logo.jpg;
    autoUpdate = true;
    
    # Method selection (optional, auto-detects by default)
    method = "legacy"; # or "uefi" or "auto"
  };
}

# With Stylix integration (optional)
{
  services.lenovo-bios-logo = {
    enable = true;
    model = "ThinkPad X1 Yoga 4th";
    # logoFile will be automatically derived from Stylix wallpaper
  };
  
  stylix = {
    enable = true;
    image = ./my-wallpaper.jpg;
  };
}

### 3. Apply Logo Update

```bash
# Process and deploy the logo
sudo lenovo-logo-process

# Reboot to apply (for UEFI methods)
sudo systemctl reboot

# For X250 Windows method, follow the on-screen instructions in Wine

Manual Process

If you prefer manual control over the process:

UEFI Direct Method

1. Boot to UEFI Shell: The module creates a boot entry automatically
2. Automatic Execution: Script runs once and cleans up after itself
3. Reboot: System reboots with new logo

Legacy BIOS Method

1. Boot to UEFI Shell: Use the created boot entry
2. Run Commands:

   compress.efi logo.jpg
   chgLogo.efi compress.bin
   

3. Reboot: System reboots with new logo

Legacy BIOS Method

1. Boot to UEFI Shell: Use the created boot entry
2. Run Commands:

   compress.efi logo.jpg
   chgLogo.efi compress.bin
   

3. Reboot: System reboots with new logo

File Structure

/boot/efi/EFI/lenovo-logo/
├── lenovo-boot-tool.efi       # Renamed BootX64.efi (UEFI method)
├── compress.efi               # Logo compression tool (Legacy method)
├── chgLogo.efi               # Logo injection tool (Legacy method)
├── logo-startup.nsh          # EFI startup script
├── logo.nsh                  # Logo replacement script
├── logo.efi                  # Processed custom logo
└── pending-logo.flag          # Auto-apply trigger

/var/lib/lenovo-bios-logo/
└── uefi-package/             # Generated update package

Logo Requirements

UEFI Direct Method

• Formats: JPG, BMP, GIF
• Size: ≤60KB after compression
• Dimensions: ≤40% of LCD resolution (≤768x432 for 1920x1080)

Legacy BIOS Method

• Formats: JPG, BMP, GIF
• Size: <20KB recommended (compresses to ~60KB max)
• Dimensions: Recommended 1024x768 or smaller

Legacy BIOS Method

• Formats: JPG, BMP, GIF
• Size: <20KB recommended (compresses to ~60KB max)
• Dimensions: Recommended 1024x768 or smaller

General Requirements

• Location: Must be on FAT32-formatted ESP partition
• Processing: Automatic resizing and optimization provided

Security Notes

⚠️ BIOS Modification Warning: This process modifies your BIOS firmware. While extensively tested, BIOS modifications carry inherent risks. Ensure you:

1. Backup: Have BIOS recovery method available
2. Power: Use stable power during update
3. Compatibility: Use tools extracted for your specific device model
4. Testing: Test in non-production environment first

Troubleshooting

Common Issues

"compress.efi not found":

• Extract tools from your device's specific BIOS update package
• Ensure files are in EFI/LenovoLogo/ on ESP

"Compression failed":

• Check logo file size (< 20KB)
• Verify logo format (JPG/BMP/GIF)
• Ensure logo file is not corrupted

"Logo injection failed":

• Verify compress.bin was created successfully
• Check BIOS supports logo modification
• Ensure sufficient BIOS space available

Boot entry not created":

• Check ESP mount point in deployment script
• Verify efibootmgr permissions
• Ensure disk/partition detection is correct

Recovery

If BIOS update fails:

1. Reboot: System should revert to previous state
2. BIOS Recovery: Use Lenovo's BIOS recovery method
3. Re-extract: Get fresh EFI tools from BIOS package
4. Retry: Attempt logo update with smaller/simpler logo

Project Structure

modules/
└── lenovo-bios-logo.nix      # Main NixOS module

tools/
├── lenovo-bios-logo.py       # Main CLI interface
├── hardware-detector.py     # Device detection
├── logo-processor.py         # Logo processing
├── uefi-script-generator.py  # UEFI script generation
├── extract-efi-tools.sh      # EFI tools extraction
└── identify-device.py        # Device identification

docs/
├── uefi-direct-logo-method.md      # UEFI method documentation
├── legacy-logo-method.md           # Legacy method documentation
└── uefi-direct-safe-implementation.md # Safety analysis

fetchers/
└── lenovo-api.nix            # Lenovo API fetcher

Usage Examples

# Detect your device
lenovo-logo-detect

# Process a logo manually
lenovo-logo-process ./my-logo.jpg

# Extract EFI tools from BIOS package
./tools/extract-efi-tools.sh extract bios-update.iso thinkpad-x1-yoga-4th

# Test device detection
python3 tools/identify-device.py identify

# With Nix flakes
nix run .#lenovo-bios-logo -- detect
nix run .#lenovo-bios-logo -- process ./logo.jpg -m "ThinkPad X1 Yoga 4th"

Contributing

We welcome contributions! Please:

1. Device Support: Add new device signatures to tools/identify-device.py
2. Testing: Test on actual hardware before submitting PRs
3. Documentation: Update documentation for new features
4. Security: Review BIOS modification safety carefully
5. Issues: Report bugs with device model and error details

Adding New Device Support

1. Add device signature to tools/identify-device.py
2. Test logo customization on the actual device
3. Update documentation with method requirements
4. Submit PR with device details and testing results

License

MIT License - See LICENSE file for details.

Security Considerations

⚠️ BIOS Modification Warning: This process modifies your BIOS firmware. While extensively tested, BIOS modifications carry inherent risks. Ensure you:

1. Backup: Have BIOS recovery method available
2. Power: Use stable power during update
3. Compatibility: Use tools extracted for your specific device model
4. Testing: Test in non-production environment first

References

• UEFI Shell Specification
• Lenovo Support
• ThinkWiki
• NixOS Module System

---

Note: This implementation supports both modern UEFI-based methods and legacy BIOS modification approaches. The module automatically selects the appropriate method based on your device type.