-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Nintendo Switch Controller Library
--   
--   Please see the README on GitHub at
--   <a>https://github.com/typedbyte/switch#readme</a>
@package switch
@version 0.1.0.0


-- | Types and functions for connecting to Nintendo Switch controllers,
--   reading input (e.g., buttons, sensors) and sending commands (e.g.,
--   rumble).
module Device.Nintendo.Switch

-- | A handle which represents a virtual Nintendo Switch console. The
--   handle is used to detect controllers and manage their connections.
data Console

-- | Initializes a Nintendo Switch console handle. In other words, it lets
--   us pretend to be Nintendo Switch console in order to detect
--   controllers and manage their connections. You must call this first
--   before doing anything else.
init :: IO Console

-- | Destroys a virtual Nintendo Switch handle. You must call this when you
--   are finished talking to the controllers.
exit :: Console -> IO ()

-- | A convenient wrapper around <a>init</a> and <a>exit</a>.
withConsole :: (Console -> IO a) -> IO a

-- | The types of Nintendo Switch controllers that are currently supported
--   by this library.
--   
--   Note that this type is mostly used on the type level (using
--   <tt>DataKinds</tt>) in order to prevent programming mistakes at
--   compile-time (e.g., to prevent sending a rumble command to a
--   controller which has no rumble feature).
--   
--   Chances are very high that you don't need this type on the value
--   level, but rather on the type level, for example via
--   <tt>TypeApplications</tt> (see <a>getControllerInfos</a>).
data ControllerType
LeftJoyCon :: ControllerType
RightJoyCon :: ControllerType
ProController :: ControllerType

-- | A handle which represents an unconnected Nintendo Switch controller.
data ControllerInfo (t :: ControllerType)

-- | A handle which represents a connected Nintendo Switch controller.
data Controller (t :: ControllerType)

-- | Detects all Nintendo Switch controllers of a specific
--   <a>ControllerType</a>, usually connected via Bluetooth.
--   
--   You may want to use this function with <tt>TypeApplications</tt> if
--   the controller type cannot be inferred, like:
--   
--   <pre>
--   <a>getControllerInfos</a> @'<a>LeftJoyCon</a> console
--   </pre>
getControllerInfos :: forall t. IsController t => Console -> IO [ControllerInfo t]

-- | Connects to a detected Nintendo Switch controller.
--   
--   Can throw a <a>ConnectionException</a> if something is very wrong with
--   your internal controller memory (i.e., if you have tampered with it).
connect :: forall t. HasCalibration t => ControllerInfo t -> IO (Controller t)

-- | Disconnects a Nintendo Switch controller. You must not use the
--   controller handle after disconnecting.
disconnect :: Controller t -> IO ()

-- | A convenient wrapper around <a>connect</a> and <a>disconnect</a>.
withController :: HasCalibration t => ControllerInfo t -> (Controller t -> IO a) -> IO a

-- | The input mode of a Nintendo Switch controller determines the
--   frequency and amount of information received by <a>getInput</a>.
data InputMode

-- | The default input mode. In this mode, controllers push <a>Input</a>
--   packages in a 60Hz (Joy-Con) or 120Hz (Pro Controller) frequency,
--   including <a>battery</a> information, <a>Analog</a> stick directions
--   (<a>stickLeft</a>, <a>stickRight</a>) and <a>Inertial</a> sensor data
--   (<a>extras</a>) if activated via <a>setInertialMeasurement</a>.
Standard :: InputMode

-- | A simple input mode where a controller only pushes its <a>Input</a>
--   whenever a button is pressed or a <a>CommandReply</a> (<a>extras</a>)
--   is sent. In this mode, controllers only send <a>Discrete</a> stick
--   directions (<a>stickLeft</a>, <a>stickRight</a>) and no inertial
--   sensor data. Furthermore, <a>battery</a> information is only sent in
--   combination with command replies.
Simple :: InputMode

-- | Sets the input mode of a Nintendo Switch controller.
--   
--   Note: After sending a command like this to a controller, it is highly
--   advised to check its corresponding <a>CommandReply</a>
--   (<a>SetInputMode</a>, to be exact) or at least call <a>getInput</a>
--   once before sending another command to that controller. The function
--   <a>withCommandReply</a> is a convenient way to wait for a specific
--   command reply from the controller.
setInputMode :: HasInputMode t => InputMode -> Controller t -> IO ()

-- | Enables (<a>True</a>) or disables (<a>False</a>) the inertial
--   measurement unit (i.e., accelerometer, gyroscope) of a Nintendo Switch
--   controller. Inertial measurement is disabled by default.
--   
--   Note: After sending a command like this to a controller, it is highly
--   advised to check its corresponding <a>CommandReply</a>
--   (<a>SetInertialMeasurement</a>, to be exact) or at least call
--   <a>getInput</a> once before sending another command to that
--   controller. The function <a>withCommandReply</a> is a convenient way
--   to wait for a specific command reply from the controller.
setInertialMeasurement :: Bool -> Controller t -> IO ()

-- | Reads input from a Nintendo Switch controller. Blocks until controller
--   input is available.
getInput :: HasInput t => Controller t -> IO Input

-- | Reads input from a Nintendo Switch controller. Blocks until controller
--   input is available or a given time interval elapses.
getTimeoutInput :: HasInput t => Int -> Controller t -> IO (Maybe Input)

-- | The input provided by a Nintendo Switch controller.
type Input = ControllerInput Float Float

-- | The input provided by a Nintendo Switch controller, where <tt>s</tt>
--   is the numeric type of the analog stick direction and <tt>e</tt> is
--   the numeric type of the sensor readings (i.e., accelerometer and
--   gyroscope).
data ControllerInput s e
Input :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> StickDirection s -> StickDirection s -> ExtraInput e -> Maybe BatteryInfo -> ControllerInput s e
[btnL] :: ControllerInput s e -> Bool
[btnZL] :: ControllerInput s e -> Bool
[btnMinus] :: ControllerInput s e -> Bool
[btnLeftStick] :: ControllerInput s e -> Bool
[btnUp] :: ControllerInput s e -> Bool
[btnLeft] :: ControllerInput s e -> Bool
[btnRight] :: ControllerInput s e -> Bool
[btnDown] :: ControllerInput s e -> Bool
[btnCapture] :: ControllerInput s e -> Bool
[btnLeftSL] :: ControllerInput s e -> Bool
[btnLeftSR] :: ControllerInput s e -> Bool
[btnR] :: ControllerInput s e -> Bool
[btnZR] :: ControllerInput s e -> Bool
[btnPlus] :: ControllerInput s e -> Bool
[btnX] :: ControllerInput s e -> Bool
[btnY] :: ControllerInput s e -> Bool
[btnA] :: ControllerInput s e -> Bool
[btnB] :: ControllerInput s e -> Bool
[btnRightStick] :: ControllerInput s e -> Bool
[btnHome] :: ControllerInput s e -> Bool
[btnRightSL] :: ControllerInput s e -> Bool
[btnRightSR] :: ControllerInput s e -> Bool
[stickLeft] :: ControllerInput s e -> StickDirection s
[stickRight] :: ControllerInput s e -> StickDirection s
[extras] :: ControllerInput s e -> ExtraInput e
[battery] :: ControllerInput s e -> Maybe BatteryInfo

-- | The direction of the left (<a>stickLeft</a>) and right
--   (<a>stickRight</a>) analog sticks.
data StickDirection a

-- | In <a>Simple</a> input mode, controllers send discrete stick
--   directions.
Discrete :: Direction -> StickDirection a

-- | In <a>Standard</a> input mode, controllers send analog stick
--   directions. The first value is left/right (interval <tt>[-1,1]</tt>),
--   the second value is down/up (interval <tt>[-1,1]</tt>).
Analog :: a -> a -> StickDirection a

-- | The nine possible discrete positions of the analog stick in
--   <a>Simple</a> input mode.
data Direction
None :: Direction
Left :: Direction
Up :: Direction
Right :: Direction
Down :: Direction
LeftUp :: Direction
LeftDown :: Direction
RightUp :: Direction
RightDown :: Direction

-- | Information about the battery of a Nintendo Switch controller. It is
--   only returned by <a>getInput</a> (see <a>battery</a>) if the
--   controller sends a command reply or the input mode of the controller
--   is <a>Standard</a>.
data BatteryInfo
BatteryInfo :: BatteryStatus -> Bool -> BatteryInfo
[batteryStatus] :: BatteryInfo -> BatteryStatus
[charging] :: BatteryInfo -> Bool

-- | The battery status of a Nintendo Switch controller.
data BatteryStatus
Empty :: BatteryStatus
Low :: BatteryStatus
Medium :: BatteryStatus
Good :: BatteryStatus
Full :: BatteryStatus

-- | Depending on the <a>InputMode</a>, <a>Input</a> can contain additional
--   information: Replies to commands (e.g., an acknowledgement when
--   sending a rumble command) and inertial sensor data (i.e.,
--   accelerometer and gyroscope).
data ExtraInput a

-- | After sending commands to the controller (e.g., setting the
--   <a>InputMode</a>), a command reply is returned as extra data in the
--   next input.
CommandReply :: ReplyData -> ExtraInput a

-- | A controller provides inertial sensor data (i.e., accelerometer and
--   gyroscope) only if it is in <a>Standard</a> input mode and inertial
--   measurement is activated via <a>setInertialMeasurement</a>.
--   
--   Regarding the x/y/z coordinate system, consider the left Joy-Con lying
--   flat on a table, the analog stick pointing up. The x-axis then points
--   towards the Z/ZL shoulder buttons (or alternatively: to where the up
--   arrow button is pointing), the y-axis points to the opposite side of
--   the SL/SR buttons (or alternatively: to where the left arrow button is
--   pointing), and the z-axis points up in the air. The coordinate system
--   is the same for all controller types.
Inertial :: Accelerometer a -> Gyroscope a -> ExtraInput a

-- | Indicates that there is no additional input data.
Unavailable :: ExtraInput a

-- | Accelerometer data consists of three measurements recorded in 15ms
--   (i.e., the precision is 5ms). Each measurement is an x/y/z triple
--   measured in Gs.
type Accelerometer a = ((a, a, a), (a, a, a), (a, a, a))

-- | Gyroscope data consists of three measurements recorded in 15ms (i.e.,
--   the precision is 5ms). Each measurement is an x/y/z triple measured in
--   radians per second.
type Gyroscope a = ((a, a, a), (a, a, a), (a, a, a))

-- | Data type that combines the command type and its corresponding
--   acknowledgement.
data ReplyData
SetHomeLight :: Acknowledgement () -> ReplyData
SetInertialMeasurement :: Acknowledgement () -> ReplyData
SetInputMode :: Acknowledgement () -> ReplyData
SetPlayerLights :: Acknowledgement () -> ReplyData
SetVibration :: Acknowledgement () -> ReplyData

-- | Whenever a command is sent to a controller (e.g., setting the
--   <a>InputMode</a>), the controller replies with an
--   <a>Acknowledgement</a>.
data Acknowledgement a

-- | The command was executed successfully, possibly holding some response
--   data (e.g., if the command was a query of the internal SPI flash
--   memory).
ACK :: a -> Acknowledgement a

-- | The command was not executed successfully.
NACK :: Acknowledgement a

-- | A convenient constant that represents no input. This can be used to
--   set specific buttons and stick directions in order to test functions
--   without having a Nintendo Switch controller at hand, like:
--   
--   <pre>
--   <a>noInput</a> { <a>btnX</a> = <a>True</a>, <a>stickLeft</a> = <a>Discrete</a> <a>Up</a> }
--   </pre>
noInput :: ControllerInput s e

-- | Converts stick directions into x/y coordinates in the interval
--   <tt>[-1,1]</tt>. <a>Analog</a> values are taken as is, while
--   <a>Discrete</a> directions are converted to their analog counterpart.
coordinates :: StickDirection Float -> (Float, Float)

-- | Merges the inputs of two Nintendo Switch controllers. The resulting
--   input contains the left button states and left analog stick direction
--   from one input, and the right button states and right analog stick
--   direction from the other input. This can be used to unify the inputs
--   of two controllers that belong together (e.g., a pair of left and
--   right Joy-Cons).
--   
--   Note that the <a>extras</a> and <a>battery</a> information of the
--   original inputs are discarded in the merged input (they are set to
--   <a>Unavailable</a> and <a>Nothing</a>, respectively).
mergeInputs :: Input -> Input -> Input

-- | Consumes inputs from a Nintendo Switch controller until a specific
--   command reply is encountered. Throws a <a>NoReplyException</a> if the
--   expected command reply is not encountered within a specified count of
--   inputs.
--   
--   This function can be used to make sure that the controller is in an
--   expected state after sending commands (e.g., to wait for an
--   <a>Acknowledgement</a> after switching its <a>InputMode</a>).
withCommandReply :: Int -> Int -> Controller t -> (ReplyData -> Maybe a) -> IO a

-- | Sets the home light (i.e., the LED ring around the home button) of a
--   Nintendo Switch controller.
--   
--   Note: After sending a command like this to a controller, it is highly
--   advised to check its corresponding <a>CommandReply</a>
--   (<a>SetHomeLight</a>, to be exact) or at least call <a>getInput</a>
--   once before sending another command to that controller. The function
--   <a>withCommandReply</a> is a convenient way to wait for a specific
--   command reply from the controller.
setHomeLight :: HasHomeLight t => HomeLightConfig -> Controller t -> IO ()

-- | The home light of a Nintendo Switch Controller can be controlled using
--   repeatable configuration cycles. See <a>endlessPulse</a> for an
--   example configuration.
data HomeLightConfig

-- | Turn off the home light.
Off :: HomeLightConfig

-- | Given a start intensity of the home light LED, fade to a target LED
--   intensity in a given time, and then keep this LED intensity up for a
--   given amount of time.
--   
--   The fade duration in milliseconds is calculated by multiplying the
--   <a>BaseDuration</a> with the <a>FadeFactor</a> of the
--   <a>CycleConfig</a>. The light upkeep duration in milliseconds is
--   calculated by multiplying the <a>BaseDuration</a> with the
--   <a>LightFactor</a> of the <a>CycleConfig</a>.
--   
--   Example - fade from a switched off LED (<tt>0</tt>) to a fully bright
--   LED (<tt>100</tt>) in 500ms (<tt>50</tt>ms * <tt>10</tt>), stay there
--   for one second (<tt>50</tt>ms * <tt>20</tt>), then turn it off:
--   
--   <pre>
--   <a>Once</a> 50 0 (100, 10, 20)
--   </pre>
Once :: BaseDuration -> Intensity -> CycleConfig -> HomeLightConfig

-- | Given a start intensity of the home light LED, repeatedly fade to a
--   target LED intensity in a given time, and then keep this LED intensity
--   up for a given amount of time. The fade durations and light upkeep
--   durations are calculated per cycle configuration as described for
--   <a>Once</a>. See <a>endlessPulse</a> for a cyclic configuration
--   example.
Cyclic :: BaseDuration -> Intensity -> [CycleConfig] -> RepeatBehaviour -> HomeLightConfig

-- | A home light cycle consists of a target LED intensity, a fade factor
--   which controls the time needed to reach that LED intensity, and a
--   light factor which controls how long to keep the target LED intensity
--   up.
type CycleConfig = (Intensity, FadeFactor, LightFactor)

-- | The base duration of a home light configuration in milliseconds. It
--   will always be limited to an interval between 8ms and 175ms. It is
--   called base duration because it will be multiplied with other factors
--   in order to obtain the overall durations of fadings within home light
--   configurations.
type BaseDuration = Word8

-- | The LED intensity of the home light. It will always be limited to an
--   interval between 0 and 100.
type Intensity = Word8

-- | The fade duration factor of the home light. It will always be limited
--   to an interval between 0 and 15 and is multiplied with the
--   <a>BaseDuration</a> to obtain the overall fade duration in
--   milliseconds.
type FadeFactor = Word8

-- | The light duration factor of the home light. It will always be limited
--   to an interval between 0 and 15 and is multiplied with the
--   <a>BaseDuration</a> to obtain the overall light duration in
--   milliseconds.
type LightFactor = Word8

-- | Defines the repeat behaviour after all the home light configuration
--   cycles have ended.
data RepeatBehaviour

-- | A convenient home light configuration which pulsates the home light
--   LED:
--   
--   <pre>
--   <a>Cyclic</a>
--     ( 100 )         -- Base duration factor is 100ms.
--     (   0 )         -- LED is turned off at the beginning (intensity 0).
--     [ (100, 5, 1)   -- Fade to LED intensity 100 in 500ms (100ms * 5) and stay there for 100ms (100ms * 1).
--     , (  0, 5, 1) ] -- Fade to LED intensity   0 in 500ms (100ms * 5) and stay there for 100ms (100ms * 1).
--     ( Forever )     -- Repeat these two cycles forever, thus generating a pulse-like LED.
--   </pre>
endlessPulse :: HomeLightConfig

-- | Sets the player lights of a Nintendo Switch controller.
--   
--   Note: After sending a command like this to a controller, it is highly
--   advised to check its corresponding <a>CommandReply</a>
--   (<a>SetPlayerLights</a>, to be exact) or at least call <a>getInput</a>
--   once before sending another command to that controller. The function
--   <a>withCommandReply</a> is a convenient way to wait for a specific
--   command reply from the controller.
setPlayerLights :: HasPlayerLights t => PlayerLightsConfig -> Controller t -> IO ()

-- | Nintendo Switch controllers have four LEDs that can be used to
--   indicate various things, for example the player number or the
--   Bluetooth pairing status. The LEDs are numbered from left to right
--   (i.e., <a>led0</a> is the leftmost LED, <a>led3</a> is the rightmost
--   LED).
data PlayerLightsConfig
PlayerLightsConfig :: LightMode -> LightMode -> LightMode -> LightMode -> PlayerLightsConfig
[led0] :: PlayerLightsConfig -> LightMode
[led1] :: PlayerLightsConfig -> LightMode
[led2] :: PlayerLightsConfig -> LightMode
[led3] :: PlayerLightsConfig -> LightMode

-- | Each player light LED can be individually turned on, turned off or
--   used in a pulsating manner (i.e., flashing).
data LightMode
LightOn :: LightMode
LightOff :: LightMode
Flashing :: LightMode

-- | A convenient player lights configuration where all LEDs are turned
--   off.
noPlayerLights :: PlayerLightsConfig

-- | A convenient player lights configuration indicating player one (i.e.,
--   <a>led0</a> is set).
playerOne :: PlayerLightsConfig

-- | A convenient player lights configuration indicating player two (i.e.,
--   <a>led1</a> is set).
playerTwo :: PlayerLightsConfig

-- | A convenient player lights configuration indicating player three
--   (i.e., <a>led2</a> is set).
playerThree :: PlayerLightsConfig

-- | A convenient player lights configuration indicating player four (i.e.,
--   <a>led3</a> is set).
playerFour :: PlayerLightsConfig

-- | A convenient player lights configuration where all LEDs are flashing.
flashAll :: PlayerLightsConfig

-- | Enables (<a>True</a>) or disables (<a>False</a>) the rumble feature of
--   a Nintendo Switch controller. The rumble feature is disabled by
--   default.
--   
--   Note: After sending a command like this to a controller, it is highly
--   advised to check its corresponding <a>CommandReply</a>
--   (<a>SetVibration</a>, to be exact) or at least call <a>getInput</a>
--   once before sending another command to that controller. The function
--   <a>withCommandReply</a> is a convenient way to wait for a specific
--   command reply from the controller.
setVibration :: Bool -> Controller t -> IO ()

-- | Sets the left rumble of a Nintendo Switch controller.
setLeftRumble :: HasLeftRumble t => RumbleConfig -> Controller t -> IO ()

-- | Sets the right rumble of a Nintendo Switch controller.
setRightRumble :: HasRightRumble t => RumbleConfig -> Controller t -> IO ()

-- | Sets both the left rumble and right rumble of a Nintendo Switch
--   controller. Note that this is more efficient than setting the left
--   rumble and right rumble separately via <a>setLeftRumble</a> and
--   <a>setRightRumble</a>.
setRumble :: (HasLeftRumble t, HasRightRumble t) => RumbleConfig -> RumbleConfig -> Controller t -> IO ()

-- | Nintendo Switch controllers have a HD rumble feature which allows
--   fine-grained control of rumble strengths and directions. As a
--   consequence, a rumble is not configured by a mere numeric value, but
--   by two (high and low) pairs of frequencies and amplitudes. This
--   library constrains the value ranges of frequencies and amplitudes in
--   order to always obtain sane configurations. However, sending extreme
--   values for these pairs over an extended period of time may still
--   damage a controller, so experiment wisely with rather short rumbles.
--   
--   For technical discussions and the meaning of these values, one can
--   read <a>this</a>, for example. A sample rumble configuration is
--   provided by <a>normalRumble</a>.
data RumbleConfig
RumbleConfig :: Double -> Double -> Double -> Double -> RumbleConfig

-- | The high frequency. It will always be limited to an interval between
--   81.75177 Hz and 1252.572266 Hz.
[highFrequency] :: RumbleConfig -> Double

-- | The high amplitude. It will always be limited to an interval between
--   0.0 and 1.0.
[highAmplitude] :: RumbleConfig -> Double

-- | The low frequency. It will always be limited to an interval between
--   40.875885 Hz and 626.286133 Hz.
[lowFrequency] :: RumbleConfig -> Double

-- | The low amplitude. It will always be limited to an interval between
--   0.0 and 1.0.
[lowAmplitude] :: RumbleConfig -> Double

-- | A convenient rumble configuration indicating a medium rumble strength.
--   
--   <pre>
--   <a>RumbleConfig</a>
--     { <a>highFrequency</a> = 800
--     , <a>highAmplitude</a> = 0.5
--     , <a>lowFrequency</a>  = 330
--     , <a>lowAmplitude</a>  = 0.75
--     }
--   </pre>
normalRumble :: RumbleConfig

-- | A convenient rumble configuration indicating no rumble.
noRumble :: RumbleConfig

-- | A <a>ConnectionException</a> is thrown if something goes wrong when
--   reading the internal data of a Nintendo Switch controller when
--   connecting to it. This should not occur if you have an unmodified
--   controller (i.e., you have not tampered with its internal SPI flash
--   memory).
data ConnectionException

-- | Indicates that a controller has no factory stick calibration.
NoFactoryStickException :: ConnectionException

-- | Indicates that a controller has no factory sensor calibration.
NoFactoryAxisException :: ConnectionException

-- | An <a>InputException</a> is thrown if something goes wrong with
--   <a>getInput</a>.
data InputException

-- | Indicates that an expected reply wasn't received in a specific time
--   interval.
NoReplyException :: InputException

-- | Indicates that the controller input has an unexpected format. It
--   essentially means that a specific part of the protocol has not been
--   implemented yet. This should not occur as long as you stick to the
--   public API of this library.
UnknownFormatException :: ByteString -> InputException

-- | An <a>OutputException</a> is thrown if something goes wrong when
--   sending commands to a Nintendo Switch controller.
data OutputException
WriteException :: OutputException

-- | A constraint which indicates that a controller is a valid Nintendo
--   Switch controller that can be detected and connected to.
class IsController (t :: ControllerType)

-- | A constraint which indicates that a Nintendo Switch controller is able
--   to turn portions of its internal flash memory into valid calibration
--   information.
class HasCalibration (t :: ControllerType)

-- | A constraint which indicates that a Nintendo Switch controller
--   supports multiple input modes (see <a>setInputMode</a>).
class HasInputMode t

-- | A constraint which indicates that a Nintendo Switch controller can
--   provide <a>Input</a> (see <a>getInput</a>).
class HasInput t

-- | A constraint which indicates that a Nintendo Switch controller has a
--   home light (see <a>setHomeLight</a>).
class HasHomeLight t

-- | A constraint which indicates that a Nintendo Switch controller has
--   player lights (i.e., the four LEDs which represent the player number;
--   see <a>setPlayerLights</a>).
class HasPlayerLights t

-- | A constraint which indicates that a Nintendo Switch controller has a
--   left-side rumble unit (see <a>setLeftRumble</a>).
class HasLeftRumble t

-- | A constraint which indicates that a Nintendo Switch controller has a
--   right-side rumble unit (see <a>setRightRumble</a>).
class HasRightRumble t