Maintenance Actions

This feature depends on Homey v3.1.0 and Homey Smartphone App v3.0.1.

Button capabilities can be flagged as maintenance action. This will show a button in 'Device settings > Maintenance actions' and hide the uiComponent in the device view. When this button is pressed the registered capability listener will be triggered. This allows you to initiate actions from the device's settings.

Example use cases:

• Starting the calibration process on a device
• Resetting accumulated power measurements

Creating a maintenance action

A maintenance action capability must be a capability that extends the system capability button. In order to mark it as a maintenance action add the maintenanceAction: true property to the capabilitiesOptions object of the driver in app.json. Additionally, provide a title property, and optionally a desc property.

/app.json

{ 
   "id": "com.example.app",
   ...
   "sdk": 2,
   "compatibility": ">=3.1.0",
   "drivers": [ 
      { 
         "name": { 
            "en": "P1 Meter"
         },
         "capabilities": [ 
            "meter_power",
            "measure_power",
            "button.calibrate",
            "button.reset_meter"
         ],
         "capabilitiesOptions": { 
            "button.calibrate": { 
               "maintenanceAction": true,
               "title": { 
                  "en": "Start calibration"
               },
               "desc": { 
                  "en": "Start the sensor calibration process."
               }
            },
            "button.reset_meter": { 
               "maintenanceAction": true,
               "title": { 
                  "en": "Reset power meter"
               },
               "desc": { 
                  "en": "Reset the accumulated power usage (kWh), note that this can not be reversed."
               }
            }
         }
         ...
      }
   ]
}

Listening for maintenance action events

Register the capability listeners in device.js to listen for maintenance action events.

/drivers/my_driver/devices.js

class MyDevice extends Homey.Device {
    onInit() {
        this.registerCapabilityListener('button.reset_meter', async () => {
            
            // Maintenance action button was pressed, return a promise
            return;
        });

        this.registerCapabilityListener('button.calibrate', async () => {
            
            // Maintenance action button was pressed, return a promise
            throw new Error('Something went wrong');
        });
    }
}