> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/rpicn/pei-jian/build-hat.md).

# Build 扩展板（Build HAT）

## 简介

[树莓派 Build 扩展板](https://raspberrypi.com/products/build-hat)是一块附加板，可连接到树莓派的 40 引脚 GPIO 排针。它与乐高®教育（LEGO® Education）合作设计，可让你轻松使用树莓派计算机控制乐高®机械组（LEGO® Technic™）电机和传感器。

> **警告**
>
> 树莓派 Build 扩展板目前尚不支持树莓派系统 *Trixie*。要使用 Build 扩展板，请暂时安装或继续使用树莓派系统 *Bookworm*。

![Build 扩展板](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-6507e51dfba728d292491dda61cf3c5379ba9600%2Fbuild-hat.jpg?alt=media)

> **注意**
>
> 受支持设备的完整列表见[设备兼容性](#设备兼容性)一节。

它为 SPIKE™ 系列产品中的乐高®机械组电机和传感器提供了四个连接器。可用的传感器包括距离传感器、颜色传感器和多用途力传感器。角度电机有多种尺寸，并带有集成编码器，可查询其位置。

Build 扩展板适用于所有带有 40 引脚 GPIO 排针的树莓派计算机，包括借助排线或其他扩展设备连接的键盘系列（Keyboard-series）设备。连接的乐高®机械组设备可轻松用 Python 控制，同时还可搭配摄像头模块等标准树莓派配件。

树莓派 Build 扩展板的电源适配器（PSU）[单独出售](https://raspberrypi.com/products/build-hat-power-supply)，旨在为 Build 扩展板、树莓派计算机以及所有连接的乐高®机械组设备供电。

![电源适配器](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-f75ced65fa748e86927dd36340465e72ccd746d8%2Fpsu.jpg?alt=media)

SPIKE™ Prime 套装 45678 和 SPIKE™ Prime 扩展套装 45681 可从乐高®教育经销商处单独购买，其中包含一组 Build 扩展板支持的实用元件。

> **注意**
>
> 该扩展板可与所有带 40 引脚 GPIO 排针的树莓派开发板配合使用，包括 Zero 系列设备。借助排线或其他扩展设备，也可与键盘系列设备配合使用。

* 最多可控制 SPIKE™ 系列产品中包含的 4 个乐高®机械组电机和传感器
* 易于使用的 [Python 库](https://buildhat.readthedocs.io/)，用于控制你的乐高®机械组设备
* 适用于所有带有 40 引脚 GPIO 排针的树莓派计算机
* 板载 [RP2040](https://www.raspberrypi.com/documentation/microcontrollers/microcontroller-chips.html) 微控制器负责乐高®机械组设备的低层控制
* 外部 8V 电源适配器[单独出售](https://raspberrypi.com/products/build-hat-power-supply)，用于为 Build 扩展板和树莓派供电

> **注意**
>
> Build 扩展板无法为键盘系列设备供电，因为它们不支持通过 GPIO 排针供电。

## 准备你的 Build 扩展板

> **注意**
>
> 在开始使用你的树莓派 Build 扩展板之前，请先设置你的树莓派，并使用[树莓派启动盘制作工具](https://www.raspberrypi.com/downloads/)安装最新版本的操作系统。

将 9 mm 间隔柱装到板的底部。将树莓派 Build 扩展板安装到你的树莓派上。确保方向正确。与其他扩展板不同，所有组件都在底部，为顶部的面包板或乐高®元件留出空间。

![安装 Build 扩展板](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-8d64b6817bbb32976c9ba7f8c433d2e4a878bb84%2Ffitting-build-hat.webm?alt=media)

### 访问 GPIO 引脚

如果你想访问树莓派的 GPIO 引脚，可以添加一个可选的长排针，并使用 15 mm 间隔柱。

![长排针](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-f07d4f976a84d2ef1bb10b21d14f79b39464817e%2Ftall-headers.jpg?alt=media)

下面的引脚由 Build 扩展板本身使用；请勿将任何东西连接到这些引脚上。

|   GPIO  |    使用   |  状态 |
| :-----: | :-----: | :-: |
| GPIO0/1 | ID prom |     |
|  GPIO4  |    重置   |     |
|  GPIO14 |    发送   |     |
|  GPIO15 |    接收   |     |
|  GPIO16 |   RTS   | 未使用 |
|  GPIO17 |   CTS   | 未使用 |

### 设置你的树莓派

树莓派启动后，单击 Raspberry 菜单按钮，然后选择 **Preferences > Control Centre**，打开控制中心工具。

选择 **Interfaces** 选项卡，并按照下图所示调整串口设置：

![设置](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-e69d97a3c2dc776701072c9015a138bcdb1635e1%2Fsetting-up.png?alt=media)

#### 以无头方式使用树莓派

如果你以无头方式运行树莓派，并使用 `raspi-config`，请从第一个菜单中选择 “Interface Options”。

![raspi config 1](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-6e3675765294e7910f04c0f1f892419fc6ecc2ca%2Fraspi-config-1.png?alt=media)

然后选择 “P6 Serial Port”。

![raspi config 2](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-4dfd19cbaf7b43be5c0366a6ae14fdcfc6ecf617%2Fraspi-config-2.png?alt=media)

禁用串口控制台：

![raspi config 3](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-239872e5222e5e13ad83efce7150b734cc76f65a%2Fraspi-config-3.png?alt=media)

然后启用串口硬件。

![raspi config 4](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-656f84895c1c0ef05ef7edfa89544b7c1854cf09%2Fraspi-config-4.png?alt=media)

最终设置如下所示。

![raspi config 5](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-c0117b0857fbb6125d6ca128260581f23ba2d692%2Fraspi-config-5.png?alt=media)

如果你在此期间进行了一些更改，此时需要重启。

### 为 Build 扩展板供电

连接外部电源：推荐使用[官方树莓派 Build 扩展板电源](https://raspberrypi.com/products/build-hat-power-supply)。不过，任何可靠的 +8V±10% 电源，只要能通过 DC 5521 中心正极桶形连接器（5.5 mm × 2.1 mm × 11 mm）提供 48 W 功率，都能为 Build 扩展板供电。除非你使用的是键盘系列设备，否则无需为树莓派连接额外的 USB 电源。

> **注意**
>
> Build 扩展板无法为键盘系列设备供电，因为它们不支持通过 GPIO 排针供电。

![扩展板供电](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-e358683f90b4942221b619d84c9515f53cda30fa%2Fpowering-build-hat.webm?alt=media)

> **注意**
>
> 乐高®机械组电机非常强大；因此，要驱动它们，你需要外部 8V 电源。如果你想从电机编码器和 SPIKE™ 力传感器读取数据，可以按照平常的方式，通过树莓派设备的 USB 电源插口为树莓派和 Build 扩展板供电。与电机一样，SPIKE™ 颜色和距离传感器也需要[外部电源](https://raspberrypi.com/products/build-hat-power-supply)。

你可以选择使用 Python 或 .NET 来操作 Build 扩展板。

## 使用 Python 操作 Build 扩展板

### 安装 Build 扩展板 Python 库

要安装 Build 扩展板 Python 库，请打开终端窗口并运行以下命令：

```bash
$ sudo apt install python3-build-hat
```

有关 Build 扩展板 Python 库的更多信息，请参阅 [ReadTheDocs](https://buildhat.readthedocs.io/)。

### 使用 Python 控制电机

有许多电机可与 Build 扩展板配合使用。

#### 连接电机

将电机连接到 Build 扩展板上的 A 端口。LPF2 连接器需要以正确的方向插入。如果连接器无法轻松滑入，请旋转 180 度后重试。

![接入电机](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-70da881290206a6c46fb7f7a29c0886b8b6afca2%2Fconnect-motor.webm?alt=media)

#### 使用电机

启动 [Thonny IDE](https://thonny.org/)。添加以下程序代码：

```python
from buildhat import Motor

motor_a = Motor('A')

motor_a.run_for_seconds(5)
```

通过单击播放/运行按钮来运行程序。如果这是自树莓派启动以来首次运行 Build 扩展板程序，固件复制到板上的过程中会暂停几秒。红色 LED 熄灭，绿色 LED 点亮。此后运行 Python 程序就不再需要这段等待。

![熄灭灯](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-12ecb8a3bb281899c4ac50dc958f49f095b1a7fd%2Fblinking-light.webm?alt=media)

你的电机顺时针转动 5 秒。

![电机转动](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-334b43eae7d9b987c8aecfd8dfefc45d3cb02e7c%2Fturning-motor.webm?alt=media)

更改程序的最后一行并重新运行。

```python
motor_a.run_for_seconds(5, speed=50)
```

电机现在转得更快了。再做一处更改：

```python
motor_a.run_for_seconds(5, speed=-50)
```

电机向相反方向（逆时针）转动。

单击 Thonny 中的加号按钮创建一个新程序。添加以下代码：

```python
from buildhat import Motor

motor_a = Motor('A')

while True:
    print("Position: ", motor_a.get_aposition())
```

运行程序。抓住电机并转动轴。Thonny REPL 中打印的数字会发生变化。

### 使用 Python 读取传感器

有大量传感器可与 Build 扩展板配合使用。

#### 使用传感器

将颜色传感器连接到 Build 扩展板上的 B 端口，将力传感器连接到 C 端口。

> **注意**
>
> 如果你不打算驱动电机，则无需外部电源，可以使用标准 USB 电源为你的树莓派供电。

创建另一个新程序：

```python
from signal import pause
from buildhat import ForceSensor, ColorSensor

button = ForceSensor('C')
cs = ColorSensor('B')

def handle_pressed(force):
    cs.on()
    print(cs.get_color())

def handle_released(force):
    cs.off()

button.when_pressed = handle_pressed
button.when_released = handle_released
pause()
```

运行程序，将一个彩色物体（乐高®元件最理想）放在颜色传感器前，然后按下力传感器的压杆。传感器的 LED 亮起，Thonny REPL 中会显示最接近的颜色名称。

## 使用 .NET 操作 Build 扩展板

### 安装 .NET 框架

微软的 .NET 框架无法通过 `apt` 在树莓派上安装。不过，你可以参照微软的[官方说明](https://docs.microsoft.com/en-us/dotnet/iot/deployment)来安装 .NET 框架。此外，还有一条简化的[第三方途径](https://www.petecodes.co.uk/install-and-use-microsoft-dot-net-5-with-the-raspberry-pi/)可将 .NET 工具链安装到你的树莓派上。

> **警告**
>
> 安装脚本以 `root` 身份运行。在运行它之前，请先阅读它，并确保你理解它在做什么。如果你有任何疑问，请按照[官方说明](https://docs.microsoft.com/en-us/dotnet/iot/deployment)手动操作。

```bash
$ wget -O - https://raw.githubusercontent.com/pjgpetecodes/dotnet5pi/master/install.sh | sudo bash
```

安装 .NET 框架后，你可以创建你的项目：

```bash
$ dotnet new console --name buildhat
```

这将在 `buildhat` 子目录中创建一个默认程序；要继续操作，需要先进入该目录：

```bash
$ cd buildhat
```

你现在需要安装以下 NuGet 软件包：

```bash
$ dotnet add package System.Device.Gpio --version 2.1.0
$ dotnet add package Iot.Device.Bindings --version 2.1.0
```

### 运行 C# 代码

你可以使用 `dotnet run` 命令运行程序。现在让我们试一下，确保一切正常。它会打印出 “Hello World!”。

```bash
$ dotnet run
Hello World!
```

（在接下来的说明中，当指示“运行程序”时，你只需重新运行 `dotnet run`）

### 编辑 C# 代码

在下面的说明中，你将编辑文件 `buildhat/Program.cs`，即运行上述命令时生成的 C# 程序。

任何文本编辑器都可以用来编辑 C# 代码，包括预装的 Geany IDE/文本编辑器。[Visual Studio Code](https://code.visualstudio.com/docs/setup/raspberry-pi/)（通常称为 “VS Code”）也是一个流行的替代方案。

### 通过 .NET 访问 Build 扩展板

树莓派 Build 扩展板在乐高®术语中被称为 “Brick（积木）”，你可以使用 [Build 扩展板串行协议](https://pip.raspberrypi.com/documents/RP-008140-DS)从 .NET 直接与它通信。

你可以按照以下方式创建一个 `brick` 对象：

```csharp
Brick brick = new("/dev/serial0");
```

但你需要记住在代码末尾释放 `brick`。

```csharp
brick.Dispose();
```

> **警告**
>
> 如果你不调用 `brick.Dispose()`，你的程序将不会终止。

如果你想避免在结尾调用 `brick.Dispose`，那么请使用 `using` 语句创建 brick 对象：

```csharp
using Brick brick = new("/dev/serial0");
```

在这种情况下，当程序结束时，你的 brick 会被自动释放。

#### 显示 Build 扩展板信息

你可以读取各种软件版本、签名和输入电压：

```csharp
var info = brick.BuildHatInformation;
Console.WriteLine($"version: {info.Version}, firmware date: {info.FirmwareDate}, signature:");
Console.WriteLine($"{BitConverter.ToString(info.Signature)}");
Console.WriteLine($"Vin = {brick.InputVoltage.Volts} V");
```

> **注意**
>
> 输入电压仅在启动时读取一次，之后不再读取。

#### 获取传感器和电机详细信息

函数 `GetSensorType` 和 `GetSensor` 可让你获取已连接传感器的任何信息。

```csharp
SensorType sensor = brick.GetSensorType((SensorPort)i);
Console.Write($"Port: {i} {(Brick.IsMotor(sensor) ? "Sensor" : "Motor")} type: {sensor} Connected: ");
```

在这个例子中，你也可以使用 `IsMotor` 静态函数来检查连接的元素是传感器还是电机。

```csharp
if (Brick.IsActiveSensor(sensor))
{
    ActiveSensor activeSensor = brick.GetActiveSensor((SensorPort)i);
}
else
{
    var passive = (Sensor)brick.GetSensor((SensorPort)i);
    Console.WriteLine(passive.IsConnected);
}
```

`ActiveSensor` 具有一系列高级属性和函数，可用于了解传感器的各个元素。还可以通过它们调用 brick 的底层函数。这样你就能选择特定模式并实现更复杂的场景。虽然这些操作都能做到，但我们已经提供了电机类和传感器类，让你用起来更省心。

#### 事件

大多数传感器在其特殊属性上实现了事件。你可以直接订阅 `PropertyChanged` 和 `PropertyUpdated`。当值发生变化时会触发 changed 事件，而当属性成功更新时会触发 updated 事件。根据所使用的模式，一些属性可能会一直在后台更新，而另一些则偶尔更新。

如果你只关心颜色变化或电机位置变化，想把电机当作转速表使用，那么 `PropertyChanged` 正是你需要的！

```csharp
Console.WriteLine("Move motor on Port A to more than position 100 to stop this test.");
brick.WaitForSensorToConnect(SensorPort.PortA);
var active = (ActiveMotor)brick.GetMotor(SensorPort.PortA);
bool continueToRun = true;
active.PropertyChanged += MotorPropertyEvent;
while (continueToRun)
{
    Thread.Sleep(50);
}

active.PropertyChanged -= MotorPropertyEvent;
Console.WriteLine($"Current position: {active.Position}, eventing stopped.");

void MotorPropertyEvent(object? sender, PropertyChangedEventArgs e)
{
    Console.WriteLine($"Property changed: {e.PropertyName}");
    if (e.PropertyName == nameof(ActiveMotor.Position))
    {
        if (((ActiveMotor)brick.GetMotor(SensorPort.PortA)).Position > 100)
        {
            continueToRun = false;
        }
    }
}
```

#### 等待初始化

brick 可能需要很长时间才能完成初始化。已实现等待传感器连接的功能。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortB);
```

如果你需要实现高级功能（例如在一段时间后警告用户并重试），还可以传入一个 `CancellationToken`。

### 使用 .NET 控制电机

电机有两种类型：**被动** 电机和 **主动** 电机。主动电机可提供详细位置、绝对位置和速度，而被动电机只能通过速度来控制。

有一组通用的函数可用于控制电机的速度。其中有两个重要的函数：`SetPowerLimit` 和 `SetBias`：

```csharp
train.SetPowerLimit(1.0);
train.SetBias(0.2);
```

这两个函数只接受 0.0 到 1.0 之间的值。功率限制是一种方便的方法，可以按比例减小最大功率。

偏置值针对当前端口设置，会加到正的电机驱动值上，并从负的电机驱动值中减去。大多数直流电机需要一定的驱动量才能开始转动，偏置值可以用来补偿这一点。

创建电机时的默认值为：功率限制 0.7，偏置 0.3。

#### 被动电机

![火车电机](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-00c342aaf54908309a03611e455395be68180a91%2Ftrain-motor.png?alt=media)

[火车电机，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0896c01)

典型的被动电机是火车电机和较旧的 Powered Up 电机。`Speed` 属性可以设置和读取。由于这类电机没有测量自身速度的方法，该值既是目标速度，也是测得的速度。取值范围为 -100 到 +100。

还提供了用于控制的 `Start`、`Stop` 和 `SetSpeed` 函数。以下是一个使用示例：

```csharp
Console.WriteLine("This will run the motor for 20 seconds incrementing the PWM");
train.SetPowerLimit(1.0);
train.Start();
for (int i = 0; i < 100; i++)
{
    train.SetSpeed(i);
    Thread.Sleep(250);
}

Console.WriteLine("Stop the train for 2 seconds");
train.Stop();
Thread.Sleep(2000);
Console.WriteLine("Full speed backward for 2 seconds");
train.Start(-100);
Thread.Sleep(2000);
Console.WriteLine("Full speed forward for 2 seconds");
train.Start(100);
Thread.Sleep(2000);
Console.WriteLine("Stop the train");
train.Stop();
```

> **注意**
>
> 火车启动后，你可以调整速度，电机会相应调整。

#### 主动电机

![主动电机](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-c933668fa2eb32c83cf60482954929beda07d1a9%2Factive-motor.png?alt=media)

[主动电机，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0960c01)

主动电机具有 `Speed`、`AbsolutePosition`、`Position` 和 `TargetSpeed` 等特殊属性。即使电机停止运行，这些属性也会持续更新。

以下代码片段展示如何获取电机、启动它们并读取属性：

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
brick.WaitForSensorToConnect(SensorPort.PortD);
var active = (ActiveMotor)brick.GetMotor(SensorPort.PortA);
var active2 = (ActiveMotor)brick.GetMotor(SensorPort.PortD);
active.Start(50);
active2.Start(50);
// 确保端口 A 和 D 上插有主动电机
while (!Console.KeyAvailable)
{
    Console.CursorTop = 1;
    Console.CursorLeft = 0;
    Console.WriteLine($"Absolute: {active.AbsolutePosition}     ");
    Console.WriteLine($"Position: {active.Position}     ");
    Console.WriteLine($"Speed: {active.Speed}     ");
    Console.WriteLine();
    Console.WriteLine($"Absolute: {active2.AbsolutePosition}     ");
    Console.WriteLine($"Position: {active2.Position}     ");
    Console.WriteLine($"Speed: {active2.Speed}     ");
}

active.Stop();
active2.Stop();
```

> **注意**
>
> 在需要时不要忘记启动和停止你的电机。

高级功能适用于主动电机。你可以让它转动指定秒数，也可以把它移动到特定位置或特定绝对位置。以下是一些示例：

```csharp
// 承上例，这会把电机转回初始位置：
active.TargetSpeed = 100;
active2.TargetSpeed = 100;
// 先让这台电机转动，会阻塞线程
active.MoveToPosition(0, true);
// 再让另一台电机转动，同样会阻塞线程
active2.MoveToPosition(0, true);
```

每个函数都允许你在操作执行期间阻塞或不阻塞线程。请注意，对于绝对位置和相对位置移动，存在几度的容差。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var active = (ActiveMotor)brick.GetMotor(SensorPort.PortA);
active.TargetSpeed = 70;
Console.WriteLine("Moving motor to position 0");
active.MoveToPosition(0, true);
Console.WriteLine("Moving motor to position 3600 (10 turns)");
active.MoveToPosition(3600, true);
Console.WriteLine("Moving motor to position -3600 (so 20 turns the other way");
active.MoveToPosition(-3600, true);
Console.WriteLine("Moving motor to absolute position 0, should rotate by 90°");
active.MoveToAbsolutePosition(0, PositionWay.Shortest, true);
Console.WriteLine("Moving motor to position 90");
active.MoveToAbsolutePosition(90, PositionWay.Shortest, true);
Console.WriteLine("Moving motor to position 179");
active.MoveToAbsolutePosition(179, PositionWay.Shortest, true);
Console.WriteLine("Moving motor to position -180");
active.MoveToAbsolutePosition(-180, PositionWay.Shortest, true);
active.Float();
```

你可以将电机置于浮动（float）状态，即不再对它施加任何约束。当你把电机用作转速表时可以使用这种模式：移动电机并读取位置。如果电机仍受约束，你可能无法移动它。

### 使用 .NET 读取传感器

与电机一样，传感器也分为主动和被动两种。较新的传感器大多是主动的。被动传感器包括灯光和简单的按钮。主动传感器包括距离传感器、颜色传感器，以及小型的 3×3 像素显示屏。

#### 按钮/触摸被动传感器

按钮/触摸被动传感器具有一个特殊属性 `IsPressed`。当按钮被按下时，该属性设置为 true。以下是一个带事件的完整示例：

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var button = (ButtonSensor)brick.GetSensor(SensorPort.PortA);
bool continueToRun = true;
button.PropertyChanged += ButtonPropertyEvent;
while (continueToRun)
{
    // 你可以在这里做许多其他事情
    Thread.Sleep(50);
}

button.PropertyChanged -= ButtonPropertyEvent;
Console.WriteLine($"Button has been pressed, we're stopping the program.");
brick.Dispose();

void ButtonPropertyEvent(object? sender, PropertyChangedEventArgs e)
{
    Console.WriteLine($"Property changed: {e.PropertyName}");
    if (e.PropertyName == nameof(ButtonSensor.IsPressed))
    {
        continueToRun = false;
    }
}
```

#### 被动灯光

![被动灯光](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-632489fd4b876e6a42dfb51d93db43fb731aac00%2Fpassive-light.png?alt=media)

[被动灯光，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=22168c01)

被动灯光是火车灯。你可以打开它们，并控制它们的亮度。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var light = (PassiveLight)brick.GetSensor(SensorPort.PortA);
// 亮度 50%
light.On(50);
Thread.Sleep(2000);
// 亮度 70%
light.Brightness = 70;
Thread.Sleep(2000);
// 关闭灯光
light.Off()
```

#### 主动传感器

主动传感器类是一个通用类，所有主动传感器（包括主动电机）都继承自它。该类包含一组属性，涉及与 Build 扩展板的连接方式、模式、详细的组合（Combi）模式、硬件和软件版本，以及一个名为 `ValueAsString` 的特殊属性。字符串值包含以字符串集合形式表示的最后一次测量。测量到达时形如 `P0C0: +23 -42 0`，枚举将包含 `P0C0:`、`+23`、`-42` 和 `0`。这样设计是为了让你在使用高级模式并自行管理组合模式和命令时，也能获取测量值。

所有主动传感器都可以运行特定的测量模式或组合模式。你可以通过高级模式，使用 `SelectModeAndRead` 和 `SelectCombiModesAndRead` 函数设置你想要持续使用的特定模式。需要注意，更改模式或设置新模式会停止之前的模式。

可以组合进组合模式的模式列在 `CombiModes` 属性中。当你设置其中某个模式时，传感器的所有属性都会自动更新。

#### WeDo 倾斜传感器

![WeDo 倾斜传感器](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-153eb43b026f3b1058c4f808b595a5df9c0d6ba6%2Fwedo-tilt.png?alt=media)

[WeDo 倾斜传感器，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=20841)

WeDo 倾斜传感器有一个特殊的 `Tilt` 属性。该类型是一个点（point），其中 X 是 X 轴倾斜值，Y 是 Y 轴倾斜值。数值范围从 -45 到 +45，被限制在这些值内，单位为度。

你可以使用 `ContinuousMeasurement` 属性为该传感器设置连续测量。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var tilt = (WeDoTiltSensor)brick.GetSensor(SensorPort.PortA);
tilt.ContinuousMeasurement = true;
Point tiltValue;
while(!console.KeyAvailable)
{
    tiltValue = tilt.Tilt;
    console.WriteLine($"Tilt X: {tiltValue.X}, Tilt Y: {tiltValue.Y}");
    Thread.Sleep(200);
}
```

#### WeDo 距离传感器

![WeDo 距离传感器](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-47bc9925e000479a1cfc4ed97c5e629da2fc0f63%2Fwedo-distance.png?alt=media)

[WeDo 距离传感器，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=20844)

WeDo 距离传感器通过 `Distance` 属性提供以毫米为单位的距离。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var distance = (WeDoDistanceSensor)brick.GetSensor(SensorPort.PortA);
distance.ContinuousMeasurement = true;
while(!console.KeyAvailable)
{
    console.WriteLine($"Distance: {distance.Distance} mm");
    Thread.Sleep(200);
}
```

#### SPIKE Prime 力传感器

![SPIKE 力传感器](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-06dc942aefd21abfdc27959472f346fa0f6f6c08%2Fspike-force.png?alt=media)

[SPIKE 力传感器，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=37312c01)

该力传感器测量施加在它上面的压力，以及它是否被按下。这两个值可分别通过 `Force` 和 `IsPressed` 属性读取。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var force = (ForceSensor)brick.GetSensor(SensorPort.PortA);
force.ContinuousMeasurement = true;
while(!force.IsPressed)
{
    console.WriteLine($"Force: {force.Force} N");
    Thread.Sleep(200);
}
```

#### SPIKE Essential 3×3 彩色灯光矩阵

![SPIKE Essential 3×3 彩色灯光矩阵](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-ce0c1efe454d748fb809667aee698a96ac633f31%2F3x3matrix.png?alt=media)

[SPIKE 3×3 矩阵，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=47592c01)

这是一个小型 3×3 显示屏，带有 9 个可单独控制的 LED。该类公开了控制屏幕的函数。以下是一个使用示例：

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var matrix = (ColorLightMatrix)brick.GetSensor(SensorPort.PortA);
for(byte i = 0; i < 10; i++)
{
    // 像进度条一样逐个点亮每个 LED
    matrix.DisplayProgressBar(i);
    Thread.Sleep(1000);
}

for(byte i = 0; i < 11; i++)
{
    // 用同一种颜色显示矩阵，并依次遍历所有颜色
    matrix.DisplayColor((LedColor)i);
    Thread.Sleep(1000);
}

Span<byte> brg = stackalloc byte[9] { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
Span<LedColor> col = stackalloc LedColor[9] { LedColor.White, LedColor.White, LedColor.White,
  LedColor.White, LedColor.White, LedColor.White, LedColor.White, LedColor.White, LedColor.White };
// 灰度层次
matrix.DisplayColorPerPixel(brg, col);
```

#### SPIKE Prime 颜色传感器与颜色和距离传感器

SPIKE 颜色传感器：

![SPIKE 颜色传感器](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-5fd8088591b800739cbd7d8c76c60393cb08f269%2Fspike-color.png?alt=media)

[SPIKE 颜色传感器，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=37308c01)

颜色和距离传感器：

![颜色和距离传感器](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-653ecb38c387ec5140fa1f36adecad6543d7c40c%2Fcolor-distance.png?alt=media)

[颜色距离传感器，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0891c01)

这些颜色传感器具有多种属性和函数。你可以获取 `Color`、`ReflectedLight` 和 `AmbiantLight`。

除此之外，颜色和距离传感器还可以测量 `Distance`，并带有一个物体计数器 `Counter`。它会自动计算进出量程的物体数量，从而可以统计经过传感器前方的物体。距离限制在 0 到 10 厘米之间。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortC);

var colorSensor = (ColorAndDistanceSensor)brick.GetActiveSensor(SensorPort.PortC);
while (!Console.KeyAvailable)
{
    var colorRead = colorSensor.GetColor();
    Console.WriteLine($"Color:     {colorRead}");
    var reflected = colorSensor.GetReflectedLight();
    Console.WriteLine($"Reflected: {reflected}");
    var ambiant = colorSensor.GetAmbiantLight();
    Console.WriteLine($"Ambiant:   {ambiant}");
    var distance = colorSensor.GetDistance();
    Console.WriteLine($"Distance: {distance}");
    var counter = colorSensor.GetCounter();
    Console.WriteLine($"Counter:  {counter}");
    Thread.Sleep(200);
}
```

> **注意**
>
> 为了获得更好的测量结果，不建议非常频繁地更改测量模式，否则颜色积分可能无法正确完成。这个示例涵盖了该传感器能做的全部事情。此外，该类没有实现连续测量模式。你可以通过高级模式，使用 `SelectModeAndRead` 函数设置你想要持续使用的特定模式。需要注意，更改模式或设置新模式会停止之前的模式。

#### SPIKE Prime 超声波距离传感器

![SPIKE 超声波距离传感器](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-2cb55a1c4ebce7fb25b59640ceb221e10de14e64%2Fspike-distance.png?alt=media)

[超声波距离传感器，来自 Bricklink 的图片](https://www.bricklink.com/v2/catalog/catalogitem.page?P=37316c01)

这是一个距离传感器，它实现了 `Distance` 属性，可提供以毫米为单位的距离。它还提供 `ContinuousMeasurement` 模式。

```csharp
brick.WaitForSensorToConnect(SensorPort.PortA);
var distance = (UltrasonicDistanceSensor)brick.GetSensor(SensorPort.PortA);
distance.ContinuousMeasurement = true;
while(!console.KeyAvailable)
{
    console.WriteLine($"Distance: {distance.Distance} mm");
    Thread.Sleep(200);
}
```

## 更多资源

你可以下载以下文档：

* [树莓派 Build HAT 串行协议](https://pip.raspberrypi.com/documents/RP-008140-DS)
* [树莓派 Build HAT Python 库](https://pip.raspberrypi.com/documents/RP-008139-DS)

Python 库文档的完整详细信息也可以在 [ReadTheDocs](https://buildhat.readthedocs.io/) 上找到。你可以在 [.NET IoT](https://github.com/dotnet/iot/tree/main/src/devices/BuildHat) GitHub 存储库中找到有关 .NET 库的更多信息。

你还可以跟着树莓派基金会的项目一起做：

* [乐高®游戏控制器](https://projects.raspberrypi.org/en/projects/lego-game-controller)
* [乐高®机器人车](https://projects.raspberrypi.org/en/projects/lego-robot-car)
* [乐高®绘图仪](https://projects.raspberrypi.org/en/projects/lego-plotter)
* [乐高®机器人脸](https://projects.raspberrypi.org/en/projects/lego-robot-face)
* [乐高®数据仪表板](https://projects.raspberrypi.org/en/projects/lego-data-dash)

## 设备兼容性

Build 扩展板库支持 SPIKE™ 系列产品中包含的所有乐高®机械组（LEGO® Technic™）设备，以及来自乐高® Mindstorms 机器人发明家（Robot Inventor）套件和其他使用 PoweredUp 连接器的设备。

> **重要**
>
> 包含 Maker Plate 的 SPIKE™ Prime 扩展套装的产品代码为 45681。最初的扩展套装为 45680，不包含 Maker Plate。

| 说明              | 颜色    | 乐高物品编号                           | 在固件中支持 | 在 Python 中支持 | 替代编号           | BrickLink                                                               | 可用于                                                               | 套装编号                | 类              | 类型 | 设备标识 |
| --------------- | ----- | -------------------------------- | ------ | ------------ | -------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------- | -------------- | -- | ---- |
| 大型角度电机          | 白色/青色 | 45602                            | 是      | 是            | 45602          | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=54675c01)  | SPIKE Prime 套装、SPIKE Prime 扩展套装                                   | 45678, 45680        | Motor          | 主动 | 31   |
| 中型角度电机          | 白色/青色 | 45603                            | 是      | 是            | 45603          | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=54696c01)  | SPIKE Prime 套装                                                    | 45678               | Motor          | 主动 | 30   |
| 中型角度电机          | 白色/灰色 | 6299646, 6359216, 6386708        | 是      | 是            | 436655         | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=54696c01)  | Mindstorms 机器人发明家                                                 | 51515               | Motor          | 主动 | 4B   |
| 小型角度电机          | 白色/青色 | 45607, 6296520                   | 是      | 是            |                | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=68488c01)  | SPIKE Essential 套装                                                |                     | Motor          | 主动 | 41   |
| 光/颜色传感器         | 白色/黑色 | 6217705                          | 是      | 是            |                | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=37308c01)  | SPIKE Prime 套装、SPIKE Prime 扩展套装、Mindstorms 机器人发明家、SPIKE Essential | 45678, 45680, 51515 | ColorSensor    | 主动 | 3D   |
| 距离传感器           | 白色/黑色 | 6302968                          | 是      | 是            |                | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=37316c01)  | SPIKE Prime 套装、Mindstorms 机器人发明家                                  | 45678, 51515        | DistanceSensor | 主动 | 3E   |
| 系统中型电机          | 白色/灰色 | 45303, 6138854, 6290182, 6127110 | 是      | 是            |                | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=21980)     | WeDo 2.0、乐高 Ideas 钢琴、App 控制的蝙蝠车                                   | 76112               |                | 被动 | 1    |
| 力传感器            | 白色/黑色 | 6254354                          | 是      | 是            | 45606          | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=37312c01)  | SPIKE Prime 套装                                                    | 45678               | ForceSensor    | 主动 | 3F   |
| 3×3 LED         | 白色/青色 | 45608, 6297023                   | 是      | 是            |                | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=47592c01)  | SPIKE Essential                                                   |                     | Matrix         | 主动 | 40   |
| 系统火车电机          | 黑色    | 88011                            | 是      | 是            | 28740, 88011-1 | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0896c01) | 货运火车、迪士尼火车和车站、客运列车                                                |                     |                | 被动 | 2    |
| PoweredUp LED 灯 | 黑色    | 88005                            | 是      |              |                | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=22168c01)  |                                                                   |                     |                | 被动 | 8    |
| 中型线性电机          | 白色/灰色 | 88008                            | 是      | 是            | 26913, 88008-1 | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0893c01) | Boost、Droid Commander                                             |                     | Motor          | 主动 | 26   |
| Technic 大型电机    | 灰色/灰色 | 88013                            | 是      | 是            | 22169          | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0959c01) |                                                                   |                     |                | 主动 | 2E   |
| Technic XL 电机   | 灰色/灰色 | 88014                            | 是      | 是            | 22172, 88014   | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0960c01) |                                                                   |                     |                | 主动 | 2F   |
| 颜色 + 距离传感器      | 白色/灰色 | 88007                            | 部分     | ？            | 26912          | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=bb0891c01) |                                                                   |                     |                | 主动 | 25   |
| WeDo 2.0 运动传感器  | 白色/灰色 | 45304, 6138855                   |        |              | 5003423-1      | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=43718)     |                                                                   |                     |                | 主动 | 35   |
| WeDo 2.0 倾斜传感器  | 白色/灰色 | 45305, 6138856                   |        |              | 5003423-1      | [链接](https://www.bricklink.com/v2/catalog/catalogitem.page?P=14618)     |                                                                   |                     |                | 主动 | 34   |

## 机械图纸

树莓派 Build 扩展板的机械图纸。

![Build 扩展板机械图纸](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-3816fa65b5c7606527682bc400a10aed0145c466%2Fmech-build-hat.png?alt=media)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://book.bsdcn.org/rpicn/pei-jian/build-hat.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
