Version 0
SmartShift
This feature exposes and configures the smart shift enhanced functionality on a 3G wheel.
Overview
The presence of this feature indicates that the device has an inertia scroll wheel with motor driven ratchet engagement. This ratchet can be configured to engage or disengage depending on wheel speed, a user button press, or via software control.
There are two different wheel modes, known as freespin and ratchet. In freespin mode the ratchet is never engaged and the wheel is always free to spin. In ratchet mode the ratchet engagement depends on the wheel speed. The wheel speed at which disengagement happens is configured by the "autoDisengage" parameter. Setting autoDisengage to 0xFF causes the ratchet to stay engaged while in ratchet mode.
When the wheel speed exceeds the speed threshold causing the ratchet to disengage it will remain disengaged as the wheel slows down and stops. Only when the user moves the wheel again at a speed slower than the threshold speed will the ratchet reengage.
The wheel mode can be changed either by the user pressing a ratchet control button or by the software setting the mode in response to a UI action or a change in users. In either of these cases the firmware should engage or disengage the ratchet immediately. The wheel mode is stored persistently in the device’s nonvolatile storage.
A ratchet control button is an undiverted 0x1B04 button with CID 196 (SmartShift) or a button remapped to a CID 196 (SmartShift) button via 0x1B04. Diverting a ratchet control button to SW via 0x1B04 or remapping it to another button effectively disables it from acting as a ratchet control button.
The 0x2121 HiResWheel feature already reports mechanical ratchet engagement state and user activation. Since it is not useful for host software to know transient ratchet states, the 0x2121 HiResWheel feature will instead report the wheel mode of this feature. During the time the ratchet is disengaged due to smartshift the 0x2121 feature will continue to report it as engaged. The 0x2121 feature should generate a ratchet change event when the wheel mode is changed either by a user button press or by software calling setRatchetControlMode to change it.
The default out of box settings are:
-
wheelMode = ratchet
-
autoDisengage = 16
-
autoDisengageDefault = 16
The autoDisengageDefault value is stored persistenly in the device’s non volatile storage.
On HID reset the autoDisengage setting will be set to the persistent
autoDisengageDefault value and the ratchet control button will be configured to
toggle the wheel mode when pressed. A HID reset will not change the wheel
mode or the autoDisengageDefault value.
The persistent autoDisengageDefault value can be changed by software.
Functions and Events
[0] getRatchetControlMode() → wheelMode, autoDisengage, autoDisengageDefault
Returns the current smartshift configuration.
Parameters
None
Returns
- wheelMode
-
Returns the current wheel mode
1 = Freespin mode 2 = Ratchet mode (smartshift and fixed ratchet)NoteThis value is not the state of the ratchet engagement. While the ratchet is in the autoDisengaged state the wheelMode is still ratchet mode. - autoDisengage
-
Returns the speed at which the ratchet automatically disengages
0x01-0xFE = Disengage when wheel rotation exceeds N/4 turns per second 0xFF = Ratchet always engaged - autoDisengageDefault
-
Returns the default value of the autoDisengage setting
0x01-0xFE = Disengage when wheel rotation exceeds N/4 turns per second 0xFF = Ratchet always engaged
| byte \ bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
0 |
wheelMode |
|||||||
1 |
autoDisengage |
|||||||
2 |
autoDisengageDefault |
|||||||
[1] setRatchetControlMode(wheelMode, autoDisengage, autoDisengageDefault) → wheelMode, autoDisengage, autoDisengageDefault
Sets the wheel mode and configures the automatic disengage setting.
Setting the wheel mode by writing a nonzero value will cause the ratchet engagement motor to activate as needed to immediately put the ratchet in the requested state. Writing zero (0 = do not change) to the wheel mode value will not activate the motor.
Changing the autoDisengage or autoDisengageDefault values will not activate the motor.
Parameters
- wheelMode
-
Sets the current wheel mode. Note that the wheel mode can also be changed by the user pressing the ratchet control button.
0 = Do not change 1 = Freespin mode 2 = Ratchet mode (used for smartshift and fixed ratchet) - autoDisengage
-
Sets the speed at which the ratchet automatically disengages. This setting has no effect if the wheel mode is freespin. If the wheel mode is ratchet, setting autoDisengage to 0xFF immediately engages the ratchet.
0x00 = Do not change 0x01-0xFE = Disengage when wheel rotation exceeds N/4 turns per second 0xFF = Ratchet always engaged - autoDisengageDefault
-
Sets the default value of the autoDisengage setting. When the device is reset the autoDisengage setting will be set to this value.
0x00 = Do not change 0x01-0xFE = Disengage when wheel rotation exceeds N/4 turns per second 0xFF = Ratchet always engaged
| byte \ bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
0 |
wheelMode |
|||||||
1 |
autoDisengage |
|||||||
2 |
autoDisengageDefault |
|||||||
Returns
On success, the parameters are echoed back as the return value.
| byte \ bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
0 |
wheelMode |
|||||||
1 |
autoDisengage |
|||||||
2 |
autoDisengageDefault |
|||||||
Suggested host software behaviour
When this feature is present, the software will present 2 drop down lists and a slider to the user:
-
Drop down list labeled "Smartshift", with settings "Enabled" or "Disabled"
-
Slider labeled "Smartshift Threshold"
-
Drop down list labeled "Default Wheel Mode", with settings "Ratchet" or "Freespin"
The default software UI settings are smartshift "Enabled" and default wheel mode "Ratchet".
Related to this feature is 0x1B04 control ID 196 (Smartshift). If a button with this control ID is left undiverted or a button is remapped to this control ID, then a ratchet mode button is assigned.
When the user changes any of the three UI settings described above or assigns or deassigns a ratchet control button, the two output values from the following table are sent to the device. Switching to another user session with different settings has the same effect.
| ratchet control button is assigned | smartshift setting | default wheel mode setting | wheelMode output | autoDisengage output |
|---|---|---|---|---|
yes |
enabled |
--- |
0 (unchanged) |
slider value |
yes |
disabled |
--- |
0 (unchanged) |
0xFF (engaged) |
no |
enabled |
--- |
2 (ratchet) |
slider value |
no |
disabled |
ratchet |
2 (ratchet) |
0xFF (engaged) |
no |
disabled |
freespin |
1 (freespin) |
0x00 (unchanged) |
ChangeLog
-
Version 0: Initial version