Guía práctica para instalación

Adcom Raspberry
Instalación, configuración y puesta en marcha

Documento pensado para personal técnico y no desarrolladores: explica desde cómo preparar la microSD hasta cómo clonar el repositorio, configurar el sistema y comprobar que todo funcione.

Documento: GI-ADCOM-RPI-001
Versión: 1.1
Fecha: 22/05/2026
Estado: Lista para entrega

Qué hace este sistema

Adcom Raspberry controla accesos con lectores RFID, QR y teclado, y registra eventos en una base local y en SQL Server.

Para quién sirve

Para técnicos de instalación, soporte en campo y personal operativo que necesita seguir pasos claros sin conocer programación.

Qué vas a necesitar

Raspberry Pi, microSD, lector(es), fuente estable, acceso a red y los datos del sitio donde se instalará el equipo.

Instalación paso a paso Clonado del repositorio Configuración sin complicaciones Pruebas de puesta en marcha

1. Objetivo de la guía

Dejar instalado y funcionando el sistema Adcom Raspberry de manera ordenada, repetible y entendible para cualquier persona encargada de una implementación.

2. Antes de empezar

Requisitos de hardware

  • Raspberry Pi 3B+, 4 o 5.
  • Fuente estable, idealmente 5V 3A para Pi 4/5.
  • microSD de 16 GB o más, clase 10.
  • Lector(es) compatibles con Wiegand o teclado.
  • Módulos relevador para apertura de accesos.
  • Cableado con tierra común para todos los dispositivos.

Datos que debes pedir al sitio

  • ID_COM del fraccionamiento o comunidad.
  • Host, usuario, contraseña y base de SQL Server.
  • URL de la API para el registro de accesos.
  • Nombre del archivo SQLite local, por ejemplo Natura.db.
Importante: si no tienes estos datos antes de instalar, puedes dejar la Raspberry lista, pero no terminarás la configuración del sitio.

3. Cómo instalar el sistema operativo

Opción recomendada

Usa Raspberry Pi OS Desktop 64-bit con Debian 12 Bookworm. Esta versión incluye interfaz gráfica y es la más fácil para una instalación guiada por una persona no desarrolladora.

Paso a paso con Raspberry Pi Imager

  1. Abre Raspberry Pi Imager en tu computadora.
  2. Elige el modelo correcto de Raspberry Pi.
  3. Selecciona Raspberry Pi OS Desktop 64-bit.
  4. Escoge la microSD destino.
  5. En opciones avanzadas define usuario, contraseña, hostname, zona horaria, SSH y WiFi si aplica.
  6. Graba la tarjeta, expúlsala con seguridad e insértala en la Raspberry.
  7. Enciende el equipo y espera el arranque inicial.
Consejo práctico: si vas a instalar en sitio, deja configurado desde el inicio el acceso por SSH y la red WiFi o por cable para evitar conectar monitor y teclado después.

4. Cómo preparar la Raspberry

Una vez conectada por SSH, actualiza el sistema y ajusta la zona horaria.

sudo apt update sudo apt upgrade -y sudo timedatectl set-timezone America/Mexico_City sudo reboot

Después del reinicio, valida la fecha y hora con:

timedatectl

5. Cómo clonar el repositorio

Primero obtén el proyecto. Si sabes usar Git, clónalo. Si no, puedes descargar el ZIP desde GitHub y descomprimirlo.

Opción A: clonar con Git

Entra a la carpeta del usuario y clona el proyecto. Sustituye el enlace por el repositorio real.

cd /home/<USUARIO>/Documents git clone <URL_DEL_REPOSITORIO> cd Adcom-Raspberry

Si la instalación ya existía, actualízala así:

cd /home/<USUARIO>/Documents/Adcom-Raspberry git pull

Opción B: descargar ZIP y descomprimir

  1. Abre el repositorio en GitHub.
  2. Presiona Code y después Download ZIP.
  3. Descomprime el archivo ZIP dentro de la carpeta Documents del usuario.
  4. Renombra la carpeta si es necesario para que quede como Adcom-Raspberry.
  5. Abre esa carpeta y continúa con la instalación.

6. Cómo instalar y ejecutar el proyecto

Opción recomendada: instalador automático

Si el archivo setup.sh está disponible, esta es la forma más fácil para personal no desarrollador.

chmod +x setup.sh ./setup.sh

El instalador pedirá el ID_COM, la información de SQL Server, la URL de la API y la base local. Al terminar dejará el servicio preparado para arrancar solo.

Opción manual

Si necesitas hacerlo sin asistente, instala los paquetes base del sistema:

sudo apt-get update sudo apt-get install -y python3-pip python3-dev python3-setuptools freetds-dev sqlite3 unzip build-essential pigpio libpigpio-dev

Instala las dependencias de Python:

sudo pip3 install pymssql pigpio RPi.GPIO gpiozero requests --break-system-packages

Inicializa la base local:

python3 init_db.py

Servicio para arranque automático

El servicio systemd permite que el sistema arranque solo después de reiniciar la Raspberry.

[Unit] Description=Servicio de Control de Acceso Adcom After=network.target pigpiod.service Wants=pigpiod.service [Service] Type=simple User=<USUARIO> WorkingDirectory=/home/<USUARIO>/Documents/Adcom-Raspberry ExecStart=/usr/bin/python3 /home/<USUARIO>/Documents/Adcom-Raspberry/revisar.py Restart=always RestartSec=5 StandardOutput=inherit StandardError=inherit Environment=PYTHONUNBUFFERED=1 [Install] WantedBy=multi-user.target

Activa los servicios con:

sudo systemctl daemon-reload sudo systemctl enable pigpiod sudo systemctl start pigpiod sudo systemctl enable adcom.service sudo systemctl start adcom.service

7. Cómo configurar el sitio

Abre config.json y completa los valores del sitio. Los campos más importantes son:

Cada cambio en config.json requiere reiniciar el servicio para que aplique.
sudo systemctl restart adcom.service

8. Conexiones GPIO

Usa esta referencia solo si vas a cablear el equipo. Toda entrada GPIO trabaja a 3.3V y requiere tierra común.

Diagrama visual de pines GPIO para Raspberry Pi
Diagrama de referencia rapida del header GPIO de Raspberry Pi (numeracion fisica y funciones BCM).

8.1 Entradas Wiegand/Teclados (BCM)

Dispositivo D0 (GPIO) D1 (GPIO) Pin físico (D0 / D1)
Lector 1 RFID Entrada14158 / 10
Lector 2 QR Entrada242518 / 22
Lector 5 RFID Salida81124 / 23
Teclado 15629 / 31
Teclado 2192035 / 38

8.2 Salidas y periféricos (BCM)

Función GPIO Pin físico Comportamiento
Relevador Entrada2215Activo en bajo
Relevador Salida921Activo en bajo
Relevador QR/Pluma1711Activo en bajo
Relevador Teclado 12713Activo en bajo
Relevador Teclado 21636Activo en bajo
Buzzer principal2316Pulso digital
Buzzer secundario2140Pulso digital
LED encendido2637Indicador de estado

8.3 Reglas eléctricas

  1. Las entradas GPIO son de 3.3V y no toleran 5V directos.
  2. Debe existir tierra común entre Raspberry, lectores y módulos relevador.
  3. Si el lector entrega señales a 5V, usa adaptador de nivel o optoacoplador.
  4. No alimentes cargas pesadas desde el GPIO.
  5. Usa una fuente externa si el consumo del sitio lo requiere.

9. Validación de arranque

Comprueba que los servicios estén arriba y revisa los registros si algo falla.

sudo systemctl status pigpiod sudo systemctl status adcom.service
journalctl -u adcom.service -f

Pruebas mínimas que deben funcionar

  1. Una tarjeta válida en lector 1 abre el relevador de entrada.
  2. Una tarjeta válida en lector 5 abre el relevador de salida.
  3. Un QR válido abre el relevador QR y se consume si es único.
  4. Un PIN válido en teclado 1 o 2 abre su relevador correspondiente.
  5. La sincronización con SQL Server aparece activa.
  6. La bitácora se envía por API y queda marcada como enviada.

10. Operación diaria

Estos comandos te sirven para mantener el servicio bajo control sin entrar al código.

sudo systemctl restart adcom.service sudo systemctl stop adcom.service sudo systemctl start adcom.service sudo journalctl -u adcom.service -n 200 --no-pager

Haz respaldo periódico del archivo SQLite definido en db_path.

10.1 Reinicio automático con crontab

El instalador setup.sh agrega un reinicio diario a las 04:00 para mantener la Raspberry limpia y estable. Revisa si ya existe con:

crontab -l | grep -F "/sbin/shutdown -r now"

Si no aparece ninguna línea, agrégala manualmente con el mismo comando que usa el instalador:

(crontab -l 2>/dev/null; echo "0 4 * * * /sbin/shutdown -r now") | crontab -

Después confirma que quedó cargada con:

crontab -l

11. Problemas comunes

12. Seguridad

  1. Cambia credenciales por defecto antes de pasar a producción.
  2. Restringe permisos del archivo de configuración.
chmod 600 config.json
  1. Usa SSH con llaves si es posible.
  2. Mantén la Raspberry actualizada.
  3. Protege físicamente la tarjeta microSD y el cableado.

13. Checklist final

  1. Sistema operativo instalado y actualizado.
  2. Hora y zona horaria correctas.
  3. Repositorio clonado y actualizado.
  4. Instalación automática o manual completada.
  5. Configuración del sitio aplicada.
  6. Base local creada y validada.
  7. Cableado verificado eléctricamente.
  8. Servicios pigpiod y adcom activados al arranque.
  9. Pruebas RFID, QR, PIN y pluma aprobadas.
  10. Logs y evidencia de instalación guardados.

14. Control de cambios

Versión Fecha Descripción Responsable
1.0 07/05/2026 Emisión inicial de guía formal. Soporte Técnico
1.1 22/05/2026 Versión ampliada con pasos para no desarrolladores, instalación del sistema operativo, clonado del repositorio y estructura visual mejorada. Bryan Loera

Este documento está pensado para usarse como guía de instalación y entrega. Se puede abrir en navegador o imprimir a PDF directamente.