ErgoDox Wireless Assembly Instructions (Group Buy Round 1)

This page contains the assembly instructions for the ErgoDox Wireless keyboard. This guide is for the group buy round 1 hardware, which sold in February/March 2021. This guide is not needed for the round 2 hardware, which sold in October 2021.

Before starting the assembly process, please read this document carefully in its entirety. Some of this stuff here is going to sound really silly but is quite important. The suggestions here will help you assemble a working keyboard. When doing the assembly, I suggest having this page by your side for you to reference.

You can watch this quick assembly video to get a general idea of assembly process but please use this guide when doing the actual thing.

Safety

  • Safety is the number one priority.
  • You should wear eye protection when you are cutting headers. The removed pieces have a tendency to fly randomly. You don't want that in your eyes.
  • You should wear eye protection when soldering.
  • When soldering, make sure USB is not plugged in and the battery is not connected.

A Gentle Reminder: Take Your Time

  • Take your time, it's not a race. Your goal is to assemble a working keyboard, not to assemble it faster than everyone else.
  • You don't have to assemble the entire keyboard in one sitting. You don't even have to finish it in one day. If you're not sure about something, stop by the Discord and ask. You can continue your assembly the next day.

Soldering Advice

  • When soldering, heat the pad for two seconds, add solder for two seconds, let the solder flow for two seconds. Do not keep your soldering iron on any PCB for longer than that to avoid overheating PCB components.
  • After soldering, give it 10-15 seconds for everything to cool down.
  • If solder didn't flow the way you wanted to, make sure the board/components have cooled down before retrying.
  • It's much easier to add solder than to remove solder. Add only a tiny bit of solder each time. If it's not enough, wait for everything to cool down and only add more solder as needed.
  • It's fine if something takes more than one try. If you don't solder frequently, it's possible that some things will take 5 or even 10 tries.
  • If solder isn't sticking as it should, add some flux.
  • Avoid cheap solder. Something like this Kester solder will make the assembly process much easier.

Solar PCB: LED Information

The blue LED indicates charging status:

  • Blue LED will blink quickly when connected over USB but there is no battery to charge.
  • Blue LED will remain solid when connected over USB and charging a battery.
  • Blue LED will be very weak (or off) when the battery is at full capacity.

The red LED is controlled by the firmware:

  • When running the initial test firmware, the red LED will turn on when the test button is pressed. It will remain on if there is a short on any of the GPIOs.
  • The red LED will pulse slowly when in bootloader mode, during which you can update the keyboard half firmware (documented below).
  • The red LED will blink once when the board is booting or rebooting.

Solar PCB: Initial Testing

You should start the assembly process by testing the solar PCBs. Even though testing was done before the PCB was shipped, you should repeat the process to be extra certain.

  • The solar PCB's button on the left of the USB C port (on the side of the solar plus label) is a test button. If you press it, a red LED should turn on.
  • The solar PCB has 13 GPIO pins for the 6 rows and 7 columns. If you short any of the 13 pins, the red LED should turn on.
  • You should test that all 13 pins work by shorting it with one another. While you do not need to test each of the 78 possible combination, you should test one pin against the other 12 pins and check that the LED responds accordingly.
  • You should not intentionally short anything else on the PCB.

Solar PCB: Component Placement

The solar PCB is reversible in the sense that the same PCB can be used for the left side and the right side. The components should be soldered in a symmetric manner as shown below. The one on the left is the orientation needed for the left side, and the right is the one for the right side.

Solar PCB: 3-Pin JST Connector

The 3-pin JST connector legs should be cut by about half its length such that you can't feel/see it on the other side of the PCB. This is important especially for solar since the PCB should sit flush against the top of the case.

The left and right connectors show the difference before and after cutting.

  • Start by soldering just one pin.
  • Check that the connector is straight. If not, heat the first pin and readjust the connector.
  • Once the connector is straight, solder the remaining two pins.

The result should be completely flat to the touch.

To finish off, use a multimeter to test that there is no short between GND (the middle pin) and the VBAT pins (the two side ones).

Solar PCB: 13-Pin GPIO Connector

For the laser cut case, cut 13-pin header such that the short end doesn't protrude beyond the solar PCB. The black insulator should sit flat against the solar PCB.

For the aluminum case, there is no need to cut the 13-pin header. The tip of the short end should be flush with the other side of the solar PCB.

The left and right shows the difference between headers needed for the aluminum case compared to the laser cut case.

When checking for straightness, you need to check from multiple angles. You may lean the 13-pin header against the 3-pin JST connector to help ensure that it is straight. For this reason I always solder the battery connector first. This is especially helpful when soldering for the aluminum case as the header is somewhat "floating" when you solder it.

  • Start by soldering just one pin.
  • Check that the connector is straight. If not, heat the first pin and readjust the header.
  • Once the header is straight, solder the last pin.
  • Check again that the connector is straight.
  • Solder the middle 11 pins and check that the header remains straight after each subsequent pin.

When soldering for the aluminum case if the headers is only slightly crooked after soldering the first pin (seen in the following picture), you may choose to solder the last pin using one hand while applying some pressure with your other hand and straightening the header at the same time.

Keyboard PCB: 13-Pin GPIO with Direct Soldering

I strongly recommend using Mill Max sockets to connect the keyboard PCB and the solar PCB (details below). However you may choose not to and decide to solder the two directly.

Before doing so, you must really make sure that everything is flat. If not, desoldering and fixing it will be a nightmare. Use some force, push a little everywhere on the PCBs to ensure flatness.

  • As the holes were designed for use with Mill Max sockets, they are on the larger side and will require quite a bit of solder.
  • Use only a little solder initially and let the joints cool down before adding more. Take care to not overheat either PCB.
  • Take care to not add too much solder and accidentally short adjacent pins. It's always better to add solder slowly than have to remove solder.

Keyboard PCB: 13-Pin GPIO with Mill Max

The primary benefit of using Mill Max sockets for connecting the keyboard PCB and the solar PCB is that it makes adjustments easier. You may not think that you need to but using sockets here will make your build a bit more resistant to mistakes.

I recommend soldering the Mill Max sockets without the headers in them. This way if you accidentally get solder in a socket, you can remove just the single socket and replace it. If you solder with the headers in the socket, you risk getting the headers stuck to sockets thus defeating the entire purpose of socketing.

You'll want to solder the sockets against a flat surface. Make sure what you use is tolerant of high temperatures as the entire socket will heat up when you solder it. One straightforward solution is to use you can use the other keyboard PCB as a surface to solder on.

Solar PCB: Solar Panels

If you are soldering for the aluminum case, I strongly recommend putting all four panels into the two halves before soldering any of the panels. The panels can be somewhat of a tight fit. It can be helpful to try different combinations of the four panels since one of them might be slightly smaller/larger and fit better into one half than the other.

You can use the rear end of a screwdriver (or use a hammer) to gently push the panels into the case. It might be difficult to flatten the panels using only your hands and fingers.

You can sand away a bit of the edges as a last resort if necessary. That said, I've assembled quite a few ErgoDox Wireless keyboards already and haven't needed to sand anything.

This fitting process isn't necessary for the laser cut case as the tolerance there will provide a looser fit.

The polarity of the solar panels should match the labels on the solar PCB.

I would recommend taping the solar panels to the top of the case to ensure that they stay flat while you solder. For the laser cut case, this is very important due to the looser tolerance. For the aluminum case, the tight fit should be enough to prevent the panels from moving but this is still good idea.

When soldering for the laser cut case, I recommend tinning the solar panel pads quite a bit to give it some additional height. This is because the panels are 1.8mm thick whereas the top layers are 3mm thick and something needs to make up the 1.2mm difference. Adding this height by tinning the pad will make it much easier to subsequently attach to the solar PCB.

When soldering for the aluminum case, you should not add any height with the tinning. The case's 1.8mm top layer matches the 1.8mm thickness of the solar panels. Tin the pads just enough to make soldering easier but not too much such that the solar PCB can't remain flush against the top of the case.

Before soldering the solar panels, you want to make sure that the solar PCB is straight and the USB port is aligned with the opening in the case. I would even recommend having the USB cable plugged in as an additional precaution.

Ideally solder the solar panels with a thin soldering iron tip that is small enough to fit inside the opening. This helps ensure that the panels are correctly attached to the solar PCB. It's better to use a higher temperature and make contact for a shorter period of time to avoid overheating the other components. As usual, allow everything to cool down in between attempts.

Solar PCB: Attaching the Battery

There is no standard for the orientation of positive and negative battery cables and the solar PCB's 3-pin JST connector (rather than a 2-pin connector) allows both orientations to be accommodated.

If you purchased a battery from the SliceMK store, the black cable is the negative terminal and should go to the middle of the 3 pins. If you got battery from elsewhere, you should double check which cable is negative and positive.

If you have any doubts about how to install the battery, please drop by the Discord and ask. Take extra care to install the battery correctly as having it installed in the wrong orientation for even a few seconds can cause irreparable damages to all the components.

In the laser cut case, you may choose to install a rubber feet or two on the battery to prevent the solar PCB from sliding down.

The same isn't strictly necessary in the aluminum case as the tolerance on the solar panels is tighter. If you wanted to, you can put two rubber feet on the USB C port.

Firmware Flashing Information

To flash a UF2 file, you should drag it into the virtual MDBT50QBOOT/SliceMK drive on your computer. Flashing will take around 5 seconds to complete.

  • After successfully flashing on macOS, you will see a "disk not ejected properly" error. This is expected.
  • After successfully flashing on Windows, the virtual drive will disappear. This is expected.

If you are using a dongle, you only need to flash the firmware on each keyboard half once. When you make changes to your keymap, you only need to update the firmware on your dongle.

If you are not using a dongle, you will need to update the firmware on your "central" half each time you make a change to your keymap.

Dongle: Flashing Information

  • To put it in bootloader mode for the first time, hold the dongle button while plugging it in to your computer. The blue light should pulse slowly and a MDBT50QBOOT drive should appear on your computer. If the blue LED is solid when you press the button and but turns off when you release the button, you didn't correctly put it into bootloader mode correctly so try again.
  • To put it in bootloader mode after you have already loaded ZMK, simply press the dongle button once. The blue light should pulse slowly and a MDBT50QBOOT drive should appear on your computer. If this doesn't happen, treat it as if you were putting it into bootloader mode for the first time (as described above).

See below for instructions on obtaining the zmk.uf2 that should be flashed to the dongle.

Solar PCB: Flashing Information

  • The solar PCB's button on the right of the USB C port (on the side of the solar minus label) is a reset button.
  • To reboot the solar PCB, press the reset button once and the red LED should blink once.
  • To put the PCB into bootloader mode, you must press the reset button twice within 500ms. The red light should pulse slowly and a SliceMK drive should appear on your computer. You can copy UF2 to the SliceMK drive.

You can find the firmware for the two keyboard halves here. The left half should receive left-prod.uf2 and the right half should receive right-prod.uf2.

Firmware Customization Information

  1. Navigate to the example ZMK configuration repository and create a fork. You will need a GitHub account.
  2. Navigate to the "Actions" tab on your fork. Click the "I understand my workflows, go ahead and enable them" button.
  3. Click "Build" in the left sidebar and click "Run workflow" to build the default keymap.
  4. Once the build completes, download the build artifacts. In particular, you will want zmk.uf2. That file should be deployed to the dongle as described above.
  5. Edit config/slicemk_ergodox.keymap as needed and your new keymap will be built automatically via GitHub Actions.

Firmware Debugging Instructions

See ZMK instructions on USB debugging.