Metadata-Version: 2.4
Name: vflexctl
Version: 0.3.1
Summary: Command line tool to set the output voltage for VFLEX devices
License: Apache 2.0
License-File: LICENSE
Author: hameedm
Author-email: hameedm@protonmail.com
Requires-Python: >=3.12,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: colorama (>=0.4.6,<0.5.0)
Requires-Dist: mido (>=1.3.3,<2.0.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pytest (>=9.0.1,<10.0.0)
Requires-Dist: python-rtmidi (>=1.5.8,<2.0.0)
Requires-Dist: rich (>=14.2.0,<15.0.0)
Requires-Dist: structlog (>=25.5.0,<26.0.0)
Requires-Dist: typer (>=0.20.0,<0.21.0)
Description-Content-Type: text/markdown

# 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:

```python
pipx install vflexctl
```

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

```python
pip3 install vflexctl
```

## Usage

### Reading your VFlex

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

```python
$ 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:

```python
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):

```python
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:

```python
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:

```python
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.

```python
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 `MIDITriplet`s

## 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.

