Wireless · ZMK

Lily58 Choc Wireless quick-start guide

Getting connected, finding your way around the layers, and making the layout your own.

Firmware: ZMK v0.3.0, the latest stable ZMK release (1 August 2025).

Updated September 30, 2026

Download PDFView the Lily58 Choc Keyboard
On this page
Good to know: the Lily58 is an open-source keyboard designed by kata0510, and the wireless version runs the open-source ZMK firmware. Everything in this guide works the same on any wireless ZMK Lily58, so the ZMK documentation and the many community guides and videos about the Lily58 apply to your keyboard too. The useful ones are listed at the end of this guide.

Connect the batteries

For safety, the batteries ship unplugged. Under each half there is a small white JST connector: plug each battery into its half. The plug only fits one way, so never force it.

To charge, plug each half into a USB-C charger or computer. If your keyboard has OLED screens, they show the battery level of each half and the connection status (see “Reading the screens”).

The reset button

Each half has a small reset button on its side.

  • Press once to restart that half, if it ever stops responding.
  • Press twice quickly to enter firmware-update mode: a USB drive appears on your computer. You only need this to install new firmware. If you enter it by accident, press reset once more to go back to normal.

Pair with your computer

  1. Once both batteries are connected, the two halves find each other automatically.
  2. Open the Bluetooth settings of your computer, tablet or phone.
  3. Select “Lily58” in the list of devices and pair it. That’s it, you can start typing.
Tip: the left half is the one that talks to your computer. If pairing fails, remove “Lily58” from your device’s Bluetooth list, press reset once on the left half and try again.

Reading the screens

If your keyboard has OLED screens, each half shows its battery level and a connection status. The symbols on your screen may look slightly different from the ones below.

Left half: connection to your devices

Connected over Bluetooth. The number is the active profile (1 to 5).
Profile 1 is free: the keyboard is ready to pair with a new device.
Profile 1 is already paired with a device that isn’t connected right now. The keyboard waits for that device and won’t pair with another one on this profile: select a free profile, or clear this one with BT_CLR (see “Use several devices”).
Typing through the USB cable of the left half.

Right half: connection to the left half

The right half is connected to the left half.
The right half isn’t connected to the left half. Check that both batteries are plugged in, then press reset once on each half.

Use several devices

The keyboard remembers up to 5 devices (Bluetooth profiles). Hold Lower (layer 1, see “The layers”), then:

  • BT_SEL 0 to BT_SEL 4, on the number keys 1 to 5, select profiles 1 to 5. Select a free profile, then pair the new device from its Bluetooth settings.
  • Afterwards, the same keys switch instantly between your paired devices.
  • BT_CLR, at the far left of the number row (Esc position), forgets the device on the current profile, if you need to pair it again. Remove “Lily58” from that device’s Bluetooth list too before pairing again.

Cable or wireless

Your keyboard can type over Bluetooth or through a USB-C cable plugged into the left half. When both are available, it uses your preferred connection. It comes set to prefer the cable. To change it, hold Lower, then press OUT_USB or OUT_BLE on the number keys 6 and 7:

  • OUT_USB, prefer the cable: when the left half is plugged into a computer, it types through the cable. Unplugged, or plugged into a charger, it types over Bluetooth.
  • OUT_BLE, prefer Bluetooth: it keeps typing over Bluetooth even while the left half is plugged into a computer, for example to charge it from one computer while typing on another device. When no cable is connected, it types over Bluetooth either way.

The keyboard remembers your choice, even after a restart, and the left screen shows the connection in use (see “Reading the screens”).

Remap any key with ZMK Studio

You can change the layout from your browser, with nothing to install or flash.

  1. Plug the left half into your computer with a USB-C cable.
  2. Open zmk.studio in Chrome or Edge and click connect.
  3. Click a key, pick its new function, then save. Changes are stored on the keyboard.
Back to the default layout: use Restore Stock Settings in ZMK Studio at any time. Keep Lower and the Bluetooth keys somewhere on your layout.

The layers

The Lily58 keeps a full number row, and puts Bluetooth, symbols, F-keys and arrows on two extra layers, reached by holding thumb keys.

The thumb keys

Alt
GUIWin / Cmd
Lowerhold: layer 1
Space
Left half
Enter
Raisehold: layer 2
Backspace
GUIWin / Cmd
Right half
  • Layer 1 · Lower (Bluetooth, F-keys and symbols): hold Lower, the third thumb key on the left half.
  • Layer 2 · Raise (numbers, F-keys and arrows): hold Raise, the second thumb key on the right half.

Reading the maps

&kpA normal key.
&moHold to use that layer: 1 for Lower, 2 for Raise.
&btBluetooth control (see “Use several devices”).
&transTransparent: the key keeps what it does on the base layer.
&noneDoes nothing on this layer.

Layer 0 · Base

Always active

^ is Ctrl and ⇧ is Shift.

Layer 1 · Lower: Bluetooth, F-keys and symbols

Hold Lower

Bluetooth profiles on the number row, OUT_USB / OUT_BLE on 6 and 7, F1 to F12 just below.

Layer 2 · Raise: numbers, F-keys and arrows

Hold Raise

Arrows on J K L ;.

Useful links

These resources cover every wireless ZMK Lily58, not only ours, so you can rely on them for anything this guide doesn’t cover.

ZMK documentationzmk.dev/docs: the official firmware docs, from basics to advanced features.
ZMK versionZMK v0.3.0, the latest stable ZMK release (1 August 2025).
ZMK Studiozmk.studio to remap in your browser, and zmk.dev/docs/features/studio for what it can do.
Key codeszmk.dev/docs/keymaps/list-of-keycodes: every key you can assign, with OS compatibility.
Bluetooth issueszmk.dev/docs/troubleshooting/connection-issues: pairing problems, and re-pairing the two halves.
Split keyboardszmk.dev/docs/features/split-keyboards: how the two halves work together.
Custom firmwarezmk.dev/docs/user-setup to build your own firmware (combos, macros, tap dance…). Keymap Editor edits the keymap file visually.
Our default configgithub.com/jerlam06/zmk-config-lily58: the firmware your keyboard ships with, ready to fork.
Controllernicekeyboards.com/docs/nice-nano: the nice!nano-compatible controller inside each half.
The Lily58 projectgithub.com/kata0510/Lily58: the original open-source design by kata0510.
CommunityZMK Discord: a very active community for firmware questions.
Typing practicekeybr.com: build speed again while you get used to the new layout.

Need help?

Something doesn’t behave as expected, or you have a question about your keyboard? Just write to us, we answer every message.

contact@thekeeblab.com · thekeeblab.com/pages/contact

Happy typing! · TheKeebLab