问题记录：树莓派3B+ RaspberryPi OS bookworm(Debian12)系统点亮SSD1306驱动OLED屏

背景

几年前买的树莓派3B+，吃灰了一段时间，拿出来玩一玩。把系统版本更新到了目前最新的 raspios bookworm（Debian 12）版本，旧版系统上有正常点亮的SSD1306驱动128x64 oled屏和python程序，准备恢复点亮的，结果遇到各种问题，就记录总结一下。

实验环境

时间：2024年8月25日
硬件：树莓派3B+
系统版本：Raspberry Pi OS Lite(32位) bookworm

问题记录

2019年，当时参考 树莓派实验室 - 在树莓派上使用 SSD1306 OLED 屏幕 这篇教程，在低版本系统上成功点亮。

这次，操作步骤还是参考上面的那片教程，但随着Debian系统和python版本更新，有些地方不再适用了。

1、sudo pip install xxx报错：error: externally-managed-environment

具体错误输出如下：

$ sudo python -m pip install --upgrade pip setuptools wheel
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    For more information visit http://rptl.io/venv

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

解决方法： Raspberry Pi OS系统版本升级后，包管理优化的一些改变。按照提示，配置 python 虚拟环境(venv)即可，上面错误信息中就有链接，教程网上也随便能搜到，不再赘述。
为了方便以后使用，我在.bashrc最后添加了激活 python 虚拟环境的命令，这样就每次 ssh 打开的远程终端都默认是虚拟环境：
~/.bashrc:

# 省略默认内容...
source /home/xxuser/rpi-py-env/bin/activate

2、sudo apt-get install python-smbus报错：E: Package ‘python-smbus’ has no installation candidate

解决方法： 新版本系统中，通过apt安装python模块的方式不再适用，通过pip install smbus方式安装，其他python中用到的依赖库同理。

pip install smbus
# python中用到的其他依赖模块...

3、pip install执行缓慢或中断失败

**解决方法：**更换国内pip镜像源，参考配置：
/home/xxuser/.config/pip/pip.conf

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
extra-index-url=
        https://mirrors.aliyun.com/pypi/simple/
        https://pypi.mirrors.ustc.edu.cn/simple/

[install]
trusted-host=
        pypi.tuna.tsinghua.edu.cn
        mirrors.aliyun.com
        pypi.mirrors.ustc.edu.cn

4、使用Pillow库报错：ImportError: cannot import name ‘_imagingft’ from ‘PIL’

解决方法： 2024年8月这个时间，pip install Pillow默认安装的最新版本是pillow 10.4.0，pillow版本和python版本不兼容会报错，经过逐一验证，回退安装低版本Pillow-8.4.0，避免该报错，但是有其他错误，下面会说到。

pip uninstall Pillow
pip install "Pillow<9.0.0"

5、使用Pillow库报错：ImportError: The _imagingft C module is not installed

解决方法： 先卸载Pillow，安装必要的依赖库，再加上--no-cache-dir参数重新安装Pillow

pip uninstall Pillow
sudo apt-get install libjpeg-dev zlib1g-dev
pip install "Pillow<9.0.0" --no-cache-dir

点亮效果

我这里使用自制的OLED屏模块，扩展连接DHT11传感器采集温湿度。各种信息采集用到了psutil和Adafruit_DHT这两个Python库，通过pip install安装即可。
在/etc/rc.local的exit之前添加上开机启动的执行命令：

# ...
# 使用Python虚拟环境，避免找不到依赖库
/home/shenyong/rpi-py-env/bin/python /home/shenyong/stats.py

exit 0

点亮脚本记录

基于 Adafruit_Python_SSD1306/example/stats.py 进行的定制修改。

# Copyright (c) 2017 Adafruit Industries
# Author: Tony DiCola & James DeVito
#
# Permission is hereby granted, free of charge, to any person obtaining a copy