homey-app

Homey Apps SDK — 技能指南

此技能可帮助你为 Homey 智能家居平台构建应用。Homey 应用是一个在 Homey Pro 上本地运行（或在 Homey Cloud 上云端运行）的 Node.js 程序包。应用为 Homey 生态系统添加设备、流程卡片、小组件等功能。

核心概念

SDK 版本：始终使用 SDK v3（在清单中设置 "sdk": 3）。SDK v3 全面采用 async/await。

Node.js：自 Homey v12.9.0 起，所有平台均运行 Node.js 22。

Homey Compose：此构建系统会将单体 app.json 清单拆分成多个较小的 *.compose.json 文件。切勿直接编辑 /app.json，应改为编辑 compose 文件。

每个应用都会扩展的三个核心类：

• Homey.App — 从 /app.js 导出，在应用启动时实例化一次
• Homey.Driver — 从 /drivers/<id>/driver.js 导出，管理配对过程和所有设备实例
• Homey.Device — 从 /drivers/<id>/device.js 导出，表示一个已配对的设备

Homey CLI（npx homey）是主要的开发工具：

• homey app create — 搭建新应用的脚手架
• homey app run — 在 Homey 上实时运行并调试（退出时会卸载）
• homey app install — 持久安装，以便测试
• homey app publish — 发布到 Homey App Store
• homey app driver create — 交互式添加驱动程序
• homey app flow create — 交互式添加流程卡片
• homey app validate — 检查清单是否有效

项目结构（Homey Compose）

com.example.myapp/
├─ .homeycompose/
│  ├─ app.json                         # Core manifest properties
│  ├─ capabilities/
│  │  └─ <custom_cap_id>.json          # Custom capability definitions
│  ├─ flow/
│  │  ├─ triggers/<id>.json            # App-level Flow trigger cards
│  │  ├─ conditions/<id>.json          # App-level Flow condition cards
│  │  └─ actions/<id>.json             # App-level Flow action cards
│  ├─ discovery/
│  │  └─ <id>.json                     # LAN discovery strategies (mDNS, SSDP, MAC)
│  └─ locales/
│     └─ en.json                       # App-level translations
├─ assets/
│  ├─ icon.svg                         # App icon (SVG)
│  └─ images/
│     ├─ small.png (250x175)
│     ├─ large.png (500x350)
│     └─ xlarge.png (1000x700)
├─ drivers/
│  └─ <driver_id>/
│     ├─ assets/
│     │  ├─ icon.svg                   # Driver icon
│     │  └─ images/ (small, large, xlarge)
│     ├─ device.js                     # Device class
│     ├─ driver.js                     # Driver class
│     ├─ driver.compose.json           # Driver manifest
│     ├─ driver.flow.compose.json      # Driver-specific Flow cards (optional)
│     └─ driver.settings.compose.json  # Device settings (optional)
├─ widgets/
│  └─ <widget_id>/
│     ├─ public/
│     │  └─ index.html                 # Widget frontend
│     ├─ api.js                        # Widget API handlers
│     ├─ widget.compose.json           # Widget definition
│     ├─ preview-dark.png              # Widget preview (dark)
│     └─ preview-light.png             # Widget preview (light)
├─ locales/
│  ├─ en.json
│  └─ nl.json
├─ settings/
│  └─ index.html                       # App settings page (optional)
├─ api.js                              # App Web API (optional, Pro only)
├─ app.js                              # App class
├─ env.json                            # Secret environment variables (gitignored!)
├─ README.txt                          # App Store long description (plain text, no markdown)
└─ .homeyignore                        # Files to exclude from publishing

如何使用此技能

创建 Homey 应用时，请遵循以下工作流：

1. 确定集成类型 — 是 LAN 设备（Wi-Fi/mDNS/SSDP）、云 API（OAuth2/webhooks），还是无线协议（Z-Wave、Zigbee、433MHz、BLE、IR、Matter）？
2. 阅读相关参考文件，了解详细模式：
   • references/app-and-manifest.md — App 类、清单、设置、环境、i18n、权限
   • references/drivers-and-devices.md — Driver/Device 类、配对、能力、设置、发现
   • references/flow-cards.md — 触发器、条件、操作、参数、令牌、设备流程卡片
   • references/widgets.md — 仪表板小组件、小组件设置、小组件 API
   • references/wireless-and-cloud.md — Wi-Fi/LAN 发现、OAuth2、webhooks、Z-Wave、Zigbee、BLE
   • references/publishing.md — App Store 指南、图标、图像、发布流程
3. 搭建项目脚手架，遵循上述 Homey Compose 结构
4. 编写代码，采用 SDK v3 模式（async/await、this.homey.* 管理器）
5. 使用 homey app validate --level=publish 进行验证

搭建新应用的脚手架

当用户要求创建新的 Homey 应用时，请生成完整的文件集。至少需要：

• /.homeycompose/app.json，包含 id、version、compatibility、sdk、name、description、category 等
• 扩展 Homey.App 的 /app.js
• 至少一个驱动程序，包含 driver.js、device.js 和 driver.compose.json
• /locales/en.json，用于存放任何翻译字符串
• README.txt

应用 ID 必须采用反向域名格式（例如 com.example.mydevice）。应用 ID 中切勿使用 “homey” 或 “athom”。

最简 app.js

'use strict';

const Homey = require('homey');

class MyApp extends Homey.App {
  async onInit() {
    this.log('MyApp has been initialized');
  }
}

module.exports = MyApp;

最简 driver.js

'use strict';

const Homey = require('homey');

class MyDriver extends Homey.Driver {
  async onInit() {
    this.log('MyDriver has been initialized');
  }

  async onPairListDevices() {
    // Return an array of discovered devices
    return [];
  }
}

module.exports = MyDriver;

最简 device.js

'use strict';

const Homey = require('homey');

class MyDevice extends Homey.Device {
  async onInit() {
    this.log('MyDevice has been initialized');

    // Register capability listeners
    this.registerCapabilityListener('onoff', async (value) => {
      // Handle the on/off command
      this.log('onoff changed to', value);
    });
  }

  async onAdded() {
    this.log('MyDevice has been added');
  }

  async onSettings({ oldSettings, newSettings, changedKeys }) {
    this.log('MyDevice settings changed');
  }

  async onDeleted() {
    this.log('MyDevice has been deleted');
  }
}

module.exports = MyDevice;

最简 driver.compose.json

{
  "name": { "en": "My Device" },
  "class": "socket",
  "capabilities": ["onoff"],
  "platforms": ["local", "cloud"],
  "connectivity": ["cloud"],
  "pair": [
    {
      "id": "list_devices",
      "template": "list_devices",
      "navigation": { "next": "add_devices" }
    },
    {
      "id": "add_devices",
      "template": "add_devices"
    }
  ]
}

关键规则

1. 绝不要直接编辑 /app.json——它由 Homey Compose 根据 *.compose.json 文件生成。
2. 绝不要覆盖 App、Driver 或 Device 的构造函数——改用 onInit()。
3. 使用 this.homey.* 设置计时器——调用 this.homey.setInterval() / this.homey.setTimeout()，而不是全局版本，以便在应用销毁时自动清除计时器（这对 Homey Cloud 多租户环境至关重要）。
4. Device 的 data 必须不可变且唯一——使用 MAC 地址或序列号，绝不要使用 IP 地址。将会变化的属性存储在设备存储区或设置中。
5. 始终处理 Promise 拒绝——未处理的拒绝会导致 Homey Cloud 上的应用崩溃。对于不等待结果的 Promise，使用 .catch(this.error)。
6. 通过 this.homey 访问管理器——例如 this.homey.flow、this.homey.settings、this.homey.drivers。
7. 从 Device/Driver 获取 App 实例：this.homey.app 可获取 App 实例。
8. 环境变量：在 /env.json 中定义，通过 Homey.env.VARIABLE_NAME 访问（名称大写，且值只能是字符串）。
9. ESM 支持：Homey 支持 ES 模块。若使用 import/export 语法，请参阅 ESM 指南。

Homey Cloud 注意事项

面向 Homey Cloud（"platforms": ["local", "cloud"]）时：

• 不支持本地 Wi-Fi（不支持 mDNS/SSDP/MAC 发现）
• 不支持 App Web API（api.js）
• 不支持应用间通信
• 不支持 homey:manager:api 权限
• 必须处理多租户：不要使用全局状态，计时器请使用 this.homey.*
• 应用在 Docker 中运行；进行云端测试时，homey app run 需要 Docker
• 未处理的 Promise 拒绝会导致应用崩溃

快速参考：常见模式

轮询云端 API

async onInit() {
  this.pollInterval = this.homey.setInterval(() => {
    this.pollDevice().catch(this.error);
  }, 30000);
}

async onUninit() {
  this.homey.clearInterval(this.pollInterval);
}

设置能力值（Device → Homey）

await this.setCapabilityValue('measure_temperature', 22.5);
// For custom boolean capabilities, this auto-triggers Flow cards

监听能力变更（Homey → Device）

this.registerCapabilityListener('target_temperature', async (value, opts) => {
  await this.api.setTemperature(value);
});

触发 Flow 触发器

// In app.js onInit():
const myTrigger = this.homey.flow.getDeviceTriggerCard('my_event');
// Later, from a device:
await this.driver.myTrigger.trigger(this, { token_key: 'value' }, {});

使用设备发现（mDNS）

阅读 references/wireless-and-cloud.md，了解完整的发现模式，包括 onDiscoveryResult、onDiscoveryAvailable 和 onDiscoveryAddressChanged。

---

有关任何主题的详细文档，请阅读上方列出的相关参考文件。 官方文档位于 https://apps.developer.homey.app/，SDK v3 API 参考位于 https://apps-sdk-v3.developer.homey.app/。