Title: Piano HAT install fails on Debian Bookworm (aarch64) — PEP 668 + Remote I/O errors on CAP1xxx

Support
1

Hi Pimoroni support — WoozyFace here. I just received a Piano HAT and I’m stuck during installation. I suspect either the installer/script is out of date for my distro or there’s a hardware/driver mismatch. Below I describe the exact environment, the commands I ran, the important outputs/errors, and what I’ve already tried. Any pointers appreciated — happy to provide additional logs if wanted.

Environment

  • Board / OS: Debian Bookworm (aarch64), kernel 6.12.47+rpt-rpi-v8 PI 3B+

  • Filesystem: overlayroot (read-only boot/overlay present on this system)

  • Python: system Python 3.11, pip available; I created a virtualenv for testing

What I tried (commands & flow)

  1. Ran the official installer:
curl https://get.pimoroni.com/pianohat | bash

Installer output shows the common PEP 668 error:

Installing Piano HAT library for Python 3...

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install python3-xyz ...
...
Python 3 library install failed!
  1. Tried the venv approach (created venv with system site-packages to allow python3-smbus usage):
python3 -m venv --system-site-packages ~/pimoroni-venv
. ~/pimoroni-venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install PianoHAT cap1xxx

Pip reports PianoHAT and cap1xxx are installed (from distro site-packages or PyPI), RPi.GPIO present.

  1. Ensured system packages:
sudo apt update
sudo apt install -y python3-smbus python3-rpi.gpio i2c-tools
sudo modprobe i2c-dev
  1. I2C device detection & probing:
ls -l /dev/i2c*
# -> /dev/i2c-2 exists

i2cdetect -l
# -> shows i2c-2 (bcm2835)

sudo i2cdetect -y 2
# -> returned addresses on bus 2 (sample output):
# 30: .. 37 .. 3a .. 4a 4b .. 50 .. 54 .. etc
  1. Ran Python probe script (uses smbus on bus 2). Output for addresses 0x28 and 0x2b:
== addr 0x28 ==
read_byte: ERR: [Errno 5] Input/output error
read_byte_data reg 0x00 -> ERR: [Errno 121] Remote I/O error
...
read_i2c_block_data 0x00 len8 -> ERR: [Errno 5] Input/output error

== addr 0x2b ==
read_byte: ERR: [Errno 5] Input/output error
read_byte_data reg 0x00 -> ERR: [Errno 121] Remote I/O error
...
  1. Running the library test (monkeypatching smbus.SMBus to use bus 2) fails with:
Traceback (most recent call last):
  ...
  File "/usr/lib/python3/dist-packages/cap1xxx.py", line 494, in _read_byte
    return self.i2c.read_byte_data(self.i2c_addr, register)
OSError: [Errno 121] Remote I/O error
  1. Kernel logs show repeated undervoltage events:
[ ... ] hwmon hwmon1: Undervoltage detected!
[ ... ] hwmon hwmon1: Voltage normalised

Observations / What’s suspicious

  • Installer fails because pip tries to install system-wide on a distro that enforces externally-managed-environment (PEP 668). Workaround: use a venv. I used --system-site-packages so the venv can see python3-smbus.

  • /dev/i2c-2 is present (not /dev/i2c-1). I forced the code to use bus 2; the HAT hardware appears on bus 2 on this machine.

  • Although i2cdetect lists several addresses on bus 2, direct reads from the CAP1xxx addresses (0x28, 0x2b) produce Remote I/O error. i2cdump also fails with Read failed.

  • Kernel shows undervoltage events repeatedly; that can cause I²C instability and failed communication.

  • After reseating HAT and reloading i2c-dev, the errors persist (same remote I/O behavior and read failures).

Files / scripts I used

  • piano_probe2.py — small smbus probe trying read_byte, read_byte_data and read_i2c_block_data for addresses [0x28, 0x2b]

  • piano_test_live.py — monkeypatches smbus.SMBus to use bus 2 and then imports pianohat and calls pianohat.auto_leds(False) to trigger CAP1xxx init.

Questions / Requests for Pimoroni support

  1. Are 0x28 and 0x2b the expected CAP1xxx addresses for Piano HAT? (I expected CAP1xxx on those, but reads fail.)

  2. Does the cap1xxx or pianohat library assume bus 1 by default? I’ve forced bus 2 with a monkeypatch and imports succeed, but register reads fail. Is there any device-tree overlay or init sequence required that the install script normally sets up on Raspberry Pi OS and that may be missing on a Debian Bookworm aarch64 image?

  3. Could the CAP1xxx chips be sensitive to undervoltage? My kernel log shows repeated undervoltage events — could that cause the Remote I/O errors I’m seeing? (I can confirm power/adapter and try another cable/PSU.)

  4. Is there any known issue with the Pimoroni installer and systems that enforce PEP 668 (system-managed Python)? The installer suggests venv usage; would you consider updating the installer to detect PEP 668 and auto-offer a venv-based install or provide clearer instructions for Debian Bookworm / aarch64 users?

  5. Are there low-level registers that are intentionally unreadable on CAP1xxx (causing i2cget to fail)? If so, which registers are safe to read to confirm the device is responsive? (I tried 0x00 and 0xFD and got I/O errors.)

  6. Any device-tree overlays / boot config lines required for Piano HAT on Debian (non-RaspberryPI OS)? If the Raspbian installer normally writes overlays to /boot/config.txt, that’s problematic on my overlayroot read-only setup — what minimal overlays are required?

Things I’m happy to try next (if you advise)

  • Confirm exact expected I2C addresses and example registers that should respond (so I can test safely).

  • Try with a different power supply and cable (I suspect undervoltage is significant).

  • Provide dmesg output, i2cdetect -y 2 output, and the Python probe script logs (I have them and can paste more if helpful).

  • Try a fresh Raspberry Pi OS image to see if the issue is distro-related (I can do that but would prefer a pointer first).

Short reproduction steps (what you can run to reproduce my state)

# on Debian Bookworm aarch64 (kernel 6.12.47+rpt-rpi-v8)
curl https://get.pimoroni.com/pianohat | bash   # shows PEP668 error when pip tries to install system packages

# create venv and install libs:
python3 -m venv --system-site-packages ~/pimoroni-venv
. ~/pimoroni-venv/bin/activate
pip install PianoHAT cap1xxx
sudo apt install -y python3-smbus python3-rpi.gpio i2c-tools
sudo modprobe i2c-dev
i2cdetect -y 2   # shows devices on bus 2
# run probe script that tries to read registers -> get Remote I/O errors

Attachments / Logs I can paste if helpful

  • dmesg output (shows undervoltage events)

  • i2cdetect -y 2 output (shows several addresses on bus 2)

  • piano_probe2.py output (shows Remote I/O error on 0x28 / 0x2b)

  • piano_test_live.py traceback (shows OSError 121 during cap1xxx init)

Thanks in advance — please let me know the minimal next checks I should run, or whether you expect the HAT to require any specific device-tree overlay or boot config on Debian Bookworm aarch64. If you want me to try a different power supply first, tell me what voltage/current you recommend.

— WoozyFace (on behalf of a test bench in the Netherlands)

2

This isn’t a solution per say, more of a work around, but I’ll post it anyway.
Seeing as this is a Pi 3B+, you don’t have to use Bookworm. You could go back a version or two and not have to use the virtual environment. The installer may work then. Worth a try especially if you have a spare SD card on hand.
Index of /raspbian/images

3

Aah yeah, the quick and dirty route. We all love doing that, but sure i will give it a try whenever i’ve got the time for it.

Thanks for sharing, i will keep you updated!

In the mean-time, maybe the script should be updated or reworked or the instructions by the manufacturer themselves since this is now officially still sold via Farnell and now looks like a scam or DOA product, they must have been noticing a increase of RMA cases?!…

Just Saying…

4

It is a pity that this is true for many of the Pimoroni Hats. They are great on the hardware side, but can’t keep up with maintaining software. Especially the (late, from PiOS perspective) switch to python-venvs has hit them hard.

It does not help that the community is small and that pull-requests in the Pimoroni-repos are not handled in a timely manner (I have a PR that is waiting since almost three years for an initial response).

5

We’ve not sold Piano HAT through our store for several years - surprised to hear that Farnell still have stock :)

Please could you open up an issue on the Piano HAT repo to let our software team know that you’re still using the product if updating the installer to work with Bookworm is something that you’d like them to take a look at?

(But as @alphanumeric says, flashing an older version of Pi OS is probably the easiest/quickest way to get it working in the meantime).

1 Like
6

Thanks for the replies — and interesting to hear that Piano HAT hasn’t been sold through the Pimoroni store for a few years.

That said, if Farnell does still have inventory, maybe there’s an opportunity for Pimoroni and the distributor to coordinate — for example a limited run, returns/buy-back, or a small support batch for existing users. It sounds odd, but I can imagine scenarios where a supplier still has units and the manufacturer could help move or support them; worth a thought.

For context on why I still care: I use the Piano HAT as a pocket-sized MIDI board — it’s perfect when I want a compact physical keyboard instead of using a touchscreen (I use an iPad a or my PiPad lot for quick projects O.T.G. but hate the touch piano controls). A Pi in my pocket. (no, i am not french but try to read this out loud with either a french or Italian accent, are you in public space? Now that’s a challenge for you 🤣 go 🧽🫧 clean up yourself) with full-octave set of something you can actually feel with your fingers is exactly what I need. There are larger, bulkier alternatives, but the size and simplicity of the Piano HAT are what make it useful for quick sketches and jams.

I’m a senior network & systems engineer and I love to tinker, but I also like things to be properly maintained and up to date. I’d be very happy to:

  • open a GitHub issue with full logs and repro steps (already preparing one),

  • test fixes (on Bookworm or Raspberry Pi OS), or

  • help validate any installer changes you make.

If the team is open to it, I can post the logs and a clear test-case on the Piano-HAT repo so your software team can reproduce the PEP 668 / CAP1xxx behaviour I’m seeing. Thanks for looking into this — I appreciate any guidance or a direction for a short-term workaround.

— WoozyFace

Done cooking on GitHub: HUMAN TITLE: This Product Is Not Obsolete Still Love And Needs To Be Loved (Again) Please 🥹! - ENGINEERS TITLE: Installer fails on Debian Bookworm (aarch64) — PEP 668 + CAP1xxx Remote I/O errors on /dev/i2c-2 · Issue #25 · pimoroni/Piano-HAT · GitHub ! now it’s 6 pm over here and also over there, time for supper haha!

1 Like
7

My suggestion: connect the Piano HAT to a Pico(2), put CircuitPython on the device and enjoy the great MIDI-support that CP provides. Your bonus: basically no boot-time and much lower current draw. You could run the system from a LiPo making an even more compact solution to carry around.

What you need: either some wires (the Piano HAT basically uses I2C and power + some digital-IOs) or a Pico-Pi adapter, e.g. Pico to Pi HAT - The Pi Hut

8

That Pico to Pi HAT isn’t so well designed, looking at the way the Pico board would need mounting and the orientation of the expansion headers. The headers would surely need boosting to allow a HAT to fit above the Pico, or they would need breaking out using something like the Mini Black HAT Hack3r.

The illustrative pictures with the headers soldered on gives a sense of the challenges. I could imagine that a version where the HAT hangs off the side might be more practical, and then we get into products resembling Pimoroni’s Pico base boards.

9

I can’t follow your argumentation. I don’t use this specific adapter because I designed my own, but they are mechanically very similar. I never had any problems mounting any of my HATs on these adapters, even without booster headers as long as I solder the Pico directly to the adapter-board.

The Piano HAT will certainly not have any problems, since it does not have any components on the bottom side.

10

I was mostly thinking of the scenario where the Pico is mounted on the headers provided with the board. One you add the height of those headers, the Pico will be towering over the HAT expansion headers. This is shown in the later pictures for the product.

11

That’s why they provide a booster header for the HATs with the -H variant. I have exactly this kind of setup here for testing. No need to worry. Not ideal because of the extra height. That is why I prefer to solder the Pico either flat to the adapter or I add pin headers to the Pico and then solder them to the adapter. The latter setup allows access to all Pico-pins from below. The additional height from the black spacers of the pin-headers is not critical.

2 Likes
12

I also do that when I can. It makes for a nice clean slim setup. =)