Using the learn callback in actions and feedback

To make it easier for users to configure your actions and feedbacks, you can implement the learn callback. This is intended to allow for the options of an action or feedback to be set to match the current state of the device. For example, you can program a learn callback to set the value for a "Set-Position" action to set the position of a picture-in-picture to its current location on your device. The callback simply queries the current state of the device and returns the appropriate value, as described below.

When implemented, a Learn Values button appears in the action or feedback allowing the user to trigger a learn event.

Launcher window

Implementing this callback is the same for actions and feedbacks, but the parameters do vary a little accordingly.

For an action which has a single option called input, one implementation could look like:

learn: (event) => {
    return {
        input: this.currentDeviceState.input,
    }
},

In the call, you are passed the same action/feedback object as you would for other callbacks. The callback should return a similar event.options object, containing only the new values. You cannot return an expression in these, only plain values.

In this example, only the input field is updated:

learn: (event) => {
    return {
        input: this.currentDeviceState.inputs[event.options.output],
    }
},

warning

As of API 2.0, you must only return the 'learnt' options in the result. Returning all options will overwrite any expressions the user may be using, so you should avoid returning fields which are unchanged.

Prior to API 2.0, it was recommended to include all options in the result, otherwise they would become undefined.

If for some reason you are not able to provide any new values, you can instead return undefined to tell Companion to abort this learn operation.

learn: (event) => {
    const input = this.currentDeviceState.inputs[event.options.output]

    if (input === undefined) {
        // No value in the state
        return undefined
    }

    // Return the new options
    return {
        input: input,
    }
},

Further Reading​

Further Reading