Skip to main content

ThumbsUp! Trackball v4: ZMK.Studio Key Layout

ThumbsUp! Trackball v4 supports ZMK.Studio for the button configuration.

ZMK.Studio Connection

To connect to ZMK.Studio: 
- connect trackball to computer with USB cable, 
- in the Internet Browser navigate to https://zmk.studio/

A prompt will be shown:

 Select USB, device selection window will open:


Select Trackball v4, click Connect.
Note that some applications may intercept COM ports (e.g. Cura 3D Slicer) and prevent ZMK connection to that device, showing an error message. Close all apps that may work with COM ports and try again.

A prompt to unlock the device should/may appear, this is a ZMK security feature, protecting the trackball from the unauthorized re-configuration by malicious software:


You need to press once a metal button labeled UNLOCK (or ZMK.Studio, depending on the board revision) on the middle board:


After that ZMK.Studio screen should appear:

To configure button - select layer, then the key, and then pick the desired action for that key:


Changes are applied immediately.

Buttons v. Switches  

DO NOT MODIFY THE TWO BOTTOM ROWS OF KEYS!

Slider switches and service buttons on the middle PCB could be redefined with ZMK.Studio.
It is a good idea to leave them as they are.

Slider switches define layer for buttons: normal (USB away from you) or backward (USB cable towards you), hand the trackball is used with, and the ball behavior - whether it should be treated as pointer move or scrolling. See below for the layer definition.

Metal buttons are used for pre-defined actions:
RESET is hardwired to put the device in the bootload mode, to flash the firmware.
UNLOCK sends a special command to unlock ZMK.Studio as described above.
BT NEXT switches to the next Bluetooth profile, there are three profiles to use the trackball with three different computers. This button switches between those three defices.
BT RESET clears the current Bluetooth profile, making the device to forget computer associated with that profile.



Layers

Layers are used to define the trackball orientation, hand the ball is used with which are used - slider switches on the back of the device are 

0, FRONT_RIGHT - Mouse is held with right hand, USB port points away from you
1, FRONT_LEFT - Mouse is held with left hand, USB port points away from you
2, BACK_RIGHT - Mouse is held with right hand, USB port points towards you
3, BACK_LEFT - Mouse is held with left hand, USB port points towards you

4, FRONT_SCROLL - Mouse is held with right hand, USB port points towards you
5, BACKWARD_SCROLL 

First four layers are controlled by the configuration slider switches on the back of the trackball.
Scrolling layers are turned on momentarily by holding one of the keys:


You probably need to restrict button definition to one of the layers 0..3 - the one that fits your slider switch positions.

Mouse Key Configuration

Unfortunately, ZMK.Studio does not show mouse buttons labels:


Definition of the mouse keys appears only when specific button is selected:



Mouse key labels include: 

DefineAction
MB1, LCLKLeft click
MB2, RCLKRight click
MB3, MCLKMiddle click
MB4Mouse button 4, in Internet Browsers it is usually Forward
MB5Mouse button 5, Backward

Trackball Reset

You can always revert the trackball to its default configuration by re-flashing its firmware.
For that:
- download two UF2 files to your computer from here:
    https://github.com/ak66666/ThumbsUp-Trackball-v4/tree/main/firmware.working
- connect trackball to the computer with USB cable
- press RESET button on the middle PCB.
- a new drive should appear in the system.
- copy file "a_ball-nice_nano_v2-zmk.uf2" to that drive.
- device will restart and the default button layout.
- Bluetooth connections should be preserved.

Troubleshooting

If the device misbehaves, e.g. is unable to connect to BT, try flash file "settings_reset-nice_nano_v2-zmk.uf2" using the steps mentioned above, then re-flash "a_ball-nice_nano_v2-zmk.uf2" again.
All Bluetooth configuration will be erased, you will need to re-connect trackball to Bluetooth.

Comments

Post a Comment

Popular posts from this blog

ThumbsUp! Trackball v3/v5 Assembly Steps

I designed a trackball, two versions actually, which differ in the switches used V3 with Kailh Choc switches: https://github.com/ak66666/ThumbsUp-Trackball-v3 V5 with Omron micro-switches: https://github.com/ak66666/ThumbsUp-Trackball-v5-Omron Assembly steps are quite the same, except for the switches. The original article version described v3, steps specific for v5 are added in the end. I sell the PCBs on Etsy: https://www.etsy.com/ca/listing/4367668734/thumbsup-trackball-v3-pcbs-for-dyi In this post I show the process of building the board. Bill of Materials To assemble you will need to obtain the following parts: 1x PMW3610 sensor and lens (https://www.aliexpress.com/item/1005007118767775.html) 1x Nice!nano v2 (or clone) (https://www.aliexpress.com/item/1005006074191337.html) This will give you a Bluetooth-connected device. You may add another nice!nano to make a USB dongle . 1x 34mm ball (https://www.aliexpress.com/item/1005007857787050.html) 1x 3.7V 110mAh 301230 Lithium Polymer...
Post a Comment
Read more

ThumbsUp! Trackball v3/5, v4 Usage

ThumbsUp! Trackball comes in three versions, v3 (the bottom one), v5 (top left) and v4 (top right): https://github.com/ak66666/ThumbsUp-Trackball-v3 https://github.com/ak66666/ThumbsUp-Trackball-v4 https://github.com/ak66666/ThumbsUp-Trackball-v5-Omron Trackball v3 and v5 Versions v3 and v5 have the same layout, six mouse buttons in each, plus configuration buttons and three slider switches. The only difference between them is the switch types they use: Kailh Choc in v3 and regular mouse-type buttons Omron in v5,  These two versions can be used as thumb- or finger-operated with either left or right hand. Two slide switches define device orientation and hand it is used with: In thumb-operating mode index finger presses left button, middle finger - middle button, and ring finger - right button, this configuration is kept in all device positions (configured through switches shown above) : Trackball v4 v4 got two more buttons and it uses Kailh Choc switches. In v4 the orientation switc...
Post a Comment
Read more

Adding a Touchpad

  Updated:   Jun 5 The unibody ThumbsUp! keyboards support ProGlide Cirque touchpads. Cirque touchpad fits nicely under the top PCB and are not visible from outside, so here its picture sticking out, not yet glued to the top PCB:     There are tracks leading to a connector on the top board. (Add it to the order and let me know if you want the connector to be installed, provided I have them in stock.)     You'd need to buy these two parts from Mouser (or any other vendor): Mouser #: Mfr. #: Desc.: 355-TM0400402024-301 TM040040-2024-301 Capacitance Touch Sensor Modules Capacitance Touch Sensor Modules 40mm Round SPI/I2C adhesive overlay 538-15166-0125 15166-0125 FFC / FPC Jumper Cables FFC / FPC Jumper Cables FFC 0.50 Type A 12 ckts lgt 127   Touchpads need to be modified: R1 needs to be removed to use I2C the boards support:   For the ProMicro and Atmel32U4-based keyboards the touchpad also needs to be made t...
Post a Comment
Read more