KerbalController: a Custom Control Panel for Rocket Game Kerbal Space Program

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

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.

Joysticks

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.

• Ground
• Wiper --> Arduino analog input pin
• 5V

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.

LCD Modes

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!

Tips:

• 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

Comments

[jfmonod]

Hi, does this work with KSP 2 ?

[scubahamster]

Hi Hugo, I read that your final fuel bar wiring was different to the image. Do you have an up to date image that fits the final code by any chance? Many thanks!

[armorealm]

I'm just starting out with building this myself now, it looks so cool! Any chance you could convert the afdesign files to pdf?

[CobaltKyro]

Does the software side of things still work on the recent version of KSP? Also does the API plugin fork work on Windows?

[lucaspb]

I also would like to know it! I'm having problems with the handshake. It just doesn't work!

[Eaurouge86]

Did you ever get it to work?

[lucaspb]

Nah... There's no support for this mod. Go for Kerbal simpit and be happy! There's a huge discord community ready to help you out!

[Nicolem1234]

I'm a mom who has been tasked with purchasing all of the items on this list so that my 13 year old can build this controller (with some help). I have NO knowledge of what all of these parts are, but I managed to load some of them into my cart...only to find that upon checkout on the Tinytronics website (for the billing address), I'm unable to put USA as my country. So I suppose I have to stop right there? Does this company not ship to the USA? I wish it was possible to purchase this controller...kiddo is a (what I consider) master KSP gamer. He thinks this controller looks great! Any help or suggestions are appreciated!

[hugopeeters]

Hi Nicole,
Tinytronics is a local website I used to get my parts. There are different websites offering these parts in the USA. A quick google results in this overview: https://www.build-electronic-circuits.com/buy-elec...
AliExpress also has a lot of these parts, but shipping will take much more time. You can also copy/paste the name of the component into Google and find online shops.
Good luck!
Hugo

[morgoth_lord]

Seems like I replied to your comment by mistake instead of Nicolem1234's.
Anyway, thanks for the Instructable! I've taken inspiration from it to make a new design and add some functions. Will post pictures when done...

[morgoth_lord]

Hello Nicole,

Were you able to get the parts? I'm also in the US and ended up buying them from a combination of sites. Sparkfun.com
has some of the components for a good price, especially if you want
higher quality Arduino and related components. I found that Amazon.com
is generally much more expensive, but you should always compare prices,
because I found very good prices for protoboards (the PCB-like
prototyping boards) and some switches (and of course, you get the items a
lot faster). Finally, whatever I couldn't get in the above two sites, I
ended getting from AliExpress.com.
It takes a while to get to the US, and one of the shipments has been
delayed, but sometimes they have parts you can't find anywhere else, or
they have them for much cheaper. Heads up: If you're buying in
AliExpress, try to find a good reliable seller and buy most components
from the same seller if possible. that way you're not dealing with all
kinds of different stores and pricing schemes, and you might even get
free shipping.
I also had to get quite a few more parts than this
project, as I only took inspiration from it. I'm building my own control
panel with quite a few more functions and a different design. Depending
on your home city, you might have Maker Shops available to make the top
panel for a low price. Unfortunately that was not an option in my city,
so I ended up buying my own CNC machine to make the panel. Maybe I
should start offering to make panels for other people and offset the
cost....lol

[philipkyriacopoulos]

I have no clue how to make the handshake between the arduino code and the KSP Serial IO mod. I have been trouble shooting for a few days and I am using the slide potentiometer for the throttle to test the input and I am having no luck. Any tips or suggestions?

[lucaspb]

I'm also trying to figure it out. Guess those mods are not compatible with W10...

[MikeK270]

I've been wanting to make this forever now and I finally got parts to start working on it. Are you powering everything through just the arduino?

[Crowsjunker]

HugoPeters! Incredible job with this. You (and the countless other KSP modders) inspired me make my own! I was working with the same joysticks you use in this and I was banging my head against the wall trying to figure out why the Z axis was eternally wonky! I took a step back and began sifting through your code and stumbled on this.

if(analogRead(pRZ) <= 40){CPacket.Roll = constrain(map(analogRead(pRZ),0,40,-1000,0),-1000,0);}
else if(analogRead(pRZ) >= 60){CPacket.Roll = constrain(map(analogRead(pRZ),60,500,0,1000),0,1000);}
else {CPacket.Roll = 0;}

Seeing this, I realized that the Z axis seems like it was just as wonky for you! I decided to test a second joystick and found the same thing. a wonky z-axis! I was doubtful that between you and I we had gotten 4 defective sticks.
I took stick apart, hoping that there was something impacting the Z-pot - but found nothing - UNTIL I realized that it was wired wrong! (read: I had it wired wrong). It goes against logic (at least in mind) - but the z axis pot is wired so that BLACK is the wiper, not white!

I changed my wiring and presto - my z-axis produces results just like X or Y!
It just so happens that I took a close up look at the pictures you posted and, like I did initially, you used white as the wiper (wiper--->analog input pin)! It looks like it's a pain to change, but FWIW, I'll bet if you make black the wiper - it will no longer be wonky for you!


TLDR: For those joysticks, black is the z-axis wiper, not white!

Love the controller! Thanks again for the inspiration!!!

[hugopeeters]

Really?! Great find, thank you for sharing! Fly safe.

[frankieorabona]

I'm not sure about this...by putting the black as a wiper, the roll is fixed all on the right and I have no travel on the left...
I still have the Z-axis completely crazy....

[Kspmaker]

Hi does this work with ps4

[jinnylikestechystuff]

Hello hugopeeters and everyone!
Numerous questions here: sorry if I take up your time!
I am someone who would love to build this controller.
I have purchased all the parts and am going to prototype them pretty soon.
I plan to do exactly the same as hugopeeter's but I wanted to add a few touches I felt would be useful to me in gameplay. Some of them include: A launch button (With an arm button and a key 'arm'; this is just an extra stage button for fun), a craft to map toggle switch and I wanted to add an additional abort button alongside the arm switch.
Your instructions were really helpful and useful to me. I am confident in wiring and breadboarding.
The only problem I am afraid of is programming. I have a little previous knowledge in Python, Java and Swift (I know the basics like loops, variables, functions and statements) and have watched a couple of videos on Arduino programming and read the code you provided. I understand about 50% of the code, I still seem a little discombobulated; do you have any tips or tricks for programming this for a beginner like myself?
The second question I have is that if it is ok to use a GND, VCC, SDA, SCL instead of GND, RX, VDD. And if so, how should I wire it?
Any help at all would be greatly appreciated!

[abelcheban]

Hi everyone and Hugo. I am trying to build a button box with dual joysticks just as shown here excluding the LCD screen and fuel gauges. Could anyone lend me a hand in coding it or lead me to someone that has shown how to do so? I want to make it so it can be swapped to other games such as flight sim. train sim, and practically any other game that can really read a controller input. Thanks for any help!

P.S. The main focus is on the dual joysticks. The buttons and encoders I believe I can figure out but if any help can be given for those as well I would very much appreciate it!