Skip to main content

2.4 Python Usage Guide

Last Version: 10/09/2025

This guide covers the essentials of using Python on the Bianbu ROS system.

Common Commands Summary

FunctionCommand
Install virtual environment toolssudo apt install python3-venv python3-pip
Create virtual environmentpython3 -m venv myenv
Activate virtual environmentsource myenv/bin/activate
Upgrade pippip install --upgrade pip
Set PyPI sourcepip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.extra-index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple
Deactivate virtual environmentdeactivate

Using Python in the System Environment

The Bianbu ROS system includes a default Python interpreter. You can access it by typing python3 in the terminal:

Exit the interpreter with Ctrl + D.

  • Check Python Location Use which python3 to find the Python interpreter’s path:

    bianbu@bianbu:~$ which python3

    # Output example
    /usr/bin/python3
  • Install Packages in the System Environment Use apt (not pip) to manage Python packages in the system environment. Example: to install the scientific computing library scipy:

    sudo apt install python3-scipy

    To find available Python packages, use:

    apt search python3-

    Example: The numpy package is listed as python3-numpy.

    Note: Do not use pip to install packages in the system environment to avoid conflicts.

Using a Virtual Environment

To use a virtual environment, create a container to hold the Python environment. There are several ways to do this depending on how you plan to use Python. Here, we use the venv tool as an example.

  1. Install venv in the system Python environment:

    sudo apt install python3-venv python3-pip
  2. Run the following command to create a folder for your virtual environment (replace myenv with any name you prefer):

    python3 -m venv myenv
  3. Execute the bin/activate script inside the virtual environment folder to enter the virtual environment:

    source myenv/bin/activate

    Your terminal prompt changes to indicate the active environment:

    (myenv) ➜  ~

    The myenv prefix in the command prompt indicates that the current terminal session is inside the virtual environment named myenv.

  4. To verify the virtual environment by using pip list to view the list of installed packages:

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

    The list should be shorter than the packages installed in the system Python.

  5. You can now safely install Python packages using pip. Here are the key points to remember:

    • Packages installed with pip will only exist in your current virtual environment. Your system-wide Python environment will not be affected at all

    • When your virtual environment is activated:

      • The python and python3 commands will automatically use the virtual environment's interpreter
      • All imported packages will come from the virtual environment, not the system

    To ensure proper use of pip, upgrade pip to the lastest version:

    pip install --upgrade pip

    Example: install the wheel package using pip:

    (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

    Verify installation in Python by running python3 and then importing the installed module:

    (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
  6. Verify Interpreter Path by using the sys module to check that the current interpreter path matches the expected virtual environment:

    >>> import sys
    >>> print("Current Python interpreter path:", sys.executable)
    Current Python interpreter path: /home/zq-card/myenv/bin/python3
  7. Use exit() to quit the interactive mode:

    >>> exit()
    (myenv) ➜ ~
  8. To exit the virtual environment, run the following command:

    (myenv) ➜  ~ deactivate

Configuring SpacemiT PyPI Source

When installing Python packages in a virtual environment using pip, you may encounter a problem on RISC-V platforms:

  • If no precompiled .whl (wheel) file is available, pip will download the source code and try to build it locally.
  • Packages that include C/C++ code can take a long time to compile and may fail if system dependencies are missing.

To improve efficiency and avoid build errors, SpacemiT provides precompiled wheel files for common Python packages (for example, numpy). This section explains how to configure pip to use SpacemiT’s package source.

  1. Configure as an extra source

    By default, pip supports one main index-url (the main package source). You can add an additional source using extra-index-url.

    Run the following commands to add the SpacemiT source as an additional location to search for packages:

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

    You can verify the configuration with

    pip config list

    If successful, you will see output similar to:

    global.extra-index-url='https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple'
    global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
  2. Install PyPI Packages

    To install a package from the SpacemiT source, use the following command:

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

    Replace <package_name> with the desired package.

Using ONNX Runtime

Please make sure you have completed the previous sections before proceeding.

This section shows how to set up onnxruntime with SpacemiT’s custom execution provider (spacemit_ort), verify the installation, and run a sample inference demo.

  1. Create a Virtual Environment

    python3 -m venv ort_env

    Activate it:

    source ort_env/bin/activate
  2. Install spacemit_ort

    pip install spacemit_ort

    If successful, the terminal will show an installation summary similar to this:

  3. Verify the Installation

    • Launch Python inside the virtual environment with the following commands:

      python
      >>> import onnxruntime as ort
      >>> import spacemit_ort
      >>> available_providers = ort.get_available_providers()
      >>> print(available_providers)
      ['SpaceMITExecutionProvider', 'CPUExecutionProvider']

      If everything is installed correctly, the output should include: ['SpaceMITExecutionProvider', 'CPUExecutionProvider']

    • Exit Python with Ctrl + D.

  4. Installing Demo Dependencies

    source ort_env/bin/activate
    pip install opencv-python pillow matplotlib onnx
  5. Download Models, Labels, and Images

    SpacemiT provide quantized open-source models, which can be downloaded from ModelZoo.

    In theory, ONNX models can also be used for inference, but their performance may be slightly lower than our quantized versions.

    Download and extract the model and related files:

    wget https://archive.spacemit.com/spacemit-ai/ModelZoo/classification.tar.gz
    tar -zxf classification.tar.gz
    wget -P classification https://archive.spacemit.com/spacemit-ai/ModelZoo/classification/kitten.jpg
    wget -P classification https://archive.spacemit.com/spacemit-ai/ModelZoo/classification/synset.txt
  6. Run the Demo Script

    • Create a file called demo.py:
    vim demo.py
    • Paste the following code into it:
    import onnx
    import numpy as np
    import onnxruntime as ort
    import spacemit_ort
    from PIL import Image
    import cv2
    import matplotlib.pyplot as plt
    import time

    # Image loading
    def get_image(path, show=False):
    with Image.open(path) as img:
    img = np.array(img.convert('RGB'))
    if show:
    plt.imshow(img)
    plt.axis('off')
    return img

    # Image Preprocessing
    # Preprocess the input image for inference -> scale to 0~1, resize to 256x256, take a 224x224 center crop, normalize the image, transpose to NCHW format, convert to float32, and add a batch dimension.
    def preprocess(img):
    img = img / 255.
    img = cv2.resize(img, (256, 256))
    h, w = img.shape[0], img.shape[1]
    y0 = (h - 224) // 2
    x0 = (w - 224) // 2
    img = img[y0 : y0+224, x0 : x0+224, :]
    img = (img - [0.485, 0.456, 0.406]) / [0.229, 0.224, 0.225]
    img = np.transpose(img, axes=[2, 0, 1])
    img = img.astype(np.float32)
    img = np.expand_dims(img, axis=0)
    return img

    # Prediction
    def predict(path):
    img = get_image(path, show=True)
    img = preprocess(img)
    ort_inputs = {session.get_inputs()[0].name: img}
    start = time.time()
    preds = session.run(None, ort_inputs)[0]
    end = time.time()
    preds = np.squeeze(preds)
    a = np.argsort(preds)[::-1]
    print('time=%.2fms; class=%s; probability=%f' % (round((end-start) * 1000, 2), labels[a[0]], preds[a[0]]))

    # Load model, labels, and run inference
    with open('classification/synset.txt', 'r') as f:
    labels = [l.rstrip() for l in f]

    # Set the number of inference threads
    session_options = ort.SessionOptions()
    session_options.intra_op_num_threads = 2

    # IMPORTANT: Specified SpaceMITExecutionProvider providers
    session = ort.InferenceSession('classification/resnet50/resnet50.q.onnx', sess_options=session_options, providers=["SpaceMITExecutionProvider"])

    img_path = 'classification/kitten.jpg'
    predict(img_path)
  • Run the Demo

    source ort_env/bin/activate
    python demo.py

    Expected output (your numbers may vary slightly):

    time=95.15ms; class=n02123045 tabby, tabby cat; probability=13.498201

API Reference

For more information about available APIs, see the official API Overview.

Using gpiozero

The Python gpiozero library can be used to control the GPIO pins on the board, enabling basic input/output, PWM, and other functions.

  1. Install system dependencies

    Run this command to install gpiozero with the necessary system permissions for GPIO access:

    sudo apt install python3-gpiozero
  2. Install inside Virtual Environment

    # Create a virtual environment named gpioenv
    python3 -m venv gpioenv

    # Activate the environment
    source gpioenv/bin/activate

    # Install gpiozero using the SpacemiT package source
    pip install gpiozero --index-url https://git.spacemit.com/api/v4/projects/33/packages/pypi/simple

    For a detailed usage guide, see the official guide: Using GPIO from Python.