Skip to content

Development notes

Jump to bottom Edit New page
Joolee edited this page Feb 19, 2022 · 5 revisions

Creating a new sensor driver

  • Copy an existing driver that comes closest to the new one
  • For the icon, preferable use the same style as Athom does. For most drivers, it's possible to copy or modify a capability icon
  • Modify the class names in driver.js and device.js
  • Set the driver name in driver.compose.json

Adding a new driver makes the app version number to go up by one 'minor' version.

Creating new capabilities

  • Create the capability in .homeycompose/capabilities
  • For measure_ capabilities:
    • Add a trigger flowcard in .homeycompose/flow/trigger. It will automagically be called
    • Make sure all drivers with compatible values are listed in the '$filter' property of the trigger
      • Drivers of note: pulse_counter, input_analog

Sensor driver driver.js syntax

A new driver or device can very quickly be added if you understand the driver.js file. Here is where the connection between the ESP Easy devices (tasks and their values) and Homey devices (drivers and their capabilities) are made. The driver extends SensorDriver and needs two properties: taskTypes and values

Property: taskTypes

This array contains a list of all the ESP Easy plugins are supported and which values they export. The array is static because the app will want to make a list of all supported plugins before the drivers are initialized.

While filling out this list, it is convenient to keep the /json page of a live ESP Easy unit at hand.

  • name [String] is mandatory and contains the full name of the task (e.g. Environment - DS18b20). This name is used to match a task to this driver
  • plugin [Int] is mandatory and contains the plugin id as noted in the c source code or as p0xx in ESP Easy
  • values [Array [String]] is only mandatory if more than one value is supported by the driver. It contains a list (of max 4) values in the order they are listed in ESP Easy. The names can be made up and can be changed after release. Recommended to use the same names as the value names in ESP Easy. Can be substituted by the variants property
  • variants [Object] When ESP Easy allows different configurations for a single device that might change the values or the order they are listed in, make one variant for every possibility. Used in place of the values property. Keys can be made up but cannot be changed after release.
    • variantTitle [String] is mandatory when variants are used, it is the name the user will see during pairing, preferably the same name as used in ESP Easy
    • numValues [Int] The number of values the ESP Easy task must list for this variant to be selectable (I don't remember why this isn't calculated from the values property...)
    • variants [Array [String]] The same as when used outside of a variant

When variants are used, the user is asked what variant is configured during the pairing process. Only variants with matching number of values are selectable.

Property: values

In the most simple form, this is a mapping of an ESP Easy 'value' to a Homey capability. Allows modifying or validating any send value before applying them in Homey (e.g. to invert a boolean or apply a factor to a number.) Also allows the user to select their own compatible capability when applicable.

  • name [String] is mandatory, should match the 'value' name used in taskTypes. The name can be made up and can be changed after release. Recommended to use the same name as the value name in ESP Easy.
  • capability [String] or [Function]
    • [String] the exact capability name used to show this value to the user
    • [Function] gets one parameter capability. This function is called to filter the object in allCapabilities.json and all custom capabilities for compatibility with this value
      • Example: cap => !cap.setable && cap.getable && cap.type == "number"
      • The filtered capabilities are shown to the user for selection during pairing
  • modifier [Function] gets one parameter value every time Homey receives a new value from ESP Easy and can return a modified value before it is stored in Homey
  • validate [Function] gets two parameters, the taskValue (the value object from the /json) and value. Can be used to ignore certain values or, for example, set the device state to unavailable when a certain value is received

Note: When you want to reference the Device instance as this in a [Function] parameter, use a full function(taskVal, value) {} as property and not an arrow function (taskVal, value) => {}.

Driver/Device classes and their dependencies

  • Homey.Device

    • GeneralDevice (/lib/GeneralDevice.js)
      • GPIODevice (/lib/GPIODevice.js)
        • ..All GPIO devices in /drivers/x/device.js..
      • SensorDevice (/lib/SensorDevice.js)
        • ..All sensor devices in /drivers/x/device.js except the P1 device!..
      • P1_Device (/drivers/p1/device.js)
    • UnitDevice (/drivers/unit/device.js)

  • Homey.Driver

    • GeneralDriver (/lib/GeneralDriver .js)
      • GPIODriver (/lib/GPIODriver.js)
        • ..All GPIO drivers in /drivers/x/driver.js..
      • SensorDriver (/lib/SensorDriver.js)
        • ..All sensor drivers in /drivers/x/driver.js..
      • UnitDriver (/drivers/unit/driver.js)

You can find more support in the Forum

Add a custom sidebar
Clone this wiki locally