Button boxes with SimHub
Last updated · SimHub 9.11.22
SimHub supports button matrices, individual press buttons, rotary encoders and TM1638 module buttons on an Arduino. The distinction that matters most: buttons wired this way are read by SimHub, which can act on them — switching dashboard screens, toggling effects — but that is not the same as your game seeing a controller input. For the game to see the buttons you need a board with gamepad capability, which means a Pro Micro or a Leonardo specifically, or you route them through SimHub's Control Mapper.
Getting that distinction wrong is the single most common disappointment with a homemade button box, and it is a hardware decision made before you solder anything — so it is first.
Two very different kinds of button
| SimHub actions | Game inputs | |
|---|---|---|
| What sees the press | SimHub | The game, as a controller button |
| What it can do | Switch dashboard screens, toggle effects, trigger SimHub functions | Anything the game binds — pit limiter, headlights, wipers, MFD |
| Board required | Any supported board | Pro Micro or Leonardo only |
| How it works | SimHub reads the serial data | The board presents itself to Windows as a USB gamepad |
Gamepad features require a Pro Micro or a Leonardo. Exclusively. This is stated in the official documentation and it is a hardware decision you cannot undo in software. An Uno cannot present itself as a USB gamepad — the chip does not support it. If you want the game to see your buttons, buy the right board first.
The third route is Control Mapper, SimHub's bundled plugin that aggregates controllers into one virtual device using either vJoy or an Arduino Bridge. That is how you get game input from a board that cannot do it natively.
Button matrices
A matrix is how you get many buttons out of few pins. Wire buttons in a grid of rows and columns, and the number of pins needed is rows plus columns rather than one per button.
| Grid | Buttons | Pins |
|---|---|---|
| 3 × 3 | 9 | 6 |
| 4 × 4 | 16 | 8 |
| 5 × 5 | 25 | 10 |
| 6 × 6 | 36 | 12 |
| Directly wired | 16 | 16 |
The saving grows with size, which is why any box beyond about eight buttons uses a matrix.
Add diodes if you need more than two buttons at once. Without a diode per button, pressing three buttons simultaneously can register a fourth that is not pressed — an artefact called ghosting. On a sim racing box you rarely press three at once, so many builds skip them. If yours has a handbrake, a clutch bite point and a shift on the same panel, fit them.
Rotary encoders
Encoders are the reason a homemade box beats a bought one for many people. A rotary encoder turns continuously in both directions and reports each click as a discrete step, which maps naturally onto everything adjustable in a modern race car.
- Brake bias — forward and back, which is exactly what a rotary is for.
- Traction control and ABS levels.
- Engine maps.
- Dashboard page — bind to SimHub's
NextScreenandPreviousScreen. - In-car MFD navigation.
Encoders use two pins each, plus a third if you want the push-to-click that most of them include. That push is a normal button and is worth using — a bias encoder that also resets to default when pressed is a nice thing to have.
Encoders come in different detent counts. Twenty detents per revolution is comfortable for adjustments where each click matters; higher counts suit continuous scrolling and feel imprecise for stepped settings.
The TM1638 shortcut
A TM1638 module gives you digits, indicator LEDs and buttons on one board using three pins. For a compact panel that both displays and controls something, it is one component instead of three.
The buttons are typically small tactile switches rather than the chunky ones you would want as a primary control, so treat it as a secondary panel — menu navigation, mode selection, a readout with adjustment buttons beside it — rather than as the main button box.
More on the display side on the 7-segment page.
Building one
Choose the board by what the buttons must reach
Pro Micro or Leonardo if the game needs to see them. Any supported board if they only drive SimHub. This decision comes first because it cannot be changed later without rewiring.
Plan the layout physically
Which buttons you press without looking, which you need to find. Group by function, space by feel, and put the ones you use mid-corner where your thumb already is.
Wire the matrix
Rows and columns, diodes if you will press three at once. Keep the grid layout on paper — a matrix is not obvious to reverse-engineer six months later.
Configure in the firmware wizard
Tick the button matrix, encoders and any TM1638, set the quantities, and assign pins. Every pin must be unique across all enabled features.
Test every button before closing the box
Every single one. A cold joint is far easier to fix before the enclosure is screwed shut, and this is the most common regret in a build like this.
Bind them
In SimHub for SimHub actions, and in the game's controller settings for game inputs.
Common mistakes
- Wrong board. Building on an Uno and then discovering the game cannot see the buttons. This is the big one, and it is why board choice is the first section on this page.
- Too many buttons. Twenty-four buttons you cannot find by feel are worse than eight you can. Sim racing is not a flight sim — you are not looking down.
- No diodes on a box that needs them. If three-button combinations behave oddly, that is ghosting.
- Untested joints inside a sealed box. Test before assembly, always.
- Pin collisions. A box with a matrix, encoders and a display uses a lot of pins, and SimHub's defaults will collide. Assign explicitly.
- Nothing labelled. You will not remember which encoder is brake bias. Label the panel and keep the wiring diagram.
Common questions
Will my game see buttons on a SimHub button box?
Only if the board can present itself as a USB gamepad, which means a Pro Micro or a Leonardo specifically — gamepad features require those boards exclusively. On any other board the buttons drive SimHub actions rather than game inputs, unless you route them through Control Mapper.
Can I use an Arduino Uno for a button box?
Yes for buttons that control SimHub — switching dashboard screens, toggling effects. No for buttons the game needs to see as controller inputs, because the Uno's chip cannot present itself as a USB gamepad. Choose the board based on which you need.
How many buttons can I wire to one Arduino?
A matrix needs rows plus columns rather than one pin per button, so a 4×4 grid gives 16 buttons on 8 pins and a 6×6 gives 36 on 12. The practical limit is SimHub's rule that every assigned pin must be unique across all enabled features.
Do I need diodes in a button matrix?
Only if you will press three or more buttons simultaneously — without a diode per button, that can register a phantom press. Many sim racing boxes skip them because three-at-once is rare. Fit them if a handbrake, clutch and shift share the panel.
What should I put on a rotary encoder?
Anything stepped and bidirectional: brake bias, traction control level, ABS, engine map, or SimHub's dashboard page via NextScreen and PreviousScreen. Most encoders also click as a button, which is worth using — a bias encoder that resets to default when pressed is handy.
Can I add buttons to an Arduino that already drives LEDs?
Yes, subject to pins. That is exactly the situation where SimHub's default pin assignments collide and the firmware refuses to build, so assign every pin explicitly rather than accepting the defaults.
Sources
Related guides
SimHub is developed independently by Wotever and is not affiliated with oesimracing. This page was checked against SimHub 9.11.22 on 4 August 2026; where the interface has moved on since, the version stamp tells you how far. More on what SimHub is and what it costs.