Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
70 lines (53 loc) · 3.25 KB

TROUBLESHOOTING.md

File metadata and controls

70 lines (53 loc) · 3.25 KB
The board shows no signs of life when I plug in my USB power
  1. Try to use your PC (not a wall adapter)
  2. Try to use a different cable (try USB Type A-to-C instead of C-to-C)
  3. Unplug the battery and try again
  4. Make sure you didn't confuse sensor and encoder cables
  5. Try to disconnect every possible cable (sensors, encoders, battery, vibromotor)
  6. Inspect the motherboard for unexpected shorts if it was soldered by you
  7. If nothing helps, reach to the support with a high-res photo
The device turns on but my host doesn't see it
  1. Ensure the correct boot sequence — restart the device and observe the red LED. The normal behavior is two flashes, then off
  2. Disconnect both USB power and the battery, then plug back in and check
  3. Try to discover it with Bluetooth
  4. Make sure it doesn't show up as a flash drive — you need to flash the board in that case
  5. If nothing helps, inspect the board and reach to the support with a high-res photo
My buttons work but pointer doesn't

This indicates an issue with one or both sensors. You need to take a look at logs after device restart.
See the next item to learn how to read logs, and see FAQ.md to learn how to restart the device.

How to open and read logs?

Option 1 (beta): open Marshmellow UI and connect to the device
Option 2: follow the instructions from ZMK docs: https://zmk.dev/docs/development/usb-logging#viewing-logs

Pointer moves erratically, jumps and doesn't feel smooth

This indicates either ball incompatibility, or incorrect distance from the ball surface to the lenses.

  1. Make sure to try a standard (stock) red trackball with a reflective coating
  2. Check your bearings or BTUs — ensure they are inserted fully
  3. In case you are using BTUs, try the static bearings to see if it changes anything
  4. If nothing helps, install the debug firmware and open logs, it will allow you to see which sensor reports low surface quality
Pointer works in debug firmware but doesn't work with regular one

This indicates that only one of the sensors is functional. Please restart the device and open logs shortly after to learn which one is at fault.

Pointer works but is significantly off-axis (maybe even producing horizontal events when rolling vertically)

This indicates that one of the sensor boards is installed in an incorrect orientation. Please consult with the pictures in the assembly guide keeping attention to this aspect. Note that this statement is not relevant for the debug firmware.

One of the sensor reports "unexpected product id"

This typically indicates no electrical connection from the board to the sensor. Try re-seating the cable from both ends.

One of the sensor reports "failed self-test"

This typically indicates either bad electrical connection from the board to the sensor, or issues with soldering. Try re-seating the cable from both ends, and inspect the solder job.