Introduction: KerbalController: a Custom Control Panel for Rocket Game Kerbal Space Program
Why build a KerbalController?
Well, because pushing buttons and throwing physical switches feels so much more substantial than clicking your mouse. Especially when it's a big red safety switch, where you have to open the cover first, flick the switch to arm your rocket, start the countdown and 3 .. 2 .. 1 .. we have liftoff!
What is a KerbalController?
A KerbalController, also referred to as a Control Panel, Simpit (simulated cockpit), DSKY (display keyboard) or custom joystick, is a customized input device for controlling the popular rocket-building-and-flying-and-hopefully-not-exploding game Kerbal Space Program combined with optional output from the game, such as status lights, telemetry displays and/or fuel gauges.
This specific build includes inputs such as rotation and translation controls through joysticks, a throttle slider, loads of buttons with status lights, LED fuel gauges and a telemetry LCD display with multiple modes.
This guide will include everything you need to build an identical copy, or make adjustments and improvements along the way, as you see fit. Included are:
- a parts list
- digital design drawings ready for lasercutting
- wiring instructions
- Arduino code
- Code for the accompanying KSP plugin
- Lots of pictures
Ready for takeoff? Let's go!
Step 1: The Tools
The most important tool you need to have for this build is a soldering iron. That includes some solder, a metal cleaning sponge to clean the tip of the soldering iron and a "third hand".
Other tools are a wire stripper, a wire cutter, tweezers and some small size screwdrivers.
Step 2: Parts and Basic Layout
Making the best possible controller for you means selecting exactly which buttons and switches you want to implement. Because everybody plays the game differently. Some people fly planes and build SSTO's (single-stage-to-orbit). Others prefer rovers of space stations. And some just want things to spectacularly explode!
It helps to draw all the parts in their approximate size and drag them around in a vector drawing program (like Affinity Designer or Inkscape) or 3D drawing program (like SketchUp).
If you want an easier build, you can just copy my controller and get the parts listed on the attached parts list.
Step 3: Create a Prototype (optional)
If you are copying my controller, you can skip this step.
If you are going for a custom layout, I recommend using a shoe box first to create a working prototype with the main controls. It really helps to fine tune the position of the main controls. It's also nice to get the confidence you can get it to work before you continue to invest time and money in the final build. I actually played the game for quite a while with my shoe box controller. Isn't it the Kerbal way to use salvaged parts to hack something together?
Step 4: Tips on Wiring
When creating a prototype, don't solder all your buttons in unless you want to de-solder them when you get to the final enclosure. I soldered some wires to the buttons and used a solderless breadboard to make the temporary connections to the Arduino.
When connecting all electronics to the final faceplate, you can reduce clutter by creating loops for 5V and ground. You don't connect all ground pins directly to the Arduino, but rather connect ground on one button to ground on the next button and loop all around. Finally, you connect to the Arduino.
After creating loops for power and ground, all the connections to the Arduino pins remain. I recommend getting some strips of header pins and soldering the wires to those. You can use these as a big connector, so you can still unplug your Arduino for testing.
The length of the wires is a balancing act between short enough to keep the enclosure free of excess tangles of wire (which might prevent you from being able to close the box) and long enough to be able to move parts out of the way to solder other parts in, tighten screws and poke around with your multimeter while debugging.
Step 5: Getting the Faceplate Lasercut
Achieving a clean, professional look is very hard when sawing and painting by hand. Luckily, laser cutting is not very expensive any more. It allows for extreme precision, as long as your design is accurate.
Attached is my faceplate design, in formats appropriate for Affinity Designer and other vector drawing programs like the free InkScape.
I had the faceplate lasercut in The Netherlands at Lichtzwaard. They have since closed and activities have been taken over by Laserbeest, where I had the box laser cut. Every shop may have different requirements for the design, so check with your shop before submitting. They also almost always offer design help at an hourly rate.
Important things to keep in mind:
- Everything must be vector based. That's why the logo in my faceplate design didn't get etched. Note this is not fixed in the designs attached.
- Even text has the be vector based. So convert those letters into curves!
- Measure. Measure. Measure. I failed to take into account the size required for mounting the joysticks and had to hack it. Turned out fine, luckily. Note this is fixed in the attached designs.
After checking everything thoroughly, send it to the lasercutting shop. Expect to pay 40-50 euros in The Netherlands and get this beautiful result in the mail the next day!
Step 6: Hooking Up Buttons and Switches
Most switches and buttons have the connectors labeled C, NO, NC, +, -. Here's how to hook them up to the Arduino.
Simple switch or pushbutton:
- Ground --> C (common)
- Arduino digital pin --> NO (normally open)
We will configure the digital pin as INPUT_PULLUP, which means the Arduino will keep the pin at 5V and detect when the pin gets grounded and treat that as an input. The NO connector on the switch or button is Normally Open, so the circuit is not connected. When you push the button or toggle the switch, the circuit gets closed and the pin gets grounded.
Pushbutton with LED:
The button part is the same as above. For the LED, you attach additional wires:
- Ground --> - (negative)
- Arduino digital pin --> + (positive)
This part is pretty straightforward. We will use the Arduino pin in normal OUTPUT mode.
Safety switches with LED:
These are a bit different and do not allow control over the LED independent from the switch position. The LED will always only light up when the switch is toggled on. They have a +, - and signal connector.
- Ground --> - (negative)
- 5V --> + (positive)
- Arduino digital pin --> S (signal)
We will use the Arduino pin in INPUT mode. When the switch is toggled on, the LED lights up and the signal pin goes high.
Step 7: Hooking Up Joysticks and the LCD
The LCD is very simple. It just needs power, ground and serial.
- 5V --> VDD
- Ground --> GND
- Arduino Tx PIN --> RX
You can use a JST connector or solder the wires to the board directly.
The joysticks might look daunting at first, but they are quite easy to connect. There are three axis that are connected in the same way. Two of them are using the connectors on the bottom of the joystick. The third uses some wires.
- Wiper --> Arduino analog input pin
The connectors can be attached in this order. Don't worry about getting it backwards, the wiper is always the middle one. If power and ground are swapped, we can flip the axis around in the Arduino code later.
The wires might have a different colouring scheme on your joystick, but in general: the two wires with identical colours are for the button on top. Red or orange is 5V, Black or brown is Ground. The remaining wire is the wiper.
Step 8: LED Bar Fuel Gauges
Okay. This is the hardest part of the entire build. Feel free to skip this on your first build, or improve it and let me know!
I got these great LED bars I want to use as fuel gauges. The top LED is blue, then some green, then orange and finally red. If we can light one LED at a time, we can let it represent the fuel level on our spacecraft.
I initially ordered driver IC's with them. They work great! You can select dot mode or bar mode and it will display an analogue input voltage as a single LED (dot) or a range of LEDs (bar). But an Arduino does not output an analogue voltage! And the PWM feature that allows you to dim a LED by sort of emulating an analogue voltage, does not work with these driver IC's.
On to plan 2: shift registers. You get to work with these in every Arduino starter kit. And you can learn more about them here: https://www.arduino.cc/en/Tutorial/ShiftOut
The plan is to somehow convert the fuel levels into the proper string of bits that will represent the fuel levels on the LED bars. With 5 fuel gauges, all fuel levels filled up would need to be 10000000001000000000100000000010000000001000000000. With monopropellant empty, it would become: 10000000001000000000100000000010000000000000000001.
Sound simple enough. There are some complications. The shift registers have 8 pins, while the LED bars have 10 LEDs. I use 7 shift registers to get 56 outputs. When wiring them in, I skipped an IC pin somewhere (we'll fit that in code). And I wiring one LED bar in starting at the other end (we'll fix that in code). Oh and Arduino math that we need sometimes uses floating point arithmetic which causes rounding errors (we'll fix that in code). Note that I share the code in a later step.
My final build did not match the attached wiring diagram, so if you rebuild this controller, some updates are required to the code. Comment below if you need assistance.
Every LED requires it's own resistor. Try some different values in order to match the brightness. Green appears much brighter than red with the same resistors, so it helps to balance that out.
End result: instead of 50 digital pins required to power the 5 LED bars, that is reduced to 3: a clock signal, a latch signal and a data signal.
Step 9: Building the Enclosure
Time to get my revenge with those logo's!
I converted the logo's to proper vector drawings so they get etched just fine. This time, I have a different issue. The screw holes are not in the right places for proper assembly of the box. I used 6mm MDF for the box. Unfortunately, screwing of nailing into the edges causes them to split. I hacked it together with additional wood scraps and glue. Lot's of glue.
For those of you that are better with wood, glue and/or nails, I have attached a version of the designs without the screw holes altogether.
Despite the difficulties, the end result is quite slick.
Step 10: Software and Testing
Download the following software to make the controller work with Kerbal Space Program:
KSP plugin: https://github.com/hugopeeters/KSPSerialIO
The ZIP file is the compiled plugin. The rest is source code you can use to modify the plugin and compile your own version. Unpack the plugin into the GamaData directory.
Arduino Code: https://github.com/hugopeeters/KerbalController
Use the Arduino IDE to upload the code onto the Arduino Mega in your controller.
Look at the bottom right of the Arduino IDE to figure out which serial port the controller is on (e.g. /dev/cu.usbmodem1421). Open the config.xml file from the plugin directory and make sure your port is filled in. Now you are good to go!
You can use debug mode by putting the small on/off switch top left into the ON position. The LCD should display a string of letters. Each letter represents a button or switch and switches between lower and upper case when you press the button or toggle the switch. Setting the xyz switches into Xyz (on/off/off) will also display the throttle slider values. xYz displays joystick values for the Translation (left) joystick. xyZ for the Rotation (right) joystick.
The following display modes can be selected for display on the LCD by using the x, y and z switches.
TakeOff Mode: Suface Velocity / Acceleration (G)
Orbit Mode: Apoapsis + Time to Apoapsis / Periapsis + Time to Periapsis
Maneuver Mode: Time to next maneuver node / Remaining Delta-V for next node
Rendezvous Mode: Distance to target / Velocity relative to target
Re-Entry Mode: Percentage overheating (max) / Deceleration (G)
Flying Mode: Altitude / Mach number
Landing Mode: Radar Altitude / Vertical Velocity
Extra Mode: not implemented (yet)
To see the different modes in action, look at the video at the end of the instructable.
Step 11: To the Moon!
Fire up KSP, load your favourite vessel, or build a new one and off you go!
- Use custom action group 5 for your ladders
- Use custom action group 6 for your solar panels
- Use custom action group 7 for parachutes or drogue chutes
- Assign the launch escape system and the appropriate decouplers to the Abort action group
- Don't forget you need to Arm the Staging button
We have a be nice policy.
Please be positive and constructive.
Based on your design I made an EBay listing. I will update it to add your copyright notice.
I had a similar issue with another project where I had to use an obscene amount of shift registers (had to control 144 circuits independently). I designed/built a custom PCB that handled 40 circuits per board. It worked great, and I would look into this route for future shift register needs. I had it printed through Hackvana, which only cost me $40 for the parts. Shipping was a different story, since I needed it fast, but that is usually very cheap via Hong Kong post. I designed the PCB in KiCad.
I am using the exact same joysticks as listed in the excel sheet. My board slowly (in the matter of about 5 seconds)powers down and reboots if either joystick is twisted along the z axis clockwise only. Did you have this issue?
Had the same problem. For my joysticks, the internal wiring of the z-axis was done wrong by the manufacturer (black was the wipper and white the ground). I simply opened them and resoldered the wires. Or you could just change the wiring in your controller. Hope this helps!
Yes. When you twist them too far clockwise, the resistance drops too far. You should be able to solve that by putting a resistor in series with that axis.
What were the size dimensions for the top and sides of the cutouts for this project? as in what was the tops length and width along with the sides so i can configure my lazer cutter right.
The faceplate containing all the buttons should be 300 mm wide by 200 mm tall.
For the rest of the box, the drawing contains a red square for scaling that should be 10x10 mm.
Hey, I love your design. I am thinking of making one, but I am still wondering one thing. For things like map screen, fuel transfer, etc., will you have to use a keyboard for it?
I did not implement a dedicated button for map screen, but that would be easy to add (or re-assign one button). Fuel transfer requires you to click on the menu's with your mouse. I don't know of a way to bind that to your keyboard.
Is it necessary to use an Arduino Mega, or would a cheaper model work too?
That IO expander should work. Not sure if the pro mini is slower than a mega, but you always reduce the refresh rate of the calculations. I bet it'll work fine.
So, in theory, would this allow me to use a Pro Mini to cut costs?