树莓派Pan-Tilt HAT云台组装与Python控制实操

想给树莓派装一对"眼睛"，让它能左右张望、上下打量，两轴舵机云台是最省事的路子。Pimoroni 的 Pan-Tilt HAT 是这套方案里比较经典的一块板：双路舵机驱动加云台支架，还能顺带驱动一条 WS2812 灯条补光。这篇把官方装配指南和库文档理顺，从装架子到跑通 Python 代码一次讲完，坑点也一并标出来。

这块板是什么结构

Pan-Tilt HAT 是一块双通道舵机驱动板，专门用来带一个小型舵机云台。板上预留四个安装孔固定云台模块，PCB 上开了两条走线槽，一条走舵机线、一条走摄像头排线，都直接穿到板子下面接 Pi 的 GPIO 和 CSI 接口。除了两个舵机通道，它还能控制 PWM 调光或者 WS2812 像素灯，官方标称最多 24 颗 RGB 或 18 颗 RGBW。

翻到背面才是关键：三组三针焊针，丝印分别是 SERVO1、SERVO2 和 LIGHT。两个舵机插哪组都行，官方教程是把水平旋转的 pan 舵机接通道 1、垂直俯仰的 tilt 舵机接通道 2，接反了也不要紧，软件里换过来就行。

装配四步：模块、舵机线、摄像头、灯条

第一步固定云台模块。用四颗黑色尼龙 M2 螺栓螺母把云台底座锁在 PCB 正面，螺母从云台底座上方塞入，再穿过 PCB 的四个孔，在板子背面拧紧。方向有讲究：官方教程特意强调让云台头部绕 PCB 左边缘旋转，这样运动范围才不受限。尼龙螺栓穿出太长的话，用剪刀或斜口钳剪平，板子才能贴平 Pi 顶部。

第二步接舵机线。两根舵机线从 PCB 正面丝印 SERVO CABLE 的走线槽穿下去，背面插到焊针上，棕色线对地。想整洁可以用两根小扎带把舵机线绑在云台塑料架上，但官方提醒要留够余量，别让线绷紧卡住舵机转动。

第三步装摄像头。附带的亚克力支架是两块黑色小板，用白色尼龙 M2 螺栓把摄像头锁在中间：带 T 形孔的那块贴住摄像头正面，排线从支架顶边伸出，圆角更大的一块盖在上面。装好后整个支架卡进云台头部，曲线要对上。摄像头排线穿过丝印 CAM CABLE 的走线槽，另一头插进 Pi 的 CSI 排线座。

第四步是可选项：补光灯条。8 颗装的 Adafruit NeoPixel 灯条焊上排针后，用杜邦线接到 HAT 背面的 5V、GND、DATA 三根针上，磨砂亚克力扩散片用剩下的螺栓固定在摄像头支架上方。到这里，把 HAT 插上 Pi 的 GPIO 排针就算装完了。如果没用 Pibow Coupé 外壳，官方建议加两个金属铜柱配 M2.5 尼龙螺丝把板子撑稳，别让它悬空晃。

装库：一条脚本或手动三步

软件侧依赖的是 Pimoroni 官方的 pantilthat Python 库，走 I2C 通信。推荐用官方一键脚本装：

curl https://get.pimoroni.com/pantilthat | bash

脚本会把依赖全部装齐。手动装也不复杂，GitHub 仓库的 README 写得很清楚，先开 I2C，再装库：

sudo raspi-config nonint do_i2c 0

python3 -m pip install pantilthat

个别系统可能需要加 sudo。I2C 没开的话库会直接找不到设备，这是新手最常卡住的一步。顺带说下引脚占用：HAT 的扩展排针直连 GPIO，按官方引脚表，SDA 是 BCM2、SCL 是 BCM3，PWM 引脚是 BCM18，想再接别的外设要避开这几个。

跑通第一段代码：正弦波扫摆

控制接口非常直接，pan() 和 tilt() 两个函数，接受 -90 到 90 的角度值。官方 examples 目录里有个 smooth.py，让云台按正弦波平滑扫摆，代码全文如下，一个字符没动：

#!/usr/bin/env python

import math
import time

import pantilthat


while True:
    # Get the time in seconds
    t = time.time()

    # Generate an angle using a sine wave (-1 to 1) multiplied by 90 (-90 to 90)
    a = math.sin(t * 2) * 90

    # Cast a to int for v0.0.2
    a = int(a)

    pantilthat.pan(a)
    pantilthat.tilt(a)

    # Two decimal places is quite enough!
    print(round(a,2))

    # Sleep for a bit so we're not hammering the HAT with updates
    time.sleep(0.005)

逻辑就是把当前时间塞进正弦函数，乘 90 得到 -90 到 90 之间的角度，同时喂给 pan 和 tilt。频率由 t*2 里的 2 决定，想扫得慢就调小。最后那个 0.005 秒的 sleep 不是摆设——没有它脚本会以极高频率刷 I2C，官方注释里专门写了别去硬砸 HAT。

想从网页控制的话，官方还带了一个基于 Flask 的 pantiltweb 示例，起在本机 9595 端口，暴露 pan 和 tilt 两个接口，角度范围是 0 到 180（代码内部再减 90 映射到舵机行程）。跑起来后手机浏览器连上去，就能当遥控云台用。

几个容易踩的点

一是角度范围别越界。pan 和 tilt 的合法区间就是 -90 到 90，超了轻则不动，重则舵机堵转发热。想加限位保护，自己包一层和官方示例里 limit 同思路的钳位函数即可。

二是供电。云台套件配的是 9g 级小舵机，单板测试问题不大，但如果再加灯条或长时间连续扫摆，Pi 的 5V 轨道吃紧了就会出现掉电重启，老玩家的常规做法是舵机单独供电、与 Pi 共地。

三是方向反了别拆板。pan 和 tilt 接反、或者装的方向和预期镜像，都只需要在软件里把角度取反或换通道，官方教程原话就是"软件里很容易换过来"。

把这套装到机器狗或者小车的头顶，配合摄像头做追踪，就是一个能转头盯人的"眼睛"。官方杂志给这块板的评价是"可爱且实用"，从装机到出片确实门槛不高，一个下午足够。装完记得先跑 smooth.py 验证行程，再谈上层应用。