Manual del Conector de Campo

Cómo conectar la telemetría de cualquier pozo — con cualquier levantamiento y cualquier SCADA — a Oilboards, punta a punta: del tag crudo al tablero latiendo. Incluye el circuito de práctica con el pozo virtual y el procedimiento completo para un pozo real.

01Qué es y cómo fluye el dato

El Conector de Campo (conector.oilboards.com) es la herramienta con la que un ingeniero conecta un pozo a Oilboards en una sola visita. Guía cinco pasos y produce un conector: un script Python de ~100 líneas que corre en la red del cliente, lee su SCADA y empuja lotes a la nube.

Tres propiedades que se repiten en todo el manual porque son el argumento de venta ante el cliente: el conector solo lee (no existe ruta de comando hacia su red), solo sale (HTTPS 443, cero puertos entrantes) y nada se oculta (el paso 5 muestra en vivo qué se lee, qué se transforma y qué se escribe).

02Antes de empezar: los 3 requisitos

Los tres viven en la plataforma (app.oilboards.com) y sin ellos la telemetría no entra:

1. Cuenta de la empresa activa — la da de alta el staff de Oilboards con su primer usuario (dueño de la cuenta).
2. El pozo registrado — con su tipo de levantamiento y su slug (identificador estable, p. ej. pozo-101h). La API solo acepta telemetría de entidades registradas: un slug desconocido rechaza con unknown_entity.
3. Token de fuente de ingesta — lo genera el propio cliente en app.oilboards.com → Conexión de datos → «Nueva fuente» (una por SCADA o batería). Se muestra una sola vez: cópielo en ese momento al gestor de secretos. Ahí mismo se revoca al instante o se regenera (el anterior muere y nadie puede leer ninguno después — solo se guarda el hash, ni el staff de Oilboards ve tokens de clientes).

▲ el renglón verde de la ficha: cópielo tal cual — ese texto exacto es lo que su conector usa como entity

Del lado del campo, para un pozo real: acceso de lectura a la SCADA o al historiador, una máquina con salida HTTPS al puerto 443 y reloj sincronizado por NTP (la API tolera +2 minutos hacia el futuro y 7 días hacia atrás).

03Práctica punta a punta con el pozo virtual

El pozo virtual (wellsim.oilboards.com) simula un pozo completo con switch de levantamiento: BEC, bombeo mecánico, PCP, gas lift, bombeo hidráulico y flujo natural. Ensaye el circuito completo con cada uno antes de viajar — seis ensayos, cero sorpresas en campo.

1Leer la SCADA

1. Abra conector.oilboards.com.
2. Pulse «Usar el pozo virtual (práctica)». La app lee la fuente, lista los tags con sus valores y unidades, y detecta sola el levantamiento que tenga puesto el switch de wellsim.
3. Revise la tabla: esa lista es todo lo que se leerá. Con BEC verá 12 tags (presiones en kg/cm², frecuencia, corriente, aislamiento…).

▲ pantalla ilustrativa — el botón ámbar de práctica llena la URL y lee solo

2Mapear los tags

1. Capture el slug del pozo: está en su ficha («Identificador de ingesta», con botón copiar) y en app.oilboards.com → Conexión de datos → «Entidades y sus identificadores». Si la API responde unknown_entity, coteje ahí el slug exacto.
2. Verifique el levantamiento seleccionado — filtra el catálogo para ofrecer solo variables que aplican.
3. Pulse «Sugerir mapeo automático» y revise renglón por renglón: la sugerencia es asistencia, la decisión es suya.
4. Observe los huecos (variables sin tag): con el pozo virtual en BEC es normal ver PRES_FONDO, BSW_PCT, PROD_BRUTA… — documentan lo que la instrumentación no mide. No es obligatorio enviarlo todo.
5. Descargue la plantilla CSV si quiere la tabla de mapeo como evidencia.

▲ cada renglón muestra su conversión y su veredicto; el slug se copia de la ficha del pozo

3Generar el script

El conector aparece completo en pantalla, con el mapeo cargado. Léalo — es el hábito que después repetirá frente al equipo de ciberseguridad del cliente. Descárguelo si va a correrlo fuera del navegador; para la práctica no es necesario.

▲ el código completo se lee en pantalla — el argumento para ciberseguridad OT del cliente

4Conectar a la API

1. En app.oilboards.com, con la sesión del usuario cliente (la vista «Entrar como cliente» del admin es de solo lectura y no deja configurar): registre el activo y el pozo de práctica (mismo levantamiento que el switch de wellsim) y genere el token en Conexión de datos → Nueva fuente.
2. Pegue el token en el paso 4. Vive solo en memoria: al cerrar la pestaña desaparece.
3. Pulse «Enviar lote de prueba». El lote se arma con lecturas reales del momento. Lo esperado: 200 OK · accepted: 12 · rejected: 0.
4. Si hay rechazos, la tabla los muestra con índice, razón y detalle — corrija el mapeo y repita (ver §07).

▲ el cliente crea, revoca y regenera sus tokens sin llamar a nadie — y aquí mismo cotejan los slugs

▲ lo esperado: accepted 12 · rejected 0 — si hay rechazos, la tabla dice índice, razón y detalle

5Ver el latido

1. Pulse «Iniciar latido». En modo observación no se envía nada: es la vitrina de transparencia — qué se lee, qué se transforma (con la conversión kg/cm² → psi número por número) y el lote listo.
2. Active «Enviar a Oilboards»: cada ciclo escribe de verdad y muestra la respuesta. La guardia de física valida en pantalla la jerarquía BHP > PIP > THP > FLP.
3. Abra la Sala de Monitoreo en otra pestaña: el pozo virtual late dentro del producto. Ese momento — datos moviéndose punta a punta — es la demo.
4. Repita el circuito cambiando el switch de wellsim a otro levantamiento (paso 1 → releer → paso 2 → …).

▲ la pantalla para dejar abierta junto al equipo de seguridad del cliente: nada oculto entre columna y columna

Práctica avanzada: la ruta Modbus, con RTU de verdad

El pozo virtual no solo habla HTTP: expone además un RTU Modbus TCP genuino en wellsim.oilboards.com:502 — mismo protocolo y puerto que un RTU/PLC real, con este mapa de registros (holding registers, float32 en 2 registros, big-endian). Es el ensayo idéntico a llegar a un pozo de campo:

1. En el paso 1 elija Modbus TCP: host wellsim.oilboards.com, puerto 502, unit ID 1.
2. Pulse «Cargar lista de tags…» y pegue el mapa tal cual:

PT_CABEZA, 0, float32, 1, kg/cm2
PC_CABEZA, 2, float32, 1, kg/cm2
PRES_LINEA, 4, float32, 1, kg/cm2
PIP_BOMBA, 6, float32, 1, kg/cm2
PDIS_BOMBA, 8, float32, 1, kg/cm2
FREC_VARIADOR, 10, float32, 1, Hz
AMP_MOTOR, 12, float32, 1, A
VOLT_MOTOR, 14, float32, 1, V
FP_MOTOR, 16, float32, 1, adim
TEMP_MOTOR_FONDO, 18, float32, 1, C
AISLAMIENTO, 20, float32, 1, MOhm
VIB_MOTOR, 22, float32, 1, mm/s

3. Mapee (paso 2), genere el conector (paso 3) y córralo desde su laptop — el navegador no habla Modbus, y ese es justo el punto del ensayo:

   pip install requests pymodbus
   python3 conector_pozo-101h.py --escanear   # lee el RTU y muestra las lecturas
   OILBOARDS_TOKEN='...' python3 conector_pozo-101h.py --una-vez

4. El JSON de --escanear puede pegarse de vuelta en el paso 1 — el mismo truco del huevo y la gallina que usará en campo (§04).

Los valores por Modbus y por HTTP coinciden: es el mismo motor de física del simulador visto por dos protocolos, como un pozo real visto por su RTU y por su historiador.

Hay además un segundo pozo virtual — pozo-demo-02, gas lift — con su propio RTU en wellsim.oilboards.com:503 (dos pozos = dos RTUs, como en campo). Su mapa, con la mezcla de unidades típica de un pozo neumático (presiones locales en kg/cm², inyección ya en MMpcd):

PT_CABEZA, 0, float32, 1, kg/cm2
PC_CABEZA, 2, float32, 1, kg/cm2
PRES_LINEA, 4, float32, 1, kg/cm2
INY_GAS_LIFT, 6, float32, 1, MMpcd
CHOKE_PCT, 8, float32, 1, %
BSW_PCT, 10, float32, 1, %
PROD_BRUTA, 12, float32, 1, bbl

04Pozo real punta a punta

El flujo es idéntico al de práctica; cambian dos cosas: cómo llegan los tags al paso 1, y que el conector corre en una máquina del cliente, no en su navegador.

Elegir el protocolo según lo que haya en sitio

Truco del huevo y la gallina: si nadie tiene el listado de tags a la mano, genere el conector con 2–3 tags conocidos, córralo en la máquina del cliente con --escanear y pegue el JSON que imprime de vuelta en el paso 1. La lista real sale de la propia SCADA.

El procedimiento

1. Paso 1 — elija el protocolo, capture la conexión (IP, puerto, endpoint…) y cargue los tags por el método de la tabla.
2. Paso 2 — slug y levantamiento reales del pozo, sugerencia automática y revisión renglón por renglón. La trampa clásica del campo mexicano: presiones en kg/cm² de la instrumentación local contra psi del equipo importado — un error de 14×. Declare la unidad de cada tag; la puerta convierte explícitamente y la validación de rango atrapa lo demás.
3. Paso 3 — genere y descargue el conector. Entrégueselo al ingeniero del cliente para que lo lea: es su código, corre con sus credenciales.
4. Paso 4 — con el pozo ya registrado en la plataforma, genere el token y haga la prueba de humo. Si la fuente no se lee desde navegador, la prueba definitiva es en la máquina del cliente:

   pip install requests pymodbus        # según el protocolo
   export OILBOARDS_TOKEN='(del gestor de secretos)'
   python3 conector_pozo-101h.py --una-vez

   Lo esperado: nada de RECHAZOS: en la salida y el dato visible en la plataforma segundos después.
5. Paso 5 — deje la vitrina de transparencia abierta con el equipo del cliente mientras validan que los números coinciden con su SCADA local. Luego instale el servicio (§05) y cierre con las pruebas de aceptación (§06).

05Dejar el conector como servicio

El botón «Ver unidad systemd» del paso 3 genera el archivo de servicio con estas instrucciones incluidas. En la máquina del conector (Linux):

# 1. Usuario de servicio sin shell y carpeta del conector
sudo useradd -r -s /usr/sbin/nologin oilboards-conector
sudo mkdir -p /opt/oilboards-conector
sudo cp conector_pozo-101h.py /opt/oilboards-conector/
sudo chown -R oilboards-conector: /opt/oilboards-conector

# 2. El token: en un archivo raíz-solo-lectura, jamás en el código
echo 'OILBOARDS_TOKEN=aqui-el-token' | sudo tee /etc/oilboards-conector.env
sudo chmod 600 /etc/oilboards-conector.env

# 3. Instalar y arrancar
sudo cp conector-pozo-101h.service /etc/systemd/system/
sudo systemctl enable --now conector-pozo-101h

# 4. Vigilar (la palabra clave es RECHAZOS:)
journalctl -u conector-pozo-101h -f

El buffer en disco (./buffer) hace el resto: si el enlace se cae, el conector acumula y al volver reenvía todo con sus timestamps originales — la ventana de 7 días y la idempotencia garantizan que el periodo se rellena íntegro y sin duplicados.

06Pruebas de aceptación — la integración se cierra ejercitándola

• Todos los pozos del alcance reportan; ninguna entidad muestra «—» permanente.
• rejected = 0 sostenido durante al menos 48 horas de operación normal.
• La guardia de física sin críticas atribuibles al mapeo (jerarquía de presiones coherente).
• Valores cotejados contra el SCADA local por los ingenieros del cliente: mismas magnitudes, mismas unidades, al menos una variable de cada tipo.
• Prueba de corte: desconectar el conector 30+ minutos, reconectar y verificar que el periodo se rellena completo, con timestamps originales y sin duplicados.
• Prueba de revocación: revocar un token de prueba → el envío recibe 401 de inmediato; reponer con token nuevo sin pérdida (el buffer reenvía).
• El token de producción vive en el gestor de secretos del cliente — no en el código, no en un correo.
• Alerta del cliente si el conector deja de recibir 200 por N minutos (Oilboards además detecta la fuente silenciosa y avisa).

07Solución de problemas

La regla de oro: vigilar rejected > 0. Un rechazo sostenido casi siempre es un tag mal mapeado o una unidad mal declarada — se corrige en minutos si se ve, contamina en silencio si no.

08Respuestas de seguridad para el cliente

Las preguntas que hará su equipo de ciberseguridad OT, con la respuesta corta:

• «¿Qué leen de nuestra SCADA?» — Exactamente los tags de la tabla del paso 1, nada más. Verificable con una captura de tráfico: una sola conexión saliente.
• «¿Pueden escribir hacia nuestros PLCs?» — No, por arquitectura: no existe ruta de comando en el producto. El conector es código de ustedes, legible completo, y solo abre conexiones salientes al 443.
• «¿Qué necesita nuestro firewall?» — Una regla de salida HTTPS (443) hacia app.oilboards.com. Cero reglas entrantes, cero VPN, cero hardware ajeno.
• «¿Y el token?» — Vive en su gestor de secretos; Oilboards guarda solo un hash irreversible. Se revoca al instante desde la plataforma y la revocación no pierde datos (el buffer reenvía con el token nuevo).
• «¿Quién más ve nuestros datos?» — Nadie: aislamiento por empresa impuesto en la base de datos misma (Row-Level Security), y la telemetría es append-only — lo que entró no se edita ni se borra.

Referencia normativa: Manual de Integración para Clientes — Ingesta de telemetría SCADA, API v1 (rev. agosto 2026). Este manual de campo lo resume para el uso de la herramienta; ante cualquier diferencia, gana el manual del API.