| Copyright | (c) 2016, Drew Hess |
|---|---|
| License | BSD3 |
| Maintainer | Drew Hess <src@drewhess.com> |
| Stability | experimental |
| Portability | non-portable |
| Safe Haskell | Safe |
| Language | Haskell2010 |
System.GPIO.Monad
Description
A monadic context for GPIO computations.
- newtype Pin = Pin Int
- pinNumber :: Pin -> Int
- data PinInputMode
- data PinOutputMode
- data PinCapabilities = PinCapabilities {}
- data PinDirection
- data PinActiveLevel
- data PinValue
- data PinInterruptMode
- class Monad m => MonadGpio h m | m -> h where
- withPin :: (MonadMask m, MonadGpio h m) => Pin -> (h -> m a) -> m a
- data InputPin h
- withInputPin :: (MonadMask m, MonadGpio h m) => Pin -> PinInputMode -> Maybe PinActiveLevel -> (InputPin h -> m a) -> m a
- readInputPin :: MonadGpio h m => InputPin h -> m PinValue
- getInputPinInputMode :: MonadGpio h m => InputPin h -> m PinInputMode
- getInputPinActiveLevel :: MonadGpio h m => InputPin h -> m PinActiveLevel
- setInputPinActiveLevel :: MonadGpio h m => InputPin h -> PinActiveLevel -> m ()
- toggleInputPinActiveLevel :: MonadGpio h m => InputPin h -> m PinActiveLevel
- data InterruptPin h
- withInterruptPin :: (MonadMask m, MonadGpio h m) => Pin -> PinInputMode -> PinInterruptMode -> Maybe PinActiveLevel -> (InterruptPin h -> m a) -> m a
- readInterruptPin :: MonadGpio h m => InterruptPin h -> m PinValue
- pollInterruptPin :: MonadGpio h m => InterruptPin h -> m PinValue
- pollInterruptPinTimeout :: MonadGpio h m => InterruptPin h -> Int -> m (Maybe PinValue)
- getInterruptPinInputMode :: MonadGpio h m => InterruptPin h -> m PinInputMode
- getInterruptPinInterruptMode :: (MonadThrow m, MonadGpio h m) => InterruptPin h -> m PinInterruptMode
- setInterruptPinInterruptMode :: MonadGpio h m => InterruptPin h -> PinInterruptMode -> m ()
- getInterruptPinActiveLevel :: MonadGpio h m => InterruptPin h -> m PinActiveLevel
- setInterruptPinActiveLevel :: MonadGpio h m => InterruptPin h -> PinActiveLevel -> m ()
- toggleInterruptPinActiveLevel :: MonadGpio h m => InterruptPin h -> m PinActiveLevel
- data OutputPin h
- withOutputPin :: (MonadMask m, MonadGpio h m) => Pin -> PinOutputMode -> Maybe PinActiveLevel -> PinValue -> (OutputPin h -> m a) -> m a
- writeOutputPin :: MonadGpio h m => OutputPin h -> PinValue -> m ()
- toggleOutputPin :: MonadGpio h m => OutputPin h -> m PinValue
- readOutputPin :: MonadGpio h m => OutputPin h -> m PinValue
- getOutputPinOutputMode :: MonadGpio h m => OutputPin h -> m PinOutputMode
- getOutputPinActiveLevel :: MonadGpio h m => OutputPin h -> m PinActiveLevel
- setOutputPinActiveLevel :: MonadGpio h m => OutputPin h -> PinActiveLevel -> m ()
- toggleOutputPinActiveLevel :: MonadGpio h m => OutputPin h -> m PinActiveLevel
- data SomeGpioException = Exception e => SomeGpioException e
- gpioExceptionToException :: Exception e => e -> SomeException
- gpioExceptionFromException :: Exception e => SomeException -> Maybe e
GPIO types
For your convenience, the following types are re-exported from the System.GPIO.Types module.
A GPIO pin, identified by pin number.
Note that GPIO pin numbering is platform- and runtime-dependent. See the documentation for your particular platform for an explanation of how pin numbers are assigned to physical pins.
data PinInputMode Source #
GPIO pins may support a number of different physical configurations when used as a digital input.
Pins that are capable of input will at least support the
InputDefault mode. InputDefault mode is special in that, unlike
the other input modes, it does not represent a unique physical
configuration, but is simply a pseudonym for another (actual) input
mode. Exactly which mode is used by the hardware when
InputDefault mode is specified is platform-dependent. By using
InputDefaut mode, you are saying that you don't care about the
pin's actual configuration, other than the fact that it's being
used for input.
Constructors
| InputDefault | The pin's default input mode, i.e., the mode used when a more specific mode is not specified |
| InputFloating | A floating / high-impedance / tri-state mode which uses little power, but when disconnected, may cause the pin's value to be indeterminate |
| InputPullUp | The pin is connected to an internal pull-up resistor such
that, when the pin is disconnected or connected to a floating /
high-impedance node, its physical value will be |
| InputPullDown | The pin is connected to an internal pull-down resistor such
that, when the pin is disconnected or connected to a floating /
high-impedance node, its physical value will be |
data PinOutputMode Source #
GPIO pins may support a number of different physical configurations when used as a digital output.
Pins that are capable of output will at least support the
OutputDefault mode. OutputDefault mode is special in that,
unlike the other output modes, it does not represent a unique
physical configuration, but is simply a pseudonym for another
(actual) output mode. Exactly which mode is used by the hardware
when OutputDefault mode is specified is platform-dependent. By
using OutputDefaut mode, you are saying that you don't care about
the pin's actual configuration, other than the fact that it's being
used for output.
Constructors
| OutputDefault | The pin's default output mode, i.e., the mode used when a more specific mode is not specified |
| OutputPushPull | |
| OutputOpenDrain | The output actively drives the |
| OutputOpenDrainPullUp | The output actively drives the |
| OutputOpenSource | The output actively drives the |
| OutputOpenSourcePullDown | The output actively drives the |
data PinCapabilities Source #
Catalog a pin's capabilities.
Constructors
| PinCapabilities | |
Fields
| |
Instances
data PinDirection Source #
A pin's direction (input/output).
Instances
data PinActiveLevel Source #
A pin's active level (active-high/active-low).
Constructors
| ActiveLow | |
| ActiveHigh |
Instances
A pin's signal level as a binary value.
Instances
data PinInterruptMode Source #
A pin's interrupt mode.
Note that the pin's interrupt mode is defined in terms of the pin's
logical signal value; i.e., when the pin is configured for
active-low logic, RisingEdge refers to the physical signal's
trailing edge, and FallingEdge refers to the physical signal's
rising edge.
Constructors
| Disabled | Interrupts are disabled |
| RisingEdge | Interrupt on the pin's (logical) rising edge |
| FallingEdge | Interrupt on the pin's (logical) falling edge |
| Level | Interrupt on any change to the pin's signal level |
Instances
MonadGpio class
class Monad m => MonadGpio h m | m -> h where Source #
A monad type class for GPIO computations. The type class specifies a DSL for writing portable GPIO programs, and instances of the type class provide the interpreter needed to run these programs on a particular GPIO platform.
In the type signature, h represents a (platform-dependent)
abstract pin handle for operating on opened pins. It is analogous
to a file handle.
Active-high versus active-low logic
The DSL supports both active-high and active-low logic. That
is, the active level of a GPIO pin can be configured as
ActiveHigh or ActiveLow. If a pin's active level is
ActiveHigh, then for that pin, a PinValue of High corresponds
to a "high" physical signal level, and a PinValue of Low
corresponds to a "low" physical signal level. The converse is true
when the pin's active level is ActiveLow.
Despite the potential confusion, the advantage of supporting
active-low logic is that you can, if you choose, write your program
in terms of "positive" logic (where High always means "on" and
Low always means "off"), and, with the same program, interface
with either positive (active-high) or negative (active-low) logic
simply by setting the pin's active level before running the
program.
In the documentation for this package, whenever you see a reference to a "pin value" or "signal level," unless otherwise noted, we mean the logical value or level, not the physical value or level; that is, we mean the abstract notion of the pin being "on" or "off," independent of the voltage level seen on the physical pin. If the pin is configured as active-high, then the logical and physical values are one and the same; if not, they are the inverse of each other.
Note that the active-high/active-low setting is per-pin; each pin's active level is independent of the others.
Not all platforms natively support active-low logic. On platforms without native support, the platform interpreter will invert values (both read and written) in software when a pin is configured as active-low.
Minimal complete definition
pins, pinCapabilities, openPin, closePin, getPinDirection, getPinInputMode, setPinInputMode, getPinOutputMode, setPinOutputMode, readPin, pollPin, pollPinTimeout, writePin, togglePin, getPinInterruptMode, setPinInterruptMode, getPinActiveLevel, setPinActiveLevel, togglePinActiveLevel
Methods
Get a list of available GPIO pins on the system.
This command makes a best-effort attempt to find the available pins, but some systems may not make the complete list available at runtime. Therefore, there may be more pins available than are returned by this action.
pinCapabilities :: Pin -> m PinCapabilities Source #
Query the pin's capabilities.
openPin :: Pin -> m h Source #
Open a pin for use and return a handle to it.
Note that on some platforms (notably Linux), pin handles are global resources and it is, strictly speaking, an error to attempt to open a pin which has already been opened. However, because there is generally no way to perform an atomic "only open the pin if it hasn't already been opened" operation on such platforms, this action will squash that particular error on those platforms and return the global handle anyway, without making any other state changes to the already-opened pin.
Keep in mind, however, that on these platforms where pin handles are global resources, closing one pin handle will effectively invalidate all other handles for the same pin. Be very careful to coordinate the opening and closing of pins if you are operating on the same pin in multiple threads.
closePin :: h -> m () Source #
Close the pin; i.e., indicate to the system that you no longer intend to use the pin via the given handle.
Note that on some platforms (notably Linux), pin handles are global resources and it is, strictly speaking, an error to attempt to close a pin which has already been closed via another handle to the same pin. However, this action will squash that error on those platforms and will simply return without making any changes to the GPIO environment.
Keep in mind, however, that on these platforms where pin handles are global resources, opening multiple handles for the same pin and then closing one of those handles will render all other handles for the same pin invalid. Be very careful to coordinate the opening and closing of pins if you are operating on the same pin in multiple threads.
Note that there are also platforms (again, notably certain Linux systems) where some pins are effectively always open and cannot be closed. Invoking this action on such a pin will squash any error that occurs when attempting to close the pin, and the action will simply return without making any changes to the GPIO environment.
getPinDirection :: h -> m PinDirection Source #
Get the pin's currently configured direction.
Note that there is no setPinDirection action. You set the pin's
direction indirectly by setting its input mode or output mode via
setPinInputMode and setPinOutputMode, respectively.
Rarely, a particular pin's direction may not be available in a
cross-platform way. In these cases, calling this action is an
error. In general, though, if the pin's capabilities indicate
that it supports at least one PinInputMode or PinOutputMode,
it's safe to call this action.
getPinInputMode :: h -> m PinInputMode Source #
Get the pin's input mode.
If the pin is not currently configured for input, it's an error to call this action.
setPinInputMode :: h -> PinInputMode -> m () Source #
Set the pin's input mode. This action will also set the pin's
direction to In.
It is an error to call this action if the given pin does not support the given input mode.
getPinOutputMode :: h -> m PinOutputMode Source #
Get the pin's output mode.
If the pin is not currently configured for output, it's an error to call this action.
setPinOutputMode :: h -> PinOutputMode -> PinValue -> m () Source #
Set the pin's output mode and value. This action will also set
the pin's direction to Out
If the pin is already in output mode and you only want to change
its value, use writePin.
It is an error to call this action if the given pin does not support the given output mode.
readPin :: h -> m PinValue Source #
Read the pin's value.
Note that this action never blocks.
pollPin :: h -> m PinValue Source #
Block the current thread until an event occurs on the pin which corresponds to the pin's current interrupt mode. Upon detection of the event, return the pin's value.
If the pin does not support interrupts, then this action's behavior is plaform-dependent.
It is an error to call this action when the pin is not configured for input.
Note: due to its interaction with the threading system, this
action may behave differently across different implementations of
Haskell. It has only been tested with GHC. (On GHC, you should
compile any program that uses this action with the -threaded
option.)
pollPinTimeout :: h -> Int -> m (Maybe PinValue) Source #
Same as pollPin, except with a timeout, specified in
microseconds. If no event occurs before the timeout expires, this
action returns Nothing; otherwise, it returns the pin's signal
level wrapped in a Just.
If the timeout value is negative, this action behaves just like
pollPin.
If the pin does not support interrupts, then this action's behavior is platform-dependent.
It is an error to call this action when the pin is not configured for input.
Note: due to its interaction with the threading system, this
action may behave differently across different implementations of
Haskell. It has only been tested with GHC. (On GHC, you should
compile any program that uses this action with the -threaded
option.)
writePin :: h -> PinValue -> m () Source #
Set the pin's output value.
It is an error to call this action when the pin is not configured for output.
togglePin :: h -> m PinValue Source #
Toggle the pin's output value and return the pin's new output value.
It is an error to call this action when the pin is not configured for output.
getPinInterruptMode :: h -> m PinInterruptMode Source #
Get the pin's interrupt mode.
If the pin does not support interrupts, it is an error to call this action.
(Note that RisingEdge and FallingEdge are relative to the
pin's active level; i.e., they refer to the pin's logical
signal edges, not its physical signal edges.)
setPinInterruptMode :: h -> PinInterruptMode -> m () Source #
Set the pin's interrupt mode (only when the pin is configured for input).
A pin's interrupt mode determines the behavior of the pollPin
and pollPinTimeout actions. Those actions will block the
current thread on an input pin until a particular event occurs on
that pin's signal waveform: a low-to-high transition
(RisingEdge), a high-to-low transition (FallingEdge), or any
change of level (Level).
You can also disable interrupts on the pin so that pollPin will
block the current thread indefinitely (or until a timer expires,
in the case of pollPinTimeout). This functionality is useful
when, for example, one thread is dedicated to servicing
interrupts on a pin, and another thread wants to mask interrupts
on that pin for some period of time.
Some pins (or even some GPIO platforms) may not support interrupts. In such cases, it is an error to call this action.
It is an error to use this action on a pin configured for output.
getPinActiveLevel :: h -> m PinActiveLevel Source #
Get the pin's active level.
setPinActiveLevel :: h -> PinActiveLevel -> m () Source #
Set the pin's active level.
togglePinActiveLevel :: h -> m PinActiveLevel Source #
Toggle the pin's active level. Returns the pin's new level.
Instances
| MonadGpio h m => MonadGpio h (MaybeT m) Source # | |
| MonadGpio h m => MonadGpio h (ListT m) Source # | |
| MonadGpio h m => MonadGpio h (CatchT m) Source # | |
| (Functor m, MonadCatch m, MonadMask m, MonadThrow m, MonadSysfs m) => MonadGpio PinDescriptor (SysfsGpioT m) Source # | |
| (MonadGpio h m, Monoid w) => MonadGpio h (WriterT w m) Source # | |
| (MonadGpio h m, Monoid w) => MonadGpio h (WriterT w m) Source # | |
| MonadGpio h m => MonadGpio h (StateT s m) Source # | |
| MonadGpio h m => MonadGpio h (StateT s m) Source # | |
| MonadGpio h m => MonadGpio h (ExceptT e m) Source # | |
| MonadGpio h m => MonadGpio h (IdentityT * m) Source # | |
| MonadGpio h m => MonadGpio h (ReaderT * r m) Source # | |
| MonadGpio h m => MonadGpio h (ContT * r m) Source # | |
| (MonadGpio h m, Monoid w) => MonadGpio h (RWST r w s m) Source # | |
| (MonadGpio h m, Monoid w) => MonadGpio h (RWST r w s m) Source # | |
withPin :: (MonadMask m, MonadGpio h m) => Pin -> (h -> m a) -> m a Source #
Exception-safe pin management.
withPin opens a pin using openPin and passes the handle to the
given GPIO computation. Upon completion of the computation, or an
exception occuring within the computation, withPin closes the
handle using closePin and then propagates the result, either by
returning the value of the computation or by re-raising the
exception.
Safer types
If you can restrict your use of a particular pin to just
one mode of operation (input, interrupt-driven input, or
output), you can achieve better type-safety than is
possible with the fully-general Pin type by using the
one of the following more limited types and its
corresponding actions.
A caveat
On some GPIO platforms (e.g., Linux sysfs), no provision
is made for opening pins in "exclusive mode," and as such,
pins can be opened and configured by any number of
processes on the system other than our own programs.
Therefore, even when using these safer types, a robust
hpio program should still be prepared to deal with
configuration-related errors in case another process
re-configures a pin while the hpio program is using it.
In other words, even when using these safer types, you
should still be prepared to handle the full range of
SomeGpioExceptions.
A handle to a pin that's been configured for non-blocking reads only.
You cannot poll an InputPin for interrupts. See InterruptPin.
withInputPin :: (MonadMask m, MonadGpio h m) => Pin -> PinInputMode -> Maybe PinActiveLevel -> (InputPin h -> m a) -> m a Source #
Like withPin, but for InputPins. Sets the pin's input mode to
the specified PinInputMode value.
If the optional active level argument is Nothing, then the pin's
active level is unchanged from its current state. Otherwise, the
pin's active level is set to the specified level.
It is an error to call this action if the pin cannot be configured for input, or if it does not support the specified input mode.
getInputPinInputMode :: MonadGpio h m => InputPin h -> m PinInputMode Source #
Like getPinInputMode.
getInputPinActiveLevel :: MonadGpio h m => InputPin h -> m PinActiveLevel Source #
Like getPinActiveLevel.
setInputPinActiveLevel :: MonadGpio h m => InputPin h -> PinActiveLevel -> m () Source #
Like setPinActiveLevel.
toggleInputPinActiveLevel :: MonadGpio h m => InputPin h -> m PinActiveLevel Source #
Like togglePinActiveLevel.
data InterruptPin h Source #
A handle to a pin that's been configured both for non-blocking reads and for interrupt-driven polling reads.
Instances
| Eq h => Eq (InterruptPin h) Source # | |
| Show h => Show (InterruptPin h) Source # | |
withInterruptPin :: (MonadMask m, MonadGpio h m) => Pin -> PinInputMode -> PinInterruptMode -> Maybe PinActiveLevel -> (InterruptPin h -> m a) -> m a Source #
Like withPin, but for InterruptPins. The pin is opened for
input, is input mode is set to the specified PinInputMode value,
and its interrupt mode is set to the specified PinInterruptMode
value.
If the optional active level argument is Nothing, then the pin's
active level is unchanged from its current state. Otherwise, the
pin's active level is set to the specified level.
It is an error to call this action if any of the following are true:
- The pin cannot be configured for input.
- The pin does not support the specified input mode.
- The pin does not support interrupts.
readInterruptPin :: MonadGpio h m => InterruptPin h -> m PinValue Source #
Like readPin.
pollInterruptPin :: MonadGpio h m => InterruptPin h -> m PinValue Source #
Like pollPin.
pollInterruptPinTimeout :: MonadGpio h m => InterruptPin h -> Int -> m (Maybe PinValue) Source #
Like pollPinTimeout.
getInterruptPinInputMode :: MonadGpio h m => InterruptPin h -> m PinInputMode Source #
Like getPinInputMode.
getInterruptPinInterruptMode :: (MonadThrow m, MonadGpio h m) => InterruptPin h -> m PinInterruptMode Source #
Like getPinInterruptMode.
setInterruptPinInterruptMode :: MonadGpio h m => InterruptPin h -> PinInterruptMode -> m () Source #
Like setPinInterruptMode.
getInterruptPinActiveLevel :: MonadGpio h m => InterruptPin h -> m PinActiveLevel Source #
Like getPinActiveLevel.
setInterruptPinActiveLevel :: MonadGpio h m => InterruptPin h -> PinActiveLevel -> m () Source #
Like setPinActiveLevel.
toggleInterruptPinActiveLevel :: MonadGpio h m => InterruptPin h -> m PinActiveLevel Source #
Like togglePinActiveLevel.
A handle to a pin that's been configured for output only.
Note that output pins can be both read and written. However, they only support non-blocking reads, not interrupt-driven polling reads.
withOutputPin :: (MonadMask m, MonadGpio h m) => Pin -> PinOutputMode -> Maybe PinActiveLevel -> PinValue -> (OutputPin h -> m a) -> m a Source #
Like withPin, but for OutputPins. Sets the pin's output mode
to the specified PinOutputMode value.
The PinValue argument specifies the pin's initial output value.
It is relative to the active level argument, or to the pin's
current active level if the active level argument is Nothing.
It is an error to call this action if the pin cannot be configured for output, or if it does not support the specified output mode.
getOutputPinOutputMode :: MonadGpio h m => OutputPin h -> m PinOutputMode Source #
Like getPinOutputMode.
getOutputPinActiveLevel :: MonadGpio h m => OutputPin h -> m PinActiveLevel Source #
Like getPinActiveLevel.
setOutputPinActiveLevel :: MonadGpio h m => OutputPin h -> PinActiveLevel -> m () Source #
Like setPinActiveLevel.
toggleOutputPinActiveLevel :: MonadGpio h m => OutputPin h -> m PinActiveLevel Source #
Like togglePinActiveLevel.
The GPIO exception hierarchy
Re-exported from System.GPIO.Types.
data SomeGpioException Source #
The top level of the GPIO exception hierarchy.
Constructors
| Exception e => SomeGpioException e |
Instances
gpioExceptionToException :: Exception e => e -> SomeException Source #
Convert SomeGpioException to SomeException.
gpioExceptionFromException :: Exception e => SomeException -> Maybe e Source #
Ask whether an exception is SomeGpioException.