The Control Presets Tab
- Marc Lievin
The Control Presets tab allows you to create and edit device mapping presets.
A preset contains a reference to a control interface and a list of device mappings. A device mapping contains a list of field mappings between control interface fields and device fields.
All control interfaces loaded from content are listed here.
Select the desired control interface to map it to one or multiple devices.
When a control interface is selected, the default preset will be shown. It cannot be edited.
If there is a preferred control preset set for that control interface, it will show up as well.
The selected preset tab is the active one, i.e., the one that is currently mapped to the shown devices. The other presets are inactive.
List of Control Interface fields. A Control Interface has two categories of fields:
The Input fields (From Device category). The control interface input fields are mapped to the device output fields.
The Output fields (To Device category): The control interface output fields are mapped to the device input fields.
The Preset Management toolbar contains the following:
Add (or modify) a device mapping script to an existing preset. This will display the Device Mapping Script dialog.
Remove a device mapping script from an existing preset.
Duplicates an existing preset.
Creates an empty preset.
Saves the active preset.
Note: To remove a preset, its file must be manually deleted from the ControlPresets subfolder in the application’s Data Store and the application needs to be restarted.
List of all connected devices in the simulator.
Select a device from the list of connected devices and click on the Map Device button. This will append a device mapping column to the current preset.
Select a device from the list of connected devices and click on the Device Deadband Detection button. The Device Deadband Detection dialog will guide you through the deadband detection process.
Map a control interface input field to a device output field by selecting device output field from the first combo box. When Automatic mapping is enabled, you can select a field mapping cell and press a button (or move an axis) on the device to set the mapping automatically. If the control interface field was already mapped to a device button, the new mapping will overwrite the previous one. To remove a field mapping, select the field mapping cell and hit the DEL key on the keyboard. Once the primary device output field is set, the second combo box can be used to select an optional modifier (typically a button). With a modifier, the primary device output field’s value is only applied if the modifier is active.
The Current Value column displays the device field value when pressing a button or moving an axis.
The Calibrate button
allows you to calibrate the device field that is mapped to the current mapping cell. The Device Mapping Calibration dialog is displayed.
Map a control interface output field to a device input field. For example, a device input field could be a light on the device. The combo box displays a list of device input fields to be mapped to the control interface output fields. To remove a field mapping, select the -- entry in the combo box.
Click the
button to add a new field mapping row. This allows you to map more than one device field to the same control interface field.
To remove a field mapping row, make sure to first remove all device mappings on that row, and click the
button.
Click the Preferred Preset icon
to make a preset the "preferred" one. Check the Set Preferred icon
to remove the preferred preset setting. Only one control preset can be preferred.
Note that, for convenience, a control interface always has a default preset, but that default preset cannot be set as the "preferred" preset.Preset tabs
Click on a tab to change the active preset.
Click the selected tab to rename the preset.
A modified preset will have an asterisk (*) after its name until it is saved.
Click the menu button
to reassign a device (from among all connected devices), or to delete a device mapping from the current preset.
Once all your control interfaces are mapped to your liking, deselect Enable preset editing. Leaving it enabled could affect simulation performance.
Device Mapping Calibration
The Device Calibration Dialog is used to modify the transfer functions of the device output fields.
Device Mapping Script
The Device Mapping Script dialog is used to specify an optional Python3 script for more complex device mapping scenarios.
Specify the Python3 script path.
Use the buttons in this section to add input fields for the device mapping script. Each row describes an input field.
to add a row
to remove a row
to move a row up
to move a row down
This column is used to choose a source for the field that will connect to a device mapping script’s input field. The source can be one of the preset’s mapped devices or the preset's selected control interface.
This column is used to choose the field from the specified source. The field can be a device output field or a control interface (“To Device”) output field.
Use the buttons in this section to add output fields for the device mapping script. Each row describes an output field.
to add a row
to remove a row
to move a row up
to move a row down
This column is used to choose a source for the field that will connect to a device mapping script’s output field. The source can be one of the preset’s mapped devices or the preset's selected control interface.
This column is used to choose the field from the specified source (a device input field or a control interface (“From Device”) input field).
Press OK to accept the modifications, Cancel to exit without making any changes.
It is possible to map identical fields in both the standard device mappings and in the device mapping script. This situation may lead to unexpected outcomes since one will overwrite the target field that the other intends to modify.
Device Mapping Script’s Python3 Code
Refer to Setting the Python Interpreter if needed.
Accessing Device Mapping Script Fields
The device mapping script can have input or output fields. These fields are in sub-containers named with the field's source name or destination name.
Input Fields
To retrieve an input field, use extension.getInputContainer()[<source_name>][<field_name>] where <source_name> is the field’s source and <field_name> is the field’s name.
extension.getInputContainer()['XInput Controller 0']['AxisX']Output Fields
To retrieve an output field, use extension.getOutputContainer()[<destination_name>][<field_name>] where <destination_name> is the field’s destination and <field_name> is the field’s name.
extension.getOutputContainer()['ControlInterface']['Throttle']Read or Write Field Values
Remember to use the field’s value property to read or write to a field (e.g. output_field.value = input_field.value, where input_field and output_field are previously retrieved fields).
Callbacks for a Device Mapping Script
Good Practice
In any given script, if a callback is not needed, it is more efficient to simply remove it. In the template below, all callbacks are not doing anything but using the statement “pass”.
Just having any Python callback defined means it will be invoked by Vortex when needed. If the callback is not present, Vortex will be more efficient.
Removing all callbacks that do no effective changes is good practice.
Template
import Vortex
"""Please remove any functions that are not needed.
It is more efficient as the simulation will not invoke a non-existing function rather then using Python to invoke an empty function.
"""
def on_initialize_mapping(extension):
""" Called after the DeviceMappingScript extension was added or modified.
Use this method to define specific actions that must be taken when intializing.
Parameters
----------
extension : object
The DeviceMappingScript extension referring to this script.
"""
pass
def on_uninitialize_mapping (extension):
""" Called before the DeviceMappingScript extension is modified or removed.
Use this method to define specific actions that must be taken when unintializing.
Parameters
----------
extension : object
The DeviceMappingScript extension referring to this script.
"""
pass
def on_update_mapping(extension):
""" Called for each frame of the simulation.
Use this method to get inputs and set outputs.
Parameters
----------
extension : object
The DeviceMappingScript extension referring to this script.
"""
pass