Setting up the modules

Rules are small mappings the firmware runs 200 times a second, edited on the Configure page of the desktop app and saved to the box. There is no connect button; the app finds the box on its own, and the dot in the top right turns green once it has. The Device page shows a live view of what the box sends.

On Linux the app cannot open the port until your user is in the dialout group, and it will not tell you that is the problem: it just says Searching for devices… forever. Run sudo usermod -aG dialout $USER and log out and back in.

Pins in, buttons out

The three things worth understanding before touching a rule:

• Inputs are pins (D7), outputs are buttons (B30). By default every pin passes straight through: D1 is B1, D2 is B2, and so on.
• B128 is the highest button there is. Any pin can drive any button up to it, so D1 could go to B1 or to B128; how you organise them does not matter at all.
• When a rule needs a spare button, the only requirement is not reusing one you already assigned. No need to write anything down: the rules list shows what is taken.

Find out which pin is which

1. On the Device page, operate one control at a time and note which cell lights up. The cell number is the pin number: cell 7 means D7.

   A 3-way or the lever lights a cell per outer position and nothing in the middle, an encoder makes two cells flicker, and a rotary lights a cell per position except the last. All of that is expected.

A control that stays dark in every position is a wiring problem: back to soldering and wiring. The A pins never pass through on their own, so anything wired to one stays dark until a rule reads it.

How the rule editor works

On the Configure page, open the Rules tab. Each rule is a card with a plain English summary of what it does. Order matters: rules run top to bottom, and a rule can read the output of any rule above it. Nothing reaches the box until Save to device, which checks the whole configuration, writes it, and reboots the box.

Buttons, keys, and the lever

Nothing to set up. If a sim binding wants a short press instead of a hold, add a Timed Pulse: the pin in, its own button number out, 100 ms.

On/off toggles and the guarded switch

The on side already works. The off side has no button of its own, and most sims want one, so this is the rule almost every box gets: a Direct Map with the pin as Input, a spare button as Output, and Invert ticked.

3-way switches

Up and down already work; the middle is both pins open, so it needs a rule:

1. Add an All-Off Detector with the switch's two pins in Inputs (any of) and a spare button as Output.

   Despite the label saying any of, the output is on when none of the inputs are, which is what a middle position is.

The lever is wired the same way, so if you want its middle position as a button, it gets this rule too.

Rotary encoders

An encoder always needs a rule; without one its two pins just flicker. Add a Rotary Encoder rule: Pin A and Pin Bare the encoder's pins, CW out and CCW out those same numbers as buttons. Leave the rest at its defaults.

Use the pins' own button numbers as outputs. A rule only replaces the passthrough for the buttons it writes to, so an encoder on D17/D18 mapped to B60/B61 keeps the raw flicker on buttons 17 and 18 next to the clean presses.

If one detent gives two presses, set Steps/detent to 4; two detents for one press, set it to 1. Sim missing the presses, raise Pulse (ms). Direction backwards, tick Invert.

Driving an axis instead

For a trim wheel or a brightness knob: on the Axes tab, add an axis and pick a HID axis under Output. Then, below the encoder rule, an Increase Axis rule reading the CW button and a Decrease Axis rule reading the CCW button, each with a Step of 2048 (32 detents across the range). They must sit below the encoder rule, since they read its outputs.

Set the axis Output to Backlight Only and the knob dims the labels instead of reporting to the sim. Tick Remember and the brightness survives unplugging.

The 5 and 8 position rotaries

Every wired position is already a button that stays held while the knob rests there. If you wired the last position too, you are done. If not, it gets an All-Off Detector like a 3-way middle, with all the rotary's pins in Inputs (any of) and a spare button as Output.

Latching

To make a momentary control switch something on and off, go through a variable: add one on the Variables tab, then a Toggle Switch rule from the pin to the variable, and a Direct Map below it from the variable to a spare button. Each press now flips the button. Tick Remember on the variable and the state survives a power cycle.