Skip to content

Flash guide · Method 5 of 5

Build from source with PlatformIO

~30–45 min Developer For contributors

PlatformIO is the build-from-source route: clone a firmware repository, compile it, and flash the result to your Xteink. It's for contributors and developers who want to modify firmware, build a custom fork, or run unreleased code. If you just want to install CrossPoint, use the web flasher instead. It's much faster.

What you need

  • PlatformIO IDE or PlatformIO Core (CLI) installed
  • Python 3.x
  • Git with submodule support
  • USB-C data cable and an unlocked Xteink

How to build and flash from source

  1. 1

    Clone the repository with submodules. The --recursive flag is required to pull them.

    git clone --recursive <repo-url>
  2. 2

    Open the project in VS Code with the PlatformIO extension, or build and flash in one step from the terminal.

    pio run --target upload
  3. 3

    Monitor serial output to see boot logs and debug output.

    pio device monitor

Good to know: PlatformIO is the required build path for Microreader, and it's how every fork is compiled before release.

Build uploaded? Load your books next

Once your build boots, send your library over with Calibre or OPDS, then add custom fonts, themes and sleep screens.

Load your books Make it yours: fonts & themes

Troubleshooting PlatformIO builds

Build fails with missing dependencies
Run pio pkg update to update libraries, and check you're on a compatible PlatformIO version (each project's README lists the required one).
git submodule errors
Run inside the cloned directory:git submodule update --init --recursive
Upload fails after build
Follow the same esptool port troubleshooting: check the serial port, cable, and device wake state. PlatformIO uses esptool internally.
Build takes very long
Normal on the first run, while PlatformIO downloads toolchains. Later builds are faster.

Still stuck, or hit a different error? Browse every fix in the Xteink firmware help & FAQ — searchable by problem.

Most owners don't need this

Just want to install CrossPoint?

The web flasher installs CrossPoint in about a minute. No terminal, no Python, no build tools.

Install CrossPoint with the web flasher →