Skip to content

Bitfocus Companion 5.0 Split Touch Strips for Loupedeck Live / Razer Stream Controller – v1.1.0

Choose a tag to compare

View all tags
@ninoleto ninoleto released this 14 Jul 01:00
· 12 commits to main since this release
v1.1.0
cf8484f

Important

This release is obsolete and is preserved only for historical reference.

Version 1.1.0 was created before the official Bitfocus Loupedeck module added six independently programmable controls across the two vertical touch strips.

I originally used this split-strip layout with a personal custom module for Companion 4.x. When Companion 5 introduced a new surface-module and rendering system, that implementation no longer worked correctly, so I adapted it for Companion 5 and released it publicly as v1.1.0.

A few days later, the official Bitfocus module v1.1.1 added native support for the same six strip controls, using the full-height strip area. This made the original unofficial v1.1.0 implementation unnecessary for normal installations.

Use:

  • The official Bitfocus Loupedeck module for the standard native strip layout.
  • Unofficial v1.1.3 for the option to switch between the latest official native layout and separated 60 × 60 strip buttons with touch-inactive gaps.

Version 1.1.0 remains available to document the original Companion 5 adaptation, but it is not recommended for new installations.

Loupedeck split-strips module v1.1.0

Loupedeck Live and Razer Stream Controller with six split touch-strip controls in Bitfocus Companion 5

Loupedeck Live / Razer Stream Controller using six independent split touch-strip controls

Bitfocus Companion 5 button configuration for Loupedeck split touch strips

Companion 5 button layout and configuration

This custom Bitfocus Companion 5 surface module converts the two vertical touch-strip displays on the Loupedeck Live / Razer Stream Controller into six independently programmable Companion controls.

The Loupedeck Live and Razer Stream Controller are the same physical control surface sold under different branding. This module supports both versions of the device.

Version 1.1.0 updates the split-touch-strip implementation for Bitfocus Companion 5.0.

What this module does

The controller has two narrow vertical touch displays, one on each side of the main button grid.

This module divides those displays into six independent Companion controls:

  • Three controls on the left strip
  • Three controls on the right strip
  • Six additional programmable Companion controls in total

The internal control IDs are:

strip-left-0
strip-left-1
strip-left-2

strip-right-0
strip-right-1
strip-right-2

Each strip section is exposed to Companion as an independent 60 × 90 pixel RGB bitmap control.

Every strip section can:

  • Display its own Companion button graphic
  • Display independent text and colors
  • Show different button states
  • React to Companion feedbacks and variables
  • Generate normal press and release events when touched
  • Run any Companion actions assigned to that control

The normal buttons, rotary encoders and other standard controls continue to use the behavior of the official Bitfocus Companion Loupedeck surface module.

Changes in v1.1.0

  • Updated for Bitfocus Companion 5.0
  • Updated the surface schema for the Companion 5 surface-module system
  • Restored all six split touch-strip controls
  • Added three independent controls to the left vertical strip
  • Added three independent controls to the right vertical strip
  • Added independent bitmap rendering for every strip section
  • Added independent touch press and release handling
  • Preserved the normal behavior of the main buttons and rotary encoders
  • Packaged as an installable Companion 5 surface-module package

Compatibility

Companion

This release was built and tested for:

Bitfocus Companion 5.0

It is not intended for Companion 4.x.

Compatibility with later Companion releases is expected but cannot be guaranteed if the Companion surface API changes.

Controller

Supported controller names:

  • Loupedeck Live
  • Razer Stream Controller

These are differently branded versions of the same physical control surface.

Download

Download this file from the Assets section of the release:

companion-surface-loupedeck-split-strips-v1.1.0.tgz

This .tgz file is the complete installable Companion surface-module package.

It is not a Windows executable, Linux application or firmware update.

Normal users do not need:

  • Node.js
  • Yarn
  • Git
  • Visual Studio
  • A compiler
  • The module source code

Recommended installation for Companion 5

This is the preferred installation method for most users.

It uses Companion’s browser-based Admin interface and does not require extracting the package or configuring a developer-module directory.

It can be used with:

  • Windows desktop Companion
  • macOS desktop Companion
  • Linux desktop Companion
  • Linux headless Companion
  • CompanionPi
  • Raspberry Pi installations
  • Companion installations managed by a service or startup script

1. Download the package

Download:

companion-surface-loupedeck-split-strips-v1.1.0.tgz

Do not extract the file.

2. Open the Companion Admin interface

Start Companion and open its Admin interface in a web browser.

For a local Companion installation, the address is normally:

http://127.0.0.1:8000

For Companion running on another computer, use its hostname or local IP address:

http://COMPANION-IP:8000

3. Import the module package

In the Companion Admin interface:

  1. Open the Modules page.
  2. Click Import module package.
  3. Select:
companion-surface-loupedeck-split-strips-v1.1.0.tgz
  1. Confirm the import.

Use Import module package.

Do not choose Import offline module bundle. An offline module bundle is a different archive containing multiple modules.

4. Add or update the Loupedeck surface integration

Open the Surfaces page.

If the right-hand settings panel is not visible, click:

Show Settings

In the Surface Integrations section:

  1. Click Add Surface Integration.
  2. Click All Available if it is not already selected.
  3. Search for Loupedeck.
  4. Select the Loupedeck surface integration.
  5. Select module version 1.1.0 if Companion asks which installed version to use.
  6. Add or enable the integration.

If a Loupedeck surface integration already exists, open its settings and confirm that it is using version:

1.1.0

If Companion does not allow the existing integration to switch versions, remove that surface integration and add it again after importing version 1.1.0.

5. Close the official controller software

Completely close the official Loupedeck or Razer Stream Controller software before using the controller with Companion.

The official application may keep control of the USB device and prevent Companion from opening it.

Check that the application is not still running in the background or system tray.

6. Connect and detect the controller

Connect the Loupedeck Live / Razer Stream Controller directly to the computer running Companion.

Open the Surfaces page and click:

Rescan USB

The controller should appear in the configured surfaces list.

Companion can also watch for newly connected USB devices when Watch for new USB Devices is enabled in the Surfaces settings.

7. Restart if necessary

If version 1.1.0 does not appear immediately:

  1. Completely stop Companion.
  2. Start Companion again.
  3. Open the Modules page and confirm that version 1.1.0 is installed.
  4. Open the Surfaces page and confirm that the Loupedeck integration uses version 1.1.0.
  5. Click Rescan USB.

Windows desktop installation

For normal Windows Companion 5 installations, use the recommended Import module package method above.

You do not need to:

  • Extract the .tgz package
  • Create a developer directory
  • Use the Companion Launcher cog
  • Install Node.js or Yarn

Use the developer-folder method below only when the package importer is unavailable or when testing the module manually.

macOS desktop installation

For normal macOS Companion 5 installations, use the recommended Import module package method above.

You do not need to extract the package or configure a developer-module directory.

Completely close the official Loupedeck software before attempting to detect the controller in Companion.

Linux desktop installation

For normal Linux desktop Companion 5 installations, use the recommended Import module package method above.

After enabling the Loupedeck surface integration, Companion may report that the Linux USB permission rules need to be installed or updated.

Follow the prompt shown on the Surfaces page, allow Companion to install the generated desktop udev rules, and then:

  1. Disconnect the controller.
  2. Reconnect the controller.
  3. Click Rescan USB.

More detailed Linux USB information is included later in this document.

Advanced desktop installation using the Companion Launcher

This method applies only to installations that have the separate graphical Companion Launcher window.

The Launcher is separate from the browser-based Companion Admin interface.

The cog icon is located in the Companion Launcher window. It does not appear inside the browser interface.

Use this method only when:

  • The package importer is unavailable
  • You want to load an extracted local copy
  • You are testing the module as a developer module
  • You specifically need Companion’s developer-folder system

1. Extract the package

Windows

Use 7-Zip or another archive tool.

A .tgz archive may require two extraction operations:

  1. Extract the .tgz file.
  2. Extract the resulting .tar file.

Linux or macOS

Assuming the package is in the Downloads directory:

rm -rf /tmp/companion-loupedeck-v1.1.0
mkdir -p /tmp/companion-loupedeck-v1.1.0

tar -xzf ~/Downloads/companion-surface-loupedeck-split-strips-v1.1.0.tgz \
  -C /tmp/companion-loupedeck-v1.1.0

The extracted archive contains a directory named:

pkg

2. Rename or move the extracted directory

The pkg directory must become a module directory named:

companion-surface-loupedeck

Windows example

Create:

C:\CompanionDev

Move and rename pkg so that the final structure is:

C:\CompanionDev\
└── companion-surface-loupedeck\
    ├── companion\
    │   ├── manifest.json
    │   └── HELP.md
    ├── main.js
    ├── package.json
    └── node_modules\

Linux example

mkdir -p ~/companion-module-dev

rm -rf ~/companion-module-dev/companion-surface-loupedeck

mv /tmp/companion-loupedeck-v1.1.0/pkg \
  ~/companion-module-dev/companion-surface-loupedeck

The final structure is:

/home/USERNAME/companion-module-dev/
└── companion-surface-loupedeck/
    ├── companion/
    ├── main.js
    ├── package.json
    └── node_modules/

macOS example

mkdir -p ~/CompanionDev

rm -rf ~/CompanionDev/companion-surface-loupedeck

mv /tmp/companion-loupedeck-v1.1.0/pkg \
  ~/CompanionDev/companion-surface-loupedeck

The final structure is:

/Users/USERNAME/CompanionDev/
└── companion-surface-loupedeck/

3. Configure the Companion Launcher

Open or show the separate Companion Launcher window.

In the upper-right corner of that Launcher window:

  1. Click the cog icon.
  2. Open the Advanced Settings window.
  3. Find the Developer section.
  4. Select the parent directory containing the module directory.
  5. Enable Developer Modules.

Correct Windows path

C:\CompanionDev

Incorrect Windows path

C:\CompanionDev\companion-surface-loupedeck

Correct Linux path

/home/USERNAME/companion-module-dev

Incorrect Linux path

/home/USERNAME/companion-module-dev/companion-surface-loupedeck

Correct macOS path

/Users/USERNAME/CompanionDev

The Developer Module Path must point to the parent directory containing one or more module directories.

It must not point directly to the inner companion-surface-loupedeck directory.

4. Launch Companion

From the Companion Launcher, launch the Companion GUI/Admin interface.

Because this custom module uses the same internal module identity as the standard Loupedeck surface module, Companion may show both a normal version and a development version.

When configuring the Loupedeck surface integration, select the version marked:

dev

or version:

1.1.0

depending on how Companion displays the local module.

Headless Linux, Raspberry Pi and no-Launcher installations

A headless installation normally has:

  • No separate Companion Launcher window
  • No Launcher cog icon
  • No Enable Developer Modules switch in the browser interface
  • Configuration performed through the browser, startup command, service or configuration files

The recommended installation is still the browser-based Import module package method described at the beginning of this document.

Use the following manual method only when you specifically want to load the extracted package from a local developer directory.

Method A: existing CompanionPi or headless developer directory

Many CompanionPi and headless Linux installations use a developer-module directory such as:

/opt/companion-module-dev

Only use this path automatically if the existing installation is already configured to scan it.

Extract the package:

rm -rf /tmp/companion-loupedeck-v1.1.0
mkdir -p /tmp/companion-loupedeck-v1.1.0

tar -xzf /PATH/TO/companion-surface-loupedeck-split-strips-v1.1.0.tgz \
  -C /tmp/companion-loupedeck-v1.1.0

Install the module:

sudo mkdir -p /opt/companion-module-dev

sudo rm -rf \
  /opt/companion-module-dev/companion-surface-loupedeck

sudo mv /tmp/companion-loupedeck-v1.1.0/pkg \
  /opt/companion-module-dev/companion-surface-loupedeck

The final structure must be:

/opt/companion-module-dev/
└── companion-surface-loupedeck/
    ├── companion/
    ├── main.js
    ├── package.json
    └── node_modules/

Restart Companion using the update or restart method provided by that installation.

Method B: custom direct-launch installation

Use this method when Companion is started manually, through a script, or through a custom service.

Create a parent directory:

mkdir -p ~/companion-module-dev

Extract the package:

rm -rf /tmp/companion-loupedeck-v1.1.0
mkdir -p /tmp/companion-loupedeck-v1.1.0

tar -xzf /PATH/TO/companion-surface-loupedeck-split-strips-v1.1.0.tgz \
  -C /tmp/companion-loupedeck-v1.1.0

Install it:

rm -rf ~/companion-module-dev/companion-surface-loupedeck

mv /tmp/companion-loupedeck-v1.1.0/pkg \
  ~/companion-module-dev/companion-surface-loupedeck

Add this option to the command already used to start Companion:

--extra-module-path=/home/USERNAME/companion-module-dev

Example:

YOUR-EXISTING-COMPANION-COMMAND \
  --extra-module-path=/home/USERNAME/companion-module-dev

Replace:

YOUR-EXISTING-COMPANION-COMMAND

with the command your installation already uses to start Companion.

The extra module path must point to the parent directory.

Correct:

/home/USERNAME/companion-module-dev

Incorrect:

/home/USERNAME/companion-module-dev/companion-surface-loupedeck

Restart the Companion process or service after changing the startup command.

Source-development environment variable

When running Companion from source in a development environment, the developer directory can also be provided through:

COMPANION_DEV_MODULES=/home/USERNAME/companion-module-dev

This environment variable is primarily intended for source-development setups.

For a normal packaged Companion installation, prefer:

  • Import module package
  • The existing CompanionPi/headless developer directory
  • --extra-module-path for custom direct-launch installations

Linux USB permissions and udev rules

Linux requires udev rules before Companion can access locally attached Loupedeck, Stream Deck, X-keys and other USB surfaces.

Since surface support is provided by modules, Companion generates the required USB rules dynamically according to the enabled surface integrations.

Linux desktop

After importing and enabling this module, Companion should display a warning on the Surfaces page if its generated USB rules are missing or outdated.

Allow Companion to apply the desktop rules.

The generated desktop rules file is named:

50-companion-desktop.rules

After installing or updating the rules:

  1. Disconnect the controller.
  2. Reconnect the controller.
  3. Click Rescan USB.

Official CompanionPi or recommended headless installation

The official headless installation script normally configures:

  • The companion user and group
  • USB permissions
  • Generated headless udev rules
  • Automatic synchronization of changed rules

After enabling a new surface module, restart Companion and reconnect the controller if it is not detected.

Manually configured headless installation

For a manually configured headless installation, Companion generates:

50-companion-headless.rules

inside the udev-rules directory of the Companion configuration folder.

Copy the generated file into:

/etc/udev/rules.d/

Example:

sudo cp \
  /PATH/TO/COMPANION-CONFIG/udev-rules/50-companion-headless.rules \
  /etc/udev/rules.d/

Reload the rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Then disconnect and reconnect the controller.

The user running Companion must have the permissions expected by the generated rule, normally through membership in the companion group for a headless installation.

The generated rules may change when surface modules are enabled, disabled or updated. Repeat this process when Companion reports that the rules are outdated.

Docker installations

Direct USB surface access is not currently supported correctly by Companion inside Docker.

The package may import into a Docker-based Companion installation, but a Loupedeck Live / Razer Stream Controller connected directly to the Docker host should not be expected to work through the container.

For this controller, use a native installation on the computer physically connected to the controller:

  • Windows desktop Companion
  • macOS desktop Companion
  • Linux desktop Companion
  • Linux headless Companion
  • CompanionPi

A remote surface may also be connected through Companion Satellite when that surface and configuration are supported by Satellite.

Updating from an older version

Package imported through the Modules page

  1. Download:
companion-surface-loupedeck-split-strips-v1.1.0.tgz
  1. Open Companion’s Modules page.
  2. Click Import module package.
  3. Select the new .tgz package.
  4. Confirm the import.
  5. Open the Surfaces page.
  6. Open the Loupedeck surface integration.
  7. Select module version 1.1.0.
  8. Restart Companion if necessary.
  9. Click Rescan USB.

Module loaded from a developer directory

  1. Stop Companion.
  2. Delete the existing local directory:
companion-surface-loupedeck
  1. Extract the new .tgz package.
  2. Rename or move its pkg directory to:
companion-surface-loupedeck
  1. Place it inside the same parent developer directory.
  2. Keep the existing Launcher Developer Module Path or --extra-module-path.
  3. Restart Companion.

Do not keep multiple copies of companion-surface-loupedeck inside the same parent developer directory.

Removing the custom module

Imported package

  1. Open the Surfaces page.
  2. Disable or remove the surface integration using version 1.1.0.
  3. Add the standard Loupedeck surface integration if required.
  4. Open the Modules page.
  5. Remove version 1.1.0 if Companion offers the uninstall option.
  6. Restart Companion.

Developer-directory installation

  1. Stop Companion.
  2. Delete the local directory:
companion-surface-loupedeck
  1. Remove the developer path only if it is no longer used by any other custom modules.
  2. Restart Companion.
  3. Add or enable the standard Loupedeck surface integration.

Troubleshooting

There is no cog icon

The cog icon exists only in the separate graphical Companion Launcher window.

It does not exist in the browser-based Companion Admin interface.

Use:

Modules → Import module package

For a headless or custom direct-launch installation, use the manual headless instructions only when package import is not suitable.

The package will not import

Confirm that you selected:

companion-surface-loupedeck-split-strips-v1.1.0.tgz

Do not extract the package before importing it.

Use:

Import module package

Do not use:

Import offline module bundle

The module imports, but the split controls do not appear

Confirm that:

  • Companion 5.0 is running
  • Module version 1.1.0 is installed
  • The active Loupedeck surface integration uses version 1.1.0
  • An older developer copy is not overriding the imported package
  • Companion was restarted after changing the active version

The controller does not appear

  • Close the official Loupedeck or Razer Stream Controller software.
  • Check background processes and system-tray applications.
  • Disconnect and reconnect the controller.
  • Try a direct USB port instead of a hub.
  • Open the Surfaces page.
  • Click Rescan USB.
  • Check Companion’s log.
  • On Linux, check the generated udev rules.
  • Restart Companion.

The manual module directory is not detected

Confirm that Companion is pointed to the parent directory.

Correct:

C:\CompanionDev

Incorrect:

C:\CompanionDev\companion-surface-loupedeck

Correct:

/home/USERNAME/companion-module-dev

Incorrect:

/home/USERNAME/companion-module-dev/companion-surface-loupedeck

Companion loads the wrong Loupedeck module

  • Remove duplicate local copies.
  • Check all configured developer-module directories.
  • Confirm that the Loupedeck surface integration uses version 1.1.0.
  • Restart Companion.

It works on Windows but not Linux

The most likely cause is missing or outdated Linux udev rules.

Enable the Loupedeck surface integration first, install the newly generated rules, reload udev, reconnect the controller and click Rescan USB.

It is installed in Docker but the controller is unavailable

Direct USB surfaces are not currently supported correctly inside the Companion Docker container.

Use a native Companion installation on the machine connected to the controller.

Important information

  • This is an unofficial custom Bitfocus Companion surface module.
  • It is not part of the standard Bitfocus Companion distribution.
  • It uses the existing Loupedeck surface-module identity.
  • Version 1.1.0 must be active for the six split-strip controls to appear.
  • It does not modify the controller firmware.
  • It does not modify the official Loupedeck or Razer software.
  • It changes only how Companion exposes and handles the two vertical touch displays.
  • Back up the Companion configuration before installing custom modules.
  • Use at your own risk.

This project is based on the official open-source Bitfocus Companion Loupedeck surface module.

Development and testing note

This module and its documentation were created with assistance from ChatGPT. The module itself is used daily by the developer, has been tested extensively in a real Bitfocus Companion 5 environment, and has proven stable and reliable in regular use.

Released under the MIT License.

Assets 3
Loading