SkyCtrl3Gamepad
public protocol SkyCtrl3Gamepad : Peripheral
Gamepad peripheral for skyCtrl3
remote control devices.
This peripheral allows:
- To receive events when physical inputs (buttons/axes) on the device are triggered.
- To configure mappings between combinations of physical inputs and predefined actions to execute or events to forward to the application when such combinations are triggered.
To start receiving events, a set of SkyCtrl3Button
and SkyCtrl3Axis
must be grabbed and
and some event listener has to be provided.
When a gamepad input is grabbed, the remote control will stop forwarding events associated to this input to the connected drone (if any) and instead forward those events to the application-provided listener.
Each input may produce at least one, but possibly multiple specific events, which is documented in
SkyCtrl3Button
and SkyCtrl3Axis
.
To stop receiving events, the input must be ungrabbed, and by doing so the remote control will resume forwarding
that input events back to the connected drone instead, or, if the VirtualGamepad
was grabbing navigation events,
it will receive again the navigation events.
Alternatively the application can unregister its event listeners to stop receiving events from all grabbed inputs altogether. Note, however, that doing so does not release any input, so the drone still won’t receive the grabbed input events.
To receive input events, the application must register some listener to which those event will be forwarded. Event listeners come in two kind, depending on the event to be listened to:
- A
(_ event: SkyCtrl3ButtonEvent, _ state: SkyCtrl3ButtonEventState) -> Void
that receives events from inputs producingSkyCtrl3ButtonEvent
events. This listener also provides the physical state of the associated input, i.e. whether the associated button is.pressed
or.released
. Note that physical axes produce a button press event every time they reach the start or end of their course, and a button release event every time they quit that position. - A
(_ event: SkyCtrl3AxisEvent, _ value: Int) -> Void
that receives events from inputs producingSkyCtrl3AxisEvent
events. This listener also provides the current value of the associated input, i.e. an int value in range [-100, 100] that represents the current position of the axis, where -100 corresponds to the axis at start of its course (left for horizontal axes, down for vertical axes), and 100 represents the axis at end of its course (right for horizontal axes, up for vertical axes).
A mapping defines a set of actions that may each be triggered by a specific combination of inputs events (buttons, and/or axes) produced by the remote control. Those mappings can be edited and are persisted on the remote control device: entries can be modified, removed, and new entries can be added as well.
A SkyCtrl3MappingEntry
in a mapping defines the association between such an action, the drone model on which
it should apply, and the combination of input events that should trigger the action.
Two different kind of entries are available:
- a
SkyCtrl3ButtonsMappingEntry
entry allows to trigger aSkyCtrl3ButtonsMappableAction
when the gamepad inputs produce some set ofSkyCtrl3ButtonEvent
in the.pressed
state. - a
SkyCtrl3AxisMappingEntry
entry allows to trigger anSkyCtrl3AxisMappableAction
when the gamepad inputs produce someSkyCtrl3AxisEvent
, optionally in conjunction with some set ofSkyCtrl3ButtonEvent
in the.pressed
state.
This peripheral can be retrieved by:
drone.getPeripheral(Peripherals.skyCtrl3Gamepad)
-
Listener that will be called when input button events are grabbed, and that their state changes. Parameter event of the listener represents the button event that is concerned. Parameter state of the listener represents the state of the button event
Declaration
Swift
var buttonEventListener: ((_ event: SkyCtrl3ButtonEvent, _ state: SkyCtrl3ButtonEventState) -> Void)? { get set }
-
Listener that will be called when input axis events are grabbed, and that their value changes. Parameter event of the listener represents the axis event that is concerned. Parameter value of the listener represents the current position of the axis, i.e. an int value in range [-100, 100], where -100 corresponds to the axis at start of its course (left for horizontal axes, down for vertical axes), and 100 represents the axis at end of its course (right for horizontal axes, up for vertical axes).
Declaration
Swift
var axisEventListener: ((_ event: SkyCtrl3AxisEvent, _ value: Int) -> Void)? { get set }
-
Set of currently grabbed buttons.
Declaration
Swift
var grabbedButtons: Set<SkyCtrl3Button> { get }
-
Set of currently grabbed axes.
Declaration
Swift
var grabbedAxes: Set<SkyCtrl3Axis> { get }
-
Current state of all the button events produced by all the grabbed inputs.
Declaration
Swift
var grabbedButtonsState: [SkyCtrl3ButtonEvent : SkyCtrl3ButtonEventState] { get }
-
Set of drone models supported by the remote control.
This defines the set of drone models for which the application can edit mappings.
Declaration
Swift
var supportedDroneModels: Set<Drone.Model> { get }
-
Currently active drone model.
The active drone model is the model of the drone currently connected through the remote control, or the latest connected drone’s model if the remote control is not connected to any drone at the moment.
Declaration
Swift
var activeDroneModel: Drone.Model? { get }
-
Grabs gamepad inputs.
Grabs the given set of inputs, requiring the skycontroller3 device to send events from those inputs to the application listener instead forwarding them of the drone.
The provided set of inputs completely overrides the current set of grabbed inputs (if any). So, for instance, to release all inputs, this method should be called with an empty set. To grab or release some specific inputs without altering the rest of the grabbed inputs,
grabbedButtons
andgrabbedAxes
may be used to construct a new set of inputs to provide to this method.Declaration
Swift
func grab(buttons: Set<SkyCtrl3Button>, axes: Set<SkyCtrl3Axis>)
Parameters
buttons
set of buttons to be grabbed
axes
set of axes to be grabbed
-
Gets a mapping for a given drone model
Declaration
Swift
func mapping(forModel droneModel: Drone.Model) -> Set<SkyCtrl3MappingEntry>?
Parameters
droneModel
the drone model for which to retrieve the mapping
Return Value
set of current mapping entries as configured for the provided drone model (possibly empty if no entry is defined for that model), otherwise nil in case the drone model is not supported.
-
Registers a mapping entry.
This allows to setup a new mapping entry in a drone model’s mapping (in case the entry’s action is not registered yet in the drone mapping) or to modify an existing entry (in case the entry’s action is already registered in the drone mapping).
If the drone model is supported, the entry gets persisted in the corresponding mapping on the remote control.
Note
that adding or editing a mapping entry may have impact on other existing entries in the same mapping, since the same combination of input events cannot be used on more than one mapping entry at the same time. As a result, when hitting such a situation, the existing conflicting entry is removed, and the new entry is registered instead.
Also note that adding a
SkyCtrl3ButtonsMappingEntry
with an empty button events set will be refused.Declaration
Swift
func register(mappingEntry: SkyCtrl3MappingEntry)
Parameters
mappingEntry
mapping entry to register
-
Unregisters a mapping entry
This allows to remove a mapping entry from a drone model’s mapping. If the drone model is supported, the entry gets persistently removed from the corresponding mapping on the remote control.
Declaration
Swift
func unregister(mappingEntry: SkyCtrl3MappingEntry)
Parameters
mappingEntry
mapping entry to unregister
-
Resets a drone model mapping to its default (built-in) value.
Declaration
Swift
func resetMapping(forModel droneModel: Drone.Model)
Parameters
droneModel
the drone model for which to reset the mapping
-
Resets all supported drone models mappings to their default (built-in) value.
Declaration
Swift
func resetAllMappings()
-
Sets the interpolation formula to be applied on an axis.
An axis interpolator affects the values sent to the connected drone when moving the gamepad axis. It maps the physical linear position of the axis to another value by applying a predefined formula.
Note
Note that the current interpolator set on an axis also affects the values sent through
axisEventListener
for grabbed inputs.Declaration
Swift
func set(interpolator: AxisInterpolator, forAxis axis: SkyCtrl3Axis, droneModel: Drone.Model)
Parameters
interpolator
interpolator to set
axis
axis to set the interpolator for
droneModel
drone model for which the axis interpolator must be applied
-
Gets the axis interpolator currently applied on a given drone model on a given axis.
Declaration
Swift
func interpolator(forAxis axis: SkyCtrl3Axis, droneModel: Drone.Model) -> AxisInterpolator?
Parameters
axis
axis of the given drone model whose interpolator must be retrieved
droneModel
drone model whose axis interpolators must be retrieved
Return Value
an interpolator if the drone model is supported and the interpolator is known, otherwise nil
-
Reverses a gamepad axis.
A reversed axis produces values reversed symmetrically around the axis standstill value (0). For instance, an horizontal axis will produce values from 100 when held at (left) start of its course, to -100, when held at (right) end of its course, while when not reversed, it will produce values from -100 when held at (left) start of its course, to 100 when held at (right) end of its course. Same thing applies to vertical axes, where produced values will range from 100 (bottom start) to -100 (top end) instead of -100 (bottom start) to 100 (top end).
Reversing an already reversed axis sets the axis back to normal operation mode.
The axis inversion stage occurs before any interpolation formula is applied.
Note
Note that axis inversion has no effect whatsoever on the values sent through
axisEventListener
for grabbed inputs. In other words, when receiving grabbed axes events, it can be considered that the axis is never reversed.Declaration
Swift
func reverse(axis: SkyCtrl3Axis, forDroneModel droneModel: Drone.Model)
Parameters
axis
axis to reverse
droneModel
drone model for which the axis must be reversed
-
Gets all currently reversed axis for a given drone model.
Declaration
Swift
func reversedAxes(forDroneModel droneModel: Drone.Model) -> Set<SkyCtrl3Axis>?
Parameters
droneModel
drone model whose reversed axes must be retrieved
Return Value
the set of currently reversed axes, or
nil
if the provided drone model is not supported -
Setting for volatile mapping mode All mapping entries registered with volatile mapping enabled will be removed when it is disabled or when remote control is disconnected. Disabling volatile mapping also cancels any ongoing action. Setting is nil if volatile mapping is not supported.
Declaration
Swift
var volatileMappingSetting: BoolSetting? { get }