Guia do Zero

QR50 + Raspberry Pi 4
Sistema de Controlo de Acesso

Do unboxing ao sistema funcional — passo a passo para quem nunca usou nenhum dos dois.

1

O que comprar

Antes de começar, certifique-se que tem todos estes componentes. Pode encontrar na Tecmicro ou encomendar via Amazon e Ali Express.

🖥️
Raspberry Pi 4
Modelo B, 2GB RAM é suficiente
Obrigatório
💾
Cartão microSD
Mínimo 16GB, Classe 10. Samsung ou SanDisk
Obrigatório
🔌
Fonte USB-C 5V/3A
Fonte oficial Raspberry Pi ou equivalente
Obrigatório
📺
Monitor + cabo micro-HDMI
Qualquer monitor com HDMI. Necessário só na 1ª config.
Obrigatório
⌨️
Teclado e rato USB
Qualquer teclado USB. Só para configuração inicial.
Obrigatório
🟢
LEDs (verde + vermelho)
LEDs normais 5mm + resistências 220Ω
Opcional
🔊
Buzzer activo 5V
Buzzer passivo também funciona
Opcional
🔧
Protoboard + jumper wires
Para ligar os componentes sem soldar
Recomendado
⚠️
Nota sobre o leitor QR50

O leitor ZKTeco QR50 já o tem. Vai ligá-lo ao Raspberry Pi por cabo USB — é simples como ligar um pen drive.

2

Montar o Raspberry Pi

O Raspberry Pi é uma placa de circuitos. Ao tirá-lo da caixa, precisa de:

Colocar na caixa (case)

Se comprou uma case, encaixe a placa com cuidado. Há normalmente 4 pontos de encaixe.

Instalar o dissipador de calor

Se o kit incluiu peças metálicas com autocolante — são dissipadores. Cole-os nos chips maiores da placa. O Pi 4 aquece bastante e isto é importante.

Identificar as portas
  • 2 × portas micro-HDMI (lado esquerdo)
  • 4 × portas USB (lado direito)
  • 1 × porta USB-C para alimentação (lado esquerdo)
  • Conector de 40 pinos GPIO (fileira de pinos dourados)
NÃO ligue a alimentação ainda

Primeiro precisa de preparar o cartão SD com o sistema operativo.

3

Instalar o sistema operativo no cartão SD

Isto faz-se no seu computador Windows/Mac, não no Raspberry Pi.

Descarregar o Raspberry Pi Imager

Vá a raspberrypi.com/software e descarregue o programa gratuito para o seu sistema operativo.

Inserir o cartão microSD no computador

Use um adaptador SD se o seu computador não tiver leitor de cartões.

Abrir o Raspberry Pi Imager e configurar
  • Clique em "Choose Device" → seleccione Raspberry Pi 4
  • Clique em "Choose OS" → seleccione Raspberry Pi OS (64-bit)
  • Clique em "Choose Storage" → seleccione o seu cartão SD
Configurar antes de gravar (muito importante!)

Clique no botão "Next" e depois em "Edit Settings". Configure:

  • Hostname: qracesso
  • Username: pi  |  Password: uma senha à sua escolha
  • Wi-Fi: coloque o nome e senha da sua rede
  • Locale: seleccione o seu país e fuso horário
Gravar e aguardar

Clique em "Write". O processo demora cerca de 5-10 minutos. No final, ejeccte o cartão com segurança.

✅
O cartão está pronto

Insira o cartão microSD no Raspberry Pi (slot na parte de baixo da placa).

4

Primeira ligação e configuração inicial

Ligar tudo
  • Monitor → cabo micro-HDMI → Raspberry Pi (porta HDMI 0, a mais próxima do USB-C)
  • Teclado USB → qualquer porta USB do Raspberry Pi
  • Rato USB → qualquer porta USB do Raspberry Pi
Ligar a alimentação

Ligue o cabo USB-C. O Pi vai iniciar automaticamente. Verá texto a aparecer no ecrã — é normal.

Aguardar o ambiente de trabalho

Ao fim de 1-2 minutos aparece o ambiente de trabalho do Raspberry Pi OS.

Verificar ligação à internet

No canto superior direito, veja o ícone de Wi-Fi. Se configurou correctamente no passo anterior, já estará ligado.

Abrir o Terminal

Clique no ícone do terminal no topo do ecrã (parece um ecrã preto). Este será o seu principal instrumento.

Actualizar o sistema (obrigatório)

No terminal, escreva os comandos abaixo um de cada vez. Cada um pode demorar alguns minutos:

# Actualizar a lista de programas disponíveis
sudo apt update

# Instalar as actualizações
sudo apt upgrade -yTERMINAL
💡
Dica: Usar SSH (opcional)

Depois desta configuração inicial, pode controlar o Raspberry Pi a partir do seu computador via SSH, sem precisar de monitor. No seu PC: ssh pi@qracesso.local

5

Instalar o Python e dependências

O Python já vem instalado no Raspberry Pi OS. Só precisa de instalar as bibliotecas adicionais.

# Verificar versão do Python (deve ser 3.x)
python3 --version

# Instalar o gestor de pacotes pip
sudo apt install python3-pip -y

# Instalar a biblioteca para controlar os pinos GPIO
pip3 install RPi.GPIO --break-system-packages

# Instalar a biblioteca para fazer pedidos HTTP (para a API futura)
pip3 install requests --break-system-packagesTERMINAL
✅
Tudo instalado

Se não aparecerem mensagens de erro, está pronto para continuar.

6

Configurar o leitor QR50

Esta configuração faz-se uma única vez no seu computador Windows/Mac com o software DEMO da ZKTeco.

// O que queremos fazer

Activar o modo HID Keyboard no QR50. Assim, quando alguém apresentar um QR Code, o leitor envia o conteúdo como se fosse um teclado a digitar — o Raspberry Pi lê esse texto directamente.

Descarregar o software DEMO

Vá ao site zkteco.com, procure por "QR50 software" ou peça ao seu fornecedor. O programa chama-se QR50&QR500 Configuration Demo.

Ligar o QR50 ao computador Windows

Use o cabo USB que veio com o leitor. O Windows vai instalar os drivers automaticamente.

Abrir o software e conectar
  • Seleccione USB no campo de ligação
  • Clique em Connect
  • Deve aparecer "Connect successful" em verde
Entrar nas definições avançadas

Clique no ícone de quadrícula no canto superior direito → seleccione "Enter advanced settings_QR50".

Activar o HID Keyboard

Na página Function Selection, localize o campo "HID keyboard" e mude de Close para Open.

Guardar a configuração

Clique em "Write configuration". Aguarde a confirmação de sucesso.

Desligar do Windows e ligar ao Raspberry Pi

Remova o cabo USB do Windows e ligue-o a qualquer porta USB do Raspberry Pi.

⚠️
Configuração feita uma única vez

O QR50 guarda esta configuração internamente. Não precisa de repetir este processo.

7

Ligar os componentes ao Raspberry Pi

Esta parte é opcional mas recomendada. Usamos os pinos GPIO do Raspberry Pi para ligar LEDs e buzzer.

💡
Nunca usou GPIO?

Os pinos GPIO são como interruptores que o programa pode ligar e desligar. Cada pino tem um número. Usamos uma protoboard (placa branca com furos) para montar os circuitos sem soldar.

// Diagrama de Ligação

Raspberry Pi → Componente Observação
GPIO 17 (Pino 11) → Resistência 220Ω → LED Verde(+) — Acesso Permitido
GPIO 27 (Pino 13) → Resistência 220Ω → LED Vermelho(+) — Acesso Negado
GPIO 22 (Pino 15) → Buzzer (+) — Alerta Sonoro
GND (Pino 6 ou 9) → LED(-) e Buzzer(-) — Terra/Ground

// Esquema visual simplificado

  Raspberry Pi GPIO          Protoboard
  ─────────────────          ──────────────────────────
  Pino 11 (GPIO17) ─────────► [220Ω] ─► LED VERDE ─► GND
  Pino 13 (GPIO27) ─────────► [220Ω] ─► LED VERM. ─► GND
  Pino 15 (GPIO22) ─────────────────► BUZZER (+)  ─► GND
  Pino 6  (GND)    ─────────────────────────────────► GND
  
  USB do QR50      ─────────► porta USB do Raspberry PiDIAGRAMA
⚠️
A resistência é obrigatória para os LEDs!

Sem resistência o LED queima. A resistência fica em série entre o pino GPIO e o ânodo (+) do LED. A perna mais comprida do LED é o ânodo (+).

// Localização dos pinos no Raspberry Pi 4

Pino Físico Nome GPIO Uso neste projecto
Pino 6 GND Terra (ground)
Pino 11 GPIO 17 LED Verde
Pino 13 GPIO 27 LED Vermelho
Pino 15 GPIO 22 Buzzer
8

Copiar e correr o código

No terminal do Raspberry Pi, execute os seguintes comandos:

🐍

Descarregar Código-Fonte

Pode descarregar o ficheiro pronto para usar ou copiar o conteúdo abaixo.

Baixar qr_access_control.py
Criar uma pasta para o projecto
mkdir ~/qr_acesso
cd ~/qr_acessoTERMINAL
Criar o ficheiro do programa
nano qr_access_control.pyTERMINAL

O editor nano abre. Agora copie todo o conteúdo do ficheiro Python que recebeu anteriormente e cole aqui (Ctrl+Shift+V no terminal).

Para guardar: Ctrl+O → Enter. Para sair: Ctrl+X.

Confirmar que o ficheiro foi criado
ls -la
# Deve aparecer: qr_access_control.pyTERMINAL
Correr o programa
python3 qr_access_control.pyTERMINAL

Deve aparecer:

==================================================
  Sistema de Controlo de Acesso — QR50
  Aguardando leitura de QR Code...
==================================================OUTPUT
9

Testar o sistema

// Teste rápido sem o leitor (digitando no teclado)

Com o programa a correr, escreva no terminal e carregue Enter:

ACESSO-001   ← Enter (deve acender LED verde + 1 bip)
INVALIDO      ← Enter (deve acender LED vermelho + 3 bips)TESTE

// Teste com o QR50

Gerar um QR Code de teste

No seu telemóvel, abra qualquer gerador de QR (ex: qr-code-generator.com) e crie um QR com o texto ACESSO-001.

Apresentar ao leitor

Aproxime o telemóvel do QR50. O leitor deve beepar e o terminal mostrará o código lido.

Ver o resultado

Se o código estiver na lista de válidos → LED verde acende e 1 bip. Se não estiver → LED vermelho e 3 bips.

// Iniciar automaticamente com o sistema

Para o programa iniciar sozinho quando o Raspberry Pi ligar:

# Abrir o ficheiro de tarefas automáticas
crontab -e

# Seleccione o editor 1 (nano) se perguntado
# Adicione esta linha no final do ficheiro:
@reboot python3 /home/pi/qr_acesso/qr_access_control.py >> /home/pi/qr_acesso/log.txt 2>&1TERMINAL
→

Próximos passos — Integração com API

O código já está preparado para a Fase 2. Quando a sua API estiver pronta, são apenas 2 alterações no ficheiro Python:

// Alteração 1 — Configurar o URL da API

# No início do ficheiro, altere:
API_URL = "https://sua-api-real.com/validar"
API_KEY = "a-sua-chave-secreta"PYTHON

// Alteração 2 — Trocar validação local por API

# Na função processar_qr(), comente esta linha:
# resultado = validar_local(codigo_qr)

# E descomente esta:
resultado = validar_api(codigo_qr)PYTHON

// Resposta esperada da API

A sua API deve retornar um JSON neste formato:

// Acesso permitido:
{ "permitido": true, "nome": "João Silva" }

// Acesso negado:
{ "permitido": false, "motivo": "Acesso expirado" }JSON

// Ideias para expandir o projecto

Funcionalidade Como implementar
Ecrã LCD com nome do utilizador Módulo I2C LCD + biblioteca RPLCD
Registo de entradas/saídas SQLite local + envio para API
Câmera fotográfica no acesso Módulo Raspberry Pi Camera
Controlo de fechadura eléctrica Relé 5V ligado ao GPIO + fechadura 12V
Painel web de administração Flask/FastAPI no próprio Raspberry Pi

🎉 Sistema Operacional!

Seguindo estes passos tem um sistema de controlo de acesso funcional por QR Code, com alertas luminosos e sonoros, pronto para integração com qualquer API.


ZKTeco QR50 + Raspberry Pi 4 — Guia v1.0