vflexctl 0.3.1

Command line tool to set the output voltage for VFLEX devices

vflexctl

An unofficial CLI for setting the voltage on VFLEX devices with MIDI control.

Why? I dunno, I like the idea of being able to work this without needing a website?

Installation

An easy way is to use pipx if it's installed on your system, using Python 3.12 or later.

Using pipx, install this tool with:

pipx install vflexctl

You can also just use pip to install it - this then means invoking it with python -m vflexctl instead:

pip3 install vflexctl

Usage

Reading your VFlex

To read your VFlex's current state, use the read command:

$ vflexctl read
VFlex Serial Number: <your serial here>
Current Voltage: 12.00
LED State: Always On

You can set either your voltage, LED state (always on or not always on), or both:

vflexctl set -v <voltage> -l <always-on|disabled>

On firmware >= 5.00.00, you can also set the led colour (this can be done in combination with the others):

vflexctl set --led-colour/--led-color/--colour/--color ...

The difficulty with this is (at least, based on lib.vflex.app) that there is no way to read what the current LED colour flag is.

Voltage

Voltage is set with the --voltage or -v flag, with your volts as XX.XX. For example:

vflexctl set -v 12
vflexctl set -v 5.50
vflexctl set -v 48.5
vflexctl set -v 12.0000001

The VFlex communication over MIDI limits the maximum voltage to around 65.5V (the limit of a 16-bit integer). Trying to set a higher value will prevent the voltage from being set.

LED state

LED state is set using the --led or -l flag, with the value as either:

vflexctl set -l always-on
vflexctl set -l disabled

To set both voltage and LED state, use both flags (in any order).

--deep-adjust

--deep-adjust is a flag to use the old (<= 0.1.2) setting behaviour.

Since 0.2.0, the tool only sends a serial number request after the initial wake-up. This should work to set the voltage more quickly, but you can add this flag to be extra sure (or if your VFlex becomes "gone" while adjusting):

vflexctl --deep-adjust set -v 12
vflexctl set -v 12

Open a PR (or an issue) if this doesn’t work.

The VFlex object

If you're using this as a module (firstly, yay! welcome!) you have access to the VFlex object.

from vflexctl.device_interface import VFlex

Hopefully the docstrings make sense, but to summarise:

Methods

• get_any(cls, ...) - This gets the first VFlex that matches the default MIDI port name ("Werewolf vFlex")
  • This is used by the CLI to get the connected VFlex
• with_io_name(cls, name: str, ...) - This initialises a VFlex with a MIDO BaseIOPort using the provided name. This is useful if you want to connect to a specific one and know what the port name is using mido.
• initial_wake_up() - run this to grab the serial number, and current LED state and Voltage

Properties

• io_port - if you want to send MIDI directly, you can use this as a way to send messages
• firmware_version - The version string from getting the firmware version (APP.XX.XX.XX)
• firmware_version_components - The firmware version split into a three-integer tuple (tuple[int, int, int])

Other points on using vflexctl as a package

vflexctl includes some custom types (such as MIDITriplet and VFlexProtoMessage) used in its type annotations. These are available for import from vflexctl.types.

As a quick summary:

• MIDITriplet — A three-integer tuple representing a single MIDI message
• VFlexProtoMessage — A protocol-encoded message for controlling a VFlex device. To send this to a device, it must be converted into a list of MIDITriplets

Comparison with the official tool

Tundra Labs also provides a tool as part of their lib.vflex.app project.

Both tools provide similar core functionality, but differ in setup and intended use.

Which should I use?

• Use vflexctl if you want a simple, reliable CLI with minimal setup, or Python bindings for automation/integration
• Use the lib.vflex.app tool if you are already working in a JavaScript/Bun environment or want tighter integration with their ecosystem

Overview

Area	vflexctl (Python)	lib.vflex.app tool (JavaScript)
Installation	pipx install vflexctl	bunx / npx
Runtime	Python >=3.12	Bun or Node.js
Usage model	CLI + importable package	Runtime-invoked tool
Scriptability	Native Python	JS ecosystem
Precision	Explicit (Decimal, controlled rounding)	Implementation-dependent
Scope	Focused tool	Broader platform/tooling

Notes

• vflexctl installs as a persistent CLI, avoiding repeated runtime resolution (bunx/npx)
• Designed to be both a CLI and a reusable Python library
• Emphasises predictable behaviour (e.g. controlled voltage rounding)

The lib.vflex.app tool is part of a broader ecosystem and may integrate more naturally with web-based workflows.

vflexctl intentionally focuses on doing one thing well: providing a predictable, scriptable interface for controlling VFlex devices.

Current state

This is working, and based on the information released now from lib.vflex.app, seems to have essentially been correct.

This still works with "one" connected VFlex. There's no guarantee that on subsequent runs the same VFlex will be adjusted if you have multiple connected.

Multi-selection is currently not in scope, but if it's important, feel free to open an issue or, preferably, a PR.

Developer info

This project uses poetry for managing dependencies and building, built with Python 3.12.10. Unless there's a huge shift and poetry becomes terrible, please don't commit in a requirements.txt.

There are black rules for formatting in pyproject.toml as well - if your IDE formats on save, it (should) pick these up and format your files for you. The project also uses mypy for typing. Since this has a py.typed, you likely want to run mypy . and fix any typing issues before opening a PR or something.

Add unit tests for things that you add in as well, even for something minor.

Fork/pull/PR as you want!

---

This is an independent hobby project. It is not affiliated with, endorsed by, or connected to any company. All product names, trademarks, and brands are the property of their respective owners.