Conector Protocol Translator

Descripción General

El conector Protocol Translator decodifica una carga desde un formato estructurado a un mapa plano clave-valor, opcionalmente renombra claves y luego codifica el resultado en un formato de destino diferente. Es el puente canónico entre los protocolos industriales y las etapas descendentes nativas de JSON.

Tipo de Conector: MeddleProtocolTranslator

Formatos Admitidos

• flat-json — Mapa plano clave/valor ({ "temp": 25.5, "press": 101.3 })
• nested-json — Objeto anidado; decodificado aplanando con puntos, codificado desaplanando con puntos ({ "sensor": { "temp": 25.5 } } ↔ { "sensor.temp": 25.5 })
• sparkplugb — Forma Eclipse Sparkplug B: un array metrics de entradas { "name": "...", "value": ... }
• opcua-json — JSON OPC-UA por nodo: cada clave de nivel superior se mapea a { "value": ..., "sourceTimestamp": ... }

sourceFormat y targetFormat deben ser diferentes.

Configuración

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "sparkplugb",
    "targetFormat": "flat-json",
    "keyMappings": {
      "Temperature/Zone1": "temperature_zone_1",
      "Pressure/Main":     "pressure_main"
    }
  }
}

El conector primero decodifica las métricas de Sparkplug B en { "Temperature/Zone1": 25.5, "Pressure/Main": 101.3 }, luego renombra las claves según keyMappings y por último emite el JSON plano.

Parámetros de Configuración

• sourceFormat (obligatorio): Uno de flat-json, nested-json, sparkplugb, opcua-json
• targetFormat (obligatorio): Uno de flat-json, nested-json, sparkplugb, opcua-json (debe diferir de sourceFormat)
• keyMappings: Mapa opcional oldKey -> newKey. Las claves no presentes en el mapa pasan sin cambios.

Pipeline de Traducción

1. Decodificar — La carga fuente se normaliza a un map[string]any plano.
   • flat-json copia la carga tal cual
   • nested-json aplana objetos anidados usando . como separador
   • sparkplugb extrae cada metrics[i].value con clave metrics[i].name
   • opcua-json extrae el campo value de cada nodo de nivel superior
2. Renombrar — Aplicar keyMappings para renombrar claves.
3. Codificar — Reformar el mapa plano al formato de destino.
   • flat-json escribe el mapa directamente
   • nested-json desaplana las claves delimitadas por . en objetos anidados
   • sparkplugb envuelve cada clave/valor como { "name": k, "value": v } en un array metrics
   • opcua-json envuelve cada valor como { "value": v, "sourceTimestamp": null }

Casos de Uso

1. Sparkplug B a JSON plano para ingestar en bases de datos que esperan claves simples
2. OPC-UA JSON a JSON plano para eliminar metadatos del nodo antes de alertar
3. JSON plano a Sparkplug B al publicar en un broker MQTT compatible con Sparkplug
4. Aplanado de JSON anidado para conectores descendentes que esperan un espacio de claves plano

Ejemplo: OPC-UA a JSON Plano

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "opcua-json",
    "targetFormat": "flat-json"
  }
}

Entrada:

{
  "ns=2;s=Temp":  { "value": 25.5, "sourceTimestamp": "2025-01-01T12:00:00Z" },
  "ns=2;s=Press": { "value": 101.3, "sourceTimestamp": "2025-01-01T12:00:00Z" }
}

Salida:

{
  "ns=2;s=Temp":  25.5,
  "ns=2;s=Press": 101.3
}

Ejemplo: JSON Plano a JSON Anidado

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "flat-json",
    "targetFormat": "nested-json",
    "keyMappings": {
      "temp": "sensor.temperature",
      "press": "sensor.pressure"
    }
  }
}

Entrada: { "temp": 25.5, "press": 101.3 }

Salida: { "sensor": { "temperature": 25.5, "pressure": 101.3 } }

Mejores Prácticas

• Usa keyMappings para alinear los nombres de tags ascendentes con las convenciones de esquema descendentes en un solo paso
• Combina con Transform para cambios a nivel de valor (fórmulas, coerción de tipos) que vayan más allá del renombrado de claves
• Las cargas Sparkplug B deben contener un array metrics de objetos con campos name y value — valida aguas arriba si la fuente no es fiable
• Hacer ida-y-vuelta flat-json -> opcua-json -> flat-json está soportado, pero sourceTimestamp se establece a null al codificar

Conectores Relacionados

• Transform - Extracción con JSONPath, plantilla y valor estático
• Reshape - Renombrado directo de claves sin cambio de formato
• File Format - Parseo de CSV y XML