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 ファイルを編集してください。

すべてのアプリで拡張する3つの主要クラス：

• Homey.App — /app.js からエクスポートされ、アプリの起動時に一度だけインスタンス化されます
• Homey.Driver — /drivers/<id>/driver.js からエクスポートされ、ペアリングとすべてのデバイスインスタンスを管理します
• Homey.Device — /drivers/<id>/device.js からエクスポートされ、ペアリング済みデバイスを1つ表します

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／webhook）、またはワイヤレスプロトコル（Z-Wave、Zigbee、433MHz、BLE、IR、Matter）のいずれですか？
2. 詳細なパターンについて、references/ から関連するリファレンスファイルを読みます：
   • 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、webhook、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 アプリの作成を依頼された場合は、必要なファイル一式を生成してください。最低限、次のものが必要です。

• id、version、compatibility、sdk、name、description、category などを含む /.homeycompose/app.json
• Homey.App を拡張する /app.js
• driver.js、device.js、driver.compose.json を含むドライバーを少なくとも1つ
• 翻訳対象の文字列用の /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 を直接編集しないでください — *.compose.json ファイルから Homey Compose によって生成されます。
2. App、Driver、Device のコンストラクターを上書きしないでください — 代わりに onInit() を使用してください。
3. タイマーには this.homey.* を使用してください — グローバル版ではなく this.homey.setInterval() / this.homey.setTimeout() を呼び出してください。アプリの破棄時にタイマーが自動的にクリアされます（Homey Cloud のマルチテナント環境では特に重要です）。
4. Device の data は不変で、一意である必要があります — IP アドレスではなく、MAC アドレスやシリアル番号を使用してください。変更されるプロパティはデバイスストアまたは設定に保存してください。
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）の使用

onDiscoveryResult、onDiscoveryAvailable、onDiscoveryAddressChanged を含む検出パターンの詳細については、references/wireless-and-cloud.md を参照してください。

---

各トピックの詳細については、上記の該当するリファレンスファイルを参照してください。 公式ドキュメントは https://apps.developer.homey.app/ にあり、SDK v3 API リファレンスは https://apps-sdk-v3.developer.homey.app/ にあります。