HomeyCompose is a powerful tool but saying the documentation is sparse would be an understatement. This page tries to list ways you can utilize HomeyCompose, hidden properties you might use and common pitfalls.

It is recommended not to edit the main app.json file at all when you use HomeyCompose. You can create an app.json file in your .homeycompose folder and define all main properties of your app. (Like id, version and author but not flows, drivers and signals.) If you do this correctly, you can replace the main app.json with a file containing just {} and HomeyCompose will re-populate the file for you with all properties when you run homey app build.

Example: https://github.com/Joolee/nl.joolee.homey.espeasy/blob/master/.homeycompose/app.json

This subject ís actually covered in the documentation but not extensively and it might be nice to show a few use cases.

You can use templates by defining them in

• /.homeycompose/drivers/flow/<triggers|conditions|actions>/<flow_id>.json
  • Used in /drivers//driver.flow.compose.json
  • driver.flow.compose.json can contain three arrays named 'triggers', 'conditions' and 'action'. Each of those contain 'card' objects which can contain an $extends property. Any other card properties are optional, you can define the whole card in a template and only have the $extends property in your driver file.
• /.homeycompose/drivers/templates/<template_id>.json
  • Used in /drivers//driver.compose.json
• /.homeycompose/drivers/settings/<setting_id>.json
  • Used in /drivers//driver.settings.compose.json

Use the templates by referencing them in a property called $extends containing either an array with template names (without .json) or a string with a single template name.

The id property of any template will be added (or overwritten) automatically by HomeyCompose based on the template filename. If you want to define an Id other then the filename, name the property $id and include it in either the template or besides an $extend property.

All properties defined in a template will be merged with the properties already defined in a driver. You can use this to build standard drivers by combining multiple templates.

For example I define the folowing templates:

• .homeycompose/drivers/templates/default-images.json

  • {
        "images": {
            "large": "{{driverAssetsPath}}/images/large.png",
            "small": "{{driverAssetsPath}}/images/small.png"
        }
    }

• .homeycompose/drivers/templates/default-sensor-capabilities.json

  • {
        "class": "sensor",
        "capabilities": [
            "measure_idle_time",
            "device_heartbeat"
        ]
    }

• .homeycompose/drivers/templates/pair-list-settings-done.json

  • {
        "pair": [{
                "id": "list_devices",
                "template": "list_devices",
                "options": {
                    "singular": true
                },
                "navigation": {
                    "next": "settings"
                }
            },
            {
                "id": "settings",
                "navigation": {
                    "prev": "list_devices",
                    "next": "done"
                }
            },
            {
                "id": "done",
                "template": "done"
            }
        ]
    }

For a sensor device, my driver.compose.json file might simply look like this:

{
	"name": {
		"en": "Energy AC/DC",
		"nl": "Energie AC/DC"
	},
	"capabilities": [
		"device_specific_capability"
	]
	"$extends": [
		"default-images",
		"default-sensor-capabilities",
		"pair-list-settings-done"
	]
}

All properties (and sub-properties) in a driver's json object can contain special variables which will be replaced by HomeyCompose. These are:

• {{driverId}}
• {{driverName}}
• {{driverNameEn}} | {{driverNamePl}} | {{driverNameNl}} | {{driverNameDe}} | ...
  • En|Pl|Nl|De is the locale with first letter uppercase, second letter lowercase. When the driver name is not defined in that locale, EN will be used.
• {{driverPath}}
  • Same as /drivers/{{driverId}}
• {{driverAssetsPath}}
  • Same as /drivers/{{driverId}}/assets
• {{zwaveParameterIndex}}

The special parameters listed above are used by Athom in their default capability definitions (as you can see here and here.) They are not parsed by the HomeyCompose library and can therefore not be used in your custom capability definitions. ($flowis parsed here, the other two are not used any more)

Homeycompose will remove all properties starting with $ which it doesn't support. This means you can actually use these special parameters when you don't use HomeyCompose but it is undocumented, unsupported and worse; considered a bug. Therefore not recommended for use.