How to Build Custom Firmware for Xteink X4 with Biscuit on Linux 2025

Introduction

The Xteink X4 is a budget e-ink reader ($70) that becomes significantly more powerful when running Biscuit custom firmware. Instead of just reading ebooks, you get a multifunctional wireless device with passive/active network scanning, crypto tools, games, and system monitoring—all on a device that runs for days on a single charge.

This guide walks you through building Biscuit from source on Linux, configuring the ESP32-C3 toolchain, and flashing the firmware to your device. We'll assume you have basic familiarity with the command line and USB serial tools.

Prerequisites

Before starting, gather these requirements:

• Xteink X4 device with USB-C cable
• Linux system (Ubuntu 22.04+ tested; Debian, Fedora also work)
• Python 3.8+ installed
• Git for cloning the repository
• ~500MB free disk space for the ESP32 toolchain
• USB serial driver (usually auto-detected on modern Linux)

Verify your Linux system recognizes the device:

lsusb | grep -i "esp32\|usb"

Step 1: Install the ESP32 Build Toolchain

The Biscuit project targets the ESP32-C3 (RISC-V architecture, 160MHz). You need the Espressif IDF toolchain:

# Install system dependencies
sudo apt update
sudo apt install -y git wget flex bison gperf python3 python3-pip cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

# Create a directory for ESP tools
mkdir -p ~/esp
cd ~/esp

# Clone ESP-IDF (v5.0+ supports Biscuit)
git clone --depth 1 --branch v5.1.2 https://github.com/espressif/esp-idf.git
cd esp-idf

# Run the installation script
./install.sh esp32c3

# Source the environment
source ~/esp/esp-idf/export.sh

Add this to your ~/.bashrc or ~/.zshrc so the toolchain is available in future sessions:

alias get_idf='source ~/esp/esp-idf/export.sh'

Step 2: Clone Biscuit Repository

cd ~
git clone https://github.com/yattsu/biscuit.git
cd biscuit

# Verify you're on the main branch
git status

Biscuit is forked from CrossPoint Reader, so it inherits core e-reader functionality. Check the README for any branch-specific build instructions.

Step 3: Configure Build Parameters

Create a build configuration file (most projects use sdkconfig):

# Set the target to ESP32-C3
idf.py set-target esp32c3

# Open menuconfig to verify hardware settings
idf.py menuconfig

In menuconfig, verify these settings:

• Component Config → ESP32C3-Specific → CPU frequency: 160 MHz
• Serial Flasher Config → Default serial port: /dev/ttyUSB0 (or your device's port)
• Partition Table: Ensure it matches the 16MB flash layout

Save and exit (Q → Y).

Step 4: Build the Firmware

idf.py build

This compiles the firmware, links the binary, and generates the image. Expect 3-5 minutes on a typical machine. You should see output like:

[100%] Built target biscuit_app.elf
Building apps from binaries in ~/biscuit/build/bin/
--- Building app binary ---

The compiled firmware appears in build/biscuit.bin.

Step 5: Flash to Device

Important: Plug in your Xteink X4 via USB-C before running flash commands.

Check USB Device Detection

ls -l /dev/ttyUSB*
# or
dmesg | tail -20  # Check kernel messages for device attachment

If you see /dev/ttyUSB0, proceed. If nothing appears, install the CH340 driver (common on these devices):

sudo apt install ch340-dkms
sudo modprobe ch340

Flash the Firmware

idf.py -p /dev/ttyUSB0 -b 460800 flash

The flasher will:

1. Detect the chip (should identify as ESP32-C3)
2. Erase the flash (takes ~10 seconds)
3. Write the firmware (takes ~15-30 seconds)
4. Verify the image

Expected output:

Erase flash : 100% |████████| (time taken)
Writing at 0x00000000... (100%)
Verified 262144 bytes of data
Hard resetting via RTS pin...

Step 6: Monitor Serial Output (Optional)

Watch the device boot and verify firmware is running:

idf.py -p /dev/ttyUSB0 monitor

You'll see boot logs from the ESP32. Press Ctrl+A → K to exit.

Troubleshooting

"Device Not Found" on Flash

• Verify USB cable is data-capable (not power-only)
• Check device is in bootloader mode (some devices auto-enter; others require button press)
• Ensure user has USB permissions: sudo usermod -a -G dialout $USER (then log out/in)

Timeout During Write

If flashing hangs at "Writing at 0x...", the serial connection is unstable:

# Retry with lower baud rate
idf.py -p /dev/ttyUSB0 -b 115200 flash

Permission Denied on /dev/ttyUSB0

sudo chmod 666 /dev/ttyUSB0
# OR add user to dialout group (persistent)
sudo usermod -a -G dialout $USER

"Unexpected response" / CRC Errors

Indicates flash corruption. Perform a full erase first:

idf.py -p /dev/ttyUSB0 erase-flash
idf.py -p /dev/ttyUSB0 -b 460800 flash

What to Expect After Flashing

Once flashing completes, your device will boot into the Biscuit home screen—a tile-based dashboard showing:

• Recon: Passive WiFi/BLE scanning (no transmission)
• Offense: Active wireless testing and profiling
• Defense: Stealth and hardening tools
• Comms: Messaging and exchange utilities
• Tools: Crypto, network, and productivity apps
• Games: Entertainment
• Reader: Original ebook reading with OPDS support
• Settings: Device configuration and file management

Navigate using the seven physical buttons. Battery should still provide 5-7 days runtime.

Building Custom Apps for Biscuit

Once the base firmware runs, you can extend Biscuit by adding custom apps. The project structure uses the IDF component system. Create new apps in the components/ directory:

mkdir -p components/my_app
# Add your source in components/my_app/
idf.py build  # Rebuilds with your new component

Next Steps

• Read docs/ARCHITECTURE.md in the Biscuit repo for app structure
• Explore existing Recon and Offense apps to understand the UI framework
• Review the CrossPoint Reader docs for ebook format support
• Check the MicroSD card requirements for database files (OUI vendor lookup, etc.)

Summary

Building Biscuit on Linux requires the ESP-IDF toolchain, a USB connection, and patience during the first compile. Once flashing succeeds, you've transformed a $70 e-reader into a portable wireless security and utility device without losing ebook functionality. The modular architecture makes it straightforward to add custom tools tailored to your needs.