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
pull/581/head
Hiroshi Yoshioka 2 weeks ago committed by GitHub
parent 6ae558ee2b
commit 66c6997a61
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

@ -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
```

Loading…
Cancel
Save