个人翻译的 HomeSpan 2.1.7（家庭扩展），请前往原文 下载 体验。

欢迎使用 HomeSpan - 一个强大且极其易于使用的 Arduino 库，完全在 Arduino IDE 内创建你自己的基于 ESP32 的 HomeKit 设备。

HomeSpan 实现了以微控制器为中心的 Apple HomeKit 附件协议规范版本 R2 (HAP-R2)，专为在 Arduino IDE 中运行的乐鑫 ESP32 微控制器设计。HomeSpan 通过家庭无线网络与 HomeKit 配对，无需任何外部网桥。通过 HomeSpan，你可以使用 ESP32 I/O 的全部功能来创建自定义控制软件和/或硬件，并能以 iPhone、iPad 或 Mac 上的“家庭”应用或 Siri 自动操作外部设备。

• 提供自然、直观且非常易于使用的框架
• 利用独特以服务为中心的方法创建 HomeKit 设备
• 充分利用广受欢迎的 Arduino IDE
• 完全符合 HAP-R2 标准
• 数十种集成 HomeKit 服务
• 支持附件模式和桥接模式
• 支持通过与设置码或二维码配对
• 支持与家庭无线网络和以太网连接
• 支持 IPv4 和 IPv6 地址的双栈使用

• Arduino 串行监视器的广泛使用
  • 实时、易于理解的诊断
  • 对每个底层 HomeKit 操作、数据请求和数据响应完全透明
  • 具有各种信息、调试和配置命令的命令行界面
• 内置数据库验证，确保配置满足所有 HAP 要求
• 利用 ESP32 的 16 通道 PWM 外设的专用类，可轻松控制：
  • LED 亮度（包括自动淡化）
  • 伺服电机
• 集成按钮和拨动开关功能，支持单击、双击和长按：
  • 将 ESP32 引脚连接到地或 VCC 的物理按钮
  • 连接到 ESP32 引脚的触摸板/传感器（用于支持触摸板的 ESP32 设备）
• 集成对 ESP32 片上远程控制外设的访问，可轻松生成红外和射频信号
• 控制单线和双线可寻址 RGB 和 RGBW LED 和 LED 灯带的专用类
• 专门用于控制步进电机的类，可以在后台平稳运行，而不会干扰 HomeSpan 设备
• 使用 ESP-NOW 在 ESP32 设备之间实现点对点通信的专用类
• 用于用户定义的日志消息的集成网络日志
• 带有大量注释的教程示例，将带你体验从 HomeSpan 的基础知识到高级 HomeKit 主题
• 展示 HomeSpan 实现的其他示例和项目
• 一套完整的文档，全面解释了 HomeSpan 的各种 API

• 嵌入式无线网络接入点和网络界面，允许最终用户（非开发人员）：
  • 使用自己的家庭无线凭据设置 HomeSpan
  • 创建自己的 HomeKit 配对设置代码
• 状态指示灯和控制按钮，允许最终用户：
  • 强制解除设备与 HomeKit 的配对
  • 执行恢复出厂设置
  • 启动无线网络接入点
• 独立、详细的最终用户指南

• HomeSpan 现在支持基于 WS2801 的双线可寻址 RGB LED

  • 新增 WS2801_LED 类
  • 使用 SPI 总线以获得最佳性能
  • 包含与 HomeSpan 现有 Pixel 和 Dot 类相同的 set() 和 Color() 方法：
  • 在 HomeSpan 的 Pixels 教程草图中添加了一个完整的示例，演示如何实现一个 25 像素的 WS2801 RGB LED 灯串。
  • 请参阅 Pixels 页面以获取完整文档。

• 修正了 Dot 类中的开始/结束块逻辑，以提高 DotStar RGB LED 的性能。
• 将 Arduino-ESP32 Core 的最低版本要求从 3.1.0 提升至 3.3.0。
  • 反映了 HomeSpan 2.1.6 版本中引入的重大变更。

有关此版本中包含的所有更改和错误修复的详细信息，请参阅 发布 更新。

HomeSpan 更新明细

HomeSpan 包括以下文档：

• HomeSpan 入门 - 设置开发 HomeSpan 设备所需的软件和硬件
• HomeSpan API 概述 - HomeSpan API 概述，包括开发第一个 HomeSpan 示例的分步指南
• HomeSpan 教程 - HomeSpan 的示例指南
• HomeSpan 服务和特性 - HomeSpan 支持的所有 HAP 服务和特性的列表
• HomeSpan 附件类别 - HomeSpan 定义的所有 HAP 附件类别的列表
• HomeSpan 命令行界面 - 配置 HomeSpan 设备的无线凭据，修改其设置代码，监控和更新其状态，并从 Arduino IDE 串行监视器访问详细的实时设备诊断
• HomeSpan 无线和以太网连接 - HomeSpan 无线网络和以太网连接选项的高级讨论
• HomeSpan 用户指南 - 有关如何配置已编程的 HomeSpan 设备的无线凭据、修改其设置代码以及将设备与 HomeKit 配对的交钥匙式说明。不需要电脑！
• HomeSpan API 参考 - HomeSpan 库 API 的完整指南
• HomeSpan 二维码 - 创建并使用二维码来配对 HomeSpan 设备
• HomeSpan OTA - 直接从 Arduino IDE 无线更新示例，无需串行连接
• HomeSpan 看门狗定时器 - 可选的保护功能，如果您的示例长时间挂起或冻结，可以触发自动重启
• HomeSpan PWM - 使用 ESP32 的片载 PWM 外设集成控制标准 LED 和伺服电机
• HomeSpan 射频控制 - 使用 ESP32 的片载 RMT 外设，轻松生成射频和红外遥控信号
• HomeSpan 灯带 - 可寻址的单线和双线 RGB 和 RGBW LED 和 LED 灯带的集成控制
• HomeSpan 控制步进电机 - 步进电机集成控制，包括 PWM 微步进
• HomeSpan Span 热点 - 使用 ESP-NOW 促进 ESP32 设备之间的点对点双向通信
• HomeSpan 电视服务 - 如何使用 HomeKit 未记录的电视服务和特性
• HomeSpan 消息日志记录 - 如何生成在 Arduino 串行监视器上显示的日志消息，以及可选地发布到集成的网络日志页面
• HomeSpan TLV8 特性 - 用于创建 TLV8 对象以与基于 TLV8 的特性一起使用的类和方法
• HomeSpan 设备复制 - 将损坏的设备无缝更换为新设备，而无需重新配对和丢失 HomeKit 自动化
• HomeSpan 项目 - HomePan 库的实际应用
• HomeSpan FAQ - 常见问题解答
• 常见问题的解决方案 - 解决使用/编译 HomeSpan 时的一些常见问题
• HomeSpan 推荐示例 - 一系列独立的参考示例，展示了一些更复杂的 HomeKit 服务，如恒温器和灌溉系统

请注意，所有文档都是受版本控制的，并与每个分支相关联。master 分支通常指向最新版本。当可用时，该 dev 分支将包含正在开发的代码。

除了 HomeSpan 资源之外，刚接触 HomeKit 编程的开发人员可能会发现 Apple 的 HomeKit 附件协议规范非商业版本 R2 (HAP-R2) 的第 8 章和第 9 章非常有用。不幸的是， Apple 不再提供这份文件（也许是因为它最后一次更新是在 2019 年 7 月，现在已经有些过时了）。但是，你可以在网络上的其他地方找到此文档的副本。请注意，Apple 并未将 HAP-R2 文档替换为用于非商业版本的任何其他版本，并且 Apple 的开源 HomeKit ADK 仅反映了原始的 HAP-R2 规格（而不是用于商业设备的 HomeKit 中提供的所有最新服务和特性）。

由于 HomeSpan 完全围绕 HAP-R2 构建，因此没有计划使 HomeSpan 与 Matter 兼容。此外，Apple 和乐鑫都发布了供公众使用的 Matter SDK，因此无需再额外开发 Matter SDK。

请将 HomeSpan 的错误报告或其他问题提交至 Issues 页面。请将有关 HomeSpan 的所有其他问题（使用、功能、规格、示例等）或你对新功能的任何想法、建议或有关 HomeSpan 或 HomeKit 的任何反馈发布到 Discussion 页面。对于与特定 HomeSpan 问题或与功能无关的更一般的问题或反馈，你可以直接 homespan@icloud.com 给我发电子邮件。

HomeSpan 由 Gregg Berman 开发并持续维护和支持。它最初是为了解决无法用 Siri 操作射频控制的厨房通风罩的麻烦问题。我希望你会发现它很有用，而且使用起来很有趣。

这是我的第二个大型开源项目——我的第一个项目是设计一个开源系统，用于操作铁路模型，仅使用 Arduino Uno 和 Arduino Motor Shield 来生成数字命令和控制 (DCC) 信号。虽然我已经多年没有参与铁路模型爱好的建设，但展示我的原始系统（称为 DCC++）的视频，以及它如何工作的详细教程，仍然可以在 DCC++ YouTube 频道 上找到。