`, helping you match the types.
+
+## Further Reading
+
+- [Autogenerated docs for the module `InstanceBase` class](https://bitfocus.github.io/companion-module-base/classes/InstanceBase.html)
+- [User-configuration management](./user-configuration.md)
+- [Actions](./actions.md)
+- [Feedbacks](./feedbacks.md)
+- [Presets](./presets.md)
diff --git a/for-developers/module-development/home.md b/for-developers/module-development/home.md
index 2aca7e4..c12f563 100644
--- a/for-developers/module-development/home.md
+++ b/for-developers/module-development/home.md
@@ -1,5 +1,5 @@
---
-title: Module Development Setup
+title: Getting Started with Modules
sidebar_label: Getting Started with Modules
sidebar_position: 1
description: Developer environment setup specific to module development.
@@ -46,26 +46,31 @@ However, starting with v4.0, note that **your new dev module will show up in the
With over 700 published modules, you may find a module already written for you device. You can find the GitHub repository for each module by searching [Bitfocus in GitHub](https://github.com/bitfocus).
- If you want to **contribute to an existing module**, clone it to your development folder using your [preferred git tool](../git-workflows/installing-git.md). (See [Git Crash Course](../git-workflows/git-crashcourse.md) and [The GitHub Workflow](../git-workflows/github-workflow.md) for important details).
-- If you are **writing a new module**, then download and expand the zip file for the [TypeScript template module](https://github.com/bitfocus/companion-module-template-ts/archive/refs/heads/main.zip) into the module development folder (see the next section on naming your module). If you prefer, you can clone the [template repo](https://github.com/bitfocus/companion-module-template-ts), but remember to delete the remote link (`git remote remove origin`) before continuing. We encourage you to use Typescript for all new modules but acknowledge that it isn't for everyone, so we fully support [Javascript](https://github.com/bitfocus/companion-module-template-js) too!
-- Alternatively for a new module, you can start by downloading the zip or cloning a module that controls a device similar to yours -- both options can be found under the the green **<> Code ▼** button for that module's GitHub repo. Beware: by using another module as a base, you could inherit some subtle misconfigurations or deviations they have made from our recommendations. As with using the template, if you cloned the repo be sure to remove the remote connection by running `git remote remove origin`, since you will be creating a new module rather than modifying the existing one.
+- If you are **writing a new module**, then download and expand the zip file for the [TypeScript template module](https://github.com/bitfocus/companion-module-template-ts/archive/refs/heads/main.zip) into the module development folder (see the next section on naming your module). If you prefer, you can clone the [template repo](https://github.com/bitfocus/companion-module-template-ts), but remember to delete the remote link (`git remote remove origin`) before continuing. We encourage you to use TypeScript for all new modules but acknowledge that it isn't for everyone, so we fully support [Javascript](https://github.com/bitfocus/companion-module-template-js) too!
+- Alternatively for a new module, you can start by downloading the zip or cloning a module that controls a device similar to yours -- both options can be found under the green **<> Code ▼** button for that module's GitHub repo. Beware: by using another module as a base, you could inherit some subtle misconfigurations or deviations they have made from our recommendations. As with using the template, if you cloned the repo be sure to remove the remote connection by running `git remote remove origin`, since you will be creating a new module rather than modifying the existing one.
### Additional steps for new modules
1. Rename your module's directory _companion-module-mymanufacturer-myproduct_, replacing _mymanufacturer-myproduct_ with appropriate names. Try to think of what is most appropriate for your device: Are there other similar devices by the manufacturer that use the same protocol that the module could support later on? If so try and name it to more easily allow for that.
-2. In at least _package.json_, _companion/manifest.json_ and _companion/HELP.md_, edit the name and description of the module to match what yours is called. The search feature in your IDE is really helpful to find all of the places the name shows up! See the [Module Configuration section](./module-config/file-structure.md) and especially the [documentation for the manifest.json file](./module-config/manifest.json.md) for further details.
+2. In at least _package.json_, _companion/manifest.json_ and _companion/HELP.md_, edit the name and description of the module to match what yours is called. The search feature in your IDE is really helpful to find all of the places the name shows up! See the [Module Configuration section](./module-setup/file-structure.md) and especially the [documentation for the manifest.json file](./module-setup/manifest.json.md) for further details.
-3. Please see [Module Configuration](./module-config/file-structure.md) and the other pages in that section for more details and more options on starting your own module.
+3. Please see [Module Configuration](./module-setup/file-structure.md) and the other pages in that section for more details and more options on starting your own module.
## Install the dependencies
In a shell inside the new folder, run the following:
-1. `yarn install` This will install any dependencies needed by the module.
+```
+yarn install
+```
+
+This will install any dependencies needed by the module.
:::tip
-If you are using an IDE such as [VS Code](https://code.visualstudio.com/), make the clone your current project (i.e., open the repository folder), then open a terminal (shell) inside the IDE to ensure you are running yarn in the correct folder.
+If you are using an IDE such as [VS Code](https://code.visualstudio.com/), make the clone your current project
+(i.e., open the repository folder), then open a terminal (shell) inside the IDE to ensure you are running yarn in the correct folder.
:::
@@ -73,7 +78,7 @@ If you are using an IDE such as [VS Code](https://code.visualstudio.com/), make
You are now ready to start developing your module. Here are our suggested next steps:
-- Familiarize yourself with the [Module Configuration](module-config/file-structure.md) to understand the general file structure and configuration options, especially if working on a new module.
+- Familiarize yourself with the [Module Configuration](./module-setup/file-structure.md) to understand the general file structure and configuration options, especially if working on a new module.
- Read [Module development 101](./module-development-101.md) for an overview of the development lifecycle.
- Review the recommended [GitHub Workflow](../git-workflows/github-workflow.md) to learn best practices for new features to your codebase.
diff --git a/for-developers/module-development/images/bonjour.png b/for-developers/module-development/images/bonjour.png
new file mode 100644
index 0000000..7ab6839
Binary files /dev/null and b/for-developers/module-development/images/bonjour.png differ
diff --git a/for-developers/module-development/index.md b/for-developers/module-development/index.md
new file mode 100644
index 0000000..c53357a
--- /dev/null
+++ b/for-developers/module-development/index.md
@@ -0,0 +1,8 @@
+---
+title: Companion Module Developers' Guide
+description: Outline of the Module Development section.
+auto_toc: 2
+---
+
+This section describes everything you need to know to develop your own modules for Companion. Below is
+an outline of the top-level pages and folders in this section. For pages, the main headings inside each file are listed as bulleted lines. Folders are shown preceded by '> ', and the immediate contents of that folder are shown below it using "└─ " to indicate pages (or subfolders) inside that folder.
diff --git a/for-developers/module-development/module-config/_category_.json b/for-developers/module-development/module-config/_category_.json
deleted file mode 100644
index 9639e8b..0000000
--- a/for-developers/module-development/module-config/_category_.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
- "label": "Module Configuration",
- "position": 10,
- "link": {
- "type": "generated-index",
- "title": "Configuring your companion module"
- },
- "customProps": {
- "description": "The files and file structure necessary to configure a module repository."
- }
-}
diff --git a/for-developers/module-development/module-debugging.md b/for-developers/module-development/module-debugging.md
new file mode 100644
index 0000000..e863d74
--- /dev/null
+++ b/for-developers/module-development/module-debugging.md
@@ -0,0 +1,93 @@
+---
+title: Debugging Modules
+sidebar_label: Debugging Modules
+sidebar_position: 7
+description: How to debug your Companion module during development.
+---
+
+Once you've started coding, debugging the code will become essential to your success. We consider it
+important enough that we're covering it here before you dive into the details in the following sections.
+
+There are three main routes to debugging: log through the API, console.log, interactive debugging
+
+## Log through the API
+
+Companion provides individual log pages for each module that are different from the main Companion log page.
+
+You can open the module-specific log view from the connections page by clicking the ⋮ button and selecting "View logs":
+
+
+
+The module InstanceBase class provides a logging function that allows you to specify the log-level as one of: `"info"`, `"warn"`, `"error"`, or `"debug"`. For example:
+
+```ts
+this.log('debug', 'My debug message.')
+```
+
+These messages will show up in the module-specific log page and can be filtered by selecting/deselecting the "Debug" button (or whichever log-level you chose) in the top-left of the window:
+
+
+> 26.01.01 00:00:00 **Module**: My debug message.
+
+
+## Log to the console
+
+The simplest debugging method is to log to the console.
+
+`console.log('your data/message');`
+
+These messages will still show up in the module-specific log page and can be filtered by selecting/deselecting the "Console" button in the top-left of the window:
+
+
+> 26.01.01 00:00:00 **Console**: your data/message
+
+
+:::note
+Depending on buffering, several `console.log()` messages may be grouped together, so only the first will appear to have a timestamp. Use the API `this.log()` function described above, if seeing things reported in exactly the call order is important.
+:::
+
+## Attach a debugger
+
+Often it can be useful and more convenient to attach a debugger to your module so you can create breakpoints from which you can inspect its state while the module is running. This method also has the advantage of not requiring the addition of numerous logging statements.
+
+To attach to your module's process, first add a file named `DEBUG-INSPECT` (no suffix) in the root of your module folder. The file can be empty or have a single number in it, which specifies the debugger port number. Next time you start Companion, it will launch your module with the remote debugging protocol enabled.
+
+By default Companion will pick and use a random port that will change each launch, alternatively, you can specify a port number inside the `DEBUG-INSPECT` file to use a fixed port for debugging.
+
+You can use any compatible debugger such as the built-in VS Code debugger, or Chrome inspector to connect to your process.
+
+:::warning
+
+It may not be possible to debug the `init` method from your module with this, Companion still imposes the same launch timeout as usual here. But you can attach after this and see what is going on.
+
+:::
+
+:::tip[VS Code]
+
+VS Code users can store a setup which allows you to use F5 to initiate debugging as follows:
+
+1. Put a port number in `DEBUG-INSPECT` -- for this example it is 12345.
+
+2. Put the following into the file `.vscode/launch.json` (where the value of "port" matches the value in `DEBUG-INSPECT`).
+
+```json
+{
+ "configurations": [
+ {
+ "name": "Attach to Companion module",
+ "port": 12345,
+ "request": "attach",
+ "skipFiles": ["/**"],
+ "type": "node"
+ }
+ ]
+}
+```
+
+:::
+
+## Further reading
+
+- [Autogenerated docs for the InstanceBase log method](https://bitfocus.github.io/companion-module-base/classes/InstanceBase.html#log)
+- [Module development 101](./module-development-101.md)
+- [Module Basics Overview](./connection-basics/overview.md)
diff --git a/for-developers/module-development/module-development-101.md b/for-developers/module-development/module-development-101.md
index e9ecd8c..f24c324 100644
--- a/for-developers/module-development/module-development-101.md
+++ b/for-developers/module-development/module-development-101.md
@@ -15,22 +15,22 @@ If you are creating a new module, then the very first thing you'll want to do is
## Configure the module
-There are a few files that make up every module. Please familiarize yourself with the basic structure described in our pages on [Module Configuration](module-config/file-structure). In particular, _package.json_,
-[_companion/manifest.json_](./module-config/manifest.json.md) and _companion/HELP.md_ define the identity of the module. Once these are defined, you will spend most of your time crafting the module source code.
+There are a few files that make up every module. Please familiarize yourself with the basic structure described in our pages on [Module Configuration](module-setup/file-structure). In particular, _package.json_,
+[_companion/manifest.json_](./module-setup/manifest.json.md) and _companion/HELP.md_ define the identity of the module. Once these are defined, you will spend most of your time crafting the module source code.
## Program the module
-While you can handle all your module's code in one big file, we strongly recommend splitting it across several files as illustrated [here](./module-config/file-structure#file-structure).
+While you can handle all your module's code in one big file, we strongly recommend splitting it across several files as illustrated in our [file structure overview](./module-setup/file-structure#file-structure).
To understand what is needed in a module it helps to understand how the code is used. Your module is presented to Companion as a class that extends the module base class. A user can add one or more _instances_ of your module to their Companion site. When Companion starts up, it initializes each instance of the module by starting a new process and passing configuration information, as described next.
### The module class and entrypoint (Module base class, configs)
-In the [typical module structure](./module-config/file-structure#file-structure), the entrypoint and module class are defined in _src/main.ts_. When your module is started, first the `constructor` of your module's class will be called, followed by your [upgrade scripts](https://github.com/bitfocus/companion-module-base/wiki/Upgrade-scripts) and then the `init` method.
+In the [typical module structure](./module-setup/file-structure#file-structure), the entrypoint and module class are defined in _src/main.ts_. When your module is started, first the `constructor` of your module's class will be called, followed by your [upgrade scripts](./connection-basics/upgrade-scripts.md) and then the `init` method.
Your constructor should only do some minimal class setup. It does not have access to the configuration information, so it should not be used to start doing things. Instead...
-The `init` method is passed any previously-stored user-config information. (The structure of the user-config is defined by you and used as the type of the generic base class.) Inside the `init` method you should initiate the connection to your device (but dont await it! Instead use the The `updateStatus()` method to inform Companion asynchronously of the connection status). Here you also pass the module's actions, feedbacks, variables and presets to Companion for the first time.
+The `init` method is passed any previously-stored user-config information. (The structure of the user-config is defined by you and used as the type of the generic base class.) Inside the `init` method you should initiate the connection to your device (but dont await it! Instead use the `updateStatus()` method to inform Companion asynchronously of the connection status). Here you also pass the module's actions, feedbacks, variables and presets to Companion for the first time.
Once the module is running the `configUpdated` (but not `init`) method will be called if the user changes the config on the Connections page. (You can programmatically change the user config by calling `saveConfig()`, defined in the base class.) You can also update the action, feedback, etc. definitions at any time.
@@ -40,13 +40,13 @@ When the module gets deleted or disabled the `destroy` function is called. here
Your module provides interaction with the user by defining user-configurations, actions, feedbacks, and variables. In addition you can define "preset" buttons that predefine combinations of common actions and feedbacks for the user's convenience. These presets can be dragged onto the button grid for "instant button configuration".
-TODO: Update links
-
-- [Module Configuration](module-config/file-structure.md)
-- [Actions](https://github.com/bitfocus/companion-module-base/wiki/Actions)
-- [Feedbacks](https://github.com/bitfocus/companion-module-base/wiki/Feedbacks)
-- [Presets](https://github.com/bitfocus/companion-module-base/wiki/Presets)
-- [Variables](https://github.com/bitfocus/companion-module-base/wiki/Variables)
+- [Module Setup](module-setup/file-structure.md)
+- [Module Basics Overview](./connection-basics/overview.md)
+- [Actions](./connection-basics/actions.md)
+- [Feedbacks](./connection-basics/feedbacks.md)
+- [Presets API v2.x](./connection-basics/presets.md)
+- [Presets API v1.x](./connection-basics/presets-1.x.md)
+- [Variables](./connection-basics/variables.md)
### Log module activity (optional)
@@ -58,6 +58,8 @@ For printing to the module debug log use:
And if you want it in the log in the web interface, see [the log method](https://bitfocus.github.io/companion-module-base/classes/InstanceBase.html#log).
+See also our instructions for [debugging your module](./module-debugging.md)
+
## Test the module
In any case, your module should be tested throughout at different stages of its life.
@@ -66,8 +68,8 @@ And last but not least you should check **all** your actions with **all** the op
## Share your code
-Once your module is tested and you are ready to release it publicly, you will use the [BitFocus Developer Portal](https://developer.bitfocus.io/modules/companion-connection/discover) to list it with Companion. Please follow the guide for [releasing your module](https://github.com/bitfocus/companion-module-base/wiki/Releasing-your-module).
+The first step in sharing your code, whether to share privately or distribute through Companion is to [package your module](./module-lifecycle/module-packaging.md).
-If your module it not intended for public release, or you want to share it locally for testing, you can also read the guide on [packaging your module](https://github.com/bitfocus/companion-module-base/wiki/Module-packaging).
+Once your packaged module has passed your quality-control and you are ready to release it publicly, you will use the [BitFocus Developer Portal](https://developer.bitfocus.io/modules/companion-connection/discover) to list it with Companion. Please follow the guide for [releasing your module](./module-lifecycle/releasing-your-module.md).
Questions? Reach out on [SLACK](https://l.companion.free/q/zYXXxnGyd)! :)
diff --git a/for-developers/module-development/module-lifecycle/_category_.json b/for-developers/module-development/module-lifecycle/_category_.json
index 8a18914..8f53358 100644
--- a/for-developers/module-development/module-lifecycle/_category_.json
+++ b/for-developers/module-development/module-lifecycle/_category_.json
@@ -1,11 +1,11 @@
{
- "label": "Module LifeCycle",
+ "label": "Module Release and Maintenance",
"position": 30,
"link": {
- "type": "generated-index",
- "title": "Maintaining you Companion module over time"
+ "type": "doc",
+ "id": "index"
},
"customProps": {
- "description": "The task necessary to maintain and upgrade a module repository over time."
+ "description": "The task necessary to release, maintain and upgrade a module repository over time."
}
}
diff --git a/for-developers/module-development/module-lifecycle/companion-module-library.md b/for-developers/module-development/module-lifecycle/companion-module-library.md
index 0770e34..4a71a7b 100644
--- a/for-developers/module-development/module-lifecycle/companion-module-library.md
+++ b/for-developers/module-development/module-lifecycle/companion-module-library.md
@@ -1,7 +1,7 @@
---
title: 'The Companion Module Libraries'
sidebar_label: '@companion-module Libraries'
-sidebar_position: 7
+sidebar_position: 1
description: Explanation of the companion module library.
---
@@ -9,7 +9,7 @@ Since Companion version 3.0, we have used `@companion-module/base` and `@compani
The libraries are available on [npm](https://www.npmjs.com/) and are installed automatically when you run `yarn install`.
-## What is the purpose of each?
+## What is the purpose of each library?
### @companion-module/base
@@ -47,4 +47,10 @@ This was the main issue that was blocking our ability to support adding newer ve
Everything that modules need to access Companion is now located inside of `@companion-module/base`. Some things have not been made available, as they were determined to not be appropriate and alternatives will be recommended to the few module authors who utilised them.
-Another benefit of this separation is that it allows us to better isolate modules from being tied to specific versions of Companion. The `@companion-module/base` acts as a stable barrier between the two. It has intentionally been kept separate from the rest of the Companion code, so that changes made here get an extra level of scrutiny, as we want to guarantee backwards compatibility as much as possible. For example, in Companion version 2.x changes made to the module api occasionally required fixes to be applied to multiple modules. By having this barrier, we can avoid such problems for as long as possible, and can more easily create compatibility layers as needed.
+Another benefit of this separation is that it allows us to better isolate modules from being tied to specific versions of Companion. The `@companion-module/base` acts as a stable barrier between the two. It has intentionally been kept separate from the rest of the Companion code, so that changes made here get an extra level of scrutiny, as we want to guarantee backwards compatibility as much as possible. For example, in Companion version 2.x changes made to the module API occasionally required fixes to be applied to multiple modules. By having this barrier, we can avoid such problems for as long as possible, and can more easily create compatibility layers as needed.
+
+## Further reading
+
+- [Introduction to modules](../home.md)
+- [Module development 101](../module-development-101.md)
+- [Module Basics](../connection-basics/)
diff --git a/for-developers/module-development/module-lifecycle/index.md b/for-developers/module-development/module-lifecycle/index.md
new file mode 100644
index 0000000..51294ab
--- /dev/null
+++ b/for-developers/module-development/module-lifecycle/index.md
@@ -0,0 +1,7 @@
+---
+title: 'Module Development Lifecycle: Release and Maintenance'
+description: The task necessary to release, maintain and upgrade a module repository over time.
+auto_toc: 2
+---
+
+This section describes the task necessary to package, deliver, maintain and upgrade a module repository over time.
diff --git a/for-developers/module-development/module-lifecycle/module-packaging.md b/for-developers/module-development/module-lifecycle/module-packaging.md
new file mode 100644
index 0000000..ae80f4f
--- /dev/null
+++ b/for-developers/module-development/module-lifecycle/module-packaging.md
@@ -0,0 +1,165 @@
+---
+title: 'Packaging a Companion Module'
+sidebar_label: 'Package a module'
+sidebar_position: 2
+description: How to package your module for delivery to others.
+---
+
+## Background
+
+Starting with Companion 3.0, modules must be packaged with some special tooling. This is done to reduce the number and total size of files in your module. Combining your module into just a few files can often reduce the size from multiple MB, to a few hundred KB, and lead to much shorter load times.
+
+:::warning
+
+Sometimes the build process introduces or reveals issues that prevent the module from running, so be sure to test it before distributing. In our experience, issues often occur when working with files from disk, or introducing a new dependency that doesn't play nice.
+
+:::
+
+## Packaging for testing
+
+If you are using one of our [recommended module templates](../module-setup/file-structure.md) you can package your module for distribution by running
+
+```bash
+ yarn companion-module-build
+```
+
+If successful, there will now be a `pkg/` folder at your module root folder a `-.tgz` file in the root folder. The module name and version are taken from your _package.json_ file, so for example, if the module is named 'generic-animation' and the version number in _package.json_ is 0.7.0, then the file will be named _generic-animation-0.7.0.tgz_.
+
+If you need to debug the package code rather than the dev code, create an empty file `DEBUG-PACKAGED` in your module folder. Companion will read the code from `pkg` instead of your source folders.
+
+You probably don't need to do a very thorough test, as long as it starts and connects to your device and a couple of actions work it should be fine.
+
+:::tip
+
+Due to how the packaging is done, it can result in some errors producing unreadable stack traces, or for a wall of code to be shown in the log making it unreadable. While using `DEBUG-PACKAGED`, if you run `yarn companion-module-build --dev` (the `--dev` parameter is key here) it will produce a larger build of your module that will retain original line numbers and formatting, making it much easier to read any output.
+
+:::
+
+If you need help, don't hesitate to reach out on the Module Developer's [Slack channel](https://bfoc.us/ke7e9dqgaz) and we will be happy to assist you.
+
+## Packaging for distribution
+
+When you run `yarn companion-module-build` (without the --dev), it produces the _.tgz_ file described above. This file contains everything a user needs to be able to run your module. A `tgz` file is like a `zip` file, but different encoding. You, or your users, can load it from the Companion Modules page and Companion will be able to run it the same as if the module came from the store.
+
+## Customising the packaging
+
+For more complex modules, it is possible to adjust some settings in the packaging process.
+
+Be careful when using these, as changing these settings are advanced features that can cause the build process to fail.
+
+To start off, create a file `build-config.cjs` in your module folder, with the contents `module.exports = {}`. Each of these customisation sections will add some data to this file.
+
+### Changing `__dirname`
+
+Webpack has a few options for how `__dirname` behaves in packaged code. By default it gets replaced with `/` which makes everything relative to the bundled main file. Alternatively, you can set `useOriginalStructureDirname: true` and the original paths will be preserved.
+
+### Including extra data files
+
+:::tip
+Since [API 1.12](../api-changes/v1.12.md), your module by default has read-only access to just your module folder, and not the whole filesystem.
+You can [opt into more permissions](../connection-advanced/permissions.md) if you need it, but this will require permission from the user in the future.
+:::
+
+Sometimes it can be useful to store some extra data as text files, or other formats on disk. Once your module is packaged, it wont have access to any files, from the repository unless they are JavaScript which gets included in the bundle or the files are explicitly copied. You will need to do this to allow any `fs.readFile()` or similar calls to work.
+
+You can include these files by adding something like the following to your `build-config.cjs`:
+
+```js
+module.exports = {
+ extraFiles: ['*.txt'],
+}
+```
+
+You can use any glob pattern to define files to be copied.
+All files will be copied to the root folder of the package, which is the same folder where the packaged main script is in. Make sure that there are no name conflicts when copying files from different folders.
+Make sure you don't copy files you don't need, as these files will be included in the installation for all users of Companion.
+
+### Using native dependencies
+
+:::tip
+Since [API 1.12](../api-changes/v1.12.md), you have to mark in your manifest.json that you need to do this. In the future we will use this as information for the user.
+Read more about [permissions](../connection-advanced/permissions.md).
+:::
+
+Native dependencies are not possible to bundle in the same way as js ones. So to support these requires a bit of extra work on your part.
+
+It is not yet possible to use all native dependencies. We only support ones that publish prebuilt binaries as part of their npm package.
+This means that some libraries are not possible to use. Reach out if you are affected by this, we would appreciate some input, and can work with you to find or fix a library to be compatible
+
+To support these modules, you should make one of two changes to your build-config.cjs, depending on how the library works.
+
+If the library is using [`prebuild-install`](https://www.npmjs.com/package/prebuild-install), then it will not work. With `prebuild-install` it is only possible to have the binaries for one platform installed, which isn't compatible with our bundling process. If you need one of these libraries, let us know and we can try to get this working with you.
+
+If the library is using [`pkg-prebuilds`](https://www.npmjs.com/package/pkg-prebuilds) for loading the prebuilt binaries, then you can use the following syntax.
+
+```js
+module.exports = {
+ prebuilds: ['@julusian/freetype2'],
+}
+```
+
+If the library is using `node-gyp-build`, then there are a couple of options.
+The preferred method is to set `useOriginalStructureDirname: true` in `build-config.cjs`. This changes the value of `__dirname` in your built module, and allows `node-gyp-build` to find its prebuilds.
+
+If you are not able to use `useOriginalStructureDirname: true`, then you can instead mark the dependency as an external:
+
+```js
+module.exports = {
+ externals: [
+ {
+ 'node-hid': 'commonjs node-hid',
+ },
+ ],
+}
+```
+
+This isn't the most efficient solution, as it still results in a lot of files on disk. We are looking into whether we can package them more efficiently, but are currently blocked on how most of these dependencies locate the native portion of themselves to load.
+
+If the library is using something else, let us know which of these approaches works, and we can update this page to include it.
+
+### Using extra plugins
+
+Sometimes the standard webpack functionality is not enough to produce working modules for the node runtime, but there is a [webpack plugin](https://webpack.js.org/plugins/) which tackles your problem.
+
+You can include additional plugins by adding something like the following to your `build-config.cjs`:
+
+```js
+module.exports = {
+ plugins: [new webpack.ProgressPlugin()],
+}
+```
+
+### Disabling minification
+
+Some libraries can break when minified, if they are relying on names of objects in a way that webpack doesn't expect. This can lead to cryptic runtime errors.
+
+You can disable minification (module-tools >=v1.4) with:
+
+```js
+module.exports = {
+ disableMinifier: true,
+}
+```
+
+Alternatively, if you are having issues with error reports from users that have unreadable stack traces due to this minification, it can be disabled. We would prefer it to remain on for all modules to avoid bloating the install size (it can triple the size of a module), we do not mind modules enabling it if they have a reason to.
+
+### Using worker threads
+
+Worker threads need their own entrypoints, and so need their own built file to execute.
+
+We need to investigate how to handle this correctly. Reach out if you have ideas.
+
+## Common issues
+
+This process can often introduce some unexpected issues, here are some of the more common ones and solutions:
+
+_TODO_
+
+## Further reading
+
+- [Introduction to modules](../home.md)
+- [Module development 101](../module-development-101.md)
+- [Debugging Modules](../module-debugging.md)
+- [Module Permissions](../connection-advanced/permissions.md)
+- [Module Setup](../module-setup/)
+- [Module Basics](../connection-basics/index.md)
diff --git a/for-developers/module-development/module-lifecycle/releasing-your-module.md b/for-developers/module-development/module-lifecycle/releasing-your-module.md
new file mode 100644
index 0000000..074fd97
--- /dev/null
+++ b/for-developers/module-development/module-lifecycle/releasing-your-module.md
@@ -0,0 +1,47 @@
+---
+title: 'Releasing a Companion Module'
+sidebar_label: 'Release a module'
+sidebar_position: 3
+description: How to release your module for delivery to others using Companion's "web store".
+---
+
+Since Companion 4.0, modules get installed on demand from our API. This allows new updates to your module to get into users hands much quicker than before, as long as your module uses a compatible version of the module API.
+
+## First Release
+
+If this is the first release of your module, you will need to request the repository on [Slack](https://bfoc.us/ke7e9dqgaz).
+
+Please post a message in the `#module-development` channel the includes your GitHub username and the desired name of your module in the `manufacturer-product` format.
+
+Once you have a repository, and have pushed your code, you can [release a new version](#releasing-a-new-version)
+
+## Releasing a New Version
+
+When a new version of your module has been tested and is ready for distribution, use the following guide to submit it for review:
+
+1. **Update `package.json` version**
+ - Use the `major.minor.patch` format (e.g., `1.2.3`).
+ - Refer to the [Versioning of Modules guide](../../git-workflows/versioning.md#version-of-modules) for details.
+
+2. **(Optional) Update `companion/manifest.json` version**
+ - This is not required; the build process will override this value with the version from the `package.json`.
+
+3. **Create a Git tag**
+ - Prefix the version number with `v` (e.g., `v1.2.3`).
+ - You can create the tag by either:
+ - [Creating a release on GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release), or
+ - [Creating a local tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) and pushing it to the repository.
+
+4. **Submit the new version in the [Bitfocus Developer Portal](https://developer.bitfocus.io/)** (login with GitHub).
+ - In the sidebar, go to **My Connections** and select the module.
+ - Click **Submit Version** (bottom of page).
+ - Choose the Git Tag to submit.
+ - (Optional) Check **Is Prerelease** if this is a beta release.
+ - Click **Submit** to send for review. The version status should show "Pending" after this.
+
+**Notes about the review process:**
+
+- Only versions submitted to the developer portal will be reviewed.
+- Reviews are done by volunteers, so review time depends on member availability and the complexity of code changes to be reviewed.
+- If adjustments are needed, you'll receive feedback through the developer portal.
+- Once approved, the new version of the module becomes immediately available to download for users on Companion v4.0.0+.
diff --git a/for-developers/module-development/module-lifecycle/renaming-your-module.md b/for-developers/module-development/module-lifecycle/renaming-your-module.md
new file mode 100644
index 0000000..02ec6b5
--- /dev/null
+++ b/for-developers/module-development/module-lifecycle/renaming-your-module.md
@@ -0,0 +1,26 @@
+---
+title: 'Renaming a Companion Module'
+sidebar_label: 'Rename a module'
+sidebar_position: 4
+description: How to rename your module after having released it.
+---
+
+Occasionally you will need to rename a module, perhaps for example, to make the name more inclusive as you add more devices, or the manufacturer releases a new device.
+
+1. Ask in the module-development slack for approval on the new name
+ This is so that we can be sure the new name conforms to our standard structure of `companion-module-manufacturer-product` (or `companion-module-manufacturer-protocol`).
+
+2. Once approved, the team will be able to rename the GitHub repository for you.
+
+3. Some additional changes need to be made. This might be done for you, or might be left for you to do:
+ - Update the `name` and any urls in the `package.json`
+ - Update the `name` and related fields in `companion/manifest.json`
+ - Add the old name to the `legacyIds` array in `companion/manifest.json`. This lets Companion know of the rename, so that existing users will be migrated across.
+
+4. Once everything is updated, you will want to publish a new version and submit that for inclusion
+
+:::tip
+
+When renaming a module like this, you must not decrease the number of upgrade scripts. The count will continue from the old module name, so removing any upgrade scripts will cause new ones to be missed for many users.
+
+:::
diff --git a/for-developers/module-development/module-lifecycle/testing-a-custom-version-of-@companion-module-base.md b/for-developers/module-development/module-lifecycle/testing-a-custom-version-of-@companion-module-base.md
new file mode 100644
index 0000000..fcee57b
--- /dev/null
+++ b/for-developers/module-development/module-lifecycle/testing-a-custom-version-of-@companion-module-base.md
@@ -0,0 +1,28 @@
+---
+title: 'Using a custom @companion-module/base library'
+sidebar_label: 'Custom @companion-module/base'
+sidebar_position: 8
+description: How to test and use your module with a non-release version of the companion modules.
+---
+
+Sometimes it may be useful to test or use an unreleased version of `@companion-module/base`. This commonly happens when new features are added to this library, before they are deemed ready for general use.
+
+:::warning
+
+Modules using unreleased versions of `@companion-module/base` should not be distributed. There will often be subtle differences between the unreleased version and the final version that will cause bugs. Make sure to only use released versions in any distributed/published module versions.
+
+:::
+
+## Using an unreleased version
+
+This can sometimes be done against a normal build of companion, unless the changes to this library require changes in companion too.
+
+1. clone this repository somewhere on your computer if you havent already `git clone https://github.com/bitfocus/companion-module-base.git`
+2. cd into the cloned folder `cd companion-module-base`
+3. If the version you want is a branch, checkout the branch, or main if you want the primary branch. eg `git checkout main`
+4. Install dependencies `yarn install`
+5. Build the library `yarn build`. If this step fails with an error, you will need to resolve this
+6. Make the library available through `yarn link` (if you have done this before, it can be skipped)
+7. Inside your module folder, link in the local version `yarn link @companion-module/base`. This may need to be repeated anytime you run add/install/remove any dependencies from your module.
+
+Note: be aware that the custom version will stay with your module as you switch branches. Once you are done, the best way to ensure you are using the version defined in your `package.json` is to delete your `node_modules` folder and run `yarn install` to regenerate it
diff --git a/for-developers/module-development/module-lifecycle/updating-nodejs.md b/for-developers/module-development/module-lifecycle/updating-nodejs.md
index 6b68fcf..4782c62 100644
--- a/for-developers/module-development/module-lifecycle/updating-nodejs.md
+++ b/for-developers/module-development/module-lifecycle/updating-nodejs.md
@@ -1,8 +1,8 @@
---
title: 'Updating the Node.JS Version in your Module'
sidebar_label: 'Updating Node.JS'
-sidebar_position: 8
-description: Explanation of the companion module library.
+sidebar_position: 5
+description: How to update your module to use a newer version of Node.JS.
---
Nodejs often makes new releases. In the major version jumps, these can include some breaking changes which could impact your module, so we don't want to do that without you being aware of it.
diff --git a/for-developers/module-development/module-lifecycle/upgrading-a-module-built-for-companion-2.x.md b/for-developers/module-development/module-lifecycle/upgrading-a-module-built-for-companion-2.x.md
new file mode 100644
index 0000000..5169616
--- /dev/null
+++ b/for-developers/module-development/module-lifecycle/upgrading-a-module-built-for-companion-2.x.md
@@ -0,0 +1,529 @@
+---
+title: 'Upgrading a module built for Companion 2.x'
+sidebar_label: 'Upgrading from Companion 2.x'
+sidebar_position: 10
+description: How to update a module that was built for Companion 2 or earlier.
+---
+
+:::danger
+
+This guide was written over 3 years ago for an earlier version of the module api.
+A majority of it will translate, but it will not be perfect match. You may want to follow this to update to the API 1.x format, then follow the newer upgrade docs for updating to the latest structure.
+
+:::
+
+## Background
+
+In Companion 3.0, we rewrote the module-api from scratch. We chose to do this because the old api had grown very organically over 5 years, and was starting to show various issues. The main issues was modules were running in the main companion thread, and method signatures were assuming various calls to be synchronous, and modules being able to access various internals of companion (and some making concerningly large use of that ability).
+Rather than trying to quickly fix up the api, it was decided to rethink it entirely.
+
+The general shape of the api should be familiar, but many methods names have been changed, and the whole api is written to rely on promises a lot more when before either callbacks were abused or methods would be synchronous.
+
+Technology has also evolved since many of the modules were written, with many of them using js syntax that was superseded in 2015! As part of this overhaul, we have imposed some minimum requirements for tooling and code style. This shouldnt be an issue, but if you run into any issues let us know on slack and we will help you out.
+
+Note: This guide is written assuming your module is an ES6 class (`class YourModule extends InstanceSkel {`). If it is not, then it would be best to convert it to that format first, to simplify this process. That can be done before starting this conversion for Companion 3.0, as it is supported in all older versions of companion
+
+## First steps
+
+You no longer need a developer version of companion to develop your module! It can now be done with the version you usually run, or you can keep to the old way if you prefer, but you shall have to refer to the main application development guides for getting that setup and running again.
+
+Once you have the companion launcher open, click the cog in the top right. This will reveal a 'Developer modules path' field. Use this to select a `companion-module-dev` folder you created containing your modules code. See the page on [Setting up the Development Folder](../local-modules.md)
+
+Companion will load in any modules it finds from that folder when starting, and will restart itself whenever a file inside that folder is changed.
+
+You can now clone or move or existing clone into the folder you specified for development modules. Once you have done this, launch companion and it will report your module as crashing in its status, as your code needs updating.
+
+While developing, you can view a log for an instance in the ui. This will show all messages written with `this.log()`, `this.updateStatus()` and anything written to the console. Some of this is omitted from other logs, this is the best place to see output from your module while it is running.
+
+
+
+### 1) Add new dependencies
+
+To help with this new flow, any files you previously imported from companion itself (eg '../../../instance_skel') have been rewritten and are now located in a dedicated npm package. And there is a second package which provides some tooling to help with packaging your module for distribution.
+
+You can add these to your module by running `yarn add @companion-module/base -T` and `yarn add --dev @companion-module/tools`
+
+Note: We recommend `@companion-module/base` to be installed as `~1.4` rather than `^1.4.1` as the version of this will dictate the versions of companion your module is compatible with. Read the documentation on module versioning if you want more details.
+
+Add a new file (if not exist already) : `.yarnrc.yml` and put the following code in:
+
+```yaml
+nodeLinker: node-modules
+```
+
+You should also add the following to your `.gitignore` file:
+
+```text
+/pkg
+/pkg.tgz
+```
+
+### 2) Create the companion manifest
+
+Previously, Companion would read some special properties from your package.json file to know about your module. We have decided that we should instead be using our own file, so that we can avoid properties we do not need, and reduce ambiguation in the contents. This will also allow us to handle modules which are not node/npm based.
+
+To start, run the command `yarn companion-generate-manifest`. This will generate the `companion` folder based on your package.json.
+
+As part of the process, you should notice that the `HELP.md` file has moved into the folder too. The `HELP.md` is also expected to be inside of this folder, as well as any images it uses.
+
+Please give the manifest a read, it should be fairly self explanatory. You should verify that the `runtime.entrypoint` property is a relative path to your main JavaScript file. It should have been generated correctly, but be aware that you will need to change this if you move/rename the file it references.
+
+### 3) package.json cleanup
+
+Now that you have the new manifest, you can cleanup the old properties from your package.json.
+
+The following properties can be removed:
+
+- api_version
+- keywords
+- legacy
+- manufacturer
+- product
+- shortname
+- description
+- bugs
+- homepage
+- author
+- contributors
+
+Note: some of these are standard npm properties, but they are no longer necessary and are defined in the manifest.json
+
+If you have a `postinstall` script defined to build your module, that should now be removed.
+
+If you are using typescript, you can move any `@types/*` packages from dependencies to devDependencies, but this is not required. The build script should be changed from `npx rimraf dist && npx typescript@~4.5 -p tsconfig.build.json` to `rimraf dist && yarn build:main`.
+
+As this is quite a large change, we should update the version number too. To make the size of the change here clear, we should increment the first number in the version. For example, `1.5.11` should become `2.0.0` or `3.0.1` should become `4.0.0`. This classes it as a breaking change. Make sure to change the number in package.json, as that is the master location for that. Refer to the [Versioning of Modules guide](../../git-workflows/versioning.md#version-of-modules) for details.
+
+### 4) Prepare to update your code
+
+You are now ready to begin updating your code. Many properties and methods have been renamed, so this can take some time in larger modules. But the hope is that it provides a much more consistent and easier to understand api than before.
+
+Because of the amount of changes, we recommend following our steps for what to do, then to test and debug it at the very end. If you attempt to run it part way through it will most likely produce weird errors or constantly crash.
+
+Before we begin, it is recommended that you ensure you have some understanding of async & Promises in nodejs. Previously the api was very synchronous, due to everything sharing a single thread, but some methods are now asynchronous as each instance of your module is run in its own thread. It is important to understand how to use promises, as you will need that to get any values from companion, and any promises left 'floating' will crash your module.
+
+TODO - write more about async or find some good tutorials/docs/examples
+
+If you are ever unsure on how something should look, we recommend looking at the following modules. This is a curated list of up-to-date and well maintained modules. If you are still unsure, then reach out in #module-development in slack.
+
+- [generic-osc](https://github.com/bitfocus/companion-module-generic-osc)
+- [homeassistant-server](https://github.com/bitfocus/companion-module-homeassistant-server)
+
+Advanced users: You are now able to make your module be ESM if you wish. It is completely optional and should require no special configuration for companion.
+
+Finally, look through your code and make sure that any dependencies you use are defined in your `package.json`. Many modules have been accidentally using the dependencies that companion defined, but in this new structure that is not possible. You may need to spend some time updating your code to work with the latest version of a library, but this is a good idea to do every now and then anyway.
+
+### 5) Update your actions
+
+If you are using typescript, `CompanionAction` and `CompanionActions` have been renamed to `CompanionActionDefinition` and `CompanionActionDefinitions` and should be imported from `'@companion-module/base'`.
+
+For the action definitions, the following changes have been made:
+
+- `label` has been renamed to `name`
+- `options` is required, but can be an empty array (`[]`)
+- `callback` is now required. This is the only way an action can be executed (more help is below)
+
+Tip: While you are making these changes, does the value of `name` still make sense? Perhaps you could set a `description` for the action too?
+
+Some changes to `options` may be required, but we shall cover those in a later step, as the same changes will need to be done for feedbacks and config_fields.
+
+If you aren't already aware, there are some other properties you can implement if you need then.
+You can find the typescript definitions as well as descriptions of each property you can set [in the module-base repo](https://github.com/bitfocus/companion-module-base/blob/main/src/module-api/action.ts). Do let us know if anything needs more explanation/clarification.
+
+The `callback` property is the only way for an action to be executed. In previous versions it was possible to do this by implementing the `action()` function in the main class too. We found that using this callback made modules more maintainable as everything for an action was better grouped together, especially when the other methods are implemented.
+If you need help figuring out how to convert your code from the old `action` method to these callbacks then reach out on slack.
+
+The parameters supplied to the `callback` or `action` function have been restructured too:
+
+- The second parameter has been merged into the first, with some utility methods provided in the second parameter.
+- `action` has been renamed to `actionId` to be more consistent with elsewhere. This is the `id` you gave your actionDefinition.
+- `deviceId` is no longer provided as we don't see a use case for why this is useful. Let us know if you have one and we shall consider re-adding it
+- `bank` and `page` are no longer provided. These have been replaced by `controlId`. Actions can reside in a trigger rather than on a bank, and controlId lets us express that better. `controlId` is a unique identifier that will be the same for all actions & feedbacks on the same button or inside the same trigger, but its value should not be treated as meaningful. In a later version of companion the value of the `controlId` will change.
+- The new second parameter contains an implementation of `parseVariablesInString`, this has more purpose for feedbacks, and is provided to actions for consistency
+
+Note: there are some properties on the object with names starting with an underscore that are not mentioned here. You must not use these, as these are temporary properties. They will be removed without notice in a future version.
+
+If you are using `subscribe`, `unsubscribe` or `learn`, the object parameter has changed a little, and is a subset of the properties supplied to `callback`.
+
+Finally, to pass the action definitions to companion has changed. It is now `this.setActionDefinitions(actions)` instead of `this.setActions(actions)` or `self.system.emit('instance_actions', self.id, actions)`
+
+### 6) Updating your feedbacks
+
+If you are using typescript, `CompanionFeedback` and `CompanionFeedbacks` have been renamed to `CompanionFeedbackDefinition` and `CompanionFeedbackDefinitions` and should be imported from `'@companion-module/base'`.
+
+For the feedback definitions, the following changes have been made:
+
+- `type` is now required. If you don't have it set already, then it should be set to `'advanced'`
+- `label` has been renamed to `name`
+- `options` is required, but can be an empty array (`[]`)
+- `callback` is now required. This is the only way an action can be executed (more help is below)
+- If your feedback is of `type: 'boolean'` then `style` has been renamed to `defaultStyle`
+
+Additionally, the `rgb` and `rgbRev` methods no longer exist on your instance class. They have been renamed to `combineRgb` and `splitRgb` and should be imported from `'@companion-module/base'`.
+
+Tip: While you are making these changes, does the value of `name` still make sense? Perhaps you could set a `description` for the action too?
+
+Some changes to `options` may be required, but we shall cover those in a later step, as the same changes will need to be done for feedbacks and config_fields.
+
+If you aren't already aware, there are some other properties you can implement if you need then.
+You can find the typescript definitions as well as descriptions of each property you can set [in the module-base repo](https://github.com/bitfocus/companion-module-base/blob/main/src/module-api/feedback.ts). Do let us know if anything needs more explanation/clarification.
+
+The `callback` property is the only way for an feedback to be checked. In previous versions it was possible to do this by implementing the `feedback()` function in the main class too. We found that using this callback made modules more maintainable as everything for a feedback was better grouped together, especially when the other methods are implemented.
+If you need help figuring out how to convert your code from the old `feedback` method to these callbacks then reach out on slack.
+
+The parameters supplied to the `callback` or `feedback` function have been restructured too:
+
+- The parameters have been merged into one, with some utility methods provided in the second parameter.
+- `type` has been renamed to `feedbackId` to be more consistent with elsewhere. This is the `id` you gave your feedbackDefinition.
+- `bank` and `page` are no longer provided. These have been replaced by `controlId`. Feedbacks can reside in a trigger rather than on a bank, and controlId lets us express that better. `controlId` is a unique identifier that will be the same for all actions & feedbacks on the same button or inside the same trigger, but its value should not be treated as meaningful. In a later version of companion the value of the `controlId` will change.
+- It is no longer possible to get the complete 'bank' object that was provided before. Do let us know if you have a use case for it, we couldn't think of one.
+- For 'advanced' feedbacks, the `width` and `height` properties are now represented by a single `image` property. This helps clarify when they will be defined. Also note that these may not be present for all feedbacks in a future version.
+- The new second parameter contains an implementation of `parseVariablesInString`. You **must** use this instead of the similar method on the class, otherwise your feedback will not be rechecked when the variables change.
+
+Note: there are some properties on the object with names starting with an underscore that are not mentioned here. You must not use these, as these are temporary properties. They will be removed without notice in a future version.
+
+If you are using `subscribe`, `unsubscribe` or `learn`, the object parameter has changed a little, and is a subset of the properties supplied to `callback`.
+
+### 7) Updating your presets
+
+If you are using typescript, `CompanionPreset` has been renamed to `CompanionButtonPresetDefinition`. There is also a `CompanionPresetDefinitions` defining a collection of these objects.
+
+The first change to be aware of, is that the `setPresetDefinitions()` function is now expecting an object of presets, rather than array. This is for better consistency with actions and feedbacks, and also provides a unique id for each preset.
+
+For the preset definitions, the following changes have been made for both types:
+
+- `type` is a new property that must be `button`
+- `label` has been renamed to `name`
+- `options` is a new property of some behavioural properties for the button. Its contents is explained below.
+- `bank` has been renamed to `style`. Additionally some properties have been moved out of this object, listed below.
+- `bank.style` has been removed
+- `bank.relative_delay` has been moved to `options.relativeDelay`
+- `bank.latch` has been removed. This will be handled below when changing the actions
+- `feedbacks` The objects inside this have changed slightly. The `type` property has been renamed to `feedbackId`, for better consistency.
+- `actions` and `release_actions` have been combined into `steps`, the exact structure is documented below.
+
+Note: Even when there are no actions or feedbacks, you would need to put those objects in : `feedbacks: []` & `steps: []`.
+
+Note: Remember that the `rgb` and `rgbRev` methods no longer exist on your instance class. They have been renamed to `combineRgb` and `splitRgb` and should be imported from `'@companion-module/base'`.
+
+The latch button mode has been replaced with a more flexible 'stepped' system. On each button, you can have as many steps as you wish, each with their own down/up/rotate actions. When releasing the button, it will by default automatically progress to the next step, or you can disable that and use an internal action to change the current step of a button.
+While is is wordier and more complex to make a latched button, this allows for much more complex flows, such as using another button as a 'shift' key, or having one 'go' button which runs the whole pre-programmed show.
+
+The `steps` property is an array of objects. Each object should be at a minimum `{ down: [], up: [] }` (`rotate_left` and `rotate_right` are also valid here).
+
+For example, a normal button will only have one step:
+
+```javascript
+steps: [
+ {
+ down: [],
+ up: [],
+ },
+]
+```
+
+Or you can match the old latching behaviour with:
+
+```javascript
+steps: [
+ {
+ // Put the 'latch' actions here
+ down: [],
+ up: [],
+ },
+ {
+ // Put the 'unlatch' actions here
+ down: [],
+ up: [],
+ },
+]
+```
+
+For the action objects inside of each of these steps, the `action` property renamed to `actionId`, for better consistency with elsewhere.
+
+### 8) Updating options and config fields
+
+The options/input fields available to use as options for actions and feedbacks, as well as for your config fields has changed a little.
+
+There may be additional new properties not listed here. You can check [the docs](../connection-basics/input-field-types.md) for full details on the available input fields.
+
+#### common changes
+
+The optional `isVisible` function has changed, its parameter is now the options object for the action/feedback, not the whole action/feedback object
+
+#### text
+
+The `text` type has been renamed to `static-text`
+
+#### textinput & textwithvariables
+
+These have been combined into one `textinput`. With a new `useVariables` property to select the mode.
+
+#### dropdown
+
+This has been split into `dropdown` and `multidropdown`.
+
+`minSelection` and `maximumSelectionLength` are only valid for `multidropdown`
+
+`maximumSelectionLength` has been renamed to `maxSelection`
+
+`regex` and `allowCustom` are only valid for `dropdown`
+
+#### multiselect
+
+`multidropdown` should be used instead
+
+#### checkbox & colorpicker & number
+
+These are unchanged
+
+#### Anything else
+
+That should be all of them, if you have something else then it has likely been forgotten/removed.
+
+Either use a supported input type or let us know what we missed.
+
+### 9) Updating variables
+
+If you are using typescript, `CompanionVariable` has been renamed to `CompanionVariableDefinition` and should be imported from `'@companion-module/base'`.
+
+For the variable definitions, the following changes have been made:
+
+- `name` has been renamed to `variableId`
+- `label` has been renamed to `name`
+
+We acknowledge that this change is rather confusing, but it felt necessary for consistency with elsewhere
+
+To set the value of variables, the `setVariables` method has been renamed to `setVariableValues`, and the `setVariable` method has been removed.
+This is to encourage multiple values to be set in the one call which will make companion more responsive by being able to process multiple changes at a time. Please try to combine calls to `setVariableValues` where possible.
+
+For example, before:
+
+```js
+this.setVariable('one', 'word')
+this.setVariable('two', 34)
+this.setVariable('three', undefined)
+```
+
+After:
+
+```js
+this.setVariableValues({
+ one: 'word',
+ two: 34,
+ three: undefined,
+})
+```
+
+### 10) Updating upgrade-scripts
+
+If you are using typescript, `CompanionStaticUpgradeScript` should be imported from `'@companion-module/base'`.
+
+If you are using the `CreateConvertToBooleanFeedbackUpgradeScript` helper method on the InstanceSkel, this has moved and should be imported from `'@companion-module/base'`.
+
+The upgrade script parameters and return value have been completely reworked, as the old functions did not fit into the new flow well.
+
+The first parameter (`context`) to the functions remains, but currently has no methods. We expect to add some methods in the future.
+The remaining parameters have been combined into a single `props` object.
+
+This object is composed as
+
+```js
+{
+ config: Object | null,
+ actions: [],
+ feedbacks: [],
+}
+```
+
+Tip: These upgrade scripts can be called at any time. They can be called to upgrade existing configuration, or when data is imported into companion.
+
+At times the config property will be null, if the config does not need updating. There may be no actions or no feedbacks, depending on what needs upgrading.
+
+Previously, the return type was simply `boolean`, to state whether anything had changed. The return type is now expected to be an object of the format:
+
+```js
+{
+ updatedConfig: Object | null,
+ updatedActions: [],
+ updatedFeedbacks: [],
+}
+```
+
+If an action or feedback is not included in the output type, then it is assumed to not have been changed and any changes you have made to the object passed in will be lost.
+If `updatedConfig` is not set, then it is assumed that the config has not changed, and any changes will be lost.
+
+This allows companion to better understand what has changed in an optimal way, and also allows you more flexibility in your code as you are no longer forced to update in place.
+
+Tip: Make sure you don't change the id fields, or it won't track the changes!
+
+The config object is the same as you receive in the module, and is the same as before.
+
+The action and feedback objects have a similar shape to how they are provided to their callbacks. You can see more about the exact structure of the objects [in the module-base repo](https://github.com/bitfocus/companion-module-base/blob/main/src/module-api/upgrade.ts). This is harder to document the changes, and upgrade scripts are not that widely used.
+
+Finally, these are no longer provided via the static method. They will be passed into a function call later described later on. We suggest making them an array outside of the class that can be used later on.
+
+### 11) Updating any uses of the TCP/UDP/Telnet helpers
+
+If you are importing the old socket helpers, you will need to make some changes to handle some changes that have been made to them.
+
+#### UDP
+
+This should be imported as `UDPHelper` from `@companion-module/base` instead of the old path.
+
+Most usage of the class is the same, only the differences are documented:
+
+- The `addMembership` method has been removed. It was previously broken and appeared unused by any module. If you have need for it, it can be reimplemented
+- The `send` method no longer accepts a callback. Instead it returns a promise that must be handled.
+- The `status_change` event emits different statuses, to match how they have changed elsewhere. It now emits `'ok' | 'unknown_error'`
+- There are some new readonly properties added: `isDestroyed`
+- Any previously visible class members have been hidden. If you rely on any, let us know and we shall look at extending the wrapper or making things public again
+
+#### TCP
+
+This should be imported as `TCPHelper` from `@companion-module/base` instead of the old path.
+
+Most usage of the class is the same, only the differences are documented:
+
+- The `send` method no longer accepts a callback. Instead it returns a promise that must be handled.
+- The `status_change` event emits different statuses, to match how they have changed elsewhere. It now emits `'ok' | 'connecting' | 'disconnected' | 'unknown_error'`
+- There are some new readonly properties added: `isConnected`, `isConnecting` and `isDestroyed`
+- The `write` and `send` methods have been combined into a single `send` method. Behaviour is the same, just the name has changed
+- Any previously visible class members have been hidden. If you rely on any, let us know and we shall look at extending the wrapper or making things public again
+
+#### Telnet
+
+This should be imported as `TelnetHelper` from `@companion-module/base` instead of the old path.
+
+Most usage of the class is the same, only the differences are documented:
+
+- The `send` method no longer accepts a callback. Instead it returns a promise that must be handled.
+- The `status_change` event emits different statuses, to match how they have changed elsewhere. It now emits `'ok' | 'connecting' | 'disconnected' | 'unknown_error'`
+- There are some new readonly properties added: `isConnected`, `isConnecting` and `isDestroyed`
+- The `write` and `send` methods have been combined into a single `send` method. Behaviour is the same, just the name has changed
+- Any previously visible class members have been hidden. If you rely on any, let us know and we shall look at extending the wrapper or making things public again
+
+### 12) Updating your main class
+
+Finally, we are ready to look at your main class.
+
+To start, you should change your class to extend `InstanceBase`, which can be imported from `@companion-module/base`.
+
+There are a few fundamental changes to `InstanceBase` compared to the old `InstanceSkel`.
+
+- You should be doing very little in the constructor. You do not have the config for the instance at this point, or the ability to call any companion methods here. The intention is to make sure various class properties are defined here, with the module truly starting to work in the `init()` method.
+- `this.config` is no longer provided for you by the base class. You are provided a new config object in `init()` and `updateConfig()`, it is up to you to to an `this.config = config` when receiving that, or to do something else with the config object.
+- `this.system` is no longer available. That was previously an internal api that too many modules were hooking into. This caused many of them to break at unexpected times, and is no longer possible in this new api. If we haven't exposed something you are using on system as a proper method on `InstanceBase`, then do let us know on slack or github, and we will either implement it or help you with an alternative.
+
+The constructor has changed to have a single parameter called `internal`. This is of typescript type `unknown`. You must not use this object for anything yourself, the value of this is an internal detail, and will change in unexpected ways without notice.
+You should start your constructor with the following
+
+```js
+constructor(internal) {
+ super(internal)
+```
+
+Remember that you do not have access to the config here, you may need to move some stuff into `init()`
+
+Hopefully you have an understanding of async code, because we now need to start using it.
+It is expected that `init()` will return a Promise. The simplest way to do this is to mark it as async.
+
+```js
+ async init(config) {
+```
+
+`init()` also has a parameter, of your config object.
+
+Inside of init, you are free to do things as you wish. But make sure that any method returning a promise isn't left floating, so that errors propagate correctly.
+
+Tip: if you do a `this.checkFeedbacks()` inside of `init()`, you can remove that line
+
+The method `config_fields` should be renamed to `getConfigFields`.
+The method `updateConfig` should be renamed to `configUpdated`, it too is expected to return a Promise and should also be marked as async.
+The method `destroy` is expected to return a Promise and should also be marked as async.
+
+If you have a method called `action` or `feedback` still, make sure it has been migrated fully in the earlier steps, then remove it as it will no longer be called.
+
+Some other methods provided by companion have been changed.
+Any where the name starts with an underscore must not be used as they are internal methods that will change without notice.
+
+- The static method `CreateConvertToBooleanFeedbackUpgradeScript` has been removed and can be imported from `@companion-module/base` instead
+- The method `saveConfig` now expects a parameter of the config object to be saved
+- The method `setActions` has been renamed to `setActionDefinitions`, as explained earlier
+- The method `setPresetDefinitions` now expects an object of presets, as explained earlier
+- The method `setVariables` has been renamed to `setVariableValues`, as explained earlier
+- The method `setVariable` has been removed, as explained earlier
+- The method `getVariable` has been renamed to `getVariableValue`.
+- The method `checkFeedbacks` now accepts multiple feedbacks to check. eg `this.checkFeedbacks('one', 'two', 'three')`
+- The method `parseVariables` has been renamed to `parseVariablesInString`. Note that this method returns a promise instead of accepting a callback.
+- The method `getAllFeedbacks` has been removed, with no replacement
+- The method `getAllActions` has been removed, with no replacement
+- The method `oscSend` is unchanged
+- The method `status` has been renamed to `updateStatus`. Additionally, the first parameter has been changed and should be provided a string with one of the values from below. The second parameter remains as an optional string for more details. Note: calls to this also now add a log line when the status changes.
+- The method `log` is unchanged.
+- The method `debug` has been removed, use `log` instead
+- The methods `rgb` and `rgbRev` have been removed. They can be imported as `combineRgb` and `splitRgb` from `@companion-module/base` instead
+- The `STATUS_*` properties have been removed, they are no longer useful
+- The `REGEX_*` properties have been removed. Instead you can import `Regex` from `@companion-module/base` and use them from there.
+- The method `defineConst` has been removed. Instead you can either define it as a constant variable outside your class `const YOUR_THING = value` (perhaps in a separate constants.js file?) or as a normal member variable `this.YOUR_THING = value`
+- Anything else? It has likely been removed or forgotten. Ask us on slack
+
+Possible values for status: 'ok', 'connecting', 'disconnected', 'connection_failure', 'bad_config', 'unknown_error', 'unknown_warning'
+Note: More will be added in the future, let us know if you have any ideas for common statuses.
+
+Once you have made sure that any method calls to methods exposed on InstanceBase have been updated, there is only a little bit more.
+
+At the bottom of your file you should find a line looking something like `export = MyInstance`.
+You should replace this line with `runEntrypoint(MyInstance, UpgradeScripts)`, making sure to pass your class as the first parameter, and your array of upgrade scripts to the second. If you have no upgrade scripts then make the second parameter be `[]`.
+
+Congratulations. You have now converted all of your code!
+
+It is time to take a break, as next we shall be running and testing it.
+
+### 13) Run it and debug!
+
+Startup companion, and make sure you have it setup so that it will find your custom module.
+
+If all went well, then your module will run and connect to your device.
+
+If it does not, hopefully you can figure out what has broken. There are too many possibilities for us to document here, but we can try to document some common issues.
+
+Once it is running, make sure to test every action, feedback, variable and preset. It is easy to make a mistake during the upgrading process. Whatever bugs you find now means less to be found by other users.
+
+When you are happy with it being stable enough for others to test, let us know and we shall include it in the beta builds.
+
+### 14) Package it and test
+
+For modules in this new format, we require them to be packaged with some special tooling. This is done to both reduce the number of files that your module spans on disk, and also the size. Loading code spread across hundreds of files is surprisingly slow on some OSes, any by combining it all into a few files, we can often reduce the size from multiple MB, to a few hundred KB.
+
+During the build process of the releases your module package will be generated automatically and bundled with the application, so you have to make sure that the final package is working. If you are developing with a complete dev environment, it is not sufficient if your module works in the dev environment.
+
+Sometimes once built there are issues that prevent a package from running, so it is mandatory to test it before distributing it. In our experience, issues often occur when working with files from disk, or introducing a new dependency that doesn't play nice. Once you have done this once, if you are just changing some internal logic you probably don't need to repeat this unless you want to be sure.
+
+You can build your module into this format with `yarn companion-module-build`. If this was successful, there should now be a `pkg` folder and a `pkg.tgz` file. These both contain the build version of your module!
+If you create an empty file `DEBUG-PACKAGED` in your module folder, then companion will read the code from `pkg` instead. This will let you test it.
+You probably don't need to do a very thorough test, as long as it starts and connects to your device and a couple of actions work it should be fine.
+
+Make sure to remove this `DEBUG-PACKAGED` file once you are done testing it, or next time you try to update your module it will keep loading the copy from `pkg`!
+
+If you encountered any issues in this process that you need help with, then have a look at the [Module packaging](./module-packaging.md) page for additional tips.
+
+### 15) Feedback
+
+Have any thoughts/feedback on this process? Anything in the docs that should be improved? Do [let us know](https://github.com/bitfocus/companion-module-base/issues), we are interested in your feedback!
+We won't be able to cater to everything you dislike about the changes, as other modules are already using these new apis, but perhaps we can make the transition smoother?
+
+Have an idea of a new connection helper that would be beneficial to you? Or have some utility code that you are copying into multiple modules? We are interested to hear this. We are happy to add more to `@companion-module/base` if it will be useful to many modules and is unlikely to result in breaking changes.
+
+We appreciate that this update is throwing a lot of changes at you, but changes of this scale are a rare occurrence and shouldn't be necessary to repeat for at least another 5 years.
+
+### 16) Follow up recommendations
+
+There are some extra steps that we recommend modules take, but are completely optional.
+
+- [Setting up code formatting](../module-setup/code-quality.md)
+- [Reusable TypeScript config](../module-setup/typescript-config.md)
+- [Could any feedbacks be converted to booleans?](../connection-advanced/migrating-legacy-to-boolean-feedbacks.md)
+- [Using the subscribe/unsubscribe callbacks in actions](../connection-basics/actions.md#subscribe--unsubscribe-flow)
+- [Using the subscribe/unsubscribe callbacks in feedbacks](../connection-basics/feedbacks.md#subscribe--unsubscribe-flow)
+- [Using the learn callbacks](../connection-advanced/learn-action-feedback-values.md)
diff --git a/for-developers/module-development/module-setup/_category_.json b/for-developers/module-development/module-setup/_category_.json
new file mode 100644
index 0000000..13f7692
--- /dev/null
+++ b/for-developers/module-development/module-setup/_category_.json
@@ -0,0 +1,11 @@
+{
+ "label": "Module Setup",
+ "position": 10,
+ "link": {
+ "type": "doc",
+ "id": "index"
+ },
+ "customProps": {
+ "description": "The files and file structure necessary to create and configure a module repository."
+ }
+}
diff --git a/for-developers/module-development/module-config/code-quality.md b/for-developers/module-development/module-setup/code-quality.md
similarity index 90%
rename from for-developers/module-development/module-config/code-quality.md
rename to for-developers/module-development/module-setup/code-quality.md
index bddbfd0..72755d2 100644
--- a/for-developers/module-development/module-config/code-quality.md
+++ b/for-developers/module-development/module-setup/code-quality.md
@@ -5,9 +5,9 @@ sidebar_position: 4
description: Using prettier and a linter to prevent common bugs.
---
-We recommend using [eslint](https://eslint.org/) and [prettier](https://prettier.io/) to improve the readability and uniformity of your code and to prevent easily-overlooked coding errors. The two tools work together to enforces the formatting and coding rules. If you are using an IDE such as VS Code, we recommend installing the prettier plugin. In that plugin you can also enable 'format on save' to automate some of the formatting.
+We recommend using [eslint](https://eslint.org/) and [prettier](https://prettier.io/) to improve the readability and uniformity of your code and to prevent easily-overlooked coding errors. The two tools work together to enforce the formatting and coding rules. If you are using an IDE such as VS Code, we recommend installing the prettier plugin. In that plugin you can also enable 'format on save' to automate some of the formatting.
-:::important
+:::tip
Our [recommended templates](./file-structure.md) come with eslint and prettier configuration files. The remainder of this page is only necessary for people who are setting up their repo manually or want to upgrade an older module's repo... or if you just want to gain a deeper understanding of the mechanics of these config files.
@@ -24,7 +24,7 @@ If you are _not_ using the [recommended templates](./file-structure.md), you can
```json
"lint:raw": "eslint",
-"lint": "yarn lint:raw ."
+"lint": "yarn lint:raw .",
"format": "prettier -w ."
```
@@ -49,7 +49,7 @@ import { generateEslintConfig } from '@companion-module/tools/eslint/config.mjs'
export default generateEslintConfig({})
```
-If using typescript, you should specify a `typescriptRoot`
+If using typescript, you should specify `enableTypescript`
```js
import { generateEslintConfig } from '@companion-module/tools/eslint/config.mjs'
@@ -63,7 +63,7 @@ You can now run `yarn lint` and see any linter errors. If you need any help unde
:::note
-If you have any suggestions on changes to make to this eslint config, do [open an issue](https://github.com/bitfocus/companion-module-tools/issues) to let us know. We hope that this set of rules will evolve over time based on what is and isnt useful to module developers.
+If you have any suggestions on changes to make to this eslint config, do [open an issue](https://github.com/bitfocus/companion-module-tools/issues) to let us know. We hope that this set of rules will expand over time based on what is and isn't useful to module developers.
:::
@@ -98,7 +98,7 @@ Run `yarn husky` to ensure husky is initialised.
### Running the linter on push
-It is a good idea to setup a Github Actions workflow to run the linter, so that you don't get surprised by unexpected linter failures when running it locally.
+It is a good idea to setup a GitHub Actions workflow to run the linter, so that you don't get surprised by unexpected linter failures when running it locally.
To do this, create a new file in the repository at `.github/workflows/lint.yaml`, with the content:
diff --git a/for-developers/module-development/module-config/file-structure.md b/for-developers/module-development/module-setup/file-structure.md
similarity index 99%
rename from for-developers/module-development/module-config/file-structure.md
rename to for-developers/module-development/module-setup/file-structure.md
index 209d222..28cacdc 100644
--- a/for-developers/module-development/module-config/file-structure.md
+++ b/for-developers/module-development/module-setup/file-structure.md
@@ -84,7 +84,7 @@ Companion is an MIT licensed project. We recommend modules released with the pro
In the future it might be possible to use different licenses for modules, but that is not yet certain.
-:::important
+:::tip
Consult the Companion team if you wish to incorporate a dependency that does not have an MIT license.
diff --git a/for-developers/module-development/module-setup/index.md b/for-developers/module-development/module-setup/index.md
new file mode 100644
index 0000000..2e0d24b
--- /dev/null
+++ b/for-developers/module-development/module-setup/index.md
@@ -0,0 +1,7 @@
+---
+title: Module Setup and Structure
+description: The files and file structure necessary to create a module repository.
+auto_toc: 3
+---
+
+This section describes the files and file structure necessary to create a module repository.
diff --git a/for-developers/module-development/module-config/manifest.json.md b/for-developers/module-development/module-setup/manifest.json.md
similarity index 89%
rename from for-developers/module-development/module-config/manifest.json.md
rename to for-developers/module-development/module-setup/manifest.json.md
index a782573..7bf498b 100644
--- a/for-developers/module-development/module-config/manifest.json.md
+++ b/for-developers/module-development/module-setup/manifest.json.md
@@ -7,13 +7,13 @@ description: Specification of the Companion manifest file
Starting with Companion 3.0, Companion looks at the `companion/manifest.json` file for module information (before 3.0 it looked at `package.json`) This provides a companion specific and programming language agnostic manifest about your module. In the future this will allow us to do more powerful things!
-You can see the auto-generated documentation for this file as a typescript interface [here](https://bitfocus.github.io/companion-module-base/interfaces/ModuleManifest.html).
+Read the [auto-generated documentation for manifest.json](https://bitfocus.github.io/companion-module-base/interfaces/ModuleManifest.html) for more details.
Tip: At any point you can validate your `manifest.json` by running `yarn companion-module-check`.
-### Format
+## Format
-If you are comfortable reading or working with JSON Schema, you can find the formal definition [here](https://github.com/bitfocus/companion-module-base/blob/main/assets/manifest.schema.json)
+If you are comfortable reading or working with JSON Schema, you can find the [formal definition in the module-base repo](https://github.com/bitfocus/companion-module-base/blob/main/assets/manifest.schema.json)
A full manifest definition is:
@@ -46,7 +46,7 @@ A full manifest definition is:
}
```
-### Properties
+## Properties
- `id` unique id of your module. This has to match the repository name excluding the `companion-module-`
- `name` ???
@@ -68,4 +68,4 @@ The runtime block is defined as:
- `type` This can be either `node18` or `node22`, depending on the required version of Node.js. In the future this may allow for other languages to be used.
- `api` This must be `nodejs-ipc`. It defines the protocol used between your module and Companion. In the future more options will be possible, to allow for other languages.
- `apiVersion` This should be left as `0.0.0`, the build process populates with the correct value
-- `entrypoint` The main javascript file for your module. This is what companion will execute to start your module.
+- `entrypoint` The main JavaScript file for your module. This is what companion will execute to start your module.
diff --git a/for-developers/module-development/module-config/typescript-config.md b/for-developers/module-development/module-setup/typescript-config.md
similarity index 86%
rename from for-developers/module-development/module-config/typescript-config.md
rename to for-developers/module-development/module-setup/typescript-config.md
index b17efca..ea5212f 100644
--- a/for-developers/module-development/module-config/typescript-config.md
+++ b/for-developers/module-development/module-setup/typescript-config.md
@@ -5,18 +5,18 @@ sidebar_position: 5
description: Configuring the module to work with TypeScript.
---
-:::important
+:::tip
This is an advanced topic. If you use the [recommended templates](./file-structure.md), a default typescript
config file is included and you will generally not want to change it.
:::
-The [recommended templates](./file-structure.md) provide typescript config presets in _tsconfig.json_ that we believe to be best practise, but they can be configured to be too strict for some, or may need to be modified if you change the name of the source or destination directories.
+The [recommended templates](./file-structure.md) provide typescript config presets in _tsconfig.json_ that we believe to be best practice, but they can be configured to be too strict for some, or may need to be modified if you change the name of the source or destination directories.
A typical _tsconfig.json_ file looks like:
-```json
+```jsonc
{
"extends": "@companion-module/tools/tsconfig/node22/recommended",
"include": ["src/**/*.ts"],
@@ -25,27 +25,27 @@ A typical _tsconfig.json_ file looks like:
"outDir": "./dist",
"baseUrl": "./",
"paths": {
- "*": ["./node_modules/*"]
- }
- }
+ "*": ["./node_modules/*"],
+ },
+ },
}
```
Our TypeScript template splits it into two files:
-```json
+```jsonc
//tsconfig.json
{
"extends": "./tsconfig.build.json",
"include": ["src/**/*.ts"],
"exclude": ["node_modules/**"],
"compilerOptions": {
- "types": ["node"]
- }
+ "types": ["node"],
+ },
}
```
-```json
+```jsonc
// tsconfig.build.json
{
"extends": "@companion-module/tools/tsconfig/node22/recommended",
@@ -55,14 +55,14 @@ Our TypeScript template splits it into two files:
"outDir": "./dist",
"baseUrl": "./",
"paths": {
- "*": ["./node_modules/*"]
+ "*": ["./node_modules/*"],
},
"module": "Node16",
- "moduleResolution": "Node16"
- }
+ "moduleResolution": "Node16",
+ },
}
```
You are free to override properties as you wish, this is only our recommendation after all.
-If you have any suggestions on changes to make to this base tsconfig, do [open an issue](https://github.com/bitfocus/companion-module-tools/issues) to let us know. We hope to collect some alteranate presets along with recommended.
+If you have any suggestions on changes to make to this base tsconfig, do [open an issue](https://github.com/bitfocus/companion-module-tools/issues) to let us know. We hope to collect some alternate presets along with recommended.
diff --git a/for-developers/module-development/module-config/unit-testing.md b/for-developers/module-development/module-setup/unit-testing.md
similarity index 100%
rename from for-developers/module-development/module-config/unit-testing.md
rename to for-developers/module-development/module-setup/unit-testing.md
diff --git a/for-developers/setting-up-WSL.md b/for-developers/setting-up-WSL.md
index df5aa78..ff03617 100644
--- a/for-developers/setting-up-WSL.md
+++ b/for-developers/setting-up-WSL.md
@@ -70,4 +70,4 @@ EOF
- Select the USB device by clicking on it and then press the "Attach" button. The device should now move from the top pane to the forwarded devices pane.
- Optional: on the linux shell use `lsusb` to check if you find your device and remember the bus and device number.
- Optional: In the linux shell use `cat /dev/bus/usb/001/003` to check if you have access to the device. Replace the numbers (/001/003) with the bus number and the device number that you have found with lsusb
-- _Note: most Companions USB surfaces are handled as HID devices. WSL presents the HID interface through a separate “device” than shown by_ `lsusb` _Instead when an HID device is added via the usb-ip driver, it will set up_ `/dev/hidraw#` where # is an integer starting from 1. If permissions are incorrectly set, Companion will output an error message in the terminal. _You can also test it directly, as above._
+- _Note: most Companion's USB surfaces are handled as HID devices. WSL presents the HID interface through a separate “device” than shown by_ `lsusb` _Instead when an HID device is added via the usb-ip driver, it will set up_ `/dev/hidraw#` where # is an integer starting from 1. If permissions are incorrectly set, Companion will output an error message in the terminal. _You can also test it directly, as above._
diff --git a/for-developers/setting-up-developer-environment.md b/for-developers/setting-up-developer-environment.md
index 5b45351..778dcbb 100644
--- a/for-developers/setting-up-developer-environment.md
+++ b/for-developers/setting-up-developer-environment.md
@@ -7,7 +7,7 @@ description: Setting up a Developer Environment
import UserGuideLink from '@site/src/UserGuideLink';
-Companion is written in Javascript/Typescript and uses the [Node.js](https://nodejs.org/en/) runtime. In addition, all parts of Companion are organized and tracked using [Git](./git-workflows/installing-git.md). Here we will provide instructions for installing the development tools you will need for contributing to Companion, whether as a module or a part of core Companion.
+Companion is written in Javascript/TypeScript and uses the [Node.js](https://nodejs.org/en/) runtime. In addition, all parts of Companion are organized and tracked using [Git](./git-workflows/installing-git.md). Here we will provide instructions for installing the development tools you will need for contributing to Companion, whether as a module or a part of core Companion.
Companion, Javascript and Node.js are platform independent, so you can develop on Windows, macOS or Linux and the code you write will be able to run on all three platforms.
@@ -110,7 +110,7 @@ yarn globally and are having problems, consider removing the global install.
See the [instructions for installing Git here](./git-workflows/installing-git.md).
-:::important[Windows Note]
+:::info[Windows Note]
As per [the windows note here](./git-workflows/installing-git.md#configure-git):
In order for `git clone` to give you `lf` endings, this default needs to be overridden _**before you clone the companion repository**_. In a git bash window type:
diff --git a/src/css/custom.css b/src/css/custom.css
index 4fe2ca5..ef8c1a7 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -254,11 +254,6 @@
color: #6b7280;
}
-/* In markdown pages indent all text, including subheaders, under H2 headers */
-.markdown h2 ~ :not(h1, h2) {
- margin-left: 2rem;
-}
-
/* Auto-generated TOC heading links should be white, not red */
.auto-toc-heading a {
color: var(--ifm-heading-color);
@@ -269,3 +264,32 @@
color: var(--ifm-heading-color);
text-decoration: underline;
}
+
+/* In markdown pages indent all text, including subheaders, under H2 headers */
+.markdown h2 ~ :not(h1, h2) {
+ margin-left: 2rem;
+}
+
+/* Some default numbers: in markdown, the ifm defaults are overridden
+ --ifm-heading-line-height: 1.25;
+ --ifm-h1-font-size: 2rem; but 3rem for top of file (.markdown h1:first-child),
+ --ifm-h2-font-size: 2rem; in markdown (default is 1.5 rem)
+ --ifm-h3-font-size: 1.5 in markdown; normal is 1.25rem;
+ --ifm-h4-font-size: 1rem; (unchanged)
+ --ifm-h5-font-size: 0.875rem;
+ --ifm-h6-font-size: 0.85rem;
+ */
+.markdown h1 {
+ --ifm-h1-vertical-rhythm-bottom: 1;
+ font-size: 2em; /* setting --ifm-h1-font-size doesn't work (because of specificity?) */
+}
+
+.markdown h2 {
+ --ifm-h2-vertical-rhythm-top: 1; /* default 2 is too much. Also, we already indent everything under H2 to make H2 breaks clear */
+ --ifm-heading-vertical-rhythm-bottom: calc(0.5 / 1.25); /* this is multiplied by --ifm-leading = 1.25 */
+ font-size: 1.5em;
+}
+
+.markdown h3 {
+ font-size: 1.25em;
+}
diff --git a/src/remark/autoTocPlugin.mjs b/src/remark/autoTocPlugin.mjs
index 67f20dd..b799341 100644
--- a/src/remark/autoTocPlugin.mjs
+++ b/src/remark/autoTocPlugin.mjs
@@ -3,12 +3,18 @@
*
* When a document has `auto_toc: true` in its frontmatter, this plugin reads
* all sibling `.md` files in the same directory, extracts their titles and
- * headings, and appends an organized TOC to the document.
+ * headings, and appends a bulleted TOC to the document.
+ *
+ * If subdirectories exist, they will be listed with their files as the "content"
+ *
+ * auto_toc: number | boolean - if number, only include headers to that H# level. If `true`, go up to H3.
*/
-import { readFileSync, readdirSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { dirname, basename, join } from 'node:path'
-/** Parse YAML frontmatter from a markdown string (simple key: value only). */
+/** Parse YAML frontmatter from a markdown string (simple key: value only).
+ * Note: a possibly better way to do this would be with npm gray-matter. Leaving this for now
+ */
function parseFrontmatter(content) {
const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
if (!match) return { frontmatter: {}, body: content }
@@ -84,22 +90,54 @@ function parseInlineContent(text) {
export default function autoTocPlugin() {
return (tree, vfile) => {
- if (!vfile.data?.frontMatter?.auto_toc) return
+ const auto_toc = vfile.data?.frontMatter?.auto_toc
+ if (!auto_toc) return
+ const depth = typeof auto_toc === 'number' ? auto_toc : 3 // max header-level depth
const dir = dirname(vfile.path)
- const files = readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('index'))
+ const vfilename = basename(vfile.path)
+ const files = readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith(vfilename))
+ const subdirs = readdirSync(dir).filter((f) => existsSync(join(dir, f, '_category_.json')))
+
+ const getPages = (fileList, dir) =>
+ fileList.map((f) => {
+ const content = readFileSync(join(dir, f), 'utf-8')
+ const { frontmatter, body } = parseFrontmatter(content)
+ let title = frontmatter.sidebar_label?.replace(/└─ */, '') || frontmatter.title || f.replace(/\.md$/, '')
+ // replace enclosing quotes, if present. putting this in parseFrontmatter didn't work for some reason.
+ title = title.replaceAll(/^["']|["']$/g, '')
+ return {
+ slug: f.replace(/\.md$/, ''),
+ title: title,
+ sidebarPosition: parseInt(frontmatter.sidebar_position || '0', 10),
+ headings: extractHeadings(body),
+ files: [],
+ }
+ })
- const pages = files.map((f) => {
- const content = readFileSync(join(dir, f), 'utf-8')
- const { frontmatter, body } = parseFrontmatter(content)
+ let pages = getPages(files, dir)
+
+ // TODO: handle directories inside the subdir
+ // compile a list of files inside a subdir:
+ const dirs = subdirs.map((d) => {
+ const subdir = join(dir, d)
+ const raw = readFileSync(join(subdir, '_category_.json'), 'utf-8')
+ const frontmatter = JSON.parse(raw)
+ const indexfile = frontmatter.link?.id ?? 'index.md' // if link is missing, it appears to default to a doc named index.md, if present.
+ const subfiles = readdirSync(subdir).filter((f) => f.endsWith('.md') && !f.startsWith(indexfile))
+ const subpages = getPages(subfiles, subdir)
+ subpages.sort((a, b) => a.sidebarPosition - b.sidebarPosition)
return {
- slug: f.replace(/\.md$/, ''),
- title: frontmatter.title || f.replace(/\.md$/, ''),
- sidebarPosition: parseInt(frontmatter.sidebar_position || '0', 10),
- headings: extractHeadings(body),
+ slug: d,
+ title: '> ' + (frontmatter.label || d),
+ sidebarPosition: frontmatter.position || 0,
+ headings: [],
+ files: subpages,
}
})
+ pages = pages.concat(dirs)
+
// Ascending sidebar_position → most-negative first → newest version on top
pages.sort((a, b) => a.sidebarPosition - b.sidebarPosition)
@@ -108,7 +146,7 @@ export default function autoTocPlugin() {
// ### [Page Title](./slug)
nodes.push({
type: 'heading',
- depth: 3,
+ depth: 3, // make page name h3
data: {
hProperties: {
className: 'auto-toc-heading',
@@ -117,7 +155,9 @@ export default function autoTocPlugin() {
children: [
{
type: 'link',
- url: `./${page.slug}`,
+ // folder URLs need a trailing slash in order for links on the target page (not the link itself) to work!
+ // i.e. w/o this the url is: ""./category" instead of ""./category/"" and the links in index.md will go to ""./subfile" instead of ""./category/subfile"
+ url: `./${page.slug}` + (page.files.length > 0 ? '/' : ''),
children: [{ type: 'text', value: page.title }],
},
],
@@ -129,22 +169,46 @@ export default function autoTocPlugin() {
type: 'list',
ordered: false,
spread: false,
- children: page.headings.map((h) => ({
- type: 'listItem',
- spread: false,
- children: [
+ children: page.headings
+ .filter((h) => h.level <= depth)
+ .map((h) => ({
+ type: 'listItem',
+ spread: false,
+ children: [
+ {
+ type: 'paragraph',
+ children: [
+ {
+ type: 'link',
+ url: `./${page.slug}#${h.id}`,
+ children: parseInlineContent(h.text),
+ },
+ ],
+ },
+ ],
+ })),
+ })
+ }
+
+ // Bullet list of each subdirectory file as a link
+ if (page.files.length > 0) {
+ nodes.push({
+ type: 'paragraph',
+ children: page.files.flatMap((subfile) => {
+ return [
+ {
+ type: 'text',
+ // note: the "spaces" before are U+2800: unicode Braille Pattern Blank
+ value: subfile === page.files.at(-1) ? '⠀⠀└── ' : '⠀⠀├── ',
+ },
{
- type: 'paragraph',
- children: [
- {
- type: 'link',
- url: `./${page.slug}#${h.id}`,
- children: parseInlineContent(h.text),
- },
- ],
+ type: 'link',
+ url: `./${page.slug}/${subfile.slug}`,
+ children: [{ type: 'text', value: subfile.title }],
},
- ],
- })),
+ { type: 'break' },
+ ]
+ }),
})
}
}
diff --git a/versioned_docs/version-v4.1/5_remote-control/satellite.md b/versioned_docs/version-v4.1/5_remote-control/satellite.md
index dd199be..f9ea735 100644
--- a/versioned_docs/version-v4.1/5_remote-control/satellite.md
+++ b/versioned_docs/version-v4.1/5_remote-control/satellite.md
@@ -7,4 +7,4 @@ In some environments, it can be useful to connect a remote Streamdeck into Compa
We have developed [Companion Satellite](https://user.bitfocus.io/product/companion-satellite) for this purpose.
-The satellite protocol follows SemVer and is documented on [the wiki](https://github.com/bitfocus/companion/wiki/Satellite-API)
+The satellite protocol follows SemVer and is documented on [the website](https://companion.free/for-developers/Satellite-API).
diff --git a/versioned_docs/version-v4.1/6_modules.md b/versioned_docs/version-v4.1/6_modules.md
index a357038..f1cb5c8 100644
--- a/versioned_docs/version-v4.1/6_modules.md
+++ b/versioned_docs/version-v4.1/6_modules.md
@@ -9,7 +9,7 @@ Modules are being added and updated all the time. A complete list of supported d
Most of the modules are written and maintained by the community. If your device or software is missing from this list, there are a few things you can do:
-1. If you have any experience writing code, you could make the module yourself, we are happy to accept all contributions. Read more [here](https://github.com/bitfocus/companion-module-base/wiki/Module-development-101)
+1. If you have any experience writing code, you could make the module yourself, we are happy to accept all contributions. Read more [here](https://companion.free/for-developers/module-development/home)
2. Some members on the [Community forum](https://bfoc.us/qjk0reeqmy) are available to hire to implement modules.
3. While the Bitfocus team is small, they are available to implement some modules, [get in touch](https://bitfocus.io/about#intouch) for a price and delivery date.
4. You can also [ask the open source community](https://bfoc.us/5xcykgx03n) by submitting a request, and hope that someone is willing to do the work for you.
```
-At the points where it says "ref=wiki" replace the word wiki with a reference to you or your product (only letters and numbers are allowed).
-You can scale the image to fit in your website, as long as it is still readable, you may not not change its color, rotation, animate it or change it in any other way than scaling.
+At the points where it says `"ref=bitfocus"` replace the word _bitfocus_ with a reference to you or your product (only letters and numbers are allowed).
+
+You can scale the image to fit in your website, as long as it is still readable, you may not change its color, rotation, animate it or change it in any other way than scaling.
You are not allowed to:
diff --git a/for-developers/module-development/_category_.json b/for-developers/module-development/_category_.json
index 9d59ff2..99d1ae7 100644
--- a/for-developers/module-development/_category_.json
+++ b/for-developers/module-development/_category_.json
@@ -1,7 +1,8 @@
{
- "label": "Companion Modules",
+ "label": "Module Development",
"position": 3,
"link": {
- "type": "generated-index"
+ "type": "doc",
+ "id": "index"
}
}
diff --git a/for-developers/module-development/api-changes/v1.10.md b/for-developers/module-development/api-changes/v1.10.md
index 3285e7d..a04598e 100644
--- a/for-developers/module-development/api-changes/v1.10.md
+++ b/for-developers/module-development/api-changes/v1.10.md
@@ -3,15 +3,15 @@ title: API 1.10 (Companion 3.4+)
sidebar_position: -110
---
-### Custom headlines for preset actions, feedbacks and steps {#preset-headlines}
+## Custom headlines for preset actions, feedbacks and steps {#preset-headlines}
-Presets can now define a `headline` value for each action, feedback and step, to be used as the user editable label for the action/feedback/step.
+Presets can now define a `headline` value for each action, feedback and step, to be used as the user-editable label for the action/feedback/step.
-### Array support for merging multiple Bonjour queries {#bonjour-arrays}
+## Array support for merging multiple Bonjour queries {#bonjour-arrays}
Inside your `companion/manifest.json`, each bonjour query defined can now be an array of queries, allowing two queries to be merged and used for one config field.
-### Extended format support for feedback image buffers {#image-buffers}
+## Extended format support for feedback image buffers {#image-buffers}
The `imageBuffer` property from advanced feedbacks can now be in more formats.
diff --git a/for-developers/module-development/api-changes/v1.11.md b/for-developers/module-development/api-changes/v1.11.md
index da48ead..1b15b4a 100644
--- a/for-developers/module-development/api-changes/v1.11.md
+++ b/for-developers/module-development/api-changes/v1.11.md
@@ -4,6 +4,6 @@ sidebar_position: -111
description: Node.js 22
---
-### Updated to Node.js 22 runtime {#nodejs-22}
+## Updated to Node.js 22 runtime {#nodejs-22}
Modules can now use node.js 22. We recommend all modules update when possible.
diff --git a/for-developers/module-development/api-changes/v1.12.md b/for-developers/module-development/api-changes/v1.12.md
index f692864..408ab89 100644
--- a/for-developers/module-development/api-changes/v1.12.md
+++ b/for-developers/module-development/api-changes/v1.12.md
@@ -4,7 +4,7 @@ sidebar_position: -112
description: Module permissions & isVisibleExpression
---
-### Module permissions for enhanced security {#permissions}
+## Module permissions for enhanced security {#permissions}
As of @companion-module/base v1.12, modules will be run with the nodejs permissions model enabled. This will allow us to inform users about the requirements of modules.
@@ -12,8 +12,8 @@ You can opt into additional permissions by defining the `permissions` object in
The permissions you can request are:
-- 'worker-threads' - allows using nodejs worker_thread api
-- 'child-process' - allows using nodejs child_process api
+- 'worker-threads' - allows using nodejs worker_thread API
+- 'child-process' - allows using nodejs child_process API
- 'native-addons' - allows using native (c/c++) addons
- 'filesystem' - allows read/write access to the filesystem.
@@ -30,7 +30,7 @@ We would recommend planning for this in your module implementation.
:::
-### Expression syntax support for `isVisible` on option fields {#isvisible-expressions}
+## Expression syntax support for `isVisible` on option fields {#isvisible-expressions}
The `isVisible` functions that can be defined on option fields can now be written in the companion expression syntax through a new `isVisibleExpression` property.
@@ -40,11 +40,11 @@ We advise all uses to be updated to the new syntax, the old syntax is now deprec
:::
-### Port-based filtering for Bonjour queries {#bonjour-port}
+## Port-based filtering for Bonjour queries {#bonjour-port}
Bonjour queries in the module manifest can now specify a filter based on port number.
-### New utility methods for escape character handling {#utility-methods}
+## New utility methods for escape character handling {#utility-methods}
- parseEscapeCharacters
- substituteEscapeCharacters
diff --git a/for-developers/module-development/api-changes/v1.13.md b/for-developers/module-development/api-changes/v1.13.md
index 1a4a90a..b3edfa8 100644
--- a/for-developers/module-development/api-changes/v1.13.md
+++ b/for-developers/module-development/api-changes/v1.13.md
@@ -3,7 +3,7 @@ title: API 1.13 (Companion 4.1+)
sidebar_position: -113
---
-### Variables in `textinput` fields are now automatically parsed {#variable-parsing}
+## Variables in `textinput` fields are now automatically parsed {#variable-parsing}
You no longer need to call `parseVariablesInString` in most circumstances. Any `textinput` field with `useVariables` defined will automatically have variables parsed before the action/feedback is called.
@@ -21,13 +21,13 @@ This is groundwork to better allow us to handle expressions for you, expect more
:::
-### Value-type feedbacks (support for local variables) {#value-feedbacks}
+## Value-type feedbacks (support for local variables) {#value-feedbacks}
As part of the new local variables support in Companion, you can now define `value` feedbacks. These are similar to `boolean` feedbacks, but you can return any type of value.
Within Companion, the user is able to store the value you provide into a local variable. They can also do this with `boolean` feedbacks, but `boolean` feedbacks can also be used directly in styling a button, a `value` feedback cannot
-### `options:` improvements: new `description` field; multiline `textinput` field; "infinity" bounds for `number` fields {#new-options}
+## `options:` improvements: new `description` field; multiline `textinput` field; "infinity" bounds for `number` fields {#new-options}
Every field can now specify a `description`. This is intended to be a some hint to the user that should always be visible, and gets shown below the input field.
@@ -35,7 +35,7 @@ The `textinput` field type can now request to be multiline. This will provide a
The `number` field type can opt to show the defined min or max values as infinity. This is common behaviour for audio mixers, where they treat some low value such as -90 as -infinity
-### `secret-text` field-type for Configs {#secrets}
+## `secret-text` field-type for Configs {#secrets}
There is a new `secret-text` field type available to the connection config panel.
@@ -49,10 +49,10 @@ Make sure to not mix them, or it defeats the purpose of them being separate
:::
-### subscribe/unsubscribe: More flexibility for Action/ less for feedbacks {#subscribe}
+## subscribe/unsubscribe: More flexibility for actions / less for feedbacks {#subscribe}
Actions can opt out of their unsubscribe method being called when the options change.
-They can also specify which options should not trigger a call to subscribe/unsubscribe, allowing you to filter out noisey/excessive calls.
+They can also specify which options should not trigger a call to subscribe/unsubscribe, allowing you to filter out noisy/excessive calls.
-Feedback subscrube/unsubscribe callbacks are no longer called for every options change, as this happens every time the options or a variable inside the options changes.
+Feedback subscribe/unsubscribe callbacks are no longer called for every options change, as this happens every time the options or a variable inside the options changes.
diff --git a/for-developers/module-development/api-changes/v1.14.md b/for-developers/module-development/api-changes/v1.14.md
index 4247050..1379fc6 100644
--- a/for-developers/module-development/api-changes/v1.14.md
+++ b/for-developers/module-development/api-changes/v1.14.md
@@ -4,13 +4,13 @@ sidebar_position: -114
description: Config layout changes, Connection processes now include the label
---
-### Automated layout for Config parameters {#config-layout}
+## Automated layout for Config parameters {#config-layout}
-The connection config panel allowed modules to customise the layout of input fields. This was not possible elsewhere in Companion, and is not consistent with elsewhere within the panel where fields are in the simplified layout.
+The connection config panel allowed modules to customise the layout of input fields. This was not possible elsewhere in Companion, and is inconsistent with elsewhere within the panel where fields are in the simplified layout.
-As of @companion-module/base v1.14, modules will now be presented in this consistent layout. Modules using older versions of the api will not be affected, until they update.
+As of @companion-module/base v1.14, modules will now be presented in this consistent layout. Modules using older versions of the API will not be affected, until they update.
-It is our hope that this new layout will not cause significant issues, if you have any problems or really dislike it, you can temporarily opt out of the new layout by in your module constructor by doing:
+It is our hope that this new layout will not cause significant issues, if you have any problems or really dislike it, you can temporarily opt out of the new layout by adding to your module constructor:
```js
this.instanceOptions.disableNewConfigLayout = true
@@ -26,6 +26,6 @@ Let us know if there is extra configurability that you need, we are open to rest
See the [PR](https://github.com/bitfocus/companion/pull/3569) for more examples on the impact.
-### Connection processes now include the label (name) of the connection {#connection-process-name}
+## Connection processes now include the label (name) of the connection {#connection-process-name}
To improve the developer experience, when looking at each process in task manager or activity monitor, each process is now labelled with the label of the connection.
diff --git a/for-developers/module-development/api-changes/v1.5.md b/for-developers/module-development/api-changes/v1.5.md
index c0e2f43..51ff325 100644
--- a/for-developers/module-development/api-changes/v1.5.md
+++ b/for-developers/module-development/api-changes/v1.5.md
@@ -3,7 +3,7 @@ title: API 1.5 (Companion 3.1+)
sidebar_position: -105
---
-### Automatic invert property for boolean feedbacks {#feedback-invert}
+## Automatic invert property for boolean feedbacks {#feedback-invert}
Boolean feedbacks now automatically get an 'inverted' property added by Companion.
diff --git a/for-developers/module-development/api-changes/v1.7.md b/for-developers/module-development/api-changes/v1.7.md
index 4d77a96..902346f 100644
--- a/for-developers/module-development/api-changes/v1.7.md
+++ b/for-developers/module-development/api-changes/v1.7.md
@@ -3,12 +3,12 @@ title: API 1.7 (Companion 3.2+)
sidebar_position: -107
---
-### Bonjour/MDNS device discovery config field {#bonjour-discovery}
+## Bonjour/MDNS device discovery config field {#bonjour-discovery}
Many devices use Bonjour or MDNS for discovery.
There is a new `bonjour-device` config field type that you can use to easily perform this discovery for your users as they open the configuration panel.
-### Hex color format and alpha channel support {#color-picker}
+## Hex color format and alpha channel support {#color-picker}
The `color` input field type now supports providing colors as `#000000` format hex strings, and can have alpha support enabled
diff --git a/for-developers/module-development/api-changes/v1.8.md b/for-developers/module-development/api-changes/v1.8.md
index 9b9c1e7..652e0bf 100644
--- a/for-developers/module-development/api-changes/v1.8.md
+++ b/for-developers/module-development/api-changes/v1.8.md
@@ -3,17 +3,17 @@ title: API 1.8 (Companion 3.3+)
sidebar_position: -108
---
-### Text preset type for organizing presets with headings {#text-presets}
+## Text preset type for organizing presets with headings {#text-presets}
A new 'text' preset type has been added, to allow you to put some headings and blocks of text into the presets panel.
These will also split the presets into chunks around them, allowing you to organise presets better.
-### Support for button-scoped local variables {#local-variables}
+## Support for button-scoped local variables {#local-variables}
:::tip
-Newer versions of the API, replace this with newer ways of achieving the same result. Only follow this if you can't update to those
+Newer versions of the API replace this with other ways of achieving the same result. Only follow this if you can't update to those
:::
@@ -22,9 +22,9 @@ Companion has added a few variables under the `$(this:XX)` naming. (Since this r
Due to the way the `parseVariablesInString` method works, Companion often doesn't know what button a string is being parsed for, so can't support variables scoped to a single button.
In order to support these, in your action/feedback callback, there is a second `context` parameter which holds an alternate `parseVariablesInString` implementation. This implementation is specific to that callback, so Companion knows what control it belongs to, and can handle the variables.
-Additionally, you can indicate that you are doing this and support these variables by setting the `useVariables` property to an object like `{ local: true }` to indicate this support. This allows us to show a hint to the user about this support, and suggest them whilst they type.
+Additionally, you can indicate that you are doing this and support these variables by setting the `useVariables` property to an object like `{ local: true }` to indicate this support. This allows us to show a hint to the user about this support, and suggest the available variables whilst they type.
-### Shared UDP port listener for devices with hardcoded ports {#shared-udp}
+## Shared UDP port listener for devices with hardcoded ports {#shared-udp}
A few devices have been found which are not cooperative when it comes to control, and expect to send all messages to a hardcoded UDP port.
This makes it hard to support these, as by default only one connection can listen on a port at a time.
diff --git a/for-developers/module-development/api-changes/v2.0.md b/for-developers/module-development/api-changes/v2.0.md
index ee1ccc1..48099f5 100644
--- a/for-developers/module-development/api-changes/v2.0.md
+++ b/for-developers/module-development/api-changes/v2.0.md
@@ -24,7 +24,7 @@ This also allows us to use newer language and platform features and to clean up
If your module is set to use the `node18` runtime in its manifest, it will need to be updated to `node22`.
-### @companion-mdoule/base is now ESM
+### @companion-module/base is now ESM
As part of dropping support for Node 18, this library is now written in the newer ESM syntax. For TypeScript users, update your `tsconfig` to use `"moduleResolution": "nodenext"`, or, if using our tsconfig presets, extend `@companion-module/tools/tsconfig/node22/recommended-esm`.
@@ -509,7 +509,7 @@ In very old versions of Companion, it was expected that modules should call `thi
Many versions back, it became possible to supply the types of feedbacks as an argument, to allow for only rechecking a subset of the feedbacks upon each call.
-Due to this dual behaviour, it is very easy for a module to call `this.checkFeedbacks()` without realising it was bad practise, especially with all the existing code showing exactly that.
+Due to this dual behaviour, it is easy for a module to call `this.checkFeedbacks()` without realising it was bad practice, especially with all the existing code showing exactly that.
To clarify the intended usage, this older behaviour has been removed. With a new `this.checkAllFeedbacks()` method being added instead.
diff --git a/for-developers/module-development/connection-advanced/_category_.json b/for-developers/module-development/connection-advanced/_category_.json
new file mode 100644
index 0000000..6763f61
--- /dev/null
+++ b/for-developers/module-development/connection-advanced/_category_.json
@@ -0,0 +1,11 @@
+{
+ "label": "Connections: Advanced",
+ "position": 17,
+ "link": {
+ "type": "doc",
+ "id": "index"
+ },
+ "customProps": {
+ "description": "Advanced topics for programming a connection module."
+ }
+}
diff --git a/for-developers/module-development/connection-advanced/bonjour-device-discovery.md b/for-developers/module-development/connection-advanced/bonjour-device-discovery.md
new file mode 100644
index 0000000..b944ffd
--- /dev/null
+++ b/for-developers/module-development/connection-advanced/bonjour-device-discovery.md
@@ -0,0 +1,76 @@
+---
+title: Bonjour Device Discovery
+sidebar_label: Bonjour Device Discovery
+sidebar_position: 2
+description: How to set up Bonjour Device Discovery in the user configuration.
+---
+
+Bonjour is a standardised method of device discovery, utilising MDNS.
+
+Starting with [API 1.7](../api-changes/v1.7.md) (Companion 3.2), Companion allows you to easily discover devices using the Bonjour protocol, thus helping users with configuration.
+
+## Setting up Bonjour
+
+You can do this by defining a config field such as:
+
+```js
+{
+ type: 'bonjour-device',
+ id: 'bonjour_host',
+ label: 'Bonjour Test',
+ width: 6,
+},
+```
+
+and in your `companion/manifest.json`:
+
+```js
+ "bonjourQueries": {
+ "bonjour_host": {
+ "type": "blackmagic",
+ "protocol": "tcp",
+ "txt": {
+ "class": "AtemSwitcher"
+ }
+ }
+ }
+```
+
+These two structures are linked by the common id, in the future this will allow us to automate device discovery further.
+
+In the UI, this field will look like:
+
+
+The 'Manual' option is always shown, and must be handled to allow users to manually specify an address for environments where Bonjour does not work.
+This can be achieved with further config fields such as:
+
+```js
+{
+ type: 'textinput',
+ id: 'host',
+ label: 'Target IP',
+ isVisibleExpression: `!$(options:bonjour_host)`,
+ default: '',
+ regex: Regex.IP,
+},
+```
+
+Note the presence of the `isVisibleExpression`, to control the visibility of the fields depending on whether a bonjour discovered device has been selected.
+
+In your module code, the `bonjour_host` will have a value such as `10.0.0.1:8000` or null.
+
+### Writing your Bonjour Query
+
+We currently support a subset of the possible query options. In all queries, the `type` and `protocol` must be set.
+If your device needs further filtering, this can be done by specifying any `txt` field values the entries must have.
+
+Since [API 1.10](../api-changes/v1.10.md) each entry in the manifest under `bonjourQueries` can be an array, to allow you to run multiple queries in parallel. This can be useful when supporting multiple models which use slightly different queries
+
+Since [API 1.12](../api-changes/v1.12.md) it is possible to filter by `port` number in the query. It is recommended to only use this as a last resort, as port numbers are often configurable.
+
+Since [API 2.0](../api-changes/v2.0.md) it is possible to specify an `addressFamily` for the query. This allows you to specify whether `ipv4`, `ipv6` or both (`ipv4+6`) addresses are returned by the query.
+
+## Further Reading
+
+- [User Config](../connection-basics/user-configuration.md)
+- [Autogenerated docs for the module `InstanceBase` class](https://bitfocus.github.io/companion-module-base/classes/InstanceBase.html)
diff --git a/for-developers/module-development/connection-advanced/http-handler.md b/for-developers/module-development/connection-advanced/http-handler.md
new file mode 100644
index 0000000..2bebb00
--- /dev/null
+++ b/for-developers/module-development/connection-advanced/http-handler.md
@@ -0,0 +1,144 @@
+---
+title: Adding an HTTP responder
+sidebar_label: HTTP Handler
+sidebar_position: 4
+description: How to set up HTTP handling for your module.
+---
+
+Companion's webserver that serves the Web UI also provides a path for each connection so that HTTP requests can be passed through to an instance of a module. Your module can then choose to respond or otherwise Companion will automatically respond with a 404. The path to an instance will be `/instance/INSTANCE NAME/`, so for example if a user has Companion on `http://127.0.0.1:8000/` and creates a Google Sheets connection called 'sheet', HTTP traffic to `http://127.0.0.1:8000/instance/sheet/` will be forwarded to the HTTP handler in Google Sheets for that connection.
+
+Because each instance acts as a child process of Companion, only a subset of the properties for a HTTP request to Express are passed on to the child processes. This allows for most common usages, but more complex setups such as utilizing the HTTP handler for WebSockets will not work.
+
+A few example use cases for the HTTP handler:
+
+- Expose data generated/collected by the module. For example the Google Sheets module makes all of the spreadsheet data available as both JSON and CSV, this allows apps such as vMix to utilize that as a data source far more efficiently and responsively than if it was to interact with Google Sheets itself.
+- Expose some of the functionality of Actions, so if an external device/service needs to be able to run an Action it could be made available to be run directly rather than requiring it placed on a button and then use Companion's API to press/release that button.
+- A HTML page that acts as a UI for users, which could even pull data from JSON endpoints to dynamically fill that HTML page with data, and POST endpoints that the page can send requests to for triggering functionality in the module.
+
+## API call: handleHttpRequest
+
+The `this.handleHttpRequest` method on the Instance class is what handles HTTP requests being passed from Companion to the module instance.
+
+```js
+handleHttpRequest(request: CompanionHTTPRequest): CompanionHTTPResponse | Promise