# OAK4 SoM 开发指南

Luxonis OAK4 SoM 设备支持灵活的外设配置，用户可以在多种引脚上启用或禁用 I2C、SPI 和 UART 功能。

默认情况下，大多数引脚配置为通用 I/O（GPIO）。然而，用户可以将支持的引脚重新配置为外设接口。需要注意的是，并非所有引脚都支持所有外设。下表列出了可用的 QUPv3 和 I2CHUB 引擎以及各自的配置方式。

如果您的用例需要表中未列出的配置，或者引脚标记为“当前未开放”，请联系 Luxonis 技术支持以帮助创建具有不同开放选项的自定义配置。

| **QUPv3 引擎** | **模式** | **引脚** | **备注** |
| --- | --- | --- | --- |
| QUPv3_SE0 | I2C | SDA: GPIO28SCL: GPIO29 | |
| QUPv3_SE1 | SPI | MISO: GPIO32MOSI: GPIO33SCLK: GPIO34CS0: GPIO35 | |
| QUPv3_SE2 | SPI | MISO: GPIO36MOSI: GPIO37SCLK: GPIO38CS0: GPIO39CS1: GPIO40CS2: GPIO41CS3: GPIO42 | |
| QUPv3_SE3 | / | / | 当前未开放 |
| QUPv3_SE4 | I2C | SDA: GPIO44SCL: GPIO45 | 默认启用 |
| QUPv3_SE5 | I2C | SDA: GPIO52SCL: GPIO53 | |
| QUPv3_SE6 | / | / | 当前未开放 |
| QUPv3_SE7 | UART | TX: GPIO26RX: GPIO27 | |
| QUPv3_SE8 | I2C | SDA: GPIO0SCL: GPIO1 | |
| QUPv3_SE9 | I3C | SDA: GPIO60SCL: GPIO61 | |
| QUPv3_SE10 | SPI | MISO: GPIO64MOSI: GPIO65SCLK: GPIO66CS0: GPIO67 | |
| QUPv3_SE11 | SPI | MISO: GPIO68MOSI: GPIO69SCLK: GPIO70CS0: GPIO71 | |
| QUPv3_SE12 | I2C | SDA: GPIO2SCL: GPIO3 | 默认启用 |
| QUPv3_SE13 | / | / | 当前未开放 |
| QUPv3_SE14 | UART | CTS: GPIO76RFR: GPIO77TX: GPIO78RX: GPIO79 | 高速 UART，硬件流控制 |
| QUPv3_SE15 | / | / | 当前未开放 |
| I2CHUB_SE0 | / | / | 当前未开放 |
| I2CHUB_SE1 | / | / | 当前未开放 |
| I2CHUB_SE2 | I2C | SDA: GPIO20SCL: GPIO21 | 默认启用 |
| I2CHUB_SE3 | I2C | SDA: GPIO22SCL: GPIO23 | |
| I2CHUB_SE4 | I2C | SDA: GPIO4SCL: GPIO5 | |
| I2CHUB_SE5 | / | / | 当前未开放 |
| I2CHUB_SE6 | / | / | 当前未开放 |
| I2CHUB_SE7 | / | / | 当前未开放 |
| I2CHUB_SE8 | / | / | 当前未开放 |
| I2CHUB_SE9 | / | / | 当前未开放 |

## 设备树覆盖配置

外设配置通过设备树覆盖（DTO）实现，这些覆盖在启动时应用。覆盖必须放置在设备上的 /persist/custom/dtbo 目录中。系统启动时，会应用此目录中的所有覆盖以达到所需的引脚配置。此文件夹中的文件在OTA更新后仍会保留，不会被删除。

## I2C配置示例

### 通过I2C连接BME280传感器

假设您想使用GPIO52（SDA）和GPIO53（SCL）连接博世BME280压力传感器。根据上表，这些引脚由QUPv3 SE5引擎管理。

要启用此接口，请在工作目录中创建设备树覆盖（例如 bme280.dts）：

```dts
/dts-v1/;
/plugin/;

/ {
  fragment@0 {
    target = <&qupv3_se5_i2c>;
    __overlay__ {
      status = "ok";
      #address-cells = <1>;
      #size-cells = <0>;

      bme280@76 {
        compatible = "bosch,bme280";
        reg = <0x76>;
      };
    };
  };
};
```

关键行是 status = "ok";，它实际启用所选的I2C引擎。没有它，外设将保持禁用状态。

> **注意：**
> 对于
> `target`
> ，QUP引擎使用
> `&qupv3_seX_i2c`
> ，HUB引擎使用
> `&qupv3_hub_i2cX`
> ，其中
> `X`
> 是引擎索引。

### 编译覆盖

使用SDK Docker容器编译源文件。在工作目录内运行以下命令：

```bash
docker run --rm \
  -v /etc/passwd:/etc/passwd:ro \
  -v /etc/shadow:/etc/shadow:ro \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  --user=$(id -u):$(id -g) --group-add 27 \
  luxonis/luxonis-os-rvc4:<SDK_version>-public \
  /bin/bash -c "dtc -@ -I dts -O dtb -o bme280.dtbo bme280.dts"
```

> **注意：**
> `<SDK_version>`
> 必须与目标设备刷写的OS版本一致（例如
> `1.8.0`
> ）。如果您使用的是最新的OS版本，也可以使用
> `latest`
> 。

将编译好的 .dtbo 文件传输到目标设备：

```bash
scp /app/test-overlay/bme280.dtbo user@<device-ip>:/persist/custom/dtbo/
```

然后重启设备。启动时，覆盖将自动应用。通过检查 /sys/bus/i2c/devices/ 来验证I2C设备是否已注册。

## SPI配置示例

启用SPI接口的过程类似。以下是在QUPv3 SE1上启用SPI的DTO示例：

```dts
/dts-v1/;
/plugin/;

/ {
  fragment@0 {
    target = <&qupv3_se1_spi>;
    __overlay__ {
      status = "ok";
    };
  };
};
```

编译并传输覆盖：

```bash
docker run --rm \
  -v /etc/passwd:/etc/passwd:ro \
  -v /etc/shadow:/etc/shadow:ro \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  --user=$(id -u):$(id -g) --group-add 27 \
  luxonis/luxonis-os-rvc4:latest-public \
  /bin/bash -c "dtc -@ -I dts -O dtb -o spi-overlay.dtbo spi-overlay.dts"
```

```bash
scp spi_se1.dtbo user@<device-ip>:/persist/custom/dtbo/
```

重启设备后，SPI接口即应启用。

## 出厂模式

出厂模式是Luxonis OS的一种模式，使设备在工厂环境中易于使用。它对于测试设备非常有用。它可以在任何类型的OAK4设备上启用，但对于使用SoM开发的人尤其有用，这些SoM默认也以出厂模式发货。

出厂模式会移除 root 用户的密码，并允许使用空密码通过SSH登录（无密码登录）。

通过创建 /persist/factory/enabled 文件（文件内容无关紧要）进入出厂模式。

启动时，如果找到此文件，出厂模式即被触发。

要恢复并退出出厂模式，在系统上运行此命令：

```bash
rm /persist/factory/enabled && cp -r /persist/factory/original_files/* / && rm -rf /persist/factory/original_files && sync && reboot
```

下次启动时，系统将以正常模式运行，默认root密码为 oelinux123，SSH密码登录被禁用。

## 故障排除

如果尝试了不受支持的外设配置——例如将外设分配给不兼容的QUPv3引擎——设备可能无法启动。在这种情况下，TrustZone引擎阻止了系统继续运行。

要恢复：

 1. 进入紧急下载模式（EDL）。
 2. 使用已知良好的镜像重新刷写设备。

有关如何执行完整OS刷写的步骤，请查看以下页面：[完整OS刷写](https://docs.luxonis.com/software-v3/sw-stack/luxonis-os.md)。

为了帮助调试，请使用 dmesg 检查内核消息：

```bash
dmesg | less
```

查找与设备树解析、外设激活或安全策略违规相关的错误。可选地，检查设备树覆盖加载脚本的日志：

```bash
journalctl -u apply-overlays.service
```