sdrangel/plugins/feature/jogdialcontroller/readme.md

Jogdial Controller Feature Plugin

Introduction

This plugin aims at supporting frequency control via a "jog dial". A jog dial, jog wheel, shuttle dial, or shuttle wheel is a type of knob, ring, wheel, or dial which allows the user to shuttle or jog through audio or video media.

It is designed to support the Contour ShuttleXpress and ShuttlePro products but as it is keyboard keys based any device capable of reproducing the same key sequences (including a standard keyboard - see next) can interact with this plugin.

In the last section you will find details about the key sequences and placement of supported knobs on the ShuttleXpress and ShuttlePro.

Note that it is based on Qt keyboard events. These events are supported only for GUI applications therefore this plugin is not built in the server variant.

Interface

1: Start/Stop

Use this toggle to activate or deactivate the plugin. Note that for the control to be effective the plugin should also have the focus. You can check the focus state with the focus indicator (2)

2: Focus indicator

This indicator turns green if the plugin has focus. To set the focus on the plugin just click anywhere on it. The controls are effective only if the plugin has focus.

3: Refresh channels list

Use this button to refresh the list of available channels. It will scan through all the device sets presents in the instance to list their channels in the combo box next (4).

Note that on first start the list in (4) is empty therefore you must press this button right after the plugin is started with (1)

4: Select channel

Use this combo box to select which channel to control. The list item is formatted this way:

• R or T for a source (Rx) or sink (Tx) device set
• The sequence number of the device set
• The sequence number of the channel after the semicolon separator
• The type of channel

The frequency of the device of the device set the channel belongs to can also be controlled when device control is selected. The type of control is displayed in (5)

To select the type of control:

• Press K5 on the Contour device or ¨D" (shift+D) on the keyboard for device control
• Press K9 on the Contour device or ¨C" (shift+C) on the keyboard for channel control

5: Control type indicator

It displays "D" when in device control or "C" when in channel control mode.

Contour products and keyboard control

Contour devices

The Contour devices generally have a central "jog" wheel inside a spring loaded ring called the "shuttle" wheel plus a series of buttons.

ShuttleXpress layout

ShuttlePRO layout

The jog wheel is used to go up and down in discrete frequency units. You can use the Ctl and Shift keys on the keyboard simultaneously to select the frequency step:

• No key: ± 1 Hz for channels ± 1 kHz for devices
• Ctl key: ± 10 Hz for channels ± 10 kHz for devices
• Shift key: ± 100 Hz for channels ± 100 kHz for devices
• Ctl+Shift key: ± 1 kHz for channels ± 1 MHz for devices

The shuttle wheel has a central rest position and 7 positions on the left and 7 on the right. The left positions are used to go down in frequency and the right positions to go up. The frequency increments or decrements are sent every 100 ms as long as the shuttle position is maintained. It stops at rest (central) position. The further you go from the center the larger the frequency increment or decrement at each step. The amount is multiplied by 10 from one position to the next as you move away from the center. Thus to summarize:

• Center: rest position stops moving
• ± 1 step: moves ± 1 unit (1 Hz for channels, 1 kHz for devices)
• ± 2 steps: moves ± 10 units
• ± 3 steps: moves ± 100 units
• ± 4 steps: moves ± 1000 units (1 kHz for channels, 1 MHz for devices)
• ± 5 steps: moves ± 10000 units
• ± 6 steps: moves ± 100000 units
• ± 7 steps: moves ± 1000000 units (1 MHz for channels, 1 GHz for devices)

The keys are mapped as follows:

• K5: Select device control
• K6: Move down through the list of available channels
• K7: Reset the channel frequency (set to 0) - useful when you loose the channel out of the baseband window
• K8: Move up through the list of available channels
• K9: Select channel control

Mapping to keyboard and keyboard control

The contour devices proceed by mapping their events to keyboard events and this makes them very adaptable. The Jogdial Controller feature is keyboard event based so you may as well use your keyboard for control. In that case for better visual mapping it is recommended to use a US or US International keyboard.

Contour provides software to perform the mapping on Windows. You just need to install the driver software downloaded from Contour web site, open the support program and then follow instructions. You will have to specify the target program when you create the profile for SDRangel. This is sdrangel.exe located in C:\Program Files\SDRangel. Note also that the buttons are named differently but the program shows their location on an interactive diagram so this should be no problem to identify them correctly.

When running on Linux you may use ShuttlePRO for keyboard mapping. It will work also for the ShuttleXpress with minor changes. You will have to identify the path of the Shuttle device and run the program with the device path as argument in a terminal. See the last section for details.

Keyboard mapping

The shuttle devices controls are mapped according to the following table. K5 to K9 represent the shuttle keys. S-7 to S7 represent the shuttle (outer ring) positions S0 being the rest middle position. JL is a jog step to the left and JR a jog step to the right:

Shuttle	Keyboard	Key sequence (US)	Action
K5	D	Shift+D	Device control
K6	←	←	Select previous channel in list
K7	Home	Home	Reset channel frequency (set to 0)
K8	→	→	Select next channel in list
K9	C	Shift+C	Channel control
S-7	&	Shift+7	Continuous -1 MHz / -1 GHz move
S-6	^	Shift+6	Continuous -100 kHz / -100 MHz move
S-5	%	Shift+5	Continuous -10 kHz / -10 MHz move
S-4	$	Shift+4	Continuous -1 kHz / -1 MHz move
S-3	#	Shift+3	Continuous -100 Hz / -100 kHz move
S-2	@	Shift+2	Continuous -10 Hz / -10 kHz move
S-1	!	Shift+1	Continuous -1 Hz / -1 kHz move
S0	0	0	Stop continuous move
S1	1	1	Continuous +1 Hz / +1 kHz move
S2	2	2	Continuous +10 Hz / +10 kHz move
S3	3	3	Continuous +100 Hz / +100 kHz move
S4	4	4	Continuous +1 kHz / +1 MHz move
S5	5	5	Continuous +10 kHz / +10 MHz move
S6	6	6	Continuous +100 kHz / +100 MHz move
S7	7	7	Continuous +1 MHz / +1 GHz move
JL	↓	↓	Single -1/-10/-100/-1000 (Hz/kHz) move
JR	↑	↑	Single +1/+10/+100/+1000 (Hz/kHz) move

US keyboard mapping

Running the Contour devices in Linux

As briefly introduced earlier you may use ShuttlePRO for keyboard mapping.

The program will normally work as-is for ShuttlePRO. It will also work for ShuttleXpress with a few adaptations detailed next.

Firstly you need to add the proper udev rules that are slightly different. In fact you just need to change the "ATTR" line by:

ATTRS{name}=="Contour Design ShuttleXpress" MODE="0644"

Secondly the device path is different for ShuttleXPress. You have to look for your device in the path starting with /dev/input/by-id/usb-Contour_Design_ In most cases this will be: /dev/input/by-id/usb-Contour_Design_ShuttleXpress-event-if00

You will then use this path as argument to the shuttlepro program:

shuttlepro /dev/input/by-id/usb-Contour_Design_ShuttleXpress-event-if00

You may change the argument in the shuttle script for convenience:

exec shuttlepro /dev/input/by-id/usb-Contour_Design_ShuttleXpress-event-if00

In any case you need to specify the mapping in the ~/.shuttlerc file by adding a section for SDRangel like this:

[SDRangel]
 K5 "D"
 K6 XK_Left
 K7 XK_Home
 K8 XK_Right
 K9 "C"

 S-7 XK_Shift_L/D "7"
 S-6 XK_Shift_L/D "6"
 S-5 XK_Shift_L/D "5"
 S-4 XK_Shift_L/D "4"
 S-3 XK_Shift_L/D "3"
 S-2 XK_Shift_L/D "2"
 S-1 XK_Shift_L/D "1"
 S0 "0"
 S1 "1"
 S2 "2"
 S3 "3"
 S4 "4"
 S5 "5"
 S6 "6"
 S7 "7"

 JL XK_Down
 JR XK_Up