Module User-Config Definitions
The module configuration is like preferences for the connection. E.g. the IP-address of the device controlled by the instance. The config object itself is a JavaScript object defined by you. In TypeScript, you create a type or interface to define your config object and then use that type in declaring your InstanceBase class, i.e. class ModuleInstance extends InstanceBase<MyConfigType> (see src/main.ts in the TypeScript module template).
Secrets is a new feature (since API 1.13 - Companion 4.1). By defining a field as a secret, Companion will store its values in a separate secrets object. This allows Companion to be more careful in avoiding logging of this object, and allows the user to easily omit these values when exporting their configuration, which is beneficial for sharing with others.
The fields available for secrets is quite limited, as we expect it to only be useful for API keys, usernames, passwords and similar things. If other field types would be useful, let us know and we can look at adding more.
API calls: getConfigFields(), saveConfig(), configUpdated()
As part of creating a module, you should implement the getConfigFields() method.
Companion will call this when the configuration panel is opened for your module, so that it can present the correct fields to the user. See the next section, below, for details.
When your module is initialised, you will be provided a copy of the config in the init() method, and any time the user changes the configuration, configUpdated() will be called.
If you need to programmatically change the config object, for example to save some persistent state or to allow actions to change the config, call saveConfig(newconfig). (This will not trigger configUpdated().)
The saveConfig(), configUpdated() and init() methods also provide or accept a secrets object when you are defining any secret fields.
User-Config definitions
The fields you can use here are similar to the ones for actions and feedbacks, but with more limitations. See the list of field types for more details. The linked documentation states any limitations that apply when used for the configuration, or if they are not allowed.
The contents of the config and secrets objects must be JSON safe values, due to how they are stored. Make sure to not try and use a non-json safe object or it either won't be saved, or will throw an error that can crash your module.
Layout (deprecated)
Since API v1.14, we are working to unify the layout of this configuration to match elsewhere in Companion, meaning this value is not respected by default.
At the moment (in Companion v4.2/v4.3) it is possible to opt into the old layout, if you are not ready to ensure this works well for your module, you can opt out by adding in the constructor this.options.disableNewConfigLayout = true. This should only be done as a temporary measure, at some point in the future this will not be supported.
If you do this, let us know what is missing for you to switch. We recognise that there may be functionality you need and want to expand upon what the new layout offers. Reach out on GitHub to let us know what you need to be able to migrate.
Each field is required to have a width property. This should be a value 1-12, specifying how many columns the field needs in the UI.
Device discovery
If you are connecting over the network, your device may be discoverable using the Bonjour protocol. See the advanced topic Bonjour Device Discovery for further details.
If your device uses a different discovery mechanism, we would like to hear about it so that we can expand this support for more devices. Reach out on GitHub