7.1 Swapping Microcontrollers: Bluetooth (Version 2022-07-01)

(10 min read)

Unplug any cords or batteries before swapping your microcontrollers.

QMK does not work well with Bluetooth. ZMK should be used instead.

7.1.1 Necessary tools and components

• 3mm Allen key

• 2 x Microcontroller that support Bluetooth. The nice!nano V2 is officially supported, but most microcontrollers with a footprint similar to the Arduino Pro Micro should work. Not compatible with BlueMicro840 V1.0.

• 2 x LiPo batteries with 2-Pin JST-PH. It's safest to get them from Adafruit or Sparkfun.

• If your keyboard shipped before 2022-08-01, you will also need either 2 On-Off switches or 2 wires with female pin headers on both ends. SeeChoice 1: Add a switch onto the keyboard for details.

Double check the LiPo battery for your microcontroller! Different microcontrollers may require different batteries. Using the wrong battery can lead to explosions!

Make sure that your JST-PH is correctly wired! The black wire and red wire should be in the correct orientation on the JST-PH connector, as shown in Figure 7.1.1.

It's recommended you use batteries from Adafruit or Sparkfun. You can use other vendors, but note that some vendors sell LiPo batteries with their wires reversed. See video on this issue by Adafruit here.

Figure 7.1.1 Orient your JST connector same way as the photo above. The black wire should be on the right and red should be on the left.

Figure 7.1.2. This 3.7V 110mAh LiPo battery worked with nice!nano's during testing.

7.1.2 Adding Bluetooth

Keyboards shipped after 2022-08-01

If your keyboard shipped after 2022-08-01, follow the steps below.

Step 1

Remove the plastic cover and take out the default microcontroller that came with the keyboard.

Figure 7.1.2.1 Step 1 - Take out the default microcontroller that came with the keyboard.

Step 2

Insert the Bluetooth enabled microcontroller.

Optional: If you want the USB-C port to be closer to the edge of the keyboard, you can loosen the screws counterclockwise with an 3mm Allen Key by a half circle. Then slide the PCB forward. Tighten the screw again afterwards by turning it clockwise.

Figure 7.1.2.2 Step 2 - Insert the new Bluetooth enabled microcontroller. If you want the USB-C port to be closer to the edge of the keyboard, you can loosen the screws.

Step 3

Insert the LiPo battery.

No special instructions for inserting the battery. As long as you obtained the correct battery, the connector will insert correctly. This is because the JST-PH socket can only accept the battery header in one direction.

Figure 7.1.2.3 Step 3 - Insert the new Bluetooth enabled microcontroller and the LiPo battery.

Step 4

Put the cover back on. You did it 🎉! Proceed to the section on flashing your keyboard with ZMK.

Figure 7.1.2.4 Step 4 - Put the cover back on.

Keyboards shipped before 2022-08-01

Step 1

If your keyboard was shipped prior to 2022-08-01, you have 2 choices.

Choice 1: Add a switch onto the keyboard

• 2 x On-Off switches with wires attached. Compatible switches include toggle switch, latching switch or slide switch. Momentary switches will not work.
• A Dupont connector kit such as this one will include the necessary tools below:

  • Crimping tool

  • 2 x female 2-pin header shells

  • 2 x female 2-pin header pins

Crimp the Dupont connectors onto the On-Off switch. To see how this is done, check this excellent guide from Instructables.

Latching switch

Toggle switch

Choice 2: Use a wire

• 2 x Wire with female pin headers on both ends

It's not the most exciting, but it works. Although the keyboard would remain 'ON' until you disconnect the wire or the battery runs out.

Wire with female 2-pin headers on both sides.

Step 2

a. Swap in your Bluetooth enabled microcontroller.

b. Attach the LiPo battery to the JST-PH socket indicated by the green arrow in Figure 7.7.

Figure 7.7. Keyboard with nice!nano microcontroller. Green arrow indicates the JST-PH socket for the Lipo battery. Purple arrow indicates pin headers for the on-off switch.

c. Attach the female pin headers of the on-off switch as indicated by the purple arrow in Figure 7.7. It should attach to the two male pin headers on the top right as indicated by the red arrows in Figure 7.8. The orientation doesn't matter.

If you are using a wire, connect one end to position 1 and another to position 3 as indicated in Figure 7.8. Note that if you use a wire, the keyboard would remain 'ON' until you disconnect the wire.

Figure 7.8. Attach the on-off switch to the two male pin headers on the top right as indicated by the red arrows.

d. Put the cover back on. You did it 🎉! Proceed to the section on flashing your keyboard with ZMK.