Skip to main content
Version: 0.4.x

Troubleshooting

Use this page to resolve common VibeKeys setup and connection issues.

No sessions appear in Remote mode​

The session picker stays empty when the device and vibetty are not reaching the same MQTT broker.

  1. Check that vibetty is running on your computer and its MQTT button shows conn. If it shows brkr only, the built-in broker is up but vibetty itself is not connected — re-run vibetty setup.
  2. Check that the MQTT broker URL saved on the device (via the setup page) points at the same broker vibetty uses. With vibetty's built-in broker on your PC, the device needs mqtt://YOUR_PC_LAN_IP:1883.
  3. Check that both sides are on 0.4.x — firmware v0.4.0+ and vibetty 0.4.x. The MQTT protocol changed in 0.4.0, and older firmware will not connect or display correctly. Update the firmware or vibetty as needed.
  4. Check the device is online: if the WiFi you're using isn't one of the saved networks (or is 5GHz-only), the device can't reach the broker. Add the network on the setup page.

See Remote Control Mode for the full setup flow.

Device does not appear in the setup page​

The setup page talks to the device over Web Bluetooth (BLE).

  1. Use Chrome or Edge over HTTPS — other browsers don't support Web Bluetooth.
  2. The device must be in Keyboard mode (select it in the boot menu) — the configuration service is only advertised there.
  3. If the device is already connected to a computer or phone as a Bluetooth keyboard, it stops advertising. Press the ACCEPT key on the device to re-start advertising, then click Connect again.

Voice input doesn't produce text​

  1. On the setup page, verify the ASR fields: URI, API key, and model must all match your Whisper-compatible service. In remote mode the MIC key does nothing at all until an ASR service is configured.
  2. In keyboard mode, make sure "prefer built-in ASR" is checked on the setup page — otherwise MIC forwards a keystroke to your computer instead of recording. (This setting has no effect in remote mode, which always records on the device.)
  3. Check your MIC mode: PTT requires holding the key while speaking; Toggle starts and stops with a tap.

See Voice Input in Remote Mode or Voice Input in Keyboard Mode.

Cannot update firmware via OTA​

  • Devices on 0.3.x cannot OTA to 0.4.0 — the partition layout changed. Use the ESP LaunchPad USB method once (see Updating Firmware); future updates are OTA again.
  • Devices already on 0.4.x update via Setting → OTA Update. Make sure the device can reach one of your saved WiFi networks, and use the matching OTA image for your hardware version.

Device won't connect to WiFi​

  • VibeKeys Max only connects to 2.4GHz networks — 5GHz-only networks will never appear as reachable.
  • List order is the priority order: the device connects to the first saved network in range at boot. Reorder or clean up the list under Setting → WiFi networks or on the setup page.