From 66c6997a614ed5000dd50e511649a3a2dd910f4b Mon Sep 17 00:00:00 2001
From: Hiroshi Yoshioka <40815708+hyoshioka0128@users.noreply.github.com>
Date: Sun, 13 Sep 2026 06:21:04 +0900
Subject: [PATCH] Enhance troubleshooting.md with fixes and formatting

Updated troubleshooting documentation with formatting improvements and additional details for common issues.
https://github.com/microsoft/IoT-For-Beginners/blob/main/docs/troubleshooting.md
#PingMSFTDocs
---
 docs/troubleshooting.md | 94 ++++++++++++++++++++++++++---------------
 1 file changed, 61 insertions(+), 33 deletions(-)

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 9f9e7acfb..e426614a7 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -10,49 +10,72 @@ It is designed for beginners following the IoT-For-Beginners curriculum, but is
 ### ❗ `ModuleNotFoundError: No module named 'xyz'`
 This happens when required Python modules are not installed.
 
-**Fix**
+**Fix:**
 ```bash
 pip3 install <module_name>
+```
 
- Permission denied when running scripts
-
+### ❗ Permission denied when running scripts
 Often caused by accessing GPIO, I2C or system hardware without elevated privileges.
-Quick fix:
+
+**Quick fix:**
+```bash
 sudo python3 script.py
+```
 
-Recommended fix (no sudo needed every time):
-sudo usermod -aG gpio,i2c,spi $USER
+**Recommended fix (avoids using `sudo` every time):**
+```bash
+sudo usermod -aG gpio,i2c,spi \$USER
 sudo reboot
+```
 
-2. GPIO / I2C / SPI Not Working
-❗ RuntimeError: No access to GPIO
+---
+
+## 2. GPIO / I2C / SPI Not Working
+
+### ❗ `RuntimeError: No access to GPIO`
 
 Add user to GPIO group:
-sudo usermod -aG gpio $USER
+```bash
+sudo usermod -aG gpio \$USER
 sudo reboot
+```
 
 ❗ I2C / SPI devices not detected
 
-Enable interfaces:
-sudo raspi-config
-→ Interface Options
-→ Enable I2C / Enable SPI
+1. Enable interfaces:
+   ```bash
+   sudo raspi-config
+   ```
+   → **Interface Options**
+   
+   → **Enable I2C** / **Enable SPI**
+2. Check if the I2C device appears:
+   ```bash
+   i2cdetect -y 1
+   ```
 
-Check if I2C device appears:
-i2cdetect -y 1
+---
 
-3. Camera / Video Issues
+## 3. Camera / Video Issues
 ❗ Camera not detected or fails to start
 
-Enable camera interface:
-sudo raspi-config
-→ Interface Options → Camera → Enable
-sudo reboot
-
-Check if camera is visible:
-vcgencmd get_camera
+1. Enable camera interface:
+   ```bash
+   sudo raspi-config
+   ```
+   → **Interface Options** → **Camera** → **Enable**
+2. Reboot the system:
+   ```bash
+   sudo reboot
+   ```
+3. Check if the camera is visible:
+   ```bash
+   vcgencmd get_camera
+   ```
 
 4. Wi-Fi / SSH / Connectivity Problems
+
 | Problem                          | Fix                                           |
 | -------------------------------- | --------------------------------------------- |
 | SSH connection refused           | `sudo raspi-config → Interface Options → SSH` |
@@ -60,9 +83,11 @@ vcgencmd get_camera
 | Slow Wi-Fi / unstable connection | Prefer 2.4 GHz band, update OS                |
 | Unable to access Pi headless     | Add `ssh` file to boot partition              |
 
+---
+
+## 5. Performance Issues
 
-5. Performance Issues
-Raspberry Pi running slow / laggy
+### ❗ Raspberry Pi running slow / laggy
 
 Close unused applications
 
@@ -72,11 +97,14 @@ Use Lite OS if no desktop needed
 
 Ensure sufficient power supply (5V/3A or better)
 
-Check CPU load:
-top
-htop
-
-Storage issues:
-sudo apt autoremove
-sudo apt clean
-df -h
+* **Check CPU / Memory load:** 
+  ```bash
+  top
+  htop
+  ```
+* **Storage issues:**
+  ```bash
+  sudo apt autoremove
+  sudo apt clean
+  df -h
+  ```