internals/docs/guides/peripheral-gpio.md

   1 # GPIO
   2
   3 [GPIO](https://en.wikipedia.org/wiki/General-purpose_input/output) (General-Purpose Input/Output) is a programmable interface for reading the state of binary input peripherals, such as a switch, and controlling the state of binary output peripherals, such as a LED.
   4
   5 GPIO sets a direction for the data transfer. It can also detect an interrupt signaled by a level transition: either a falling edge (high to low) or a rising edge (low to high). To detect the interrupt signal you want, set the appropriate edge mode.
   6
   7 GPIO offers the following edge modes:
   8
   9 -   Rising mode detects data changes from low to high.
  10 -   Falling mode detects data changes from high to low.
  11
  12 **Figure: GPIO edge modes**
  13
  14 ![GPIO edge modes](media/peri_api_gpio.png)
  15
  16 ## Opening and Closing a Handle
  17
  18 To open and close a handle:
  19
  20 1.  To open a GPIO handle, create `GpioPin` object:
  21
  22     ```csharp
  23     int pin = 26; /* Raspberry Pi 3 and Raspberry Pi 4 : GPIO26 */
  24     GpioPin gpio = new GpioPin(pin, GpioPinDriveMode.Input);
  25     ```
  26
  27     The `pin` parameter required for this function must be set according to the following tables.
  28
  29     **Table: Raspberry Pi 3 and Raspberry Pi 4**
  30
  31       Pin name  |Pin (parameter 1)  |Pin name  |Pin (parameter 1)
  32       ----------|-------------------|----------|-------------------
  33       GPIO4     |4                  |GPIO5     |5
  34       GPIO6     |6                  |GPIO12    |12
  35       GPIO13    |13                 |GPIO16    |16
  36       GPIO17    |17                 |GPIO18    |18
  37       GPIO19    |19                 |GPIO20    |20
  38       GPIO21    |21                 |GPIO22    |22
  39       GPIO23    |23                 |GPIO24    |24
  40       GPIO25    |25                 |GPIO26    |26
  41       GPIO27    |27                 |-         |-
  42
  43     > **Note**
  44     >
  45     >  For more information on the pin names and locations, see [Supported Protocols](peripheral.md#protocol).
  46
  47 2.  To close a GPIO handle that is no longer used, use the `gpio.Close()` method:
  48
  49     ```csharp
  50     gpio.Close();
  51     ```
  52
  53 ## Setting the Data Direction
  54
  55 Gpio object constructor expect the data transfer direction parameter. It can be set to:
  56
  57 -   `GpioPinDriveMode.Input`: Input mode to receive data from a binary output peripheral.
  58 -   `GpioPinDriveMode.OutputInitiallyLow`: Output mode to send data to a binary output peripheral. This value initializes the output peripheral state as low.
  59 -   `GpioPinDriveMode.OutputInitiallyHigh`: Output mode to send data to a binary output peripheral. This value initializes the output peripheral state as high.
  60
  61 > **Note**
  62 >
  63 > To set the data direction to `GpioPinDriveMode.OutputInitiallyHigh` or `GpioPinDriveMode.OutputInitiallyLow`, the edge mode must be set to `GpioChangePolarity.None`.
  64
  65
  66 ## Setting the Edge Mode
  67
  68 To set the edge mode, use the `gpio.Polarity` property with 1 of the following edge mode types:
  69
  70 -   `GpioChangePolarity.None`: No edge mode.
  71 -   `GpioChangePolarity.Rising`: Interrupted at a rising edge (low to high).
  72 -   `GpioChangePolarity.Falling`: Interrupted at a falling edge (high to low).
  73 -   `GpioChangePolarity.Both`: Interrupted at both rising and falling edges.
  74
  75 ```csharp
  76 GpioPin.Polarity(GpioChangePolarity);
  77 ```
  78
  79 > **Note**
  80 >
  81 > To set the edge mode to `GpioChangePolarity.Rising`, `GpioChangePolarity.Falling`, or `GpioChangePolarity.Both`, the data direction must be set to the `GpioPinDriveMode.Input`.
  82
  83
  84 ## Setting the Interrupted Callback
  85
  86 The interrupted event handler is called when the GPIO state changes, based on the selected edge mode.
  87
  88 To implement the interrupted callback:
  89
  90 1.  Subscribe to the interrupted event handler.
  91
  92     ```csharp
  93     GpioPin gpio;
  94     gpio.ValueChanged += myEventHandler;
  95     ```
  96 2.  When no longer needed, unsubscribe the interrupt event handler:
  97
  98     ```csharp
  99     gpio.ValueChanged -= myEventHandler;
 100     ```
 101
 102 ## Reading and Writing Binary Data
 103
 104 To read and write binary data:
 105
 106 -   To read binary data from a peripheral, use the `GpioPin.Read()` method:
 107
 108     ```csharp
 109     GpioPinValue value;
 110     value = gpio.Read();
 111     ```
 112
 113 -   To write binary data to a peripheral, use the `GpioPin.Write()` method:
 114
 115     ```csharp
 116     GpioPinValue value = GpioPinValue.Low;
 117     gpio.Write(value);
 118     ```
 119
 120 > **Note**
 121 >
 122 > To write binary data, the data direction must be set to `GpioPinDriveMode.OutputInitiallyHigh` or `GpioPinDriveMode.OutputInitiallyLow`.