马来西亚智能家居的 Matter 控制器：您真正需要什么
马来西亚智能家居的 Matter 控制器详解：为何要先有 Hub M3、Matter 比 Zigbee 多了什么，以及网络中断时哪些功能仍能运作。
开发者与集成商
AqaraLink 开发者平台 API：能为开发者提供什么
简要回答 — AqaraLink 是 Lumi United Technology 运营的 Aqara 开发者平台，分为两个层面：一是用于服务器对接的云端 HTTP API 加消息推送；二是 App SDK（Android 和 iOS），可把设备配网、控制、摄像头、门锁、曲线数据和 OTA 功能嵌入您自己的应用。opendoc.aqara.com 上的英文文档把 API 划分为 11 个模块。
这个平台到底是什么
Aqara 以 Zigbee 为主。大部分产品是由电池供电的子设备组成的网状网络，向网关汇报数据，再由网关连接云端。这一点决定了整个开发思路：您的应用不会直接连接 Seri Kembangan 某个单位里的传感器。您的应用连接的是该单位里的网关，再由网关去连接传感器。 您构建的一切都必须考虑到这一点。
文档把 AqaraLink 描述为 Lumi United Technology 的物联网软硬件产品开放合作平台，涵盖智能家居、酒店、办公室和教育。对马来西亚的集成商来说，真正有用的部分更具体：云端 API 让您的服务器查询设备状态、发送远程控制指令并配置联动/自动化；消息推送服务则让设备的实时上报直接送达您的服务器，无需轮询。
文档位于 opendoc.aqara.com。裸域名下是简体中文版本，开发时应以英文版为准。
两个层面，而不是一个
大多数集成失误，都是因为团队在第一天就选错了层面。
| 层面 | 适用情况 | 传输方式 | 逻辑由谁负责 |
|---|---|---|---|
| Cloud API | 由您的后台运行逻辑，例如物业管理系统、住户门户、监控仪表板 | HTTPS 请求/响应 | 您的服务器 |
| 消息推送 | 需要在服务器上接收设备事件，又不想轮询 | HTTP 推送或 MQ 推送 | 您的服务器，事件驱动 |
| App SDK | 最终用户必须使用您的应用，而不是 Aqara Home | 原生 SDK，Android 和 iOS | 您的应用 |
如果您做的是楼宇管理叠加层或设施应用，几乎可以肯定属于前两行。如果您做的是由自己负责设备入网的消费类应用，则属于第三行。第一行与第三行可以并存，但需要额外的工作量。
云端 API 模块一览
英文文档的 API List 章节分为 11 个模块。这就是整个 API 的轮廓，在写第一个请求之前值得先了解：
| 模块 | 涵盖内容 |
|---|---|
| Position management | 家庭 / 房间 / 区域的层级结构，需要在您自己的数据模型中对应建立 |
| Add device interface | 在您的授权下，把网关或设备添加到项目中 |
| Device management | 列出、查询、命名、共享和移除设备 |
| Device resource management | 设备所开放的每个资源的实时状态 |
| Device function interface (trait) | 支持的设备类型、支持的功能点、复杂 trait 详情 |
| IR device management | 红外遥控器及其码库 |
| Device firmware management | 固件查询与更新 |
| Linkage configuration interface | 读取已有自动化的定义 |
| Automation management | 创建、编辑、运行和删除自动化 |
| Scene management | 场景 |
| Multi-condition management | 自动化所使用的条件组合 |
有两点设计提示可以为您节省时间。第一，设备功能是基于 trait 的，而不是扁平的设备模型：您不会得到单一的“开关”API，而是一个 trait 层，附带支持的设备类型列表和支持的功能点列表。按 trait 来编写集成，日后增加新设备型号的成本会低得多。第二，固件管理是一等公民模块，意味着可以远程控制固件。请尽早决定项目是否允许平台自行升级，因为对于受管理的公寓楼群，您需要的是维护时段政策，而不是悄悄进行的更新。
授权：决定您数据模型的部分
文档介绍了三种授权模式，其中第三种对需要对接现有账号系统的人最重要。
- Aqara 账号授权：真实用户使用 Aqara 账号登录并授权给您。适合消费类应用，简单直接。
- 项目授权：您运营一个项目（一栋楼、一间酒店、一个园区），无需为每位用户准备消费账号，即可掌管项目内的设备。
- 虚拟账号授权：您创建虚拟 Aqara 账号，与自己的第三方账号系统对接。如果您的物业管理系统已有住户登录、单位记录和角色模型，就用这种方式来映射。您的用户永远看不到 Aqara 账号，映射关系由平台保存。
对于公寓和酒店项目，虚拟账号授权几乎总是正确的起点。请在第一周就做好规划，因为单位配置完成后再改用其他授权模式，代价很大。
消息推送：HTTP 与 MQ
推送决定了监控类产品能否正常运作。在拥有 2,000 个单位的发展项目中，每 30 秒轮询每台设备既无法扩展，还会被限流。
消息推送服务支持 HTTP 推送 和 MQ 推送，文档列出了推送模式、推送格式、推送 API 以及基于 trait 的推送 API。简单来说：您选择通道、定义订阅模式，Aqara 就会把设备上报的状态发送到您控制的端点。您需要决定该端点部署在哪里。对马来西亚的项目而言，首先要问的通常是：放在楼内的本地服务器，还是新加坡区域的云端？这个问题关乎数据驻留，而不是 MQTT 与 HTTPS 之争。
App SDK 层面
如果需要由您的应用负责设备入网，SDK 按任务划分如下：
| SDK 范畴 | 功能 |
|---|---|
| 设备配网 / 分发网络 | 有 UI、无 UI、Magic Pair、Wi-Fi、以太网、Bluetooth，以及 Zigbee 子设备配网 |
| 设备控制 | 在您自己的界面上读取并控制设备 |
| 红外遥控 | 在应用中控制红外设备 |
| 摄像头产品线 | 摄像头 SDK 集成、支持的设备列表 |
| 门锁产品线 | 门锁 SDK 集成与使用、支持的设备列表 |
| 曲线数据 | 时间序列 / 趋势数据处理 |
| OTA | 应用端的固件更新路径 |
Zigbee 子设备配网是必须做好的一环。 Zigbee 传感器不会加入客户的 Wi-Fi，而是加入网关。如果您的入网流程假设设备会以扁平列表的形式经网络出现，就经不起真实 Aqara 安装环境的考验。
Matter SDK 方面
Android 和 iOS 开发指南中的 Matter SDK 有独立的集成、使用和支持设备页面，其要求很明确：Matter SDK 需要 Matter 控制器。 Matter 子设备必须先通过 Aqara 的 Magic Pair 协议连接到 Aqara Matter 网关，之后才能在屏幕上进行设备配置和控制。
请把这理解为部署上的事实，而不是技术细节。Matter 并不能让马来西亚的公寓省掉配电箱里的网关。这意味着，网关仍是您在交楼时最重要的规格项目。这正是我们的公寓交楼智能家居规格一文的论点，也是这里的开发者平台与 Matter 说明必须对照阅读的原因。
规模，以及对马来西亚项目的意义
Aqara 网关最多可控制 128 台相关设备。这个数字会影响平面规划：一个 2,000 个单位的发展项目，加上公共大堂、健身房、泳池平台、停车场闸门以及每个单位的装修，并不是一个网状网络。请为网关的安装位置，以及配套的网络线缆和电源做好预算。
马来西亚产品线中的网关型号包括 Hub M3、Hub M200 和 Hub M100，以及 Camera Hub G3 和 Camera Hub G5 Pro 等摄像头网关。Panel Hub S1 Plus 本身就是 Zigbee 网关，通过 Hub M3 等 Matter 控制器添加后，也可以控制 Matter 配件。
投入工程资源之前
请先回答以下五个问题，并记录下来：
- 只用 Cloud API、只用 App SDK，还是两者都用？
- 采用哪种授权模式？如果用虚拟账号，映射表由谁负责？
- 推送还是轮询？推送端点在马来西亚境内放在哪里？
- 是否需要平台端固件更新？维护时段如何安排？
- 单位转售时，谁负责网关、配网以及实际的重新配对？
第五个问题最常被跳过，也是三年后引发最多支持电话的问题。
