# 示例教程

FastBee-Arduino 配置示例大全，涵盖基础 GPIO 操作、传感器接入、显示控制、通信协议及 Modbus 子设备接入。

> 推荐阅读：[模块和传感器清单](https://www.fastbee.cn/doc/device/v2/getting-started/supported-sensors-and-modules.md) - 先确认外设类型和运行时开关；[传感器与模块完整指南](https://www.fastbee.cn/doc/device/v2/peripherals/sensor-guide-complete.md) - 查看详细配置参考

## 硬件案例

以下示例分别对应不同硬件和配置，不能互相复制 JSON：

| 环境 | 示例 | 主要内容 |
| --- | --- | --- |
| `esp32c3-F4R0` | [C3 温湿度](https://www.fastbee.cn/doc/device/v2/examples/esp32c3-temperature-humidity.md) | OLED、温湿度与低内存使用 |
| `esp32c3-F4R0`（先核实 Flash） | [C3 智能开关面板](https://www.fastbee.cn/doc/device/v2/examples/esp32c3-smart-switch-panel.md) | 零火版 1/2/3 开、按键单击、继电器与 Web 同步；资料核对完成，实物待验证 |
| `esp32c6-F4R0` | [C6 RGB 快速开始](https://www.fastbee.cn/doc/device/v2/examples/esp32c6-blink-quickstart.md) | GPIO8 WS2812 和定时/平台联动 |
| `esp32-F4R0` | [普中 ESP32 测试](https://www.fastbee.cn/doc/device/v2/examples/puzhong-esp32-test.md) | 经典 ESP32 外设和规则 |
| `esp32s3-F16R8` | [ECM50-A 联网与工业采集](https://www.fastbee.cn/doc/device/v2/examples/ecm50a-networking.md) | AI/DI、SHT30、Modbus RTU、以太网和 4G |
| `esp32s3-F8R0` | [Waveshare 6 路继电器](https://www.fastbee.cn/doc/device/v2/examples/waveshare-esp32s3.md) | 6 路继电器、WS2812 和 RS485 |
| `esp32s3-F16R8` | [Waveshare 4 英寸触控屏](https://www.fastbee.cn/doc/device/v2/examples/waveshare-esp32s3-touch-lcd4.md) | RGB 显示、GT911 触摸、Web 拖拽编辑与通用设备控制 |

已有案例的对应 JSON 保存在 FastBee-Arduino 源码仓库的 `docs/` 下；智能开关面板案例提供字段说明与原始 Arduino 代码，专用配置须在实物身份确认后建立，不能套用 COM4 温湿度配置。导入前先核对芯片、引脚和本机网络参数；公开示例不包含生产 WiFi 或 MQTT 凭据。

## 示例列表

### 基础实验（01-24）

| 编号 | 名称 | 核心外设类型 |
|------|------|-------------|
| [01](https://www.fastbee.cn/doc/device/v2/examples/01-led-first.html) | LED 点亮 | GPIO\_DIGITAL\_OUTPUT |
| [02](https://www.fastbee.cn/doc/device/v2/examples/02-led-blink.html) | LED 闪烁 | GPIO\_DIGITAL\_OUTPUT + periph-exec |
| [03](https://www.fastbee.cn/doc/device/v2/examples/03-led-flowing.html) | LED 流水灯 | 多 GPIO + PERIPH/DELAY 命令脚本 |
| [03b](https://www.fastbee.cn/doc/device/v2/examples/03b-led-flowing-command-script.html) | LED 流水灯（命令脚本） | 多 GPIO + PERIPH/DELAY 命令序列 |
| [04](https://www.fastbee.cn/doc/device/v2/examples/04-buzzer.html) | 蜂鸣器 | GPIO\_DIGITAL\_OUTPUT / PWM |
| [05](https://www.fastbee.cn/doc/device/v2/examples/05-relay.html) | 继电器 | GPIO\_DIGITAL\_OUTPUT |
| [06](https://www.fastbee.cn/doc/device/v2/examples/06-button-control.html) | 按键控制 | GPIO\_DIGITAL\_INPUT\_PULLUP |
| [07](https://www.fastbee.cn/doc/device/v2/examples/07-dc-motor.html) | 直流电机 | GPIO\_DIGITAL\_OUTPUT |
| [08](https://www.fastbee.cn/doc/device/v2/examples/08-stepper-motor.html) | 步进电机 | STEPPER\_MOTOR |
| [09](https://www.fastbee.cn/doc/device/v2/examples/09-external-interrupt.html) | 外部中断 | GPIO\_INTERRUPT |
| [10](https://www.fastbee.cn/doc/device/v2/examples/10-timer-interrupt.html) | 定时触发 | TIMER\_TRIGGER |
| [11](https://www.fastbee.cn/doc/device/v2/examples/11-pwm-breathing.html) | PWM 呼吸灯 | GPIO\_PWM\_OUTPUT |
| [12](https://www.fastbee.cn/doc/device/v2/examples/12-uart-communication.html) | 串口通信 | UART |
| [13](https://www.fastbee.cn/doc/device/v2/examples/13-adc-voltage.html) | ADC 电压采集 | GPIO\_ANALOG\_INPUT |
| [14](https://www.fastbee.cn/doc/device/v2/examples/14-rgb-neopixel.html) | RGB 灯带 | NEO\_PIXEL |
| [15](https://www.fastbee.cn/doc/device/v2/examples/15-seven-segment.html) | 数码管显示 | SEVEN\_SEGMENT\_TM1637 |
| [16](https://www.fastbee.cn/doc/device/v2/examples/16-rtc-clock.html) | NTP 时钟 | 系统 NTP + 定时 |
| [17](https://www.fastbee.cn/doc/device/v2/examples/17-ds1302-rtc.html) | DS1302 RTC | 外部 RTC |
| [18](https://www.fastbee.cn/doc/device/v2/examples/18-ds18b20-temperature.html) | DS18B20 温度 | SENSOR(ONE\_WIRE) |
| [19](https://www.fastbee.cn/doc/device/v2/examples/19-dht11-humidity.html) | DHT11 温湿度 | SENSOR(DHT) |
| [20](https://www.fastbee.cn/doc/device/v2/examples/20-ultrasonic-distance.html) | 超声波测距 | SENSOR(HC-SR04) |
| [21](https://www.fastbee.cn/doc/device/v2/examples/21-ir-remote.html) | 红外遥控 | IR\_REMOTE（按环境编译；S3 F8R8 已裁剪） |
| [22](https://www.fastbee.cn/doc/device/v2/examples/22-servo-sg90.html) | 舵机控制 | PWM\_SERVO |
| [23](https://www.fastbee.cn/doc/device/v2/examples/23-oled-display.html) | OLED 显示 | LCD(SSD1306) |
| [24](https://www.fastbee.cn/doc/device/v2/examples/24-sd-card.html) | SD 卡读写 | SPI SD存储、只读状态38、专用数值记录40 |

### 扩展实验（25-44）

| 编号 | 名称 | 核心外设类型 |
|------|------|-------------|
| [25](https://www.fastbee.cn/doc/device/v2/examples/25-laser-sensor.html) | 激光传感器 | GPIO\_DIGITAL\_OUTPUT |
| [26](https://www.fastbee.cn/doc/device/v2/examples/26-tilt-sensor.html) | 倾斜传感器 | GPIO\_DIGITAL\_INPUT\_PULLUP |
| [27](https://www.fastbee.cn/doc/device/v2/examples/27-vibration-sensor.html) | 震动传感器 | GPIO\_DIGITAL\_INPUT |
| [28](https://www.fastbee.cn/doc/device/v2/examples/28-reed-switch.html) | 干簧管 | GPIO\_DIGITAL\_INPUT |
| [29](https://www.fastbee.cn/doc/device/v2/examples/29-photoelectric-sensor.html) | 对射光电 | GPIO\_DIGITAL\_INPUT |
| [30](https://www.fastbee.cn/doc/device/v2/examples/30-rain-sensor.html) | 雨滴传感器 | ADC + GPIO |
| [31](https://www.fastbee.cn/doc/device/v2/examples/31-ps2-joystick.html) | PS2 摇杆 | 双 ADC + 按键 |
| [32](https://www.fastbee.cn/doc/device/v2/examples/32-sound-sensor.html) | 声音传感器 | GPIO\_ANALOG\_INPUT |
| [33](https://www.fastbee.cn/doc/device/v2/examples/33-light-sensor.html) | 光敏传感器 | GPIO\_ANALOG\_INPUT |
| [34](https://www.fastbee.cn/doc/device/v2/examples/34-flame-sensor.html) | 火焰传感器 | GPIO\_ANALOG\_INPUT |
| [35](https://www.fastbee.cn/doc/device/v2/examples/35-smoke-sensor.html) | 烟雾传感器 MQ-2 | GPIO\_ANALOG\_INPUT |
| [36](https://www.fastbee.cn/doc/device/v2/examples/36-touch-sensor.html) | 触摸传感器 | 外接TTP223数字输出（GPIO输入） |
| [37](https://www.fastbee.cn/doc/device/v2/examples/37-rotary-encoder.html) | 旋转编码器 | ENCODER |
| [38](https://www.fastbee.cn/doc/device/v2/examples/38-ir-obstacle.html) | 红外避障 | GPIO\_DIGITAL\_INPUT |
| [39](https://www.fastbee.cn/doc/device/v2/examples/39-lcd1602-display.html) | LCD1602 显示 | LCD1602（type:52，默认关闭） |
| [40](https://www.fastbee.cn/doc/device/v2/examples/40-bmp280-pressure.html) | BMP280 气压 | I2C SENSOR（需启用 i2cSensors） |
| [41](https://www.fastbee.cn/doc/device/v2/examples/41-mpu6050-gyro.html) | MPU6050 陀螺仪 | I2C SENSOR（需启用 i2cSensors） |
| [42](https://www.fastbee.cn/doc/device/v2/examples/42-ir-tracking.html) | 红外寻迹 | GPIO\_DIGITAL\_INPUT |
| [43](https://www.fastbee.cn/doc/device/v2/examples/43-rfid-mfrc522.html) | RFID 射频卡 | SPI SENSOR（需启用 rfid） |
| [44](https://www.fastbee.cn/doc/device/v2/examples/44-pir-motion.html) | 人体红外 PIR | GPIO\_DIGITAL\_INPUT |

### Modbus 子设备（45-48）

| 编号 | 名称 | 核心外设类型 |
|------|------|-------------|
| [45](https://www.fastbee.cn/doc/device/v2/examples/45-modbus-temp-humidity.html) | Modbus 温湿度传感器 | UART(Modbus RTU) |
| [46](https://www.fastbee.cn/doc/device/v2/examples/46-modbus-stepper-motor.html) | Modbus 步进电机控制 | UART(Modbus RTU) |
| [47](https://www.fastbee.cn/doc/device/v2/examples/47-modbus-relay.html) | Modbus 继电器模块 | UART(Modbus RTU) |
| [48](https://www.fastbee.cn/doc/device/v2/examples/48-modbus-soil-sensor.html) | Modbus 土壤传感器 | UART(Modbus RTU) |

### 射频与雷达（49-50）

| 编号 | 名称 | 核心外设类型 |
|------|------|-------------|
| [49](https://www.fastbee.cn/doc/device/v2/examples/49-433mhz-rf-module.html) | 433MHz 射频模块 | RF\_MODULE |
| [50](https://www.fastbee.cn/doc/device/v2/examples/50-radar-sensor.html) | 雷达感应模块 | RADAR\_SENSOR |

### 显示联动（51-52）

| 编号 | 名称 | 核心外设类型 |
|------|------|-------------|
| [51](https://www.fastbee.cn/doc/device/v2/examples/51-display-temperature-oled.html) | OLED 温湿度显示 | LCD + SENSOR + 模板变量 |
| [52](https://www.fastbee.cn/doc/device/v2/examples/52-display-temperature-tm1637.html) | TM1637 温湿度显示 | TM1637 + SENSOR |

### Modbus 控制与采集（53-54）

| 编号 | 名称 | 核心外设类型 |
|------|------|-------------|
| [53](https://www.fastbee.cn/doc/device/v2/examples/53-modbus-control-devices.html) | Modbus 控制设备 | MODBUS\_DEVICE + 轮询触发 |
| [54](https://www.fastbee.cn/doc/device/v2/examples/54-modbus-sensor-devices.html) | Modbus 传感器设备 | MODBUS\_DEVICE + 定时采集 |

## 最佳实践

### 引脚分配原则

> 完整的引脚分配原则、硬件约束和冲突检测机制详见 [外设配置指南](https://www.fastbee.cn/doc/device/v2/peripherals.md)。经典ESP32需注意GPIO34-39输入限制、Flash保留引脚和ADC2/WiFi冲突；其他芯片按其板级能力核验，不套用该引脚表。

### 传感器配置建议

* **DHT11/DHT22**: 采样间隔 >= 2 秒,避免读取过快导致数据异常
* **DS18B20**: 单总线可并联多个传感器,通过地址区分
* **I2C 设备**: 可共用 SDA/SCL,但 I2C 地址不能冲突
* **超声波 HC-SR04**: 触发引脚和回声引脚需不同,规则间隔定时至少1秒，按实际回波与负载选择
* **BMP280/MPU6050**: 发布环境编译支持，需启用 `FASTBEE_ENABLE_I2C_SENSORS` 和运行时 `i2cSensors`

### 外设执行规则设计

* **定时采集**: intervalSec >= 5 秒,避免频繁读取传感器
* **事件触发**: 先确认采集规则已生成 `ds:<id>_<field>` 数据源
* **联动控制**: 注意继电器有效电平 (高有效/低有效)
* **脚本执行**: 需启用 `commandScript` / `ruleScript`，并通过运行时内存预算检查
* **同步延时**: 按动作顺序需要设置执行前syncDelayMs（最多10000ms）；延时不替代资源仲裁

## 联动配置入口

温湿度采集及阈值见[示例19](https://www.fastbee.cn/doc/device/v2/examples/19-dht11-humidity.md)，OLED先读取两个字段再显示见[示例51](https://www.fastbee.cn/doc/device/v2/examples/51-display-temperature-oled.md)，Modbus任务/映射见[示例45](https://www.fastbee.cn/doc/device/v2/examples/45-modbus-temp-humidity.md)。ADC原始值不等于lux、ppm或mV；电流阈值规则不能代替硬件过流保护。按键用单击事件，数字输入变化用ds:外设ID，传感器采样用ds:外设ID\_字段；不可混用。

## 固件兼容性

发布环境共享统一功能基线，但仍会按环境裁剪硬件相关能力。具体功能是否可用，以 PlatformIO 环境覆盖、Web“功能配置”页和 `/api/system/status` 返回的运行时状态为准；4MB 单应用环境不支持 OTA，C3/C6 发布环境不提供以太网或 4G。基础菜单始终显示，可选菜单仅在对应功能为 `active` 时显示。

## 相关文档

* [外设管理](https://www.fastbee.cn/doc/device/v2/system/peripheral-management.md) — 添加和配置外设
* [外设执行管理](https://www.fastbee.cn/doc/device/v2/periph-exec.md) — 规则联动配置
* [外设文档](https://www.fastbee.cn/doc/device/v2/peripherals.md) — 各外设类型详细说明
* [Modbus RTU 协议](https://www.fastbee.cn/doc/device/v2/protocols/modbus-rtu.md) — Modbus 通信配置
