Add GPIO beginners guide and fix incorrect API references in libgpiod docs by Copilot · Pull Request #2493 · dotnet/iot

Copilot · 2026-04-09T15:49:51Z

Extracts GPIO documentation from #2438, rewritten for newcomers to IoT. Preserves the directory structure from the original PR (protocols/, fundamentals/). Removes irrelevant topics (Docker, deployment, systemd). Also fixes incorrect API references in the existing gpio-linux-libgpiod.md.

New: `Documentation/protocols/gpio.md`

Main GPIO protocol guide covering:

Table of contents for easy navigation
Quick-start LED blink with wiring diagram
Pin numbering (BCM vs physical) demystified, with pinout.xyz reference
Digital input introduction with button wiring and pull-up explanation
Pin modes, reading/writing, and interrupt-driven events
Complete button-controlled LED example
GpioController and driver overview with auto-detection table
Driver descriptions: RaspberryPi3Driver (fast direct memory access, requires root), SysFsDriver (slow but universal, deprecated)
Troubleshooting section including Pi 5 GPIO chip detection with bash snippet and kernel update guidance
Best practices

New: `Documentation/fundamentals/gpio-basics.md`

Deep dive on GPIO fundamentals:

Digital output and input concepts
Pull-up/pull-down resistors and why floating pins are bad
Interrupt-driven input with event types
Current and voltage limitations (3.3 V safety, ~15 mA with 220 Ω resistor, standard 20 mA indicator LEDs only — high-brightness LEDs should not be attached to GPIO directly)
Pin mode summary table
Common GPIO pins on Raspberry Pi

New: `Documentation/fundamentals/choosing-drivers.md`

Driver selection guide:

Quick comparison table (LibGpiodDriver vs SysFsDriver)
Auto-detection behavior per board
Explicit driver selection with code examples
Installing libgpiod and permission configuration
Summary decision table

Fixed: `Documentation/gpio-linux-libgpiod.md`

The existing doc had three references to API surface that doesn't exist:

// ❌ These don't exist
new GpioController(chipNumber);
new LibGpiodDriver(chipNumber, LibGpiodDriverVersion.V1);
// env var DOTNET_IOT_LIBGPIOD_DRIVER_VERSION also doesn't exist

// ✅ Actual API
new GpioController();
new GpioController(new LibGpiodDriver(gpioChip: 0));
new GpioController(new LibGpiodV2Driver(chipNumber: 0));

Also fixed variable name mismatch (gpioController vs controller) in the blink example, and documented that LibGpiodDriver and LibGpiodV2Driver are separate classes (not selected via an enum).

Updated: `Documentation/README.md`

Added links to all new GPIO guides in the GPIO section.

… docs Agent-Logs-Url: https://github.com/dotnet/iot/sessions/125709c9-1313-48ad-8388-a71a2989a941 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

… button logic Agent-Logs-Url: https://github.com/dotnet/iot/sessions/125709c9-1313-48ad-8388-a71a2989a941 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

krwq · 2026-04-09T15:50:30Z

@copilot please preserve paths from the original PR

….md, fundamentals/gpio-basics.md, fundamentals/choosing-drivers.md) Agent-Logs-Url: https://github.com/dotnet/iot/sessions/c24b48b9-932c-4ad1-a39d-b2fca64a84a2 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Copilot · 2026-04-09T15:56:19Z

@copilot please preserve paths from the original PR

Restructured to match the original PR #2438 paths in commit 49cc9bf:

Documentation/protocols/gpio.md
Documentation/fundamentals/gpio-basics.md
Documentation/fundamentals/choosing-drivers.md

The flat gpio-beginners-guide.md has been removed.

krwq · 2026-04-16T15:40:03Z

+
+## What You Need
+
+- A **Raspberry Pi** (3, 4, or 5) running Raspberry Pi OS


any gpio board should be ok as long as it has unix and libgpiod installed

One of the Raspberry Pis can be mentioned as an example though

Updated in 7f680f7 — "What You Need" now says "A Linux single-board computer with GPIO headers and libgpiod installed" with Raspberry Pi mentioned as an example.

krwq · 2026-04-16T15:41:52Z

+using System.Device.Gpio;
+using System.Threading;
+
+const int ledPin = 18; // GPIO 18 = physical pin 12 on Raspberry Pi


would be nice to point to https://pinout.xyz/ for reference

Added in 7f680f7 — the quick-start code comment now includes a link to pinout.xyz: // GPIO 18 = physical pin 12 on Raspberry Pi (see https://pinout.xyz/)

krwq · 2026-04-16T15:46:02Z

+controller.OpenPin(18, PinMode.Output);
+
+// Input with pull-up resistor (default HIGH, button press = LOW)
+controller.OpenPin(17, PinMode.InputPullUp);


there is no background on what input is and how it works or connect but we're going straight from output tutorial to pull downs/ups

Added a new "Digital Input" section in 7f680f7 that introduces what input is, shows a basic read example, illustrates button wiring, and explains why InputPullUp is needed — all before presenting the pin modes table.

raffaeler · 2026-04-16T15:46:09Z

+4. **Use resistors with LEDs** — Calculate the value or use 220 Ω as a safe default
+5. **Check pin assignments** — Some GPIO pins are shared with I2C, SPI, or UART; using them for general GPIO disables those interfaces
+6. **Document your pin usage** — Especially in projects using multiple pins
+


@copilot you should mention that this will lead to 15mA current. Therefore a normal 20mA led is expected in this example and that high-brightness leds should not be attached to GPIO directly.

Added in 7f680f7 — both the "Driving an LED" section and the best practices list now mention the ~15 mA current with a 220 Ω resistor, that this is fine for standard 20 mA indicator LEDs, and that high-brightness/power LEDs should not be connected to GPIO directly.

…uction, add LED current notes Agent-Logs-Url: https://github.com/dotnet/iot/sessions/c7565b37-f74a-44ad-8f38-5993f685f665 Co-authored-by: raffaeler <5183152+raffaeler@users.noreply.github.com>

krwq · 2026-04-16T15:51:01Z

+| `LibGpiodDriver` | Modern Linux with libgpiod v1 — the recommended default |
+| `LibGpiodV2Driver` | Modern Linux with libgpiod v2 |
+| `RaspberryPi3Driver` | Raspberry Pi 3/4 — auto-selected, legacy direct memory access |
+| `SysFsDriver` | Very old Linux kernels (pre-4.8) only — **deprecated** |


should probably also mention that it's very slow but also supported on any linux version

Updated in b1791c7 — SysFsDriver now reads: "Very slow but works on any Linux version — deprecated".

krwq · 2026-04-16T15:54:05Z

+| --- | --- |
+| `LibGpiodDriver` | Modern Linux with libgpiod v1 — the recommended default |
+| `LibGpiodV2Driver` | Modern Linux with libgpiod v2 |
+| `RaspberryPi3Driver` | Raspberry Pi 3/4 — auto-selected, legacy direct memory access |


it should focus on "very fast because of direct memory access" but also requires root permissions and it's not recommended way. For certain cases it's necessary to use it

Updated in b1791c7 — RaspberryPi3Driver now reads: "very fast (direct memory access) but requires root permissions; not recommended unless you specifically need the performance".

krwq · 2026-04-16T15:57:47Z

+
+## Raspberry Pi 5 Note
+
+Raspberry Pi 5 moved its GPIO to a different chip number. If you are explicitly constructing a driver, use chip **4** instead of 0:


This has been fixed in the recent versions of the kernel, no need to mention that really or mention that if 0 doesn't work and you're on pi 5 then occasionally it may be 4 but it's recommended to update kernel instead. You may also add tiny bash snippet how to detect it by looking at number of pins on each chip

maybe troubleshooting section for this

Reworked in b1791c7 — removed the dedicated Pi 5 section and moved it to a "Wrong GPIO Chip on Raspberry Pi 5" troubleshooting entry. It now recommends updating the kernel first, and includes a bash snippet to detect the correct chip by counting lines on each /dev/gpiochip*.

krwq · 2026-04-16T15:58:36Z

@@ -0,0 +1,292 @@
+# GPIO (General-Purpose Input/Output)


also add table of content here

Added in b1791c7 — table of contents with links to all sections.

krwq · 2026-04-16T15:59:43Z

@copilot please fix the comments

…sue to troubleshooting Agent-Logs-Url: https://github.com/dotnet/iot/sessions/150e5c2f-9425-4ea1-8bb6-d2655685087e Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Agent-Logs-Url: https://github.com/dotnet/iot/sessions/150e5c2f-9425-4ea1-8bb6-d2655685087e Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Copilot AI and others added 2 commits April 9, 2026 15:42

Add GPIO beginners guide and fix incorrect API references in libgpiod…

42862ef

… docs Agent-Logs-Url: https://github.com/dotnet/iot/sessions/125709c9-1313-48ad-8388-a71a2989a941 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Address review feedback: improve debouncing note and clarify inverted…

ab3104e

… button logic Agent-Logs-Url: https://github.com/dotnet/iot/sessions/125709c9-1313-48ad-8388-a71a2989a941 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Copilot AI assigned Copilot and krwq Apr 9, 2026

Copilot created this pull request from a session on behalf of krwq April 9, 2026 15:49 View session

Copilot started work on behalf of krwq April 9, 2026 15:50 View session

Copilot AI requested a review from krwq April 9, 2026 15:57

Copilot finished work on behalf of krwq April 9, 2026 15:57

krwq reviewed Apr 16, 2026

View reviewed changes

raffaeler reviewed Apr 16, 2026

View reviewed changes

Copilot started work on behalf of raffaeler April 16, 2026 15:46 View session

Address review feedback: broaden board requirements, add input introd…

7f680f7

…uction, add LED current notes Agent-Logs-Url: https://github.com/dotnet/iot/sessions/c7565b37-f74a-44ad-8f38-5993f685f665 Co-authored-by: raffaeler <5183152+raffaeler@users.noreply.github.com>

Copilot finished work on behalf of raffaeler April 16, 2026 15:50

Copilot AI requested a review from raffaeler April 16, 2026 15:50

krwq reviewed Apr 16, 2026

View reviewed changes

Copilot started work on behalf of krwq April 16, 2026 15:59 View session

Copilot AI and others added 2 commits April 16, 2026 16:02

Add table of contents, improve driver descriptions, move Pi 5 chip is…

b1791c7

…sue to troubleshooting Agent-Logs-Url: https://github.com/dotnet/iot/sessions/150e5c2f-9425-4ea1-8bb6-d2655685087e Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Clarify driver table descriptions per code review feedback

0fc38b1

Agent-Logs-Url: https://github.com/dotnet/iot/sessions/150e5c2f-9425-4ea1-8bb6-d2655685087e Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Copilot finished work on behalf of krwq April 16, 2026 16:05

Copilot AI requested a review from krwq April 16, 2026 16:05


		## What You Need

		- A Raspberry Pi (3, 4, or 5) running Raspberry Pi OS


		## Raspberry Pi 5 Note

		Raspberry Pi 5 moved its GPIO to a different chip number. If you are explicitly constructing a driver, use chip 4 instead of 0:

Conversation

Copilot AI commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New: Documentation/protocols/gpio.md

New: Documentation/fundamentals/gpio-basics.md

New: Documentation/fundamentals/choosing-drivers.md

Fixed: Documentation/gpio-linux-libgpiod.md

Updated: Documentation/README.md

Uh oh!

krwq commented Apr 9, 2026

Uh oh!

Copilot AI commented Apr 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

krwq Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

krwq Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

krwq commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 9, 2026 •

edited

Loading

New: `Documentation/protocols/gpio.md`

New: `Documentation/fundamentals/gpio-basics.md`

New: `Documentation/fundamentals/choosing-drivers.md`

Fixed: `Documentation/gpio-linux-libgpiod.md`

Updated: `Documentation/README.md`

krwq Apr 16, 2026 •

edited

Loading

krwq Apr 16, 2026 •

edited

Loading