# Guia de Resolução de Problemas

Este guia ajuda a resolver problemas comuns ao trabalhar com o currículo IoT for Beginners. Os problemas estão organizados por categoria para facilitar a navegação.

## Índice

- [Problemas de Instalação](../..)
  - [Instalação do Python](../..)
  - [VS Code e Extensões](../..)
  - [PlatformIO (Wio Terminal)](../..)
  - [Bibliotecas Grove](../..)
- [Problemas de Hardware](../..)
  - [Raspberry Pi](../..)
  - [Wio Terminal](../..)
  - [Dispositivo Virtual (CounterFit)](../..)
- [Problemas de Conectividade](../..)
  - [Conexão WiFi](../..)
  - [Serviços Cloud](../..)
  - [MQTT](../..)
- [Problemas com Sensores e Atuadores](../..)
  - [Sensores Grove](../..)
  - [Câmara](../..)
  - [Microfone e Coluna](../..)
- [Problemas no Ambiente de Desenvolvimento](../..)
  - [VS Code](../..)
  - [Ambientes Virtuais Python](../..)
  - [Dependências](../..)
- [Problemas de Performance](../..)
- [Mensagens de Erro Comuns](../..)
- [Obter Ajuda](../..)

---

## Problemas de Instalação

### Instalação do Python

#### Problema: Versão do Python demasiado antiga  
**Erro:** `Python 3.6 ou superior é obrigatório`

**Solução:**  
1. Faça o download do Python 3 mais recente em [python.org](https://www.python.org/downloads/)  
2. Durante a instalação no Windows, selecione "Add Python to PATH"  
3. Verifique a instalação:  
   ```bash
   python3 --version
   ```
  
#### Problema: Múltiplas versões do Python causam conflitos  
**Sintomas:** Versão errada do Python é executada, pacotes instalados em local errado

**Solução:**  
- **Windows:** Use `py -3` em vez de `python` para chamar explicitamente o Python 3  
- **macOS/Linux:** Use `python3` em vez de `python`  
- Crie e use sempre ambientes virtuais para projetos

#### Problema: Comando pip não encontrado  
**Erro:** `'pip' não é reconhecido como um comando interno ou externo`

**Solução:**  
1. Tente `pip3` em vez de `pip`  
2. Ou use `python -m pip` ou `python3 -m pip`  
3. Certifique-se que o Python está adicionado ao PATH (reinstale o Python e selecione a opção)

### VS Code e Extensões

#### Problema: Extensão Pylance não funciona  
**Sintomas:** Sem IntelliSense Python, sem autocompletar ou verificação de tipos

**Solução:**  
1. Abra a Paleta de Comandos do VS Code (`Ctrl+Shift+P` ou `Cmd+Shift+P`)  
2. Execute "Python: Select Interpreter"  
3. Escolha o interpretador Python correto (ambiente virtual se estiver a usar)  
4. Recarregue a janela do VS Code

#### Problema: VS Code não detecta ambiente virtual  
**Sintomas:** Interpretador Python errado selecionado

**Solução:**  
1. Certifique-se que ativou o ambiente virtual no terminal  
2. Abra a Paleta de Comandos e execute "Python: Select Interpreter"  
3. Selecione o interpretador da pasta `.venv`  
4. Verifique se a barra de estado (canto inferior esquerdo) mostra a versão correta do Python

### PlatformIO (Wio Terminal)

#### Problema: Instalação do PlatformIO falha  
**Erro:** Vários erros durante a instalação do PlatformIO

**Solução:**  
1. Certifique-se que o VS Code está atualizado  
2. Instale a extensão C/C++ primeiro  
3. Reinicie o VS Code após instalar o PlatformIO  
4. Verifique a sua ligação à internet (PlatformIO descarrega ficheiros grandes)

#### Problema: Placa não detectada pelo PlatformIO  
**Sintomas:** Não consegue fazer upload do código para o Wio Terminal

**Solução:**  
1. Use um cabo USB diferente (alguns cabos são só para carregamento)  
2. Verifique o Gestor de Dispositivos (Windows) ou `ls /dev/tty*` (macOS/Linux)  
3. Instale ou atualize os drivers USB  
4. Experimente uma porta USB diferente  
5. Deslize o interruptor de alimentação do Wio Terminal duas vezes rapidamente para entrar no modo bootloader

#### Problema: Erros de compilação no PlatformIO  
**Erro:** `fatal error: Arduino.h: No such file or directory`

**Solução:**  
1. Apague a pasta `.pio` no seu projeto  
2. Execute "PlatformIO: Rebuild" na Paleta de Comandos  
3. Certifique-se que o `platformio.ini` tem a configuração correta da placa:  
   ```ini
   [env:seeed_wio_terminal]
   platform = atmelsam
   board = seeed_wio_terminal
   framework = arduino
   ```
  
### Bibliotecas Grove

#### Problema: Falha na importação da biblioteca Grove no Raspberry Pi  
**Erro:** `ModuleNotFoundError: No module named 'grove'`

**Solução:**  
1. Reinstale as bibliotecas Grove:  
   ```bash
   cd ~
   git clone https://github.com/Seeed-Studio/grove.py
   cd grove.py
   sudo pip3 install .
   ```
2. Se estiver a usar ambiente virtual, pode precisar de instalar globalmente ou copiar as bibliotecas  
3. Verifique se o I2C está ativado: `sudo raspi-config nonint do_i2c 0`

#### Problema: Sensor Grove não é detectado  
**Erro:** `IOError: [Errno 121] Remote I/O error`

**Solução:**  
1. Verifique as ligações físicas (certifique-se que o cabo Grove está totalmente inserido)  
2. Verifique se o sensor está ligado à porta correta (analógica, digital, I2C, UART)  
3. Execute `i2cdetect -y 1` para ver se o dispositivo aparece no barramento I2C  
4. Experimente um cabo Grove diferente  
5. Certifique-se que o Grove Base Hat está devidamente encaixado nos pinos GPIO do Raspberry Pi

---

## Problemas de Hardware

### Raspberry Pi

#### Problema: Raspberry Pi não arranca  
**Sintomas:** Sem imagem, sem LED ativo, ou ecrã arco-íris

**Solução:**  
1. **Verifique a alimentação:** Use a fonte oficial 5V 3A USB-C para Pi 4  
2. **Problemas com o cartão SD:**  
   - Reformatar cartão SD e reinstalar Raspberry Pi OS  
   - Experimente um cartão SD diferente (use marcas recomendadas)  
   - Certifique-se que o cartão SD está corretamente inserido  
3. **Verifique ligação HDMI:** Experimente ambas as portas HDMI no Pi 4, use a porta HDMI mais próxima da alimentação

#### Problema: Não consegue conectar via SSH ao Raspberry Pi  
**Sintomas:** Conexão recusada ou timeout

**Solução:**  
1. Ative o SSH:  
   - Ao gravar o cartão SD com o Raspberry Pi Imager, configure o SSH nas opções avançadas  
   - Ou crie um ficheiro vazio chamado `ssh` (sem extensão) na partição de boot  
2. Encontre o IP do Pi:  
   - Verifique os dispositivos conectados no seu router  
   - Use `ping raspberrypi.local` (se o mDNS funcionar)  
   - Use ferramentas de scanner de rede como `nmap` ou Angry IP Scanner  
3. Verifique a rede:  
   - Certifique-se que o Pi está na mesma rede que o seu computador  
   - Experimente ligação por ethernet em vez de WiFi  
4. Verifique o nome de utilizador/senha (padrão: utilizador `pi`, senha `raspberry`)

#### Problema: Grove Base Hat não é reconhecido  
**Sintomas:** Sensores não funcionam, erros I2C

**Solução:**  
1. Certifique-se que o Base Hat está corretamente encaixado em todos os pinos GPIO  
2. Verifique existência de pinos tortos no Pi ou Base Hat  
3. Ative a interface I2C:  
   ```bash
   sudo raspi-config nonint do_i2c 0
   sudo reboot
   ```
4. Verifique se o I2C está a funcionar: `i2cdetect -y 1`

#### Problema: Raspberry Pi lento  
**Sintomas:** Interface lenta, resposta demorada

**Solução:**  
1. Verifique a velocidade do cartão SD (use Classe 10 ou superior, ou SSD via USB)  
2. Liberte espaço em disco: `df -h` para verificar, apague ficheiros desnecessários  
3. Reduza a memória GPU em `raspi-config` se não estiver a usar a câmara/ecrã intensivamente  
4. Feche aplicações desnecessárias  
5. Considere atualizar para Pi 4 com mais RAM se estiver a usar Pi 3 ou anterior

### Wio Terminal

#### Problema: Ecrã do Wio Terminal fica negro  
**Sintomas:** Sem saída no ecrã depois de carregar código

**Solução:**  
1. Verifique se o código inicializa o ecrã (biblioteca TFT_eSPI)  
2. Atualize o firmware do Wio Terminal a partir de [Seeed Wiki](https://wiki.seeedstudio.com/Wio-Terminal-Getting-Started/)  
3. Adicione código de inicialização do ecrã:  
   ```cpp
   #include <TFT_eSPI.h>
   TFT_eSPI tft;
   tft.begin();
   tft.fillScreen(TFT_BLACK);
   ```
4. Experimente carregar sketch de exemplo do PlatformIO para testar hardware

#### Problema: WiFi não funciona no Wio Terminal  
**Sintomas:** Incapaz de conectar ao WiFi, erros de rede

**Solução:**  
1. **Atualize o firmware WiFi:** Siga o [guia de atualização do firmware WiFi do Wio Terminal](https://wiki.seeedstudio.com/Wio-Terminal-Network-Overview/)  
2. **Verifique credenciais WiFi:** Certifique-se que SSID e senha estão corretos  
3. **Banda WiFi:** Wio Terminal suporta apenas WiFi 2.4GHz (não 5GHz)  
4. **Força do sinal:** Aproxime-se do router  
5. **Configurações do router:** Algumas redes empresariais/WPA-Enterprise podem não funcionar

#### Problema: Wio Terminal não é reconhecido pelo computador  
**Sintomas:** Dispositivo USB não detectado

**Solução:**  
1. **Experimente cabo USB diferente:** Use cabo de dados, não cabo só para carregamento  
2. **Entre em modo bootloader:** Deslize o interruptor de alimentação para baixo duas vezes rapidamente  
   - O LED azul deve piscar, o dispositivo aparece como "Arduino" no Gestor de Dispositivos  
3. **Instale drivers (Windows):**  
   - Transfira e instale o [driver USB Seeed](https://wiki.seeedstudio.com/Driver_for_Seeeduino/)  
4. **Experimente porta USB diferente:** Evite hubs USB, use ligação direta  
5. **Atualize drivers USB do sistema**

#### Problema: Sensores não funcionam no Wio Terminal  
**Sintomas:** Sensores Grove não retornam dados

**Solução:**  
1. Verifique ligações dos cabos Grove  
2. Confirme que está a usar a porta Grove correta (esquerda ou direita)  
3. Inclua as bibliotecas corretas para o sensor  
4. Verifique as necessidades de alimentação do sensor  
5. Teste o sensor com código de exemplo da biblioteca

### Dispositivo Virtual (CounterFit)

#### Problema: Aplicação CounterFit não arranca  
**Erro:** Vários erros Python ao iniciar o CounterFit

**Solução:**  
1. Assegure que o ambiente virtual está ativado  
2. Instale/reinstale o CounterFit:  
   ```bash
   pip install CounterFit
   ```
3. Verifique que a porta 5000 não está já em uso:  
   - Windows: `netstat -ano | findstr :5000`  
   - macOS/Linux: `lsof -i :5000`  
4. Termine o processo a usar a porta 5000 ou use porta diferente:  
   ```bash
   counterfit --port 5001
   ```
  
#### Problema: Não consegue conectar ao CounterFit a partir do código  
**Erro:** Conexão recusada ou timeout

**Solução:**  
1. Verifique que o CounterFit está a correr: abra o browser em `http://127.0.0.1:5000`  
2. Confirme que o URL de conexão no código corresponde ao endereço do CounterFit  
3. Certifique-se que o firewall não bloqueia a conexão  
4. Tente reiniciar tanto a aplicação CounterFit como o seu código

#### Problema: Sensores não aparecem no CounterFit  
**Sintomas:** Sensores criados não aparecem na interface do CounterFit

**Solução:**  
1. Crie os sensores na interface do CounterFit antes de executar o código  
2. Atualize a página do browser  
3. Verifique se o tipo do sensor coincide com o esperado pelo código  
4. Limpe a cache do navegador

---

## Problemas de Conectividade

### Conexão WiFi

#### Problema: Dispositivo não conecta ao WiFi  
**Sintomas:** Timeout na ligação, autenticação falhada

**Solução:**  
1. **Verifique SSID e senha:** Confirme que as credenciais estão corretas  
2. **Banda WiFi:** A maioria dos dispositivos IoT suporta apenas 2.4GHz (não 5GHz)  
3. **Configurações do router:**  
   - Desative isolamento AP se estiver ativo  
   - Use segurança WPA2-PSK (evite WPA3, WEP ou redes abertas)  
   - Certifique-se que o DHCP está ativo  
4. **Redes ocultas:** Se o SSID está oculto, pode precisar de configurar explicitamente  
5. **Força do sinal:** Aproxime o dispositivo do router  
6. **Interferências:** Outros dispositivos, micro-ondas ou paredes podem interferir

#### Problema: Conexão WiFi cai frequentemente  
**Sintomas:** Conectividade intermitente

**Solução:**  
1. Verifique estabilidade do router e considere reiniciar  
2. Atualize o firmware do dispositivo  
3. Use IP estático em vez de DHCP  
4. Reduza distância ao router ou adicione repetidor WiFi  
5. Verifique interferência de outros dispositivos  
6. Confirme que a alimentação é adequada (especialmente para Raspberry Pi)

### Serviços Cloud

#### Problema: Não consegue conectar ao Azure IoT Hub  
**Erro:** Autenticação falhou, conexão recusada

**Solução:**  
1. **Verifique credenciais:**  
   - Confirme que a string de conexão está correta  
   - Assegure que não existem espaços ou quebras de linha extras na string  
2. **Verifique registo do dispositivo:** O dispositivo deve estar registado no IoT Hub  
3. **Firewall/proxy:** Garanta que as portas MQTT (8883) ou HTTPS (443) estão liberadas para saída  
4. **Região do IoT Hub:** Confirme que o IoT Hub está ativo e não numa região diferente causando latência  
5. **Limites de quota:** Verifique se os limites do nível gratuito não foram ultrapassados  
6. **Teste a conexão:**  
   ```bash
   az iot hub device-identity show-connection-string --hub-name YourIoTHub --device-id YourDevice
   ```
  
#### Problema: Azure Functions não disparam  
**Sintomas:** Mensagens enviadas mas função não executa

**Solução:**  
1. Verifique que a App Function está ativa (não parada)  
2. Confirme a string de conexão nas configurações da App Function  
3. Verifique os logs da função no Portal Azure  
4. Assegure que o ponto final compatível com Event Hub está configurado corretamente  
5. Confirme que o formato da mensagem corresponde às expectativas da função  
6. Verifique o plano de serviço da App Function (consumo vs. dedicado)

### MQTT
#### Problema: Falha na ligação MQTT  
**Erro:** Conexão recusada, autenticação falhou

**Solução:**  
1. **Endereço do broker:** Verifique se o URL/IP do broker está correto  
2. **Porta:** Verifique o número da porta (1883 para não encriptado, 8883 para TLS)  
3. **Autenticação:** Verifique o nome de utilizador/senha se necessário  
4. **TLS/SSL:** Assegure que os certificados são válidos e confiáveis  
5. **Firewall:** Confirme que a porta não está bloqueada  
6. **Teste com cliente MQTT:** Use MQTT Explorer ou mosquitto_pub/sub para testar

#### Problema: Mensagens MQTT não recebidas  
**Sintomas:** Mensagens publicadas mas não recebidas pelos subscritores

**Solução:**  
1. **Nomes dos tópicos:** Verifique se o tópico do subscritor coincide exatamente com o do publicador  
2. **Nível QoS:** Experimente QoS 1 ou 2 em vez de 0  
3. **Curingas:** Confirme que os curingas de tópico são usados corretamente (`+` para nível único, `#` para múltiplos níveis)  
4. **Mensagens retidas:** O publicador pode definir flag de retenção para manter a última mensagem  
5. **Tempo de ligação:** Garanta que o subscritor se liga antes de as mensagens serem publicadas

---

## Problemas com Sensores e Atuadores

### Sensores Grove

#### Problema: Sensor devolve valores incorretos  
**Sintomas:** Leituras são 0, -1, ou valores sem sentido

**Solução:**  
1. **Verificar ligações:** Assegure que o sensor está corretamente ligado  
2. **Porta correta:** Verifique se o sensor está na porta certa:  
   - Sensores analógicos → Portas analógicas (A0, A2, A4)  
   - Sensores digitais → Portas digitais (D5, D16, D18, etc.)  
   - Sensores I2C → Portas I2C  
3. **Calibração:** Alguns sensores necessitam de calibração (humidade do solo, luz)  
4. **Reiniciar energia:** Desligar e ligar novamente o sensor  
5. **Folha de dados do sensor:** Consultar especificações e requisitos do sensor

#### Problema: Sensor capacitivo de humidade do solo sempre indica húmido  
**Sintomas:** Sensor indica humidade alta mesmo quando está seco

**Solução:**  
1. **Necessidade de calibração:** Sensores de solo precisam de calibração:  
   - Medir valor no ar (base seca)  
   - Medir valor na água (base húmida)  
   - Mapear leituras entre estes valores  
2. **Verificar revestimento do sensor:** Sensores de humidade podem degradar se o revestimento estiver danificado  
3. **Posicionamento:** Assegure que o sensor está totalmente inserido no solo

#### Problema: Leituras incorretas do sensor de temperatura/humidade  
**Sintomas:** DHT11/DHT22 mostra temperatura ou humidade erradas

**Solução:**  
1. **Posicionamento do sensor:** Evite luz solar direta, fontes de calor ou correntes de ar  
2. **Tempo de aquecimento:** Deixe o sensor estabilizar 2 segundos após ligar antes de ler  
3. **Frequência de leitura:** Sensores DHT precisam de tempo entre leituras (mínimo 2 segundos)  
4. **Verificar condensação:** Pode afetar as leituras  
5. **Qualidade do sensor:** DHT11 é menos preciso que DHT22

### Câmara

#### Problema: Câmara não detetada no Raspberry Pi  
**Erro:** `mmal: mmal_vc_component_create: failed to create component 'vc.ril.camera'`

**Solução:**  
1. **Ativar interface da câmera:**  
   ```bash
   sudo raspi-config
   ```
   Vá a Interface Options → Camera → Enable  
2. **Verificar cabo plano:** Assegure que o cabo da câmera está bem inserido  
   - Lado azul para as portas USB no Pi Zero  
   - Lado azul afastado das portas USB no Pi 4  
3. **Atualizar firmware:**  
   ```bash
   sudo apt update
   sudo apt full-upgrade
   sudo reboot
   ```
4. **Testar câmera:**  
   ```bash
   raspistill -o test.jpg
   ```


#### Problema: Imagens da câmera com má qualidade  
**Sintomas:** Imagens desfocadas, escuras ou lavadas

**Solução:**  
1. **Foco:** Remova filme protetor da lente, ajuste foco se possível  
2. **Iluminação:** Assegure iluminação adequada  
3. **Configurações da câmera:** Ajuste exposição, ISO, balanço de brancos no código  
4. **Estabilidade:** Mantenha a câmera fixa, use tripé se necessário  
5. **Resolução:** Não ultrapasse a resolução máxima da câmara

### Microfone e Altifalante

#### Problema: Sem entrada/saída de áudio  
**Sintomas:** Microfone não grava, altifalante não reproduz

**Solução:**  
1. **Verificar ligações:** Confirme que dispositivos de áudio estão corretamente ligados  
2. **Testar hardware:**  
   - Altifalante: `speaker-test -t wav -c 2`  
   - Microfone: `arecord -l` para listar, `arecord test.wav` para gravar  
3. **Configurações de volume:** Verifique e ajuste volume:  
   ```bash
   alsamixer
   ```
4. **Selecionar dispositivo de áudio:** Especificar o dispositivo correto no código  
5. **Problemas de driver:** Atualizar ALSA ou reinstalar drivers de áudio

#### Problema: ReSpeaker hat não funciona  
**Sintomas:** Dispositivo de áudio não detetado

**Solução:**  
1. **Instalar drivers:**  
   ```bash
   git clone https://github.com/HinTak/seeed-voicecard
   cd seeed-voicecard
   sudo ./install.sh
   sudo reboot
   ```
2. **Verificar instalação:** `arecord -l` deve listar ReSpeaker  
3. **Atualizar firmware:** Algumas versões do Pi OS precisam de atualização dos drivers  
4. **Verificar ligação:** Assegurar que a hat está bem conectada aos pinos GPIO

---

## Problemas no Ambiente de Desenvolvimento

### VS Code

#### Problema: Terminal não ativa ambiente virtual automaticamente  
**Sintomas:** Terminal abre mas venv não está ativado

**Solução:**  
1. **Definir interpretador Python:** Command Palette → "Python: Select Interpreter" → Escolher venv  
2. **Reiniciar VS Code** após selecionar interpretador  
3. **Verificar configurações:** No `settings.json`, adicionar:  
   ```json
   "python.terminal.activateEnvironment": true
   ```


#### Problema: Código não corre no dispositivo  
**Sintomas:** Código corre mas nada acontece no dispositivo

**Solução:**  
1. **Verificar se código está salvo** (verificar ponto na tab do arquivo)  
2. **Verificar qual Python está a correr:** `which python` ou `where python`  
3. **Para Wio Terminal:** Assegurar que código foi carregado via PlatformIO (clicar botão upload)  
4. **Para Raspberry Pi:** Aceder por SSH e correr o código lá  
5. **Verificar janela de saída** para erros

#### Problema: IntelliSense não mostra funções da biblioteca  
**Sintomas:** Sem autocomplete para módulos importados

**Solução:**  
1. Garantir que biblioteca está instalada no ambiente atual  
2. Recarregar janela do VS Code  
3. Confirmar que interpretador Python está correto  
4. Instalar type stubs se disponíveis: `pip install types-<library-name>`

### Ambientes Virtuais Python

#### Problema: Não é possível criar ambiente virtual  
**Erro:** `The virtual environment was not created successfully`

**Solução:**  
1. **Instalar módulo venv:**  
   - Ubuntu/Debian: `sudo apt install python3-venv`  
   - macOS: Deve estar incluído com Python  
   - Windows: Reinstalar Python com todos os componentes  
2. **Verificar instalação do Python:** Confirmar que Python está corretamente instalado  
3. **Usar caminho completo:** Tentar `python3 -m venv .venv` com chamada explícita ao python3

#### Problema: Pacotes instalados na localização errada  
**Sintomas:** Erro de importação após instalar pacote

**Solução:**  
1. **Confirmar que venv está ativado:** Prompt deve mostrar `(.venv)`  
2. **Verificar localização do pip:** `which pip` deve apontar para `.venv/bin/pip`  
3. **Reinstalar no venv:** Ativar venv, depois `pip install <package>`  
4. **Não usar sudo com pip** no ambiente virtual

#### Problema: Ambiente virtual não é portátil  
**Sintomas:** Venv não funciona após mover ou noutro computador

**Solução:**  
1. **Não mover venvs:** Apague e crie novamente no novo local  
2. **Usar requirements.txt:**  
   ```bash
   pip freeze > requirements.txt
   pip install -r requirements.txt
   ```
3. **Recriar venv:**  
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate  # ou activate.bat no Windows
   pip install -r requirements.txt
   ```


### Dependências

#### Problema: Falha na instalação do pacote  
**Erro:** Vários erros de pip durante instalação

**Solução:**  
1. **Atualizar pip:**  
   ```bash
   pip install --upgrade pip
   ```
2. **Instalar ferramentas de compilação:**  
   - Ubuntu/Debian: `sudo apt install build-essential python3-dev`  
   - macOS: `xcode-select --install`  
   - Windows: Instalar Visual Studio Build Tools  
3. **Verificar ligação à internet**  
4. **Tentar outro índice de pacote:** `pip install --index-url https://pypi.org/simple/ <package>`  
5. **Instalar versão específica:** `pip install <package>==<version>`

#### Problema: Conflitos de dependências  
**Erro:** `ERROR: pip's dependency resolver does not currently take into account all the packages that are installed`

**Solução:**  
1. **Usar ambiente virtual novo** para cada projeto  
2. **Atualizar pacotes:** `pip install --upgrade <package>`  
3. **Verificar requisitos:** Usar `pip check` para encontrar conflitos  
4. **Instalar versões compatíveis:** Especificar intervalos de versão em requirements.txt

---

## Problemas de Performance

### Problema: Código corre lentamente  
**Sintomas:** Atrasos, timeouts, comportamento não responsivo

**Solução:**  
1. **Reduzir frequência de leitura dos sensores:** Não ler sensores com muita frequência  
2. **Otimizar loops:** Evitar busy-waiting, usar sleep() ou delays  
3. **Problemas de memória:**  
   - Fechar aplicações desnecessárias  
   - Libertar espaço de armazenamento  
   - Monitorizar com `top` ou `htop` no Pi  
4. **Velocidade do cartão SD:** Usar cartão SD mais rápido ou SSD para Raspberry Pi  
5. **Atrasos na rede:** Usar operações assíncronas para chamadas de rede

### Problema: Erros de falta de memória  
**Erro:** `MemoryError` ou sistema bloqueado

**Solução:**  
1. **Para Raspberry Pi:**  
   - Fechar aplicações desnecessárias  
   - Aumentar espaço de swap  
   - Usar sistema operativo mais leve (versão Lite)  
   - Atualizar RAM (Pi 4 tem opções de 2/4/8GB)  
2. **Para Wio Terminal:**  
   - Reduzir tamanhos de buffer  
   - Usar imagens menores  
   - Otimizar uso de strings  
   - Verificar fugas de memória (memória não libertada)

### Problema: Perda ou corrupção de dados  
**Sintomas:** Mensagens em falta, ficheiros corrompidos

**Solução:**  
1. **Problemas com cartão SD:**  
   - Usar cartões SD de qualidade (evitar baratos/falsificados)  
   - Fazer backups regulares  
   - Desligar sem riscos (não desligar energia abruptamente)  
2. **Overflow de buffer:** Aumentar tamanhos de buffer no código  
3. **Confiabilidade da rede:** Implementar lógica de retentativa e tratamento de erros  
4. **Qualidade de Serviço:** Usar MQTT QoS 1 ou 2 para mensagens importantes

---

## Mensagens Comuns de Erro

### `ModuleNotFoundError: No module named 'X'`  
**Causa:** Pacote não instalado ou ambiente virtual não ativado

**Solução:**  
```bash
pip install X
```
  
Assegure que o ambiente virtual está ativado primeiro.

### `Permission denied` no Linux/macOS  
**Causa:** Necessário permissões elevadas ou problema de permissões de ficheiro

**Solução:**  
- Para operações do sistema: Usar `sudo`  
- Para pip: NÃO use sudo com venv, ative venv primeiro  
- Para porta serial: Adicione utilizador ao grupo dialout: `sudo usermod -a -G dialout $USER`, depois logout/login

### `OSError: [Errno 98] Address already in use`  
**Causa:** Porta já está a ser usada por outro processo

**Solução:**  
1. Encontrar processo que usa a porta: `lsof -i :<port>` ou `netstat -ano | findstr :<port>`  
2. Matar processo ou usar porta diferente no código

### `SSL: CERTIFICATE_VERIFY_FAILED`  
**Causa:** Falha na validação do certificado SSL

**Solução:**  
1. Atualizar certificados: `pip install --upgrade certifi`  
2. Verificar se hora do sistema está correta: `date`  
3. Apenas para desenvolvimento (não produção): Desativar verificação no código

### `IndentationError: unexpected indent`  
**Causa:** Problemas de indentação Python (mistura de tabs/espaços)

**Solução:**  
1. Usar indentação consistente (4 espaços é padrão Python)  
2. Configurar editor para usar espaços em vez de tabs  
3. VS Code: Definir `"editor.insertSpaces": true` e `"editor.tabSize": 4`

### `UnicodeDecodeError` ou `UnicodeEncodeError`  
**Causa:** Problemas de codificação de caracteres

**Solução:**  
```python
# Ao ler ficheiros
with open('file.txt', 'r', encoding='utf-8') as f:
    content = f.read()

# Ao escrever ficheiros
with open('file.txt', 'w', encoding='utf-8') as f:
    f.write(content)
```
  
---

## Obter Ajuda

Se já tentou estes passos de resolução e ainda tem problemas:

### 1. Verificar Recursos Existentes  
- **Documentação:** Revise o [README](README.md) e as instruções das aulas  
- **Guias de hardware:** Consulte [hardware.md](hardware.md) para informações específicas de hardware  
- **Wiki Seeed Studio:** [Seeed Studio Wiki](https://wiki.seeedstudio.com/) para componentes Grove

### 2. Pesquisar Problemas Similares  
- **GitHub Issues:** Pesquise [problemas existentes](https://github.com/microsoft/IoT-For-Beginners/issues)  
- **Stack Overflow:** Pesquise mensagens de erro  
- **Fóruns de dispositivos:** Consulte fóruns Raspberry Pi ou Arduino

### 3. Criar um Issue no GitHub  
Se não encontrar solução:  
1. Vá a [GitHub Issues](https://github.com/microsoft/IoT-For-Beginners/issues)  
2. Clique em "New Issue"  
3. Forneça:  
   - Descrição clara do problema  
   - Passos para reproduzir  
   - Mensagens de erro (texto completo)  
   - Versões de hardware/software  
   - O que já tentou  
   - Capturas de ecrã se relevante

### 4. Junte-se à Comunidade  
- **Discord:** [Microsoft Foundry Discord](https://discord.gg/nTYy5BXMWG)  
- **Microsoft Learn:** [Microsoft Learn IoT](https://docs.microsoft.com/learn/browse/?products=azure-iot)

### 5. Forneça Bons Relatórios de Erros  
Um bom relatório de erros inclui:
- **Ambiente:** SO, versão do Python, hardware utilizado  
- **Passos para reproduzir:** Passos exatos que causam o problema  
- **Comportamento esperado:** O que deveria acontecer  
- **Comportamento real:** O que realmente acontece  
- **Mensagens de erro:** Texto completo do erro, não capturas de ecrã  
- **Código:** Exemplo mínimo de código que reproduz o problema  

---

## Dicas para Prevenção

### Boas Práticas Gerais
1. **Faça backups:** Backups regulares dos cartões SD/código que funciona  
2. **Documente alterações:** Anote o que funciona nos comentários  
3. **Controle de versão:** Use git para registar alterações no código  
4. **Teste incrementalmente:** Teste alterações pequenas antes de combinar  
5. **Leia as mensagens de erro:** Elas normalmente indicam exatamente o que está errado  
6. **Atualize regularmente:** Mantenha o software/firmware atualizado  
7. **Use componentes de qualidade:** Evite cabos/fonte de alimentação baratos  
8. **Energia estável:** Use fonte de alimentação apropriada (especialmente no Pi)  

### Fluxo de Trabalho de Desenvolvimento
1. **Comece simples:** Inicie com código de exemplo que funcione  
2. **Uma alteração de cada vez:** É mais fácil encontrar o que causa problema  
3. **Teste frequentemente:** Detecte problemas cedo  
4. **Mantenha organizado:** Organize ficheiros e código de forma lógica  
5. **Comente o código:** O futuro você irá agradecer  

---

*Este guia de resolução de problemas é mantido pela comunidade. Se encontrar uma solução para um problema não listado aqui, por favor considere [contribuir](CONTRIBUTING.md) para ajudar outros!*

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Aviso Legal**:
Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos por garantir a precisão, por favor esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original no seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se a tradução feita por um profissional humano. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->