CircuitPython on the Xteink X4 eReader

CircuitPython on a pocket eReader

by Liz Clark

published March 19, 2026, last edited May 22, 2026

posted in Hacks CircuitPython Internet of Things - IOT LCDs & Displays/ eInk / ePaper Programming/ MicroPython / CircuitPython

Save Download

New

Intermediate

Project guide

CircuitPython Helper Library

As mentioned on the Pinouts page, six of the seven buttons on the Xteink X4 are connected to a resistor ladder read by two analog pins. The Xteink X4 helper library makes reading those buttons a lot easier. There's also a few helper functions for reading the battery voltage.

Library Usage with Web Workflow

To use with CircuitPython, you need to first install the Xteink X4 library into the lib folder on the Xteink X4. Then you need to update code.py with the example script.

Thankfully, we can do this in one go. In the example below, click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file.

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: Copyright (c) 2026 Liz Clark for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""
Xteink X4 Helper Demo

Uses button inputs and battery monitor
"""

from adafruit_xteink_x4 import BatteryMonitor, InputManager

battery = BatteryMonitor()
buttons = InputManager()

print(f"Battery: {battery.percentage}% ({battery.volts:.2f}V)")
print()

while True:
    buttons.update()

    if buttons.any_pressed:
        for i in range(7):
            if buttons.was_pressed(i):
                print(f"Pressed:  {buttons.button_name(i)}")

    if buttons.any_released:
        for i in range(7):
            if buttons.was_released(i):
                held = buttons.held_time
                print(f"Released: {buttons.button_name(i)} (held {held:.2f}s)")
                print(f"Battery: {battery.percentage}% ({battery.volts:.2f}V)")

# SPDX-FileCopyrightText: Copyright (c) 2026 Liz Clark for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""
Xteink X4 Helper Demo

Uses button inputs and battery monitor
"""

from adafruit_xteink_x4 import BatteryMonitor, InputManager

battery = BatteryMonitor()
buttons = InputManager()

print(f"Battery: {battery.percentage}% ({battery.volts:.2f}V)")
print()

while True:
    buttons.update()

    if buttons.any_pressed:
        for i in range(7):
            if buttons.was_pressed(i):
                print(f"Pressed:  {buttons.button_name(i)}")

    if buttons.any_released:
        for i in range(7):
            if buttons.was_released(i):
                held = buttons.held_time
                print(f"Released: {buttons.button_name(i)} (held {held:.2f}s)")
                print(f"Battery: {battery.percentage}% ({battery.volts:.2f}V)")

View on GitHub

Extract the contents of the zip file. You'll see the following contents in the extracted folder:

Upload the Library

In the Web Workflow Code Editor, click the Open button.

This opens the file browser. Click the Upload button.

Click on Upload Folders.

Select the /lib folder in the Project Bundle and click Upload.

You'll be asked to confirm the folder upload. Click Upload to continue.

After the upload finishes, you'll be able to see the library in the /lib folder on the device.

Upload code.py

Next, you'll upload the code.py file to the Xteink X4. Click the Upload button and then Upload Files.

Select the code.py file from the Project Bundle and then click Open.

Run the Code

To run the new code.py file, click Save + Run.

After running the code, you'll see the battery voltage print out before going into the loop. In the loop, the button you press will print out to the serial monitor along with the battery voltage. You'll see the CircuitPython REPL on the eInk display.