You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
756 lines
30 KiB
756 lines
30 KiB
# 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 --> |