树莓派 5 AI 套件（Hailo）示例

系列文章目录

前言

    欢迎访问 Hailo Raspberry Pi 5 示例库。本项目展示了在 Raspberry Pi 5 上演示 Hailo AI 处理器功能的各种示例。这些示例将帮助您开始在嵌入式设备上使用人工智能。更多信息，请访问 Hailo 官方网站和 Hailo 社区论坛。 

一、如何设置 Raspberry Pi 5 和 Hailo-8L

    在本指南中，您将学习如何将 Raspberry Pi 5 与 Hailo-8L 人工智能加速器连接起来。

1.1 所需设备

• 树莓派 5
• 树莓派 M.2 M-Key HAT
• Hailo8L M.2 模块（也支持 Hailo-8）
• 散热垫（随套件提供）
• 可选：散热片
• 可选项 Raspberry Pi 官方摄像头（如摄像头模块 3 或高质量摄像头）
• 可选：USB 摄像头 USB 摄像头

1.2 硬件

    在本指南中，我们使用了 Raspberry Pi 5 型号、官方 Active Cooler 和 27W USB-C 电源。我们建议使用官方 USB-C 电源，以确保电路板能够为 M.2 HAT 提供足够的电力。

1.2.1 树莓派 M.2 密钥帽

    Raspberry Pi M.2 M 键 HAT 可与 Hailo-8L M.2 键 M 或 B+M 配合使用。(也支持 Hailo-8）。安装 M.2 模块时，请务必使用散热垫，以确保 M.2 模块和 HAT 之间的正常散热。如果您的项目封装在机箱中，请确保适当的通风以避免过热。如果需要，可为 Hailo-8L 模块添加散热片。有关如何安装 M.2 模块的详细说明，请参阅 Raspberry Pi 的官方指南。

1.2.2 Raspberry Pi 摄像头

    有关如何安装摄像头的说明，请参阅《Raspberry Pi 摄像头指南》。

1.3 软件

1.3.1 安装 Raspberry Pi 操作系统

    从此处为您的操作系统（Windows、macOS 或 Ubuntu）下载并安装最新的 Raspberry Pi Imager。

    选择 Raspberry Pi 5。

    选择 Raspberry Pi OS（64 位）。

1.3.2 更新系统

    启动 Raspberry Pi 5 进入图形环境，更新基础软件。为此，打开终端窗口并运行 

sudo apt update
sudo apt full-upgrade

     这将把系统更新到最新的 Raspberry Pi 内核，其中包括 Hailo 驱动程序支持。

1.3.3 将 PCIe 设置为 Gen3

    要使 Hailo 设备达到最佳性能，必须将 PCIe 设置为 Gen3。虽然可以选择使用 Gen2，但会降低性能。

    打开 Raspberry Pi 配置工具：

sudo raspi-config

    选择 "6 高级选项 "选项，然后选择 "A8 PCIe 速度 "选项。选择 "是 "启用 PCIe Gen 3 模式。点击 "完成 "退出。

    重新启动 Raspberry Pi。

sudo reboot

1.3.4 安装 Hailo 软件

    安装 Raspberry Pi AI 套件运行所需的所有软件。为此，请在终端窗口运行以下命令：

sudo apt install hailo-all

    这将安装以下软件组件：

• Hailo 固件

• HailoRT 运行时软件。更多信息，请参阅 HailoRT GitHub Repo。

• Hailo TAPPAS 核心软件包： 作为 TAPPAS 软件库的衍生软件，该核心软件包包含 GStreamer 元素、后处理功能以及该软件库使用的其他工具。它对于在 Pi 上开发应用程序至关重要，但不包括独立应用程序。更多信息和文档请参见 Hailo TAPPAS GitHub。

• rpicam-apps Hailo 后期处理软件演示阶段。更多信息，请参阅 Raspberry Pi 官方示例。

    重新启动 Raspberry Pi。
  

sudo reboot

1.3.5 验证安装

    现在可以检查系统是否识别 Hailo 芯片：

hailortcli fw-control identify

    如果一切正常，输出应该是这样的：

Executing on device: 0000:01:00.0
Identifying board
Control Protocol Version: 2
Firmware Version: 4.17.0 (release,app,extended context switch buffer)
Logger Version: 0
Board Name: Hailo-8
Device Architecture: HAILO8L
Serial Number: HLDDLBB234500128
Part Number: HM21LB1C2LAE
Product Name: HAILO-8L AI ACC M.2 B+M KEY MODULE EXT TMP

    如果看不到此输出，请检查 PCIe 故障排除部分。

    运行以下命令测试 TAPPAS Core 的安装情况：
     Hailotools：（TAPPAS Gstreamer 元素）

gst-inspect-1.0 hailotools

    预期结果：

Plugin Details:
  Name                     hailotools
  Description              hailo tools plugin
  Filename                 /lib/aarch64-linux-gnu/gstreamer-1.0/libgsthailotools.so
  Version                  3.28.2
  License                  unknown
  Source module            gst-hailo-tools
  Binary package           gst-hailo-tools
  Origin URL               https://hailo.ai/

  hailoaggregator: hailoaggregator - Cascading
  hailocounter: hailocounter - postprocessing element
  hailocropper: hailocropper
  hailoexportfile: hailoexportfile - export element
  hailoexportzmq: hailoexportzmq - export element
  hailofilter: hailofilter - postprocessing element
  hailogallery: Hailo gallery element
  hailograytonv12: hailograytonv12 - postprocessing element
  hailoimportzmq: hailoimportzmq - import element
  hailomuxer: Muxer pipeline merging
  hailonv12togray: hailonv12togray - postprocessing element
  hailonvalve: HailoNValve element

    Hailonet：（HailoRT 推理 Gstreamer 元素）

gst-inspect-1.0 hailo

    预期结果：

Plugin Details:
  Name                     hailo
  Description              hailo gstreamer plugin
  Filename                 /lib/aarch64-linux-gnu/gstreamer-1.0/libgsthailo.so
  Version                  1.0
  License                  unknown
  Source module            hailo
  Binary package           GStreamer
  Origin URL               http://gstreamer.net/

  hailodevicestats: hailodevicestats element
  hailonet: hailonet element
  synchailonet: sync hailonet element

  3 features:
  +-- 3 elements

    如果找不到 hailo 或 hailotools，请尝试删除 GStreamer 注册表：

rm ~/.cache/gstreamer-1.0/registry.aarch64.bin

    如果一切正常，就可以继续安装 hailo_rpi5_examples。

1.4 故障排除

    有问题？加入 Hailo 社区论坛的讨论。

1.4.1 PCIe 故障排除

    确保 PCIe 板和 M.2 模块连接正确。要测试系统是否识别 PCIe 板，请运行以下命令：

lspci | grep Hailo

    如果输出结果如下

0000:01:00.0 Co-processor: Hailo Technologies Ltd. Hailo-8 AI Processor (rev 01)

    然后系统会识别 PCIe 板。如果没有，请检查连接和电源，并确保 PCIe 已启用（请参阅 Raspberry Pi 文档）。如果电路板是新的，可能需要更新 Raspberry Pi 5 的固件。

1.4.2 驱动程序问题

    如果出现 "未安装 Hailo 驱动程序 "的错误提示，请确保内核版本大于 6.6.31。你可以运行以下命令获取内核版本：

uname -a

    如果内核版本低于 6.6.31，可能需要运行 apt update 和 apt full-upgrade 来更新内核。如果内核版本没有问题，请重启系统并重试。

1.4.3 已知问题

    以下问题应由 TAPPAS Core 安装 deb 处理，但如果遇到这些问题，可以手动修复。

1.4.3.1 PCIe 页面大小问题

    某些主机不支持某些 PCIe 描述符页面大小。如果出现如下错误

[HailoRT] [error] CHECK_AS_EXPECTED failed - max_desc_page_size given 16384 is bigger than hw max desc page size 4096

    确保/etc/modprobe.d/hailo_pci.conf 存在，并包含以下一行：

options hailo_pci force_desc_page_size=4096

    检查配置：

cat /etc/modprobe.d/hailo_pci.conf
# expected result:
options hailo_pci force_desc_page_size=4096

1.4.3.2 无法在静态 TLS 块中分配内存

    在某些情况下（尤其是 aarch64），你可能会遇到以下错误，导致某些 GStreamer 插件无法正确加载。错误信息如下

bash
(gst-plugin-scanner:67): GStreamer-WARNING **: 12:20:39.178: Failed to load plugin '/usr/lib/aarch64-linux-gnu/gstreamer-1.0/libgstlibav.so': /lib/aarch64-linux-gnu/libgomp.so.1: cannot allocate memory in static TLS block

    将此添加到 .bashrc 文件中即可解决此问题：

echo 'export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libgomp.so.1' >> ~/.bashrc

    如果您已经遇到了这个错误，可以通过运行以下命令来修复：

export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libgomp.so.1
rm ~/.cache/gstreamer-1.0/registry.aarch64.bin

二、Hailo RPi5 基本管道

    该资源库包含 Hailo RPi5 平台的基本管道示例。这些示例演示了物体检测、人体姿态估计和实例分割。您可以将这些应用作为自己项目的基础。

2.1 安装

    克隆资源库

git clone https://github.com/hailo-ai/hailo-rpi5-examples.git

    输入版本库目录：

cd hailo-rpi5-examples

2.1.1 环境配置

    要运行示例，应确保环境设置正确。我们使用 hailo-tappas-core pkgconfig 文件获取 Hailo 依赖项。

    你可以通过以下脚本进行设置。该脚本将设置所需的环境变量，并激活 Hailo 虚拟环境（如果不存在，则会创建）。

source setup_env.sh

2.1.2 安装要求

    确保已进入虚拟环境并运行以下命令：

pip install -r requirements.txt

2.1.3 资源下载

./download_resources.sh

2.2 应用程序结构

2.2.1 用户自定义数据类（user_app_callback_class）

    该用户自定义类作为输入传递给回调函数，该函数在管道输出上运行。它用于主程序与回调函数之间的通信。它对 hailo_rpi_common::app_callback_class 进行了扩展，并可根据应用程序的具体情况定制附加变量和方法。

2.2.2 应用程序回调函数（app_callback）

    您应在此处添加代码。这是一个用户自定义函数，用于处理管道中的每个帧。它由管道中的 "identity_callback "元素调用，位于网络推理和后处理之后。作为该函数输入的 GStreamer 缓冲区包括作为 Hailo 元数据的网络输出和帧本身。每个示例都演示了如何为其任务解析特定的元数据。有关 Hailo 元数据对象的更多信息，请参阅 TAPPAS 文档中的 Hailo Objects API。

2.2.3 GStreamer 应用程序类（GStreamerApp）

    使用基本管道时无需更改。该类通过扩展 hailo_rpi_common::GStreamerApp 来设置 GStreamer 管道并处理事件和回调。应用程序可以通过重载 get_pipeline_string 函数来修改网络参数和管道。有关 TAPPAS 管道和元素的更多详情，请参阅 TAPPAS 文档。

2.3 目标检测示例

    本例演示对象检测。它默认使用 YOLOv6n 模型。它还支持 yolov8s 和 yolox_s_leaky 模型。它使用 Hailo 的 NMS（非最大抑制）层作为 HEF 文件的一部分，因此所有使用 NMS 编译的检测网络都可以使用相同的代码。

    要运行示例，请使用

python basic_pipelines/detection.py --input resources/detection0.mp4

    要关闭程序，请按 "Ctrl+C"。
     如需其他选项，请运行

python basic_pipelines/detection.py --help

    另请参阅使用不同输入源运行。

2.3.1 本例中的内容：

2.3.1.1 实例分割回调类：

    回调函数展示了如何从网络输出中获取实例分割元数据。每个实例都表示为带有掩码（HAILO_CONF_CLASS_MASK 对象）的 HAILO_DETECTION。如果设置了--use-frame（使用帧）标志，代码将解析掩码，并根据帧协坐标调整它们的大小和形状。代码会将它们的形状打印到终端。在用户缓冲区上绘制掩码是可能的，但由于性能原因，本示例中并未实现。

2.3.2 其他功能

    使用 --help 标志运行任何示例，即可查看所有可用选项。例如

python basic_pipelines/pose_estimation.py --help
# Example output:
usage: pose_estimation.py [-h] [--input INPUT] [--use-frame] [--show-fps] [--disable-sync] [--dump-dot]

Hailo App Help

options:
  -h, --help            show this help message and exit
  --input INPUT, -i INPUT
                        Input source. Can be a file, USB or RPi camera (CSI camera module). For RPi camera use '-i rpi' (Still in Beta). Defaults to
                        /dev/video0
  --use-frame, -u       Use frame from the callback function
  --show-fps, -f        Print FPS on sink
  --disable-sync        Disables display sink sync, will run as fast possible. Relevant when using file source.
  --dump-dot            Dump the pipeline graph to a dot file pipeline.dot

    有关如何使用这些选项的更多信息，请参阅下文。

2.3.2.1 使用不同输入源运行

    这些示例默认使用 USB 摄像头（/dev/video0）运行。您可以使用 --input 标志更改输入源。要使用 Raspberry Pi 摄像头运行，请使用 --input rpi。(仍处于测试阶段）下面是几个示例：

python basic_pipelines/detection.py --input /dev/video2
python basic_pipelines/detection.py --input rpi
python basic_pipelines/detection.py --input resources/detection0.mp4

    注意：USB 摄像头不一定是 /dev/video0。您可以运行以下命令检查哪些视频设备可用：

ls /dev/video*

    您可以运行以下程序来测试摄像头是否正常工作：

ffplay -f v4l2 /dev/video0

    如果出现错误，请尝试其他设备，如 /dev/video2（可能是偶数）。

2.3.2.2 使用帧缓冲区

    有关使用帧缓冲器的示例，请添加 --use-frame 标志。请注意，提取视频帧并将其显示出来会降低应用程序的运行速度。这种实现方式未经优化，仅作为一个简单示例。也有可能在缓冲区中写入内容并替换管道中的旧缓冲区，但这样做效率不高。

2.3.2.3 打印帧频

    要打印帧频，请添加 --print-fps 标志。这将把帧频打印到终端和视频输出窗口。

2.3.2.4 转储管道图：

    这对调试和理解管道非常有用。要将流水线图形转存到 dot 文件中，请添加 --dump-dot 标志。这将在 basic_pipelines 目录下创建一个名为 pipeline.dot 的文件。要安装该工具，请运行

sudo apt install graphviz

    下面是使用 --dump-dot 标记运行检测示例的完整示例：

python basic_pipelines/detection.py --dump-dot
# To visulaize the pipeline run:
dot -Tx11 basic_pipelines/pipeline.dot &
# To save the pipeline as a png run:
dot -Tpng basic_pipelines/pipeline.dot -o pipeline.png

    下面是检测管道图的输出示例：

    小贴士 右键单击图像，选择 "在新标签页中打开图像"，查看完整图像。

2.3.3 姿势估计示例

2.3.4 实例分割示例

2.3.4 CLIP 应用程序 - 即将推出

    CLIP（对比语言-图像预训练），使用 Hailo-8L 人工智能处理器预测实时视频帧上最相关的文本提示。

2.3.6 树莓派官方示例

2.3.6.1 rpicam-apps

    树莓派 rpicam-apps Hailo 后处理示例。这是 Raspberry Pi 使用集成到其 CPP 摄像头框架中的 Hailo AI 处理器进行 AI 后期处理的官方示例。有关如何使用 rpicam-apps 的文档，请点击此处。要运行 rpicam-apps 中的示例，请按照以下说明操作： 克隆 rpicam-apps 软件源，获取 JSON 配置文件

git clone --depth 1 https://github.com/raspberrypi/rpicam-apps.git

    将目录更改为 assets 文件夹并运行示例

cd rpicam-apps/assets/
# Run the example
rpicam-hello -t 0 --post-process-file hailo_yolov6_inference.json --lores-width 640 --lores-height 640

2.3.6.2 picamera2 - 即将推出

    Raspberry Pi picamera2 是基于 libcamera 的 Picamera 替代品，Picamera 是 Raspberry Pi 传统相机栈的 Python 接口。Picamera2 还提供了一个易于使用的 Python API。

2.4 故障排除和已知问题

    如果遇到任何问题，请在 Hailo 社区论坛上开票。论坛上有很多有用的信息，可能已经包含了问题的解决方案。

• RPi 摄像头输入仍处于测试阶段。它可能不稳定，可能导致应用程序崩溃。

• 帧缓冲区未优化，可能会降低应用程序的运行速度。以下是一个简单的示例。

• DEVICE_IN_USE() 错误。DEVICE_IN_USE() 错误通常表示 Hailo 设备（通常为 /dev/hailo0）当前正在被其他进程访问或锁定。这种情况可能发生在并发访问尝试期间，或者前一个进程没有干净利落地终止，导致设备处于锁定状态。有关详细信息，请参阅社区论坛主题。

    解决步骤：
  

• 识别设备： 通常情况下，Hailo 设备位于 /dev/hailo0。确保这是您设置的正确设备文件。

• 查找使用该设备的进程： 运行以下命令，列出当前使用 Hailo 设备的进程： sudo lsof /dev/hailo0

• 终止进程： 使用上一条命令输出中的 PID（进程 ID）来终止进程。用实际 PID 替换 <PID>。sudo kill -9 <PID>