Adding USB Joysticks or Other USB Controllers

This section describes how to set up a USB joystick or other USB controller to select and control supported PTZ cameras, in conjunction with the DashBoard PTZ Camera Control plugin.

Camera functions that can be controlled by a USB controller fall into three groups; camera selection, camera motion (pan, tilt, zoom, and focus), and paintbox controls (lens iris and shading/paint controls). Depending on the USB controller(s) available, you can control all functions with a single controller, or add a separate controller for each group of functions.

You can also configure otherwise unassigned buttons on the controller to open DashBoard device views or panels.

The main steps are as follows:

• “Add a USB Controller in DashBoard”
• “Add Device Classes, and Map Controls to Parameters”
• “Map Device Classes to Controllers”
• “Configure Relationship Between Camera Selection and UI Focus”
• “Map Buttons for Camera Selection”

Add a USB Controller in DashBoard

To add a USB controller to control PTZ cameras :

1. Close DashBoard.

2. Plug the USB controller into a USB port on the DashBoard computer.

3. Start DashBoard.

   When DashBoard starts, it detects the controller.

   tip

   DashBoard can detect the controller only if the controller is plugged in when DashBoard starts.

4. In DashBoard, on the File menu, select New, and then select Other .

   The New dialog box appears (Figure ??).

   

   Figure 1 - Adding a USB controller

5. In the Wizards list, expand Input Devices , select New Game Controller , and then tap Next .

   The New Game Controller Connection dialog box appears (Figure ??).

   

   Figure 2 - Connecting to a USB controller

6. In the Display Name box, type a name for the controller.

7. In the Controller list, select the type of USB controller you plugged in.

   note

   If the controller type is not on the list, either it was not detected or it is already registered in DashBoard.

8. Click Finish .

   A node for the controller appears within the Game Controllers node in the DashBoard Component Tree . The node has the name you provided for the controller.

Add Device Classes, and Map Controls to Parameters

A USB controller typically has buttons and axis controls. A button is either on or off, and therefore returns one of two data values. An axis control, such as a joystick, can return any value within a range of data values, depending on how far the joystick is moved in one direction or the other.

You can configure each axis control on the USB controller to operate a robotic axis, or operate a control that accepts a continuous range of data values, such as a Master Black paint control.

Additionally, you can configure buttons to return single values. For example, if you often want to pan right or left at half speed, you can configure one button to return a value of -50 while pressed, and another to return a value of 50 (pan axis range is -100 to 100).

This section describes how to map a wide variety of commonly-used axis controls and button controls. You can decide which controls you want to map, based on your preferences and the available physical controls on your USB device(s).

To add device classes, and map controls to DashBoard parameters (OIDs):

1. In the DashBoard Component Tree , expand the Game Controllers node, and then double-tap the controller node you added.

   The configuration interface for the controller appears (Figure ??). The ptzjoystick Device Class is present by default.

   

   Figure 3 - Mapping USB controller inputs (shown with Device Classes added and OIDs mapped)

2. Tip : The number and types of axis controls and buttons vary between different models of USB controllers.

3. In the Device Classes list, add a new device class and name it paintbox .

4. In the Device Classes list, add a new device class named selector .

5. In the Axis Controls table, create mappings for the velocity parameters that you want the USB controller’s axis controls (such as joysticks) to operate.

   When you create mappings, you link data items reported by the controller to parameters (OIDs) in the PTZ Camera Control plugin.

   tip

   To determine which Axis Controls and Buttons correspond to physical controls on the controller, move the controller’s joystick and push its buttons while observing changes in the Value column.

   Relevant columns in the Axis Controls mapping table are as follows:

   • ID — The ID of the control, as reported by the controller. This is not configurable.

   • Name — You can name each control for future reference (optional).

   • Min and Max - Defines the range of data values sent to the DashBoard parameter. When the control is in a neutral position, the data value is halfway between Min and Max . For example, if Min is -100 and Max is 200 , the neutral value is 50 .

     tip

     DashBoard automatically scales the data value to suit the data range of the associated parameter. You do not need to match Min and Max to the lowest and highest parameter values.

   • Speed% — Scales the data values, to make them change more or less gradually. For example, if you use a joystick to control a paint velocity parameter such as paintbox.vel.whitebalance.gain.r , you might set Speed % to 10 . When you push the joystick all the way, the value changes at one-tenth the default rate. This enables you to see the effect more easily as you change the value.

   • Sensitivity — Defines the number of steps between each end of the data range and the controller’s neutral position. For example, if Min is -100 , Max is 100 , and Sensitivity is 20 , then the value changes by increments of 5 . The range of values starts at - 100 (-100 , -95 , -90 , etc.) and continues to 100 .

   • Invert — When selected, reverses the direction of joystick motion required to move the axis. For example, if the camera is ceiling mounted, select Invert for pan and tilt so when you move the joystick, the camera moves as desired.

   • Value — Shows the current data value reported by the controller. This is useful for testing.

   • Mapped OID — Specify the parameter OID from the PTZ Camera Control plugin to be mapped to the control.

     Table ?? lists parameters that are commonly mapped to axis controls.

Table 1 - - Parameters that are commonly mapped to axis controls

Parameter (Mapped OID)	Description
ptzjoystick.vel.tilt	Tilt axis velocity
ptzjoystick.vel.pan	Pan axis velocity
ptzjoystick.vel.zoom	Zoom axis (lens zoom) velocity
ptzjoystick.vel.focus	Focus axis (lens focus) velocity
paintbox.vel.shutter.preset	Shutter control velocity
paintbox.vel.iris.control	Iris axis (lens iris) velocity
paintbox.vel.whitebalance.gain.b	Blue Gain paint control velocity
paintbox.vel.whitebalance.gain.r	Red Gain paint control velocity

2. In the Buttons table, create mappings for the parameters that you want the USB controller’s buttons to operate.

   When you create mappings, you link data items reported by the controller to parameters (OIDs) in the PTZ Camera Control plugin.

   tip

   To determine which Axis Controls and Buttons correspond to physical controls on the controller, move the controller’s joystick and push its buttons while observing changes in the Value column.

   For an example showing the Buttons mapping table completed, see Figure 3,

   Relevant columns in the Buttons mapping table are as follows:

   • ID — The ID of the control, as reported by the controller. This is not configurable.
   • Name — You can name each control for future reference. (optional).
   • Action — The type of action to be performed when the button is pressed.
   • Value (Off) — This is the value of the parameter when the button is not pressed.
   • Value (On) — This is the value of the parameter when the button is pressed.
   • Value — Shows the current data value reported by the controller. This is useful for testing.
   • Mapped OID — Specify the parameter OID from the PTZ Camera Control plugin to be mapped to the control.
   tip

   If you are configuring multiple controllers and dividing the control functions among them, the controls within each device class must be assigned to a single controller. The name of each parameter OID starts with the name of its device class (selector , ptzjoystick , or paintbox ).

   Table ?? lists parameters that are commonly mapped to button controls.

   note

   The values required for some mappings may vary between camera models.

Table 2 - - Parameters that are commonly mapped to button controls

Parameter (Mapped OID)	Description
selector.selection	Camera selection, for systems that include multiple cameras. Map this parameter to a set of buttons to be used for selecting the camera to be controlled. Each row in the Buttons table corresponds to a button on the controller. For each button you want to assign as the selector for a camera, do the following: In the Name column, assign a camera name for future reference (optional). Set Action to Set Value. Set Value (Off) to -1 Set Value (On) to a unique camera ID number (For example, 0, 1, 2, 3, etc.). The actual ID number is arbitrary. Note the camera ID numbers. You will later map this ID number to the camera’s remote control DashBoard interface.
ptzjoystick.focus.auto_on	Auto focus mode. Configure a button to toggle auto focus on and off. To map ptzjoystick.focus.outo_on: Set Action to Toggle. Set Value (On) to 2. Set Value (Off) to 3.
ptzjoystick.focus.onepush.trigger	Enables a button on the controller to perform a one-time auto focus. To map ptzjoystick.focus.onepush.trigger: Set Action to Set Value. Set Value (Off) to 0. Set Value (On) to 1. Note: Focus mode must be set to One Push Auto Focus. For more information, see “Focus Controls”.
paintbox.autoexposure.mode	Auto exposure mode. Configure a button to toggle between values for two modes: 0 — Full Auto mode 3 — Manual mode 10 — Shutter Priority mode 11 — Iris Priority mode To map paintbox.autoexposure.mode: Set Action to Toggle. Set Value (Off) to the value for one mode. Set Value (On) to the value for another mode. For more information about auto exposure modes, see “Exposure Controls”.
paintbox.whitebalance.mode	White balance mode. Configure a button to toggle between values for two modes: 0 — Auto mode 3 — One Push mode 5 — Manual mode To map paintbox.whitebalance.mode: Set Action to Toggle. Set Value (Off) to the value for one mode. Set Value (On) to the value for another mode. For more information about white balance modes, see “Color Controls”.
paintbox.whitebalance.onepush.trigger	White balance one-push trigger. To map paintbox.whitebalance.onepush.trigger: Set Action to Set Value. Set Value (Off) to 0. Set Value (On) to 1. Note: White balance mode must be set to One Push. For more information, see “Color Controls”.
paintbox.shutter.preset	Shutter control. Configure one button to increase the value and another to decrease it: For both buttons, set Action to Increment. For the button that increases the value, Set Value (On) to 1, and set Value (Off) to 0. For the button that decreases the value, Set Value (On) to -1, and set Value (Off) to 0.
paintbox.iris.control	Iris control. Configure one button to increase the value and another to decrease it: For both buttons, set Action to Increment. For the button that increases the value, Set Value (On) to 1, and set Value (Off) to 0. For the button that decreases the value, Set Value (On) to -1, and set Value (Off) to 0.
paintbox.whitebalance.gain.b paintbox.whitebalance.gain.r	Green Gain paint control (paintbox.whitebalance.gain.g), Blue Gain paint control (paintbox.whitebalance.gain.b), and Red Gain paint control (paintbox.whitebalance.gain.r). For each of these three parameters, configure one button to increase the value and another to decrease it: For both buttons, set Action to Increment. For the button that increases the value, Set Value (On) to 1, and set Value (Off) to 0. For the button that decreases the value, Set Value (On) to -1, and set Value (Off) to 0.
camera.wiper camera.washer	Wiper (camera.wiper) and Washer (camera.washer) controls. For each parameter, configure a button: Add device class “camera”. Set Action to Set Value. Set Value(On) to 1 and set Value (Off) to 0. Note: The washer moves 4 times with every use.

2. If you want to save the mappings in a file that can be loaded onto other DashBoard computers, click the SAVE button and specify a file name and path.

   note

   The mappings are specific to the controller(s) you configured. You can use the mappings on other DashBoard computers only if their controllers are the same model, or report the exact same controls.

Map Device Classes to Controllers

Camera functions that can be controlled by a USB controller fall into three groups; camera selection, camera motion (pan, tilt, zoom, and focus), and paintbox controls (lens iris and shading/paint controls). Depending on the USB controller(s) available, you can control all functions with a single controller, or add a separate controller for each group of functions.

To map device classes to one or more controllers:

1. In the Component Tree , within the DashBoard Services node, double-tap Device Class Mappings .

   The Device Class Mappings interface appears (Figure ??).

   

   Figure 4 - Device Class Mappings for a USB controller

2. If you plan to use the controller to adjust lens iris, in the paintbox row set Selected Device to the controller you are configuring.

   tip

   If a class you want to map is already mapped, click Clear Selection and then map it to the controller.

3. If you plan to use the controller to move cameras (pan, tilt, zoom, focus), in the ptzjoystick row set Selected Device to the controller you are configuring.

4. If you plan to use buttons on the controller to select cameras in the PTZ Camera Control plugin, in the selector row set Selected Device to the controller you are configuring.

Configure Relationship Between Camera Selection and UI Focus

You can configure how the user interface interacts with the controller, to achieve your choice of the following options:

• The controller can select and control cameras ONLY IF PTZ Camera Control is the active DashBoard application (in focus).
• The controller can controller to select and control cameras regardless of what DashBoard application is active (in focus).
• If a controller button configured to open a device view or panel is pushed, that device view or panel becomes active (in focus)

To configure the relationship between camera selection and UI focus:

1. In the Component Tree , expand the DashBoard Services node, and then double-tap Selector UI Mappings .

   The Selection Mapping interface appears (Figure ??).

   

   Figure 5 - UI Follow and Autowire settings

2. Choose one of the following options and tap the corresponding button:

   • Autowire Follows UI ON

     If you select this option, you cannot use the controller to select and control cameras unless the PTZ Camera Control plugin is the active DashBoard application (in focus).

     This option helps prevent accidental movement of cameras while the operator is using other DashBoard panels or device views. It also ensures that the PTZ Camera Control plugin is always readily available while you are controlling cameras.

   • UI Follows Selection OFF

     If you select this option, you can use the controller to select and control cameras regardless of which panel or device view is active (in focus).

     This option enables you to use the PTZ Camera Control plugin and other DashBoard panels or device views for other tasks while you use the controller to select and control cameras.

   • UI Follows Selection ON

     If you select this option, whenever a configured button opens a DashBoard panel or device view, that panel or device view becomes active (in focus). If the PTZ Camera Control plugin is active and you press a controller button to open a different panel or a device view, the PTZ Camera Control plugin loses focus.

     Use this option if you want to configure otherwise unassigned controller buttons to open DashBoard panels and device views on demand, such as Carbonite control, or the PTZ Camera Control plugin.

Map Buttons for Camera Selection

This procedure applies if your system has multiple cameras and you want to configure controller buttons to select them.

To map camera selector buttons:

1. In the Selection Mapping interface (Figure ??), tap the Add Mapping button.

   A new mapping row appears in the Selection Mapping table.

   

   Figure 6 - Mapping cameras to camera selector buttons

2. In the new mapping, set ID to the camera ID number for a camera. Each mapping requires a unique ID.

   tip

   You defined the camera ID numbers as Value on settings for buttons, in a previous procedure (“Add Device Classes, and Map Controls to Parameters”).

3. Specify a Name for the mapping (optional).

4. For UI Primary Identifier , navigate to Remote Control for the camera to be selected.

5. Repeat the preceding steps for each camera selector button you want to configure.

6. If you want to save the mappings in a file that can be loaded onto other DashBoard computers, click the SAVE button and provide a file name and path.