Python 用户指南

Bianbu OS 预装了 Python 3，安装第三方 Python 库时，推荐使用正确的包管理工具，否则可能会破坏系统软件包依赖。

在 Bianbu OS中，您可以通过两种方式安装python依赖项：

使用apt安装预先配置的系统Python软件包。
创建虚拟环境，使用pip包管理工具安装软件包。

使用apt安装Python包

Bianbu OS中建议通过apt安装Python3的软件包，这些包通常是预编译的，因此安装速度更快。apt会管理所有软件包的依赖关系，安装时会包括运行该软件包所需的所有子依赖项。此外，apt确保在你卸载软件包时不会破坏其他软件包。例如，要安装Python的科学计算库scipy，请运行以下命令：

sudo apt install python3-scipy

要查找使用apt发布的 Python 包，请使用apt search 。在大多数情况下，Python 包使用前缀python3- ：例如，python3-numpy对应于Python的numpy包。

使用pip安装Python包

对pip安装的更改

在Bianbu OS 中，用户无法使用pip将库直接安装到系统版本的 Python 中。尝试在系统范围内使用pip安装 Python 包会输出类似于以下内容的错误：

➜  ~ pip install numpy
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.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

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.

通过pip安装的软件包必须安装到 Python 虚拟环境( venv ) 中。虚拟环境是一个容器，您可以在其中安全地安装第三方模块，这样它们就不会干扰您的系统Python环境。

在虚拟环境中使用 pip

要使用虚拟环境，请创建一个容器来存储Python环境。您可以通过多种方法来完成此操作，具体取决于您想要使用 Python 的方式。这里以virtualenv工具为例，首先在系统的python环境安装virtualenv：

sudo apt install python3-virtualenv

运行以下命令创建虚拟环境配置文件夹（其中的 myenv 可以替换成任何您喜欢的名字）：

virtualenv myenv

然后，执行虚拟环境配置文件夹中的bin/activate脚本，进入虚拟环境：

source myenv/bin/activate

然后您应该会看到类似于以下内容的提示：

(myenv) ➜  ~

pyenv命令提示符前缀表示当前终端会话位于名为 pyenv 虚拟环境中。要检查您是否处于虚拟环境中，请使用 pip list 查看已安装软件包的列表：

(myenv) ➜  ~ pip list
Package Version
------- -------
pip     24.0

该列表应该比系统 Python 中安装的包列表短得多。您现在可以使用pip安全地安装软件包。

为了更好的兼容性，强烈建议升级虚拟环境中的 pip 到最新版本以避免某些安装失败的问题。

pip install --upgrade pip

在虚拟环境中使用pip安装的任何软件包都只会安装到该虚拟环境中。在虚拟环境中， python或python3命令会自动使用虚拟环境下的 Python 软件包，而不是系统环境的 Python包。例如使用pip安装wheel包：

(myenv) ➜  ~ pip install wheel
Collecting wheel
  Downloading wheel-0.44.0-py3-none-any.whl.metadata (2.3 kB)
Downloading wheel-0.44.0-py3-none-any.whl (67 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 67.1/67.1 kB 27.9 kB/s eta 0:00:00
Installing collected packages: wheel
Successfully installed wheel-0.44.0

您可以通过执行python3，然后import安装的模块来验证安装是否成功。

(myenv) ➜  ~ python3
Python 3.12.3 (main, Apr 10 2024, 05:33:47) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import wheel

您可以使用sys模块来验证当前的解释器路径是否符合预期：

>>> import sys
>>> print("当前Python解释器路径:", sys.executable)
当前Python解释器路径: /home/zq-card/myenv/bin/python3

使用 exit() 退出交互式模式：

>>> exit()
(myenv) ➜  ~

要离开虚拟环境，请运行以下命令：

(myenv) ➜  ~ deactivate

Python 版本支持

Python解释器版本	支持情况
Python 3.12	长期支持
Python 3.13	长期支持

强烈建议您使用 Python 3.12 及以上版本的 Python，通常，跟随系统的 Python 版本是较好的做法。

使用pyenv管理Python 版本

pyenv 是一个非常流行的 Python 版本管理工具，它允许您轻松地安装、管理和切换多个 Python 版本。您可以根据项目需要在不同的 Python 版本之间自由切换，下面介绍如何使用 pyenv 配置多个 Python 版本。

更多信息请参考pyenv官方教程

安装pyenv

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

配置shell环境

对于Zsh：

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

对于Bash：

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

安装多个 Python 版本

您可以执行以下命令安装多个python版本，这里以3.10.0为例，也可以指定如3.8.5等 Python 版本。

pyenv install 3.10.0

安装成功会出现如下显示：

Downloading Python-3.10.0.tar.xz...
-> https://www.python.org/ftp/python/3.10.0/Python-3.10.0.tar.xz
Installing Python-3.10.0...
patching file aclocal.m4
patching file configure
Hunk #5 succeeded at 10537 (offset -15 lines).
patching file Misc/NEWS.d/next/Build/2021-10-11-16-27-38.bpo-45405.iSfdW5.rst
patching file configure
patching file configure.ac
Installed Python-3.10.0 to /home/zq/.pyenv/versions/3.10.0

输入pyenv versions 查看是否出现您安装的Python版本号：

➜  ~ pyenv versions
* system (set by /home/zq/.pyenv/version)
  3.10.0

设置全局 Python 版本

您可以使用 pyenv global 来设置默认的 Python 版本。这会影响系统中所有终端使用的 Python 版本。如果您使用的是Bash，请将.zshrc替换为.bashrc。

➜  ~ pyenv global 3.10.0
➜  ~ source ~/.zshrc
➜  ~ python3
Python 3.10.0 (default, Sep 13 2024, 20:53:06) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

再次输入 pyenv versions 您将看到python版本已经从system切换到3.10.0

➜  ~ pyenv versions
  system
* 3.10.0 (set by /home/zq/.pyenv/version)

如果您想要切回系统的python，执行 pyenv global system

➜  ~ pyenv global system
➜  ~ source ~/.zshrc
➜  ~ python3
Python 3.12.3 (main, Apr 10 2024, 05:33:47) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

当您管理多个python版本时，可以通过 pyenv versions 轻松地查看它们并切换到对应的python版本。

针对项目设置本地 Python 版本

您可以在特定目录或项目中使用不同的 Python 版本。进入项目目录（这里为myproject），然后运行 pyenv local ：

pyenv 会在该目录下生成一个名为 .python-version 的文件，指定该目录使用的 Python 版本。这样，在这个目录中工作时，Python 将默认使用 3.10.0，而不是全局版本。

➜  myproject pyenv local 3.10.0
➜  myproject ls -a
.  ..  .python-version
➜  myproject
➜  myproject python3
Python 3.10.0 (default, Sep 13 2024, 20:53:06) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
>>> exit()
➜  myproject cd ..
➜  ~ python3
Python 3.12.3 (main, Apr 10 2024, 05:33:47) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

pyenv local 设置的Python版本只在执行该命令的项目文件夹生效，当您切换到其它文件夹时，Python会默认回到系统版本。

只为当前终端设置 Python 版本

pyenv shell 命令允许您在当前的终端会话中使用指定的 Python 版本，而不影响全局设置：

➜  ~ pyenv shell 3.10.0
➜  ~ python3
Python 3.10.0 (default, Sep 13 2024, 20:53:06) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
>>> exit()
➜  ~ pyenv shell system
➜  ~ python3
Python 3.12.3 (main, Apr 10 2024, 05:33:47) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

通过这种方式，您可以快速切换版本而不用担心会对全局环境造成影响。

卸载 Python 版本

如果您不再需要某个 Python 版本，可以使用 pyenv uninstall 命令卸载它：

通过 pyenv versions 命令验证你当前使用的 Python 版本

➜  ~ pyenv uninstall 3.10.0
pyenv: remove /home/zq/.pyenv/versions/3.10.0? [y|N] y
pyenv: 3.10.0 uninstalled
➜  ~ pyenv versions
* system (set by PYENV_VERSION environment variable)

使用SpacemiT的pypi源

当您在虚拟环境中使用pip安装某些Python包时，如果这些包未提供适配于RISC-V架构的预编译whl安装文件，则pip会拉取包的源码在本地进行构建，对于底层依赖于C/C++的python包而言，这个过程通常非常耗时且容易出现编译时的依赖问题。

为了提高开发效率，SpaceMIT为 RISC-V 架构构建了一些常用的 Python 包（如 numpy），这些包已经打包为 .whl 文件，供开发者在 RISC-V 平台上使用。本教程将指导您如何在 RISC-V 环境下安装并使用这些 Python 包。

安装 PyPI 包

<package_name> 是包名。

pip install --index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple <package_name>

配置成额外源

pip默认支持一个主要的index-url，但是您可以通过配置多个extra-index-url来添加额外的源。

pip config set global.extra-index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple

可以通过pip config list查看是否成功，如果成功，可以看到以下信息。

global.extra-index-url='https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple'

如果您想上传自己编译好的whl包，请参考：如何上传Python预编译包

使用 Thonny 编辑器

我们推荐使用Thonny在 Bianbu 上编辑 Python 代码。

安装：

sudo apt install python3-tk thonny

安装完成后，终端输入 thonny 即可启动IDE界面：

thonny

默认情况下，Thonny 使用系统 Python。但是，您可以通过单击 Thonny 窗口右下角的解释器菜单切换到使用 Python 虚拟环境。可以选择已配置的环境或使用Configure interpreter…创建一个新的虚拟环境。

从 Python 使用 GPIO

我们为以下设备适配了gpiozero库

BPI-F3
MUSE Book
MUSE Pi
MUSE Card

通过该库，您可以使用Python脚本方便地控制GPIO设备，该库的完整文档位于gpiozero.readthedocs.io。

在实际的使用中，您应该特别注意GPIO引脚的编号和引脚的特殊功能，这些设备的引脚编号与树莓派的教程有所不同。

接下来以拥有26 pin的SpacemiT开发板 SpacemiT MUSE-Pi 为例引导您如何使用gpiozero库。

设备引脚布局

MUSE Pi

alt text

BPI-F3

alt text

MUSE BOOK

alt text

MUSE Card

alt text

MUSE Pi Pro

RV4B

输入表示引脚可以识别电平变化，常用于 gpiozero 读取按钮状态

输出表示引脚可以控制输出电平为0v或者3.3v，常用于gpiozero LED灯的控制

PWM表示引脚可以输出PWM波，可以用于 gpiozero 实现呼吸灯以及控制舵机等

安装并配置环境

执行以下命令安装库

主环境：

sudo apt install python3-gpiozero

虚拟环境：

pip install --index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple gpiozero

赋予权限：

sudo chmod a+rw /dev/gpiochip0

命令行执行 pinout ，您应该可以看到如下输出：

➜  pinout
Description        : spacemit k1-x MUSE-Pi board
Revision           : deb002
SoC                : M1-8571
RAM                : 7GB
Storage            : MicroSD/SSD
USB ports          : 2 (of which 2 USB3)
Ethernet ports     : 2 (1000Mbps max. speed)
Wi-fi              : True
Bluetooth          : True
Camera ports (CSI) : 1
Display ports (DSI): 1

,---------------------------------------------------------------.
| ooooooooooooo                                  J24  :
| 1oooooooooooo                                       : |Ethernet1
|     MUSE Pi                                      : |Ethernet2
,--------------------------------------------------------------.

MUSE_Pi:
   3V3  (1) (2)  5V
GPIO52  (3) (4)  5V
GPIO51  (5) (6)  GND
GPIO70  (7) (8)  GPIO47
   GND  (9) (10) GPIO48
GPIO71 (11) (12) GPIO74
GPIO72 (13) (14) GND
GPIO73 (15) (16) GPIO91
   3V3 (17) (18) GPIO92
GPIO77 (19) (20) GND
GPIO78 (21) (22) GPIO49
GPIO75 (23) (24) GPIO76
   GND (25) (26) GPIO50

LED控制

以下示例代码控制连接到 GPIO70 的 LED：

from gpiozero.pins.lgpio import LGPIOFactory
from gpiozero import Device
Device.pin_factory = LGPIOFactory(chip=0)

from gpiozero import LED
import time

pin_number = 70

led1 = LED(pin_number)

try:
    while True:
        # 设置 GPIO 70 为高电平
        led1.on()
        print(f"GPIO {pin_number} ON")
        time.sleep(1)  # 等待 1 秒

        # 设置 GPIO 70 为低电平
        led1.off()
        print(f"GPIO {pin_number} OFF")
        time.sleep(1)  # 等待 1 秒

except KeyboardInterrupt:
    # 捕捉 Ctrl+C 并退出
    print("Exiting")

led1.close()

在像 Thonny 这样的 IDE 中运行它，LED 将反复闪烁。

LED 方法包括on() 、 off() 、 toggle()和blink()。

提示

开发板上的GPIO的驱动能力通常较弱，因此不建议将LED等功率器件直接接在引脚上。建议您给GPIO引脚加上一个大于10千欧的上拉电阻，然后使用三极管或者MOS管控制LED等设备的通断。

代码解释

当您在SpacemiT的开发板上使用gpiozero库时，建议在程序的开头加上以下代码：

from gpiozero.pins.lgpio import LGPIOFactory
from gpiozero import Device
Device.pin_factory = LGPIOFactory(chip=0) # 显式指定/dev/gpiochip0

这段代码显式地指定了gpiozero库使用lgpio库作为底层的引脚工厂，lgpio是针对linux更底层的GPIO控制库，虽然gpiozero默认使用lgpio，但为了保证gpiozero在SpacemiT开发板上的正常工作，建议显示地指定引脚工厂。

当您尝试移植树莓派官方例程时，建议您在其示例代码的开头加上上述三行代码，同时注意引脚编号的差异。

您也可以使用Python lgpio库来控制GPIO设备，请参考：lgpio教程

安装Python lgpio:

sudo apt install python3-lgpio

PWMLED

以下示例代码控制连接到GPIO73的LED，并输出PWM实现一个呼吸灯：

from gpiozero.pins.lgpio import LGPIOFactory
from gpiozero import Device
Device.pin_factory = LGPIOFactory(chip=0)
from gpiozero import PWMLED
from signal import pause

pin_number = 73

print(f"PWM {pin_number}")
led = PWMLED(pin_number)

led.pulse()

pause()

通过IDE或者终端执行上述python脚本，您应该可以看到LED灯逐渐由亮变暗然后由暗变亮。

读取按钮状态

以下示例代码读取连接到 GPIO77 的按钮的状态：

from gpiozero.pins.lgpio import LGPIOFactory
from gpiozero import Device
Device.pin_factory = LGPIOFactory(chip=0)

from gpiozero import Button
from signal import pause

pin_number = 77

print(f"Button {pin_number}")

def say_hello():
    print("Hello! Pressed")

def say_goodbye():
    print("Goodbye! Released")

button = Button(pin_number)

button.when_pressed = say_hello
button.when_released = say_goodbye

pause()

通过IDE或者终端执行上述python脚本，反复按下按键，您应该可以看到如下输出：

➜  testmy python3 testbutton.py
Button 77
Hello! Pressed
Goodbye! Released
Hello! Pressed
Goodbye! Released

Python 用户指南

使用apt安装Python包​

使用pip安装Python包​

对pip安装的更改​

在虚拟环境中使用 pip​

Python 版本支持​

使用pyenv管理Python 版本​

安装pyenv​

配置shell环境​

安装多个 Python 版本​

设置全局 Python 版本​

针对项目设置本地 Python 版本​

只为当前终端设置 Python 版本​

卸载 Python 版本​

使用SpacemiT的pypi源​

使用 Thonny 编辑器​

从 Python 使用 GPIO​

设备引脚布局​

MUSE Pi​

BPI-F3​

MUSE BOOK​

MUSE Card​

MUSE Pi Pro​

RV4B​

安装并配置环境​

LED控制​

代码解释​

PWMLED​

读取按钮状态​

使用apt安装Python包

使用pip安装Python包

对pip安装的更改

在虚拟环境中使用 pip

Python 版本支持

使用pyenv管理Python 版本

安装pyenv

配置shell环境

安装多个 Python 版本

设置全局 Python 版本

针对项目设置本地 Python 版本

只为当前终端设置 Python 版本

卸载 Python 版本

使用SpacemiT的pypi源

使用 Thonny 编辑器

从 Python 使用 GPIO

设备引脚布局

MUSE Pi

BPI-F3

MUSE BOOK

MUSE Card

MUSE Pi Pro

RV4B

安装并配置环境

LED控制

代码解释

PWMLED

读取按钮状态