Homey Compose

Compose is a plugin integegrated in the Homey package. It allows for managing large apps more easily. This improves separation of concerns and keeps things organized. By default, the plugin is enabled when creating a new app with homey app create.

For example, when developing a driver you can create your driver manifest in the driver folder as driver.compose.json. A typical driver compose file can look like this:

com.athom.example/drivers/my_driver/driver.compose.json

"class": "socket",
"capabilities": [ "onoff", "dim" ],
"name": {
  "en": "My Driver",
  "nl": "Mijn Driver"
},
"images": {
  "large": "/drivers/my_driver/assets/images/large.png",
  "small": "/drivers/my_driver/assets/images/small.png"
}

This will only describe the relevant information for the current driver. When running compose, this information will be placed in the drivers property of app.json. If you have more than one driver, all the seperate driver.compose.json files from all drivers will be merged into the drivers property in app.json.

The basic principle of separating information is the same for all other entries that compose supports. Most of the compose files needs to be placed in the .homeycompose folder, located in the root folder of your Homey app.

Templating

Compose also allows for creating driver and setting templates to share common properties, for example RF signals, assets, etc. You can create a driver template by placing the shared properties in /.homeycompose/drivers/templates/<template_id>.json. Then extend from the template in your driver compose file by placing the template id the $extends property in driver.compose.json. Compose will copy all properties from the template to the final file. Should you want to overwrite an property, you can do so by placing it in your driver.compose.json.

com.athom.example/.homeycompose/drivers/templates/defaults.json

{
  "images": {
    "large": "{{driverAssetsPath}}/images/large.png",
    "small": "{{driverAssetsPath}}/images/small.png"
  },
  "icon": "{{driverAssetsPath}}/icon.svg",
  "capabilities": [],
  "class": "other"
}

com.athom.example/drivers/my_driver/driver.compose.json

{
  "name": {
    "en": "My Driver",
    "nl": "Mijn Driver"
  },
  "$extends": ["defaults"]
}

By using this template, you only have to place the values that are uniqiue to a driver in the driver.compose.json file. All other required properties are copied over from the template.

Compose file structure

The file structure when using compose looks as follows. These files are additionally to the files that an Homey app requires.

com.athom.example
├──  .homeycompose/
│    ├── app.json
│    ├── capabilities/
│    │     └── <id>.json
│    ├── screensavers/
│    │     └── <id>.json
│    ├── signals/
│    │     ├── 433/
│    │     │    └── <id>.json
│    │     ├── 868/
│    │     │    └── <id>.json
│    │     └── ir/
│    │         └── <id>.json
│    ├── flow/
│    │     ├── triggers/
│    │     │    └── <id>.json
│    │     ├── conditions/
│    │     │    └── <id>.json
│    │     └── actions/
│    │          └── <id>.json
│    ├── discovery/
│    │     └── <id>.json
│    ├── drivers/
│    │     ├── templates/
│    │     │    └── <template_id>.json
│    │     ├── settings/
│    │     │    └── <setting_id>.json
│    │     └── flow/
│    │         ├── triggers/
│    │         │    └── <id>.json
│    │         ├── conditions/
│    │         │    └── <id>.json
│    │         └── actions/
│    │              └── <id>.json
│    ├── locales/
│    │     ├── <locale>.json
│    │     └── <locale.foo>.json
└──  drivers/
     └── <driver_id>/
           ├── driver.compose.json
           ├── driver.flow.compose.json
           └── driver.settings.compose.json

Flows

There are two ways to add Flows to app.json using Homey Compose.

  1. Add a Flow card definition to the .homeycompose folder:

com.athom.example/.homeycompose/flow/triggers/<id>.json

{
  "title": {
    "en": "Something changed"
  },
  "args": [
      {
        "name": "device",
        "type": "device",
        "filter": {
          "driver_id": "my_driver_id"
        }
      }
    ]
}

Note that you have to add the device argument if you want this Flow card to be related to a single device.

  1. Add a Flow card definition to the driver.flow.compose.json file in the folder of a driver:

com.athom.example/drivers/my_driver_id/driver.flow.compose.json


{
  "triggers": [
    {
      "title": {
        "en": "Something changed"
      }
    }
  ]
}

Note that in this case you must omit the device argument. Homey Compose will add the right device argument by default. If your Flow card requires additional arguments, just add the args array with the additional arguments, still omitting the device argument.