3D Printed Keyboard for PocketChip

Clicky button goodness

I used this face plate keyboard https://www.thingiverse.com/thing:1998427

I printed the plate with clear PLA and 36% infill. It was too much infill and it got rough around the display, still usable. I’d probably reprint with 25%.

I used the PLA version of the buttons with 25% infill. I also made a small modification to the bridge that connects the escape button to the d-pad per a suggestion on the author’s GitLab account. The bridge connects to the up arrow instead of the left arrow. Not sure that it helped much because the left arrow still doesn’t feel as clicky as the rest.

You have to be super careful pulling the buttons off the printer plate to avoid breaking the bridges between the buttons. I broke two but used the tip of a hot glue gun to melt them back together.

The buttons! What do they do?

For the label, I scanned the face plate and placed all the letters in PhotoShop. It took some trial and error, but I ended up with a font and size that looks ok. I laser printed the label on removable vinyl then cut it out on the Cricut. It fit perfectly.

Cut cut cut

Here’s my edited keyboard button model and my keyboard label files. WordPress hates zip files so tar.gz it is.

300DPI (4.217″ wide)

Connecting 8BitDo Zero to PocketChip

Well this was way more involved than I had expected.

I wanted to hook up a bluetooth gamepad to my PocketChip so I could play PICO-8 games a little more ergonomically. I had a few controllers laying around, but one seemed perfect for the job: the 8BitDo Zero. It’s really small and it fits the “pocket” ethos of the PocketChip. The only downside is that I’ve never actually gotten the damn thing to work correctly on any system I’ve connected it to.

8BitDo Zero

It has a few different modes for different systems. One is a keyboard emulation which just “types” letters when you push the buttons. This is the easiest mode to get working and it works on any device that will accept a bluetooth keyboard. The downside is that you have to remap all the key bindings in the programs you’re trying to control. PICO-8 doesn’t have control profiles or anything that would make this a friendly option.

It also has a gamepad mode. That sounds promising! First thing you have to do is get it connected. Luckily I had just spent a ton of time trying to get my bluetooth speaker connected so I was familiar with bluetoothctl. power on; agent on; scan on; pair; trust; connect.

Out of the gate it looked promising because the d-pad worked like the arrow keys. I was able to navigate SPLORE, but sadly the other buttons didn’t work. Looking at the PICO-8 log, I saw that there were no joysticks discovered. Well why not?

apt install jstest-gtk
Running jstest I was able to see the buttons were actually working but that was on the `/dev/input/js0′ device. Also, the d-pad wasn’t actually getting interpreted as gamepad buttons – instead normal keyboard scan code were being sent. Sigh. After a bunch of reading, it turns out that SDL2 no longer supports the joystick devices, but instead looks at event devices.

There’s a known problem with SDL on Linux where the udev devices aren’t readable by normal users. The fix is to add add your account to the input group. That wasn’t the case on the PocketChip. The chip user was already in the input group.

I ran across some forum posts suggesting that the controller mapping may need to be updated. The “normal” way to do this is to use a tool that is only released in binary form and, sadly, there wasn’t an ARM build for the PocketChip. One user suggested building the controllermap tool from source on the device. Sounded promising, but it also sounded like a lot of typing for that tiny keyboard.

apt install openssh-server
In order to make it easier to futz around with building on the PocketChip I installed ssh server so I could at least work on a real laptop instead of the tiny screen with the tiny keyboard. Then I followed the instructions on the forum post … and it didn’t build. It wouldn’t build because configure wanted some sdl_config tool in the path… and I didn’t have that. Ok…

apt install libsdl-dev
Don’t do this. You don’t need to. I didn’t need to either, but I didn’t know that yet. That solved my problem and I was able to configure the tests and build the controllermap tool. Then I ran it… “SDL was built without joystick support.” Wat.

Well.. I already had the SDL2 sources downloaded so might as well build the whole thing. It took about 20 minutes and when it was done, I had a shiny new SDL2 from source and was able to build controllermap. This time when I ran it I got a useful error: “ERROR: Couldn’t initialize SDL: No available video device.” I guess that’s progress. Set up X forwarding… run again… “There are 0 joysticks available.” Progress?

More searching. I’m in the “3 results” part of Google now but I found a post which lead me to this udev rules file on GitHub. After a little reading about udev I gave it a shot and added this rule.

# 8Bitdo ZERO
SUBSYSTEM=="input", ATTRS{name}=="8Bitdo Zero GamePad", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"

That actually worked…ish. It worked well enough that the controllermap program at least could find gamepad. Unfortunately I wasn’t able to complete the mapping wizard because the d-pad still wasn’t working. Looking at that rules file, the author had linked to the SDL2 readme and labelled it “Useful reading“. In the last section it introduced a few new commands to try: evtest and udevadm.

Running evtest shows you a list of the event devices along with their friendly names. I picked the 8BitDo and it started logging the buttons that were pushed. Everything made sense except the d-pad which was still emitting keyboard scan codes. So I checked out the other command. sudo udevadm info --query=all --name=input/eventXX, using the event device number from evtest I got this.

P: /devices/platform/soc@01c00000/1c28c00.serial/tty/ttyS1/hci0/hci0:5/0005:05
N: input/event3
E: DEVNAME=/dev/input/event3
E: DEVPATH=/devices/platform/soc@01c00000/1c28c00.serial/tty/ttyS1/hci0/hci0:5

Hmm… INPUT_KEYBOARD doesn’t sound right. At this point I was getting frustrated so I hooked up a SteelSeries Nimbus and tried with that… after burning 30 minutes on that hot mess (something was borked with the d-pad), I tried with the Nintendo Pro controller and worked just fine. I was able to run controllermap and generate the mapping, paste it into PICO-8’s sdl_controllers.txt file and for the first time actually see that this is possible.

Looking at the the udevadm output for the Nintendo Pro controller I didn’t see anything about a ID_INPUT_KEYBOARD so I wondered if I could remove that from the 8BitDo with the udev rule. Much reading later…

# 8Bitdo ZERO
SUBSYSTEM=="input", ATTRS{name}=="8Bitdo Zero GamePad", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1", ENV{ID_INPUT_KEY}="0", ENV{ID_INPUT_KEYBOARD}="0"

I was hoping that if I turned off INPUT_KEYBOARD it would keep the d-pad from sending keyboard events. I wrote the rule to /etc/udev/rules.d/99-8bitdo.rules and reloaded the rules udevadm control --reload-rules. Then the rules needed to be triggered again so I disconnected and reconnected the gamepad. This time when I ran evtest I got sane looking events from the d-pad! Next step was to build the controllermap. Moment of truth! controllermap 0 > ~/controls.txt Hey it worked! I pasted the output controller map into PICO-8’s mapping list and booted up SPLORE and it worked! All the buttons “just worked.”

So I’m really happy. This is the first time my little 8BitDo Zero has ever actually worked correctly in all the years I’ve had it. Now I can play my PICO-8 games with a nicer controller and what a difference it makes for some of the platformers that decided that “up arrow” should be jump (mumble mumble)…

If you’re one of the very few people in the world who is trying to hook up a 8BitDo to a PocketChip (or Pi) I hope this helps. Also, hopefully I can save you a step and you can just use my PocketChip build of controllermap from the SDL2 tests.

  1. Add the udev rule above to /etc/udev/rules.d/99-8bitdo.rules
  2. Connect the gamepad with bluetoothctl
  3. Run controllermap 0 > map.txt
  4. Add the result to ~/.lexaloffle/pico-8/sdl_controllers.txt
  5. Run PICO-8

Connecting PocketChip to a Bluetooth Speaker

This ended up being more of a pain than I expected so I figured I’d write it down for the next person who tries.

  1. Set up your package manager sources if you haven’t already. Follow these instructions.
  2. Add the following packages pulseaudio, pulseaudio-utils, pulseaudio-module-bluetooth
    1. sudo apt install pulseaudio pulseaudio-utils pulseaudio-module-bluetooth
  3. Put your speaker into pairing mode.
  4. Run bluetoothctl and run the following in the prompt:
    1. power on
    2. agent on
    3. scan on
  5. Wait until you see your speaker show in the scan list and note its hardware address.
  6. In the bluetoothctl prompt run the following:
    1. pair <hardware address>
      1. Hint: type the first few digits and then tab-completion works.
    2. trust <hardware address>
    3. connect <hardware address>
  7. If everything worked correctly it should say connected: yes. After that your PocketChip should remember the speaker. You may need to run connect again, to reconnect if you turn the speaker off and on, but you won’t need to re-pair.
  8. In the prompt run:
    1. paired-devices
      1. You should see the speaker in the list.
    2. quit
  9. Try playing a sound (you can use PICO-8 or SunVox), you should hear sound from the connected speaker.
  10. If the sound is crazy loud (probably is) use alsamixer to adjust the volume.

I’ve found that if pulse audio isn’t running before attempting to connect to the speaker, the bluetooth connection will fail. I wrote a script that helps make reconnecting easier.

pulseaudio -k # kill existing service
pulseaudio --start
bluetoothctl -- connect <your speaker hardware address>
sleep 8
pacmd set-default-sink 1 # where 1 is the card id
amixer set Master 20%

Good luck and I hope this helped.