GSSkyCtrl3Gamepad

@objc
public protocol GSSkyCtrl3Gamepad : 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 producing SkyCtrl3ButtonEvent 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 producing SkyCtrl3AxisEvent 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:

This peripheral can be retrieved by:

(id<GSSkyCtrl3Gamepad>) [drone getPeripheral:GSPeripherals.skyCtrl3Gamepad]

Note

this protocol is for Objective-C only. Swift must use the protocol 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 }
  • 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 activeDroneModelAsNumber: NSNumber? { get }
  • Current state of all the button events produced by all the grabbed inputs. This maps a SkyCtrl3ButtonEventState raw value to a SkyCtrl3ButtonEvent raw value as key.

    Declaration

    Swift

    func getGrabbedButtonsState() -> [Int : Int]
  • Gets the set of currently grabbed button inputs.

    Declaration

    Swift

    func getGrabbedButtons() -> GSSkyCtrl3ButtonSet

    Return Value

    the set of grabbed buttons

  • Gets the set of currently grabbed axis inputs.

    Declaration

    Swift

    func getGrabbedAxes() -> GSSkyCtrl3AxisSet

    Return Value

    the set of grabbed axes

  • 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, getGrabbedButtons() and getGrabbedAxes() may be used to construct a new set of inputs to provide to this method.

    Declaration

    Swift

    func grab(buttonSet: GSSkyCtrl3ButtonSet, axisSet: GSSkyCtrl3AxisSet)

    Parameters

    buttonSet

    set of buttons to be grabbed

    axisSet

    set of axes to be grabbed

  • Gets the 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

    func getSupportedDroneModels() -> Drone.GSDroneModelSet

    Return Value

    a set of drone models

  • 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

    @objc(registerMappingEntry:)
    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

    @objc(unregisterMappingEntry:)
    func unregister(mappingEntry: SkyCtrl3MappingEntry)

    Parameters

    mappingEntry

    mapping entry to unregister

  • Resets a drone model mapping to its default (built-in) value.

    Declaration

    Swift

    @objc(resetMappingForModel:)
    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

    @objc(setInterpolator:forAxis:droneModel:)
    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

    @objc(interpolatorForAxis:droneModel:)
    func gsInterpolator(forAxis axis: SkyCtrl3Axis, droneModel: Drone.Model) -> NSNumber?

    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

    @objc(reverseAxis:forDroneModel:)
    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

    @objc(reversedAxesForDroneModel:)
    func gsReversedAxes(forDroneModel droneModel: Drone.Model) -> GSSkyCtrl3AxisSet?

    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