Add comprehensive essential knowledge documentation for .NET IoT newcomers #2438

Copilot · 2025-11-06T17:01:04Z

Addresses #2262 by creating structured documentation for essential IoT concepts that were previously scattered or missing, reducing onboarding friction for new users.

Documentation Structure

Created four organizational directories:

fundamentals/ - Core concepts (GPIO basics, protocol comparison, driver selection, signal debouncing, datasheet reading)
protocols/ - Complete protocol guides with consistent structure (GPIO, I2C, SPI, PWM, UART/RS232/RS485)
platforms/ - Platform-specific guides (Raspberry Pi 5 GPIO chip changes)
deployment/ - Docker containers, systemd services, cross-compilation

Key Additions

Getting Started

getting-started.md - 5-minute LED blink tutorial with clear prerequisites and next steps

Fundamentals (5 new guides)

GPIO pin modes, pull-up/pull-down resistors, interrupts
Protocol decision guide (I2C vs SPI vs UART vs PWM with comparison table)
Driver selection (libgpiod vs sysfs, auto-detection, performance comparison)
Signal debouncing patterns with multiple implementation approaches
Datasheet reading guide (extracting register maps, timing, electrical specs)

Protocols (5 comprehensive guides)

All protocol documentation follows consistent structure:

What is the protocol? - Generic explanation with key features
Example - Working code sample
Platform setup - Enabling on Raspberry Pi
Advanced configuration - Custom pins, multiple devices, performance tuning
Troubleshooting - Common issues and solutions

GPIO - Consolidated GPIO fundamentals with GpioController and driver selection (LibGpiodDriver, RaspberryPi3Driver, SysFsDriver). Links to detailed fundamentals documentation.
I2C - Two-wire protocol for sensors and peripherals
SPI - High-speed four-wire protocol with chip select
PWM - Pulse width modulation for motor control and LED dimming
UART - Serial communication (RS232/RS485) for GPS, modems, and industrial devices

Reference

glossary.md - IoT/electronics terminology (150+ terms)
troubleshooting.md - Diagnostic decision trees for GPIO, I2C, SPI, UART, PWM failures
iot-project-setup.md - Project creation with .NET CLI and Visual Studio, including DI patterns

Platform-Specific

Raspberry Pi 5 guide highlighting critical GPIO chip number change (gpiochip0 → gpiochip4)

Deployment

Docker container guide with rootless security best practices and hardware device mounting

Updated Main README

Reorganized Documentation/README.md with progressive learning path:

Getting started → 2. Fundamentals → 3. Protocol setup → 4. Project creation → 5. Deployment

Simplified navigation hierarchy by moving "Learn the Fundamentals" directly under "New to .NET IoT? Start Here!" section for cleaner, more professional documentation structure.

Documentation Style

All documentation follows professional formatting standards:

Removed unicode emojis from all section titles and content (92 instances across 10 files)
Consistent structure across all protocol documentation
Generic protocol explanations before platform-specific details
Troubleshooting sections positioned at bottom of documents
Links to related documentation to avoid content duplication
Clean, professional appearance suitable for technical documentation

Example: Before vs After

Before: User searches through scattered docs to understand why button presses register multiple times.

After: User finds answer in two clicks:

README.md → Troubleshooting
troubleshooting.md → "Button Presses Register Multiple Times" → Links to fundamentals/debouncing.md

Complete code examples provided:

const int debounceMs = 50;
DateTime lastPress = DateTime.MinValue;

controller.RegisterCallbackForPinValueChangedEvent(pin, PinEventTypes.Falling,
    (sender, args) =>
    {
        if ((DateTime.UtcNow - lastPress).TotalMilliseconds >= debounceMs)
        {
            lastPress = DateTime.UtcNow;
            // Handle button press
        }
    });

Metrics

18 documentation files created/reorganized
16,800+ words of technical content
50+ complete C# code examples
All checklist items from Raspberry Pi 5 -> GPIO Package Can it Support as of Today ???? #2262 addressed
Consistent structure across all protocol documentation
Professional formatting with no unicode emojis

Original prompt

This section details on the original issue you should resolve

<issue_title>Creating the documentation with the essential knowledge (or links)</issue_title>
<issue_description>In the triage we observed questions on topics that can be considered essential knowledge to know when interfacing devices and sensors with our library.
We all agreed that it would be important creating one or more documents providing the «essentials» concepts useful for every user. This documentation is meant to collect only the topics that are not related to specific bindings.
These are the topics I suggest to include:

Please feel free to add other topics or suggest removing one or more of the above list.
</issue_description>

Comments on the Issue (you are @copilot in this section)

@krwq Here is what copilot came up with:

Documentation Strategy for Newbies

I'd like to suggest a comprehensive strategy to make the IoT library more accessible to newcomers:

1. Create a "Getting Started" Landing Page

Build a central Documentation/getting-started.md that serves as the main entry point for new users:

Quick Start: A 5-minute "Hello World" example (blink an LED)
Prerequisites: Hardware requirements, .NET installation, supported platforms
Common Pitfalls: Permission issues, GPIO access, common error messages
Navigation: Clear links to all essential topics below

2. Organize Documentation by User Journey

Structure documentation to match how users actually learn:

Phase 1: Setup (Day 1)

Hardware setup and verification
Permissions and GPIO access troubleshooting
First successful program

Phase 2: Understanding Fundamentals (Week 1)

GPIO basics (input/output, pull-up/pull-down resistors)
Understanding protocols: When to use I2C vs SPI vs UART
Driver selection guide (libgpiod vs sysfs)
Reading datasheets and wiring diagrams

Phase 3: Common Patterns (Week 2-4)

Debouncing signals (not tied to specific binding)
Handling interrupts and events
Power management considerations
Error handling best practices

Phase 4: Production (Advanced)

Deployment strategies
Container usage
Performance optimization
Hardware debugging tools

3. Add Practical Elements to Each Doc

Each documentation page should include:

Prerequisites: What you need to know/have before starting
Step-by-step instructions: With expected output at each step
Troubleshooting section: Common errors and solutions
Verification: How to confirm it's working correctly
Next steps: Where to go from here

4. Create Protocol-Specific Guides

Expand the existing I2C/SPI/PWM docs to include:

What is it?: Brief explanation for absolute beginners
When to use it?: Comparison with alternatives
How to verify it works: Using command-line tools (i2cdetect, etc.)
Common issues: With specific error messages and fixes
Pin configuration: Including alternatives and conflicts

Missing protocol docs to add:

UART/Serial (RS232/RS485)
1-Wire
GPIO basics (digital input/output fundamentals)

5. Interactive Troubleshooting Guide

Create Documentation/troubleshooting.md with:

Decision tree format: "Are you seeing error X? Try Y"
Diagnostic commands to run
Log interpretation guide
Platform-specific issues (Raspberry Pi vs others)

6. Glossary and Concepts

Add Documentation/glossary.md with:

Pull-up/pull-down resistors
Active high/low
Open drain/collector
Voltage levels (3.3V vs 5V)
Common abbreviations (GPIO, I2C, SPI, UART, PWM, etc.)

7. Platform-Specific Quickstart Guides

Create quick reference pages:

Documentation/platforms/raspberry-pi-5.md (already tracked in Raspberry Pi 5 -> GPIO Package Can it Support as of Today ???? #2262)
Documentation/platforms/raspberry-pi-4.md
Documentation/platforms/orange-pi.md
etc.

Each should include: GPIO pin...

Fixes Creating the documentation with the essential knowledge (or links) #2261

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Microsoft Reviewers: Open in CodeFlow

…ls, drivers, debouncing Co-authored-by: krwq <[email protected]>

Co-authored-by: krwq <[email protected]>

…ployment docs Co-authored-by: krwq <[email protected]>

Co-authored-by: krwq <[email protected]>

krwq · 2025-11-13T16:49:21Z

Documentation/README.md

-1. **System.Device.Gpio** library and tests which is the main library that has the implementation for protocols such as: GPIO, SPI, I2C, PWM. This library is fully supported by the dotnet team since it has the same level of support that dotnet/corefx does. All the code for the library lives under src/System.Device.Gpio. This library targets .NET Standard 2.0, and will work on both Windows and Linux. It's implementation consists of just IL code, so that means that it is supported across different platforms. In order to add new API to this library, an API Proposal would have to be submitted and approved first. [Here](https://github.com/dotnet/iot/issues/122) is an example of a how a good API proposal should look like.
-Doing a PR on this part of the project may result in API review, higher exigence for the code quality and longer discussions. You need to be ready for this.
-1. **Iot.Device.Bindings** device bindings library. This is a collection of types which work as wrappers (or bindings) for devices and sensors which are able to talk to a microcontroller unit (or MCU like a Raspberry Pi for example) using the protocols supported by System.Device.Gpio. For example: [BME280](../src/devices/Bmxx80/README.md) is a temperature sensor which uses SPI and I2C in order to communicate with a MCU and is able to report the current temperature. Because the process of how to compute the temperature from the data is not trivial, we have a `Bme280` class which exposes friendly methods like `ReadTemperature()` which will internally use either SPI or I2C to get the current temperature value. In order to start adding a new binding, check out our [guide on how to contribute a new binding](../tools/templates/DeviceBindingTemplate/README.md). It is worth noting that even though all device bindings will be built and packaged as a single library (Iot.Device.Bindings), the code is split under src/devices on individual projects for easier development of a single binding and developer inner-loop.
+## 📚 Essential Knowledge for Newcomers


@copilot remove unicode emojis from the title
also please just remove "Essential Knowledge for Newcomers" - "Learn the Fundamentals" can go directly under "New to .NET IoT? Start Here!"

Done in commit b6fbe45. Removed all unicode emojis from section titles and moved "Learn the Fundamentals" directly under "New to .NET IoT? Start Here!" by removing the "Essential Knowledge for Newcomers" section.

@copilot thanks, please proceed with similar changes in all the other files in this pull request

Done in commit e571139. Removed all unicode emojis (🎉 ✅ ❌ ⚠️) from 9 documentation files across the PR:

getting-started.md

fundamentals/choosing-drivers.md

fundamentals/debouncing.md

fundamentals/reading-datasheets.md

fundamentals/understanding-protocols.md

protocols/uart.md

deployment/containers.md

troubleshooting.md

iot-project-setup.md

Total of 92 emoji instances removed for consistent, professional documentation style.

Co-authored-by: krwq <[email protected]>

krwq

protocols should be basic information on the protocols - what they are, sample code, then advanced settings and troubleshooting section. I've put comments on GPIO and I2C as examples, apply it for all protocols. All relevant docs should be linked from there.

Make sure other files don't repeat the same info

krwq · 2025-12-18T16:37:10Z

Documentation/protocols/gpio.md

+   ```
+
+When not explicitly specified, dotnet iot automatically tries to find a driver compatible to what library version is installed.
+


We're missing tiny section on the RaspberryPi3Driver

Done in commit 1a5e30c. Added section on RaspberryPi3Driver in gpio.md, noting it's a legacy driver for backward compatibility and recommending LibGpiodDriver for new projects.

krwq · 2025-12-18T16:38:55Z

Documentation/protocols/gpio.md

+
+## Quick usage: blink LED example
+
+This example targets a RaspberryPi 3/4, see comments for more information:


There should be mentions on GpioDriver here and what this means

Done in commit 1a5e30c. Added comprehensive "GpioController and GPIO Drivers" section explaining the GpioController class and available driver implementations (LibGpiodDriver, RaspberryPi3Driver, SysFsDriver, Windows10Driver).

krwq · 2025-12-18T16:39:49Z

Documentation/protocols/gpio.md

+## Quick usage: blink LED example
+
+This example targets a RaspberryPi 3/4, see comments for more information:
+


Other GPIO basics should be included in this docs rather than separately (specifically chosing drivers and basics). Remaining/additional docs should be linked here

Done in commit 1a5e30c. Consolidated GPIO basics and choosing drivers content directly into protocols/gpio.md. The fundamentals files now serve as detailed references that are linked from the protocol documentation rather than duplicating content.

krwq · 2025-12-18T16:40:54Z

Documentation/protocols/i2c.md

@@ -0,0 +1,175 @@
+# Enabling I2C on Raspberry Pi


This should be generic title, enabling should be a sub-section.

Done in commit 1a5e30c. Changed title from "Enabling I2C on Raspberry Pi" to generic "I2C (Inter-Integrated Circuit)". Enabling is now a subsection under platform-specific setup.

krwq · 2025-12-18T16:41:26Z

Documentation/protocols/i2c.md

@@ -0,0 +1,175 @@
+# Enabling I2C on Raspberry Pi
+
+If you want to use the I2C capabilities of your Raspberry Pi, you will need to activate this feature. And if you want to run your code without elevated root privileged to access them, then, you may as well need to make couple of modifications. This tutorial is here to help you activating I2C and making sure you'll get the right permissions.


This should say what I2C is, link to extra reading materials rather than going into RPi specific stuff.

Done in commit 1a5e30c. Added "What is I2C?" section at the beginning explaining the protocol generically, including what it is, key features, common devices, and links to external reading materials.

krwq · 2025-12-18T16:41:39Z

Documentation/protocols/i2c.md

+
+If you want to use the I2C capabilities of your Raspberry Pi, you will need to activate this feature. And if you want to run your code without elevated root privileged to access them, then, you may as well need to make couple of modifications. This tutorial is here to help you activating I2C and making sure you'll get the right permissions.
+
+## Basic Hardware I2C code


Just "example"

Done in commit 1a5e30c. Changed section title from "Basic Hardware I2C code" to "Example".

krwq · 2025-12-18T16:42:04Z

Documentation/protocols/i2c.md

+If you get an error message like this one, it means I2C has not been properly enabled:
+
+```text
+Hello I2C!


This should be somewhere in the bottom in the Troubleshooting section or similar

Done in commit 1a5e30c. Moved troubleshooting content to bottom of the document in dedicated "Troubleshooting" section.

…, examples, advanced config, troubleshooting Co-authored-by: krwq <[email protected]>

Copilot · 2025-12-18T16:51:48Z

protocols should be basic information on the protocols - what they are, sample code, then advanced settings and troubleshooting section. I've put comments on GPIO and I2C as examples, apply it for all...

Done in commit 1a5e30c. Restructured all protocol files (GPIO, I2C, SPI, PWM, UART) to follow consistent format:

What the protocol is (generic information)
Basic code example
Enabling/setup instructions
Advanced configuration
Troubleshooting section at bottom

All protocol docs now link to related fundamentals documentation instead of repeating content.

Co-authored-by: krwq <[email protected]>

Copilot AI self-assigned this Nov 6, 2025

Initial plan

b298b58

Copilot AI assigned krwq Nov 6, 2025

dotnet-policy-service bot added area-System.Device.Gpio Contains types for using general-purpose I/O (GPIO) pins area-device-bindings Device Bindings for audio, sensor, motor, and display hardware that can used with System.Device.Gpio labels Nov 6, 2025

Copilot started work on behalf of krwq November 6, 2025 17:01 View session

Copilot AI and others added 5 commits November 6, 2025 17:08

Add fundamentals documentation: getting-started, gpio-basics, protoco…

9b74b83

…ls, drivers, debouncing Co-authored-by: krwq <[email protected]>

Add reading-datasheets guide and protocol documentation including UART

85be084

Co-authored-by: krwq <[email protected]>

Add platform guides, glossary, troubleshooting, project setup, and de…

833984e

…ployment docs Co-authored-by: krwq <[email protected]>

Update main Documentation README with new structure and navigation

24108f0

Co-authored-by: krwq <[email protected]>

Fix variable name inconsistency in gpio.md code example

9668133

Co-authored-by: krwq <[email protected]>

Copilot AI changed the title ~~[WIP] Create documentation for essential knowledge on interfacing devices~~ Add comprehensive essential knowledge documentation for .NET IoT newcomers Nov 6, 2025

Copilot AI requested a review from krwq November 6, 2025 17:29

Copilot finished work on behalf of krwq November 6, 2025 17:29

krwq reviewed Nov 13, 2025

View reviewed changes

Copilot started work on behalf of krwq November 13, 2025 16:52 View session

Remove unicode emojis from section titles and reorganize structure

b6fbe45

Co-authored-by: krwq <[email protected]>

Copilot AI requested a review from krwq November 13, 2025 16:57

Copilot finished work on behalf of krwq November 13, 2025 16:57

Copilot started work on behalf of krwq November 13, 2025 16:58 View session

Remove unicode emojis from all documentation files

e571139

Co-authored-by: krwq <[email protected]>

Copilot finished work on behalf of krwq November 13, 2025 17:10

krwq requested changes Dec 18, 2025

View reviewed changes

dotnet-policy-service bot added the Needs: Author Feedback We are waiting for author to react to feedback (action required) label Dec 18, 2025

Copilot started work on behalf of krwq December 18, 2025 16:44 View session

Restructure protocol documentation with consistent format: what it is…

1a5e30c

…, examples, advanced config, troubleshooting Co-authored-by: krwq <[email protected]>

dotnet-policy-service bot removed the Needs: Author Feedback We are waiting for author to react to feedback (action required) label Dec 18, 2025

Remove backup file accidentally committed

5e2bb42

Co-authored-by: krwq <[email protected]>

Copilot AI requested a review from krwq December 18, 2025 16:53

Copilot finished work on behalf of krwq December 18, 2025 16:53

		```

		When not explicitly specified, dotnet iot automatically tries to find a driver compatible to what library version is installed.


		## Quick usage: blink LED example

		This example targets a RaspberryPi 3/4, see comments for more information:

		@@ -0,0 +1,175 @@
		# Enabling I2C on Raspberry Pi

		If you want to use the I2C capabilities of your Raspberry Pi, you will need to activate this feature. And if you want to run your code without elevated root privileged to access them, then, you may as well need to make couple of modifications. This tutorial is here to help you activating I2C and making sure you'll get the right permissions.


		If you want to use the I2C capabilities of your Raspberry Pi, you will need to activate this feature. And if you want to run your code without elevated root privileged to access them, then, you may as well need to make couple of modifications. This tutorial is here to help you activating I2C and making sure you'll get the right permissions.

		## Basic Hardware I2C code

Add comprehensive essential knowledge documentation for .NET IoT newcomers #2438

Are you sure you want to change the base?

Add comprehensive essential knowledge documentation for .NET IoT newcomers #2438

Uh oh!

Conversation

Copilot AI commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Structure

Key Additions

Updated Main README

Documentation Style

Example: Before vs After

Metrics

Comments on the Issue (you are @copilot in this section)

Documentation Strategy for Newbies

1. Create a "Getting Started" Landing Page

2. Organize Documentation by User Journey

3. Add Practical Elements to Each Doc

4. Create Protocol-Specific Guides

5. Interactive Troubleshooting Guide

6. Glossary and Concepts

7. Platform-Specific Quickstart Guides

Microsoft Reviewers: Open in CodeFlow

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

krwq left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Copilot AI commented Nov 6, 2025 •

edited

Loading