# Посібник з Усунення Неполадок

Цей посібник допоможе вам вирішити поширені проблеми під час роботи з навчальним курсом IoT для початківців. Проблеми організовані за категоріями для зручної навігації.

## Зміст

- [Проблеми з Встановленням](../..)
  - [Встановлення Python](../..)
  - [VS Code та Розширення](../..)
  - [PlatformIO (Wio Terminal)](../..)
  - [Бібліотеки Grove](../..)
- [Проблеми з Апаратним Забезпеченням](../..)
  - [Raspberry Pi](../..)
  - [Wio Terminal](../..)
  - [Віртуальний Пристрій (CounterFit)](../..)
- [Проблеми з Підключенням](../..)
  - [WiFi Підключення](../..)
  - [Хмарні Сервіси](../..)
  - [MQTT](../..)
- [Проблеми з Датчиками та Виконавчими Механізмами](../..)
  - [Grove Датчики](../..)
  - [Камера](../..)
  - [Мікрофон та Динамік](../..)
- [Проблеми з Розробницьким Середовищем](../..)
  - [VS Code](../..)
  - [Віртуальні Середовища Python](../..)
  - [Залежності](../..)
- [Проблеми з Продуктивністю](../..)
- [Типові Повідомлення про Помилки](../..)
- [Отримання Допомоги](../..)

---

## Проблеми з Встановленням

### Встановлення Python

#### Проблема: версія Python занадто стара
**Помилка:** `Потрібен Python 3.6 або новіший`

**Рішення:**
1. Завантажте останню версію Python 3 з [python.org](https://www.python.org/downloads/)
2. Під час встановлення на Windows позначте "Add Python to PATH"
3. Перевірте встановлення:
   ```bash
   python3 --version
   ```

#### Проблема: конфлікти через кілька версій Python
**Симптоми:** Запускається неправильна версія Python, пакети встановлюються не в те розташування

**Рішення:**
- **Windows:** Використовуйте `py -3` замість `python` щоб явно викликати Python 3
- **macOS/Linux:** Використовуйте `python3` замість `python`
- Завжди створюйте і використовуйте віртуальні середовища для проектів

#### Проблема: команда pip не знайдена
**Помилка:** `'pip' не розпізнано як внутрішня або зовнішня команда`

**Рішення:**
1. Спробуйте `pip3` замість `pip`
2. Або використовуйте `python -m pip` чи `python3 -m pip`
3. Переконайтеся, що Python додано в PATH (переінсталюйте Python і перевірте цей пункт)

### VS Code та Розширення

#### Проблема: розширення Pylance не працює
**Симптоми:** Немає IntelliSense Python, автозаповнення коду або перевірки типів

**Рішення:**
1. Відкрийте палітру команд VS Code (`Ctrl+Shift+P` або `Cmd+Shift+P`)
2. Виконайте "Python: Select Interpreter"
3. Виберіть правильний інтерпретатор Python (віртуальне середовище, якщо використовується)
4. Перезавантажте вікно VS Code

#### Проблема: VS Code не знаходить віртуальне середовище
**Симптоми:** Вибрано неправильний інтерпретатор Python

**Рішення:**
1. Переконайтеся, що віртуальне середовище активоване в терміналі
2. Відкрийте палітру команд і виконайте "Python: Select Interpreter"
3. Оберіть інтерпретатор з папки `.venv`
4. Перевірте, що у статусному рядку (внизу зліва) показана правильна версія Python

### PlatformIO (Wio Terminal)

#### Проблема: не вдається встановити PlatformIO
**Помилка:** Різні помилки під час встановлення PlatformIO

**Рішення:**
1. Переконайтеся, що VS Code оновлений
2. Встановіть спочатку розширення C/C++
3. Перезавантажте VS Code після встановлення PlatformIO
4. Перевірте стабільність інтернет-з’єднання (PlatformIO завантажує великі файли)

#### Проблема: PlatformIO не виявляє плату
**Симптоми:** Не вдається завантажити код на Wio Terminal

**Рішення:**
1. Спробуйте інший USB-кабель (деякі кабелі тільки для заряджання)
2. Перевірте диспетчер пристроїв (Windows) або `ls /dev/tty*` (macOS/Linux)
3. Встановіть або оновіть драйвери USB
4. Спробуйте інший USB-порт
5. Подвійно швидко сдвиньте перемикач живлення на Wio Terminal, щоб увійти в режим завантажувача

#### Проблема: помилки компіляції в PlatformIO
**Помилка:** `fatal error: Arduino.h: No such file or directory`

**Рішення:**
1. Видаляйте папку `.pio` у вашому проєкті
2. Виконайте "PlatformIO: Rebuild" в палітрі команд
3. Переконайтеся, що в `platformio.ini` вказано правильну конфігурацію плати:
   ```ini
   [env:seeed_wio_terminal]
   platform = atmelsam
   board = seeed_wio_terminal
   framework = arduino
   ```

### Бібліотеки Grove

#### Проблема: не вдається імпортувати бібліотеку Grove на Raspberry Pi
**Помилка:** `ModuleNotFoundError: No module named 'grove'`

**Рішення:**
1. Перевстановіть бібліотеки Grove:
   ```bash
   cd ~
   git clone https://github.com/Seeed-Studio/grove.py
   cd grove.py
   sudo pip3 install .
   ```
2. Якщо використовується віртуальне середовище, можливо, треба встановити глобально або скопіювати бібліотеки
3. Перевірте, чи увімкнено I2C: `sudo raspi-config nonint do_i2c 0`

#### Проблема: датчик Grove не виявляється
**Помилка:** `IOError: [Errno 121] Remote I/O error`

**Рішення:**
1. Перевірте фізичні з’єднання (переконайтеся, що кабель Grove повністю вставлено)
2. Переконайтеся, що датчик підключений до правильного порту (аналоговий, цифровий, I2C, UART)
3. Запустіть `i2cdetect -y 1` щоб перевірити, чи видно пристрій на I2C шині
4. Спробуйте інший кабель Grove
5. Переконайтеся, що Grove Base Hat правильно встановлена на GPIO контакти Raspberry Pi

---

## Проблеми з Апаратним Забезпеченням

### Raspberry Pi

#### Проблема: Raspberry Pi не завантажується
**Симптоми:** Немає зображення, відсутність активності світлодіодів або райдужний екран

**Рішення:**
1. **Перевірте блок живлення:** Використовуйте офіційний блок 5В 3А USB-C для Pi 4
2. **Проблеми з SD-карткою:** 
   - Відформатуйте SD-карту та перевстановіть Raspberry Pi OS
   - Спробуйте іншу SD-карту (використовуйте рекомендовані бренди)
   - Переконайтеся, що SD-карта вставлена правильно
3. **Перевірте підключення HDMI:** Спробуйте обидва HDMI-порти на Pi 4, використовуйте порт HDMI, який ближче до живлення

#### Проблема: не вдається підключитися по SSH до Raspberry Pi
**Симптоми:** Відмова у з’єднанні або тайм-аут

**Рішення:**
1. Увімкніть SSH:
   - Під час запису ОС на SD-карту за допомогою Raspberry Pi Imager налаштуйте SSH у додаткових опціях
   - Або створіть порожній файл з ім’ям `ssh` (без розширення) у розділі завантаження
2. Знайдіть IP-адресу Pi:
   - Перевірте пристрої, підключені до вашого маршрутизатора
   - Використайте `ping raspberrypi.local` (якщо працює mDNS)
   - Використовуйте сканери мережі, такі як `nmap` або Angry IP Scanner
3. Перевірте мережу:
   - Переконайтеся, що Pi знаходиться в тій же мережі, що й ваш комп’ютер
   - Спробуйте підключення по Ethernet замість WiFi
4. Перевірте ім'я користувача/пароль (за замовчуванням: ім’я користувача `pi`, пароль `raspberry`)

#### Проблема: Grove Base Hat не розпізнається
**Симптоми:** Датчики не працюють, помилки I2C

**Рішення:**
1. Переконайтеся, що Base Hat встановлена правильно на всі GPIO контакти
2. Перевірте на наявність зігнутих контактів на Pi або Base Hat
3. Увімкніть інтерфейс I2C:
   ```bash
   sudo raspi-config nonint do_i2c 0
   sudo reboot
   ```
4. Перевірте роботу I2C: `i2cdetect -y 1`

#### Проблема: Raspberry Pi працює повільно
**Симптоми:** Затримки інтерфейсу, повільна відповідь

**Рішення:**
1. Перевірте швидкість SD-карти (використовуйте Class 10 або вище, або SSD через USB)
2. Звільніть місце на диску: `df -h` для перевірки, видаліть непотрібні файли
3. Зменшіть обсяг пам’яті GPU в `raspi-config`, якщо не використовуєте активно камеру або дисплей
4. Закрийте непотрібні програми
5. Подумайте про оновлення до Pi 4 з більшою пам’яттю, якщо у вас Pi 3 або старший

### Wio Terminal

#### Проблема: екран Wio Terminal залишається порожнім
**Симптоми:** Немає зображення після завантаження коду

**Рішення:**
1. Перевірте, чи ініціалізується дисплей у коді (бібліотека TFT_eSPI)
2. Оновіть прошивку Wio Terminal за [Seeed Wiki](https://wiki.seeedstudio.com/Wio-Terminal-Getting-Started/)
3. Додайте код ініціалізації дисплея:
   ```cpp
   #include <TFT_eSPI.h>
   TFT_eSPI tft;
   tft.begin();
   tft.fillScreen(TFT_BLACK);
   ```
4. Спробуйте завантажити приклад з PlatformIO для тесту апаратури

#### Проблема: WiFi не працює на Wio Terminal
**Симптоми:** Не вдається підключитися до WiFi, помилки мережі

**Рішення:**
1. **Оновіть прошивку WiFi:** Дотримуйтеся [інструкції оновлення WiFi прошивки для Wio Terminal](https://wiki.seeedstudio.com/Wio-Terminal-Network-Overview/)
2. **Перевірте дані WiFi:** Переконайтеся, що SSID та пароль введені правильно
3. **Діапазон WiFi:** Wio Terminal підтримує тільки 2.4GHz WiFi (не 5GHz)
4. **Сигнал:** Перемістіть пристрій ближче до маршрутизатора
5. **Налаштування маршрутизатора:** Деякі корпоративні/WPA-Enterprise мережі можуть не працювати

#### Проблема: Wio Terminal не розпізнається комп’ютером
**Симптоми:** USB-пристрій не виявляється

**Рішення:**
1. **Спробуйте інший USB-кабель:** Використовуйте кабель для передачі даних, а не тільки для заряджання
2. **Увійдіть у режим завантажувача:** Швидко двічі сдвиньте перемикач живлення вниз
   - Синій світлодіод повинен блимати, пристрій з’явиться як "Arduino" у диспетчері пристроїв
3. **Встановіть драйвери (Windows):**
   - Завантажте та встановіть [Seeed USB driver](https://wiki.seeedstudio.com/Driver_for_Seeeduino/)
4. **Спробуйте інший USB-порт:** Уникайте USB-хабів, підключайте напряму
5. **Оновіть драйвери USB системи**

#### Проблема: датчики на Wio Terminal не працюють
**Симптоми:** Grove датчики не зчитують дані

**Рішення:**
1. Перевірте з’єднання кабелів Grove
2. Переконайтеся, що використовуєте правильний порт Grove (лівий чи правий)
3. Підключіть правильні бібліотеки для датчика
4. Перевірте живлення датчика
5. Протестуйте датчик прикладним кодом із бібліотеки

### Віртуальний Пристрій (CounterFit)

#### Проблема: додаток CounterFit не запускається
**Помилка:** Різні помилки Python при запуску CounterFit

**Рішення:**
1. Переконайтеся, що віртуальне середовище активоване
2. Встановіть/перевстановіть CounterFit:
   ```bash
   pip install CounterFit
   ```
3. Перевірте, що порт 5000 не зайнятий:
   - Windows: `netstat -ano | findstr :5000`
   - macOS/Linux: `lsof -i :5000`
4. Завершіть процес, який використовує порт 5000, або використайте інший порт:
   ```bash
   counterfit --port 5001
   ```

#### Проблема: не вдається підключитися до CounterFit з коду
**Помилка:** Відмова у з’єднанні або тайм-аут

**Рішення:**
1. Переконайтеся, що CounterFit працює: Відкрийте браузер за адресою `http://127.0.0.1:5000`
2. Перевірте, що URL підключення у коді збігається з адресою CounterFit
3. Переконайтеся, що брандмауер не блокує з’єднання
4. Спробуйте перезапустити і додаток CounterFit, і ваш код

#### Проблема: датчики не відображаються у CounterFit
**Симптоми:** Створені датчики не показуються у інтерфейсі CounterFit

**Рішення:**
1. Створіть датчики у інтерфейсі CounterFit до запуску коду
2. Оновіть сторінку браузера
3. Перевірте, що тип датчика відповідає тому, що очікує код
4. Очистіть кеш браузера

---

## Проблеми з Підключенням

### WiFi Підключення

#### Проблема: пристрій не може підключитися до WiFi
**Симптоми:** Тайм-аут з’єднання, помилка аутентифікації

**Рішення:**
1. **Перевірте SSID та пароль:** Переконайтеся, що облікові дані правильні
2. **Діапазон WiFi:** Більшість IoT-пристроїв підтримують лише 2.4GHz (не 5GHz)
3. **Налаштування маршрутизатора:**
   - Вимкніть ізоляцію AP, якщо вона ввімкнена
   - Використовуйте безпеку WPA2-PSK (уникайте WPA3, WEP або відкритих мереж)
   - Переконайтеся, що DHCP увімкнено
4. **Приховані мережі:** Якщо SSID прихований, можливо потрібно явно налаштувати його
5. **Сила сигналу:** Перемістіть пристрій ближче до маршрутизатора
6. **Перешкоди:** Інші пристрої, мікрохвильові печі або стіни можуть заважати

#### Проблема: WiFi з’єднання часто обривається
**Симптоми:** Переривчасте підключення

**Рішення:**
1. Перевірте стабільність маршрутизатора і спробуйте його перезавантажити
2. Оновіть прошивку пристрою
3. Використовуйте статичну IP-адресу замість DHCP
4. Зменште відстань до маршрутизатора або додайте WiFi-репітер
5. Перевірте наявність перешкод від інших пристроїв
6. Переконайтеся в належній потужності живлення (особливо для Raspberry Pi)

### Хмарні Сервіси

#### Проблема: не вдається підключитися до Azure IoT Hub
**Помилка:** Помилка аутентифікації, відмова у з’єднанні

**Рішення:**
1. **Перевірте облікові дані:**
   - Перевірте правильність рядка підключення
   - Переконайтеся, що в рядку підключення немає зайвих пробілів або переносів рядка
2. **Перевірте реєстрацію пристрою:** Пристрій повинен бути зареєстрований в IoT Hub
3. **Брандмауер/проксі:** Переконайтеся, що дозвіл є на вихідний MQTT (порт 8883) або HTTPS (порт 443)
4. **Регіон IoT Hub:** Переконайтеся, що IoT Hub працює і не в іншому регіоні, що викликає затримку
5. **Ліміти квот:** Перевірте, чи не перевищено обмеження безкоштовного рівня
6. **Перевірте підключення:**
   ```bash
   az iot hub device-identity show-connection-string --hub-name YourIoTHub --device-id YourDevice
   ```

#### Проблема: Azure Functions не запускаються
**Симптоми:** Повідомлення надіслані, але функція не виконується

**Рішення:**
1. Перевірте, що Function App працює (не зупинений)
2. Перевірте рядок підключення у налаштуваннях Function App
3. Перегляньте логи функції у порталі Azure
4. Переконайтеся, що сумісний з Event Hub кінцевий пункт налаштований правильно
5. Перевірте, що формат повідомлень відповідає очікуванням функції
6. Перевірте план служби Function App (споживання чи виділений)

### MQTT
#### Проблема: Помилка підключення MQTT  
**Помилка:** Підключення відхилено, невдала автентифікація

**Рішення:**  
1. **Адреса брокера:** Переконайтесь, що URL/IP брокера правильні  
2. **Порт:** Перевірте номер порту (1883 для незашифрованого, 8883 для TLS)  
3. **Аутентифікація:** Перевірте ім’я користувача/пароль, якщо потрібно  
4. **TLS/SSL:** Переконайтесь, що сертифікати дійсні та довірені  
5. **Брандмауер:** Перевірте, що порт не заблокований  
6. **Тест з MQTT клієнтом:** Використайте MQTT Explorer або mosquitto_pub/sub для тесту

#### Проблема: MQTT повідомлення не отримуються  
**Симптоми:** Повідомлення опубліковані, але не отримуються підписниками

**Рішення:**  
1. **Імена тем:** Переконайтесь, що тема підписника точно збігається з темою видавця  
2. **Рівень QoS:** Спробуйте QoS 1 або 2 замість 0  
3. **Шаблони:** Перевірте правильність використання шаблонів тем (`+` для одного рівня, `#` для багаторівневих)  
4. **Утримувані повідомлення:** Видавник може встановити прапорець утримування, щоб зберегти останнє повідомлення  
5. **Час підключення:** Переконайтесь, що підписник підключається до публікації повідомлень  

---

## Проблеми з датчиками та виконавчими пристроями

### Grove Датчики

#### Проблема: Датчик повертає неправильні значення  
**Симптоми:** Значення 0, -1 або абсурдні

**Рішення:**  
1. **Перевірте з’єднання:** Переконайтесь, що датчик правильно підключений  
2. **Правильний порт:** Перевірте тип порту датчика:  
   - Аналогові датчики → Аналогові порти (A0, A2, A4)  
   - Цифрові датчики → Цифрові порти (D5, D16, D18 тощо)  
   - I2C датчики → I2C порти  
3. **Калібрування:** Деякі датчики потребують калібрування (вологості ґрунту, світла)  
4. **Цикл живлення:** Від’єднайте та під’єднайте датчик знову  
5. **Технічна документація датчика:** Перевірте специфікації та вимоги датчика

#### Проблема: Ємнісний датчик вологості ґрунту завжди показує вологий  
**Симптоми:** Датчик показує високу вологість навіть у сухому ґрунті

**Рішення:**  
1. **Потрібне калібрування:** Ґрунтові датчики потребують калібрування:  
   - Зчитування у повітрі (суха база)  
   - Зчитування у воді (мокра база)  
   - Відображення значень між цими точками  
2. **Перевірте покриття датчика:** Вологість датчиків може погіршитись, якщо покриття пошкоджено  
3. **Розміщення:** Переконайтесь, що датчик повністю вставлений у ґрунт

#### Проблема: Неправильні значення температури/вологості  
**Симптоми:** DHT11/DHT22 показує неправильну температуру або вологість

**Рішення:**  
1. **Розміщення датчика:** Уникайте прямого сонячного світла, джерел тепла або потоку повітря  
2. **Час прогріву:** Дайте датчику 2 секунди після увімкнення перед зчитуванням  
3. **Частота зчитування:** DHT потребують мінімум 2 секунди між зчитуваннями  
4. **Перевірка на конденсацію:** Може впливати на точність  
5. **Якість датчика:** DHT11 менш точний, ніж DHT22

### Камера

#### Проблема: Камера не виявляється на Raspberry Pi  
**Помилка:** `mmal: mmal_vc_component_create: failed to create component 'vc.ril.camera'`

**Рішення:**  
1. **Активуйте інтерфейс камери:**  
   ```bash
   sudo raspi-config
   ```
   Перейдіть у Interface Options → Camera → Enable  
2. **Перевірте шлейф:** Переконайтесь, що кабель камери правильно вставлений  
   - Синя сторона на Pi Zero дивиться на USB-порти  
   - Синя сторона на Pi 4 дивиться від USB-портів  
3. **Оновіть прошивку:**  
   ```bash
   sudo apt update
   sudo apt full-upgrade
   sudo reboot
   ```
4. **Перевірте камеру:**  
   ```bash
   raspistill -o test.jpg
   ```
  
#### Проблема: Зображення з камери поганої якості  
**Симптоми:** Розмиті, темні або вигорілі зображення

**Рішення:**  
1. **Фокус:** Зніміть захисну плівку з лінзи, відрегулюйте фокус, якщо можливо  
2. **Освітлення:** Забезпечте достатнє освітлення  
3. **Налаштування камери:** Регулюйте експозицію, ISO, баланс білого в коді  
4. **Стабільність:** Тримайте камеру нерухомо, використовуйте штатив при потребі  
5. **Роздільність:** Не перевищуйте максимальну роздільність камери

### Мікрофон і Динамік

#### Проблема: Відсутній звук на вході/виході  
**Симптоми:** Мікрофон не записує, динамік не відтворює звук

**Рішення:**  
1. **Перевірте з’єднання:** Переконайтесь, що аудіопристрої правильно підключені  
2. **Тест обладнання:**  
   - Динамік: `speaker-test -t wav -c 2`  
   - Мікрофон: `arecord -l` для списку, `arecord test.wav` для запису  
3. **Налаштування гучності:** Перевірте та відрегулюйте гучність:  
   ```bash
   alsamixer
   ```
4. **Виберіть аудіопристрій:** Вкажіть правильне аудіопристрій у коді  
5. **Проблеми з драйверами:** Оновіть ALSA або перевстановіть аудіодрайвери

#### Проблема: ReSpeaker hat не працює  
**Симптоми:** Аудіопристрій не виявляється

**Рішення:**  
1. **Встановіть драйвери:**  
   ```bash
   git clone https://github.com/HinTak/seeed-voicecard
   cd seeed-voicecard
   sudo ./install.sh
   sudo reboot
   ```
2. **Перевірте встановлення:** `arecord -l` має показати ReSpeaker  
3. **Оновіть прошивку:** Деякі версії Pi OS потребують оновлення драйверів  
4. **Перевірте підключення:** Переконайтесь, що hat правильно підключений до GPIO пінів

---

## Проблеми середовища розробки

### VS Code

#### Проблема: Терминал не активує віртуальне середовище автоматично  
**Симптоми:** Терминал відкривається, але venv не активується

**Рішення:**  
1. **Встановіть інтерпретатор Python:** Palette команд → "Python: Select Interpreter" → Виберіть venv  
2. **Перезапустіть VS Code** після вибору інтерпретатора  
3. **Перевірте настройки:** В `settings.json` додайте:  
   ```json
   "python.terminal.activateEnvironment": true
   ```
  
#### Проблема: Код не запускається на пристрої  
**Симптоми:** Код виконується, але нічого не відбувається на пристрої

**Рішення:**  
1. **Переконайтесь, що код збережений** (перевірте крапку на вкладці файлу)  
2. **Перевірте, який Python використовується:** `which python` або `where python`  
3. **Для Wio Terminal:** Завантажте код через PlatformIO (натисніть кнопку завантаження)  
4. **Для Raspberry Pi:** Підключіться по SSH та виконайте код там  
5. **Перевірте вікно виводу** на наявність помилок

#### Проблема: IntelliSense не показує функції бібліотеки  
**Симптоми:** Відсутнє автозаповнення для імпортованих модулів

**Рішення:**  
1. Переконайтесь, що бібліотека встановлена в поточному середовищі  
2. Перезавантажте вікно VS Code  
3. Перевірте, що обраний правильний інтерпретатор Python  
4. Встановіть типові підстановки (type stubs), якщо є: `pip install types-<library-name>`

### Віртуальні середовища Python

#### Проблема: Не вдається створити віртуальне середовище  
**Помилка:** `The virtual environment was not created successfully`

**Рішення:**  
1. **Встановіть модуль venv:**  
   - Ubuntu/Debian: `sudo apt install python3-venv`  
   - macOS: Має бути включено у Python  
   - Windows: Перевстановіть Python з усіма компонентами  
2. **Перевірте встановлення Python:** Переконайтесь, що Python встановлений коректно  
3. **Використовуйте повний шлях:** Спробуйте `python3 -m venv .venv` з явним викликом python3

#### Проблема: Пакети встановлюються в неправильне місце  
**Симптоми:** Помилка імпорту після встановлення пакету

**Рішення:**  
1. **Переконайтесь, що venv активовано:** Запрошення командного рядка має показувати `(.venv)`  
2. **Перевірте розташування pip:** `which pip` повинен вказувати на `.venv/bin/pip`  
3. **Перевстановіть у venv:** Активуйте venv, потім виконайте `pip install <package>`  
4. **Не використовуйте sudo з pip** у віртуальному середовищі

#### Проблема: Віртуальне середовище не портативне  
**Симптоми:** Venv не працює після перенесення або на іншому комп’ютері

**Рішення:**  
1. **Не переміщуйте venv:** Видаліть та створіть заново у новому розташуванні  
2. **Використовуйте requirements.txt:**  
   ```bash
   pip freeze > requirements.txt
   pip install -r requirements.txt
   ```
3. **Створіть venv заново:**  
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate  # або activate.bat у Windows
   pip install -r requirements.txt
   ```
  
### Залежності

#### Проблема: Не вдається встановити пакет  
**Помилка:** Різні помилки pip під час встановлення

**Рішення:**  
1. **Оновіть pip:**  
   ```bash
   pip install --upgrade pip
   ```
2. **Встановіть інструменти збірки:**  
   - Ubuntu/Debian: `sudo apt install build-essential python3-dev`  
   - macOS: `xcode-select --install`  
   - Windows: Встановіть Visual Studio Build Tools  
3. **Перевірте підключення до Інтернету**  
4. **Спробуйте індекс пакетів:** `pip install --index-url https://pypi.org/simple/ <package>`  
5. **Встановіть конкретну версію:** `pip install <package>==<version>`

#### Проблема: Конфлікти залежностей  
**Помилка:** `ERROR: pip's dependency resolver does not currently take into account all the packages that are installed`

**Рішення:**  
1. **Використовуйте свіже віртуальне середовище** для кожного проекту  
2. **Оновіть пакети:** `pip install --upgrade <package>`  
3. **Перевірте залежності:** Використайте `pip check` для пошуку конфліктів  
4. **Встановлюйте сумісні версії:** Вказуйте діапазони версій у requirements.txt

---

## Проблеми з продуктивністю

### Проблема: Код працює повільно  
**Симптоми:** Затримки, таймаути, не відгукується

**Рішення:**  
1. **Зменшіть частоту зчитування датчиків:** Не зчитуйте їх занадто часто  
2. **Оптимізуйте цикли:** Уникайте активного очікування, використовуйте sleep() або затримки  
3. **Проблеми з пам’яттю:**  
   - Закрийте непотрібні програми  
   - Звільніть місце на диску  
   - Моніторинг за допомогою `top` або `htop` на Pi  
4. **Швидкість SD-карти:** Використовуйте швидшу SD-карту або SSD для Raspberry Pi  
5. **Затримки мережі:** Використовуйте асинхронні операції для мережевих викликів

### Проблема: Помилки нестачі пам’яті  
**Помилка:** `MemoryError` або зависання системи

**Рішення:**  
1. **Для Raspberry Pi:**  
   - Закрийте непотрібні програми  
   - Збільште swap-space  
   - Використовуйте легшою ОС (Lite версію)  
   - Оновіть RAM (Pi 4 має варіанти 2/4/8ГБ)  
2. **Для Wio Terminal:**  
   - Зменште розміри буферів  
   - Використовуйте менші зображення  
   - Оптимізуйте роботу зі рядками  
   - Перевірте витоки пам’яті (невивільнена пам’ять)

### Проблема: Втрата або пошкодження даних  
**Симптоми:** Відсутні повідомлення, пошкоджені файли

**Рішення:**  
1. **Проблеми з SD-картою:**  
   - Використовуйте якісні SD-карти (уникати дешевих/фальшивих)  
   - Регулярно робіть резервні копії  
   - Виконуйте чисте завершення роботи (не відключайте живлення раптово)  
2. **Переповнення буфера:** Збільшіть розміри буферів у коді  
3. **Надійність мережі:** Реалізуйте логіку повторних спроб та обробку помилок  
4. **Якість обслуговування:** Використовуйте MQTT QoS 1 або 2 для важливих повідомлень

---

## Типові повідомлення про помилки

### `ModuleNotFoundError: No module named 'X'`  
**Причина:** Пакет не встановлено або віртуальне середовище не активоване

**Рішення:**  
```bash
pip install X
```
Спочатку переконайтесь, що віртуальне середовище активовано.

### `Permission denied` на Linux/macOS  
**Причина:** Потрібні підвищені права або проблема з правами файлів

**Рішення:**  
- Для системних операцій: Використовуйте `sudo`  
- Для pip: НЕ використовуйте sudo з venv, спочатку активуйте venv  
- Для послідовного порту: Додайте користувача до групи dialout: `sudo usermod -a -G dialout $USER`, потім вийдіть/увійдіть знову

### `OSError: [Errno 98] Address already in use`  
**Причина:** Порт вже використовується іншим процесом

**Рішення:**  
1. Знайдіть процес, який використовує порт: `lsof -i :<port>` або `netstat -ano | findstr :<port>`  
2. Завершіть процес або використайте інший порт у вашому коді

### `SSL: CERTIFICATE_VERIFY_FAILED`  
**Причина:** Помилка перевірки SSL-сертифікату

**Рішення:**  
1. Оновіть сертифікати: `pip install --upgrade certifi`  
2. Переконайтесь, що системний час правильний: `date`  
3. Лише для розробки (не для продакшена): Відключіть перевірку в коді

### `IndentationError: unexpected indent`  
**Причина:** Помилки відступів у Python (змішування табуляцій та пробілів)

**Рішення:**  
1. Використовуйте послідовні відступи (4 пробіли — стандарт Python)  
2. Налаштуйте редактор на використання пробілів замість табуляції  
3. У VS Code встановіть `"editor.insertSpaces": true` та `"editor.tabSize": 4`

### `UnicodeDecodeError` або `UnicodeEncodeError`  
**Причина:** Проблеми кодування символів

**Рішення:**  
```python
# При читанні файлів
with open('file.txt', 'r', encoding='utf-8') as f:
    content = f.read()

# При записі файлів
with open('file.txt', 'w', encoding='utf-8') as f:
    f.write(content)
```
  
---

## Отримання допомоги

Якщо ви спробували ці кроки вирішення проблем і у вас все ще є проблеми:

### 1. Перевірте наявні ресурси  
- **Документація:** Перегляньте [README](README.md) та інструкції до уроків  
- **Посібники з обладнання:** Перевірте [hardware.md](hardware.md) для інформації про обладнання  
- **Вікі Seeed Studio:** [Seeed Studio Wiki](https://wiki.seeedstudio.com/) для компонентів Grove

### 2. Пошук схожих проблем  
- **GitHub Issues:** Шукайте [існуючі проблеми](https://github.com/microsoft/IoT-For-Beginners/issues)  
- **Stack Overflow:** Шукайте за текстом помилок  
- **Форуми пристроїв:** Перевірте форуми Raspberry Pi або Arduino

### 3. Створіть проблему на GitHub  
Якщо не можете знайти рішення:  
1. Перейдіть на [GitHub Issues](https://github.com/microsoft/IoT-For-Beginners/issues)  
2. Натисніть "New Issue"  
3. Зазначте:  
   - Чіткий опис проблеми  
   - Кроки для відтворення  
   - Повний текст повідомлень про помилки  
   - Версії апаратного та програмного забезпечення  
   - Те, що ви вже спробували  
   - Знімки екранів, якщо потрібно

### 4. Приєднуйтесь до спільноти  
- **Discord:** [Microsoft Foundry Discord](https://discord.gg/nTYy5BXMWG)  
- **Microsoft Learn:** [Microsoft Learn IoT](https://docs.microsoft.com/learn/browse/?products=azure-iot)

### 5. Надавайте якісні звіти про баги  
Якісний звіт про баг включає:
- **Оточення:** ОС, версія Python, використовуване обладнання
- **Кроки відтворення:** Точні кроки, що викликають проблему
- **Очікувана поведінка:** Що має відбуватися
- **Фактична поведінка:** Що відбувається насправді
- **Повідомлення про помилки:** Повний текст помилки, а не скріншоти
- **Код:** Мінімальний приклад коду, що відтворює проблему

---

## Поради для запобігання

### Загальні найкращі практики
1. **Робіть резервні копії:** Регулярно створюйте резервні копії робочих SD-карт/коду
2. **Документуйте зміни:** Фіксуйте в коментарях, що працює
3. **Контроль версій:** Використовуйте git для відслідковування змін у коді
4. **Тестуйте поступово:** Перевіряйте невеликі зміни перед їх поєднанням
5. **Читайте повідомлення про помилки:** Вони часто точно вказують, що не так
6. **Оновлюйте регулярно:** Підтримуйте програмне забезпечення/прошивку в актуальному стані
7. **Використовуйте якісні компоненти:** Уникайте дешевих кабелів/блоків живлення
8. **Стабільне живлення:** Використовуйте відповідне джерело живлення (особливо для Pi)

### Робочий процес розробки
1. **Починайте просто:** Починайте з робочого прикладного коду
2. **Одна зміна за раз:** Так легше знайти, що призводить до помилки
3. **Тестуйте часто:** Виявляйте проблеми на ранніх етапах
4. **Тримайте порядок:** Організовуйте файли та код логічно
5. **Коментуйте код:** Майбутній ви буде вдячний

---

*Цей посібник із усунення несправностей підтримується спільнотою. Якщо ви знайдете рішення проблеми, яка тут не наведена, будь ласка, розгляньте можливість [внеску](CONTRIBUTING.md), щоб допомогти іншим!*

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Відмова від відповідальності**:
Цей документ було перекладено за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, просимо враховувати, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ на його рідній мові слід вважати авторитетним джерелом. Для критичної інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння чи неправильні тлумачення, що виникли внаслідок використання цього перекладу.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->