# OCPP

> Referencia del driver OCPP: el sistema central integrado, los certificados de los puntos de recarga, los tags de conector y la regla de nombres Meter, Status y Transaction.

El driver OCPP convierte a Ganter Lab en el **sistema central** de los puntos de recarga de
vehículos eléctricos que hablan el Open Charge Point Protocol. Igual que con LoRaWAN, el
sentido está invertido: la estación no se conecta al cargador, sino que **el punto de
recarga se conecta a Ganter Lab** por un WebSocket, se registra solo y le empuja su
telemetría.

El sistema central integrado arranca cuando el primer dispositivo OCPP activado se carga en
el connector en marcha, y se detiene cuando se quita o se desactiva el último: sin ningún
punto de recarga configurado, no hay nada escuchando en el puerto. Agregar uno lo trae de
vuelta, sin reiniciar la aplicación. Cada dispositivo que usted configure representa **un
punto de recarga**, identificado por el id con el que se conecta.

## Preparar el punto de recarga {#prepare-the-charge-point}

El punto de recarga es quien llama a esta estación y, de fábrica, no sabe dónde
está. La página de cada dispositivo OCPP trae la tarjeta **Preparar el punto de
recarga** con lo que hay que indicar en la configuración OCPP del punto de recarga,
escrito para esta estación:

| Qué configurar en el punto de recarga | Qué da la tarjeta |
|---|---|
| Dirección del sistema central | `wss://<dirección>:19521/<id-del-punto-de-recarga>`, primero con la dirección por el nombre de esta estación (el "Nombre de red" de la configuración del servidor OPC UA integrado, o el nombre de la computadora mientras está vacío), luego una vez por cada dirección IPv4 que esta estación tiene en una red, cada una con un botón de copiar. Un punto de recarga que verifica el nombre del servidor necesita la dirección por el nombre; uno que no lo verifica acepta cualquiera de ellas, y entonces basta la de su propia red. |
| Identidad del punto de recarga | El **Identificador** del dispositivo o, mientras está vacío, el nombre que la estación le da al dispositivo. Muchos puntos de recarga agregan su identidad a la dirección por sí mismos: en ellos, indique la dirección solo hasta el puerto, y la identidad en su propio campo. |
| Seguridad | TLS con certificado de cliente, lo que OCPP llama perfil de seguridad 3. Los perfiles 1 y 2, que no tienen certificado de cliente, no se aceptan. El certificado del punto de recarga lleva su identidad en el nombre común o en un nombre alternativo DNS (consulte [Los certificados](#certificates)). |
| Certificado raíz del sistema central | La ruta completa de `GanterLabConnector-<station>.pem`, el certificado raíz de esta estación, que el punto de recarga instala para confiar en el sistema central, con el botón **Abrir la carpeta**, que muestra el archivo en el explorador de archivos de Windows. El botón funciona en la ventana de la propia estación; en un navegador de otro equipo queda en gris y dice por qué. |

La tarjeta está abierta mientras el punto de recarga no se conecta desde que se abrió
la estación, y se pliega cuando se conecta: se queda en la página para la próxima vez
que se configure el punto de recarga. Un punto de recarga cuyo certificado no avala
ninguna raíz instalada en Windows se rechaza en su primera conexión y espera en
[Acceso a los equipos](#equipment-access).

El archivo se escribe la primera vez que arranca el sistema central, cuando hay un punto
de recarga registrado, y hasta entonces la tarjeta lo dice. Es el mismo archivo para todos
los puntos de recarga de esta estación, y no cambia cuando cambian el nombre o las
direcciones de la estación (consulte [El certificado raíz de la estación](#the-stations-root-certificate)).

**Todo punto de recarga que recibió un archivo de una versión anterior necesita este,
instalado una vez.** En el primer arranque de esta versión, una estación cuyos puntos de
recarga pueden tener un archivo anterior muestra en la tarjeta un aviso, **El archivo de
esta estación cambió**, solo en esa ejecución. El aviso es un recordatorio, no la
instrucción: instale el archivo nuevo una vez en cada punto de recarga de una estación que
ya tenía puntos de recarga, muestre o no la tarjeta el aviso. Un punto de recarga que
verifica el nombre del servidor acepta la estación a partir de entonces.

## El sistema central y los puertos {#central-system-and-ports}

| Qué | Valor |
|---|---|
| Versiones del protocolo | OCPP **1.6**, **2.0**, **2.0.1** y **2.1** (negociación de subprotocolo por WebSocket; JSON) |
| Escucha | Todas las interfaces, puerto TCP **19521**, solo TLS |
| Dirección del punto de recarga | `wss://<dirección-de-la-estación>:19521/<id-del-punto-de-recarga>` |
| Identidad | La última parte de la ruta del WebSocket es el id del punto de recarga |

La escucha siempre es TLS; una escucha por HTTP sin cifrar se rechaza en cualquier lugar que
no sea loopback, que existe solo para las pruebas dentro del proceso. Un punto de recarga se
registra solo con su BootNotification (contestada con un intervalo de latido de 60 segundos),
y cada credencial que se presente para autorización se acepta: Ganter Lab observa la recarga,
no administra tarifas ni accesos.

## Los certificados {#certificates}

El lado de servidor del saludo TLS presenta un certificado firmado por la raíz propia de
esta estación (consulte [El certificado raíz de la estación](#the-stations-root-certificate)).
Cada punto de recarga tiene que presentar un **certificado de cliente**:

1. Tiene que ser de confianza de una de dos maneras: forma una cadena válida en esta
   máquina Windows, hasta una raíz instalada en ella, sin errores de política TLS; o usted
   aprobó este mismo certificado en **Acceso a los equipos** en la página de este driver
   (más abajo). En los dos casos tiene que estar dentro de sus fechas de validez. Una
   verificación fallida rechaza la conexión y el diario técnico registra qué verificación
   falló.
2. El nombre común de su sujeto o un nombre alternativo de sujeto de tipo DNS tiene que
   **nombrar el id del punto de recarga** con el que se conecta. Un certificado que nombre
   otro punto de recarga distinto del que va en la ruta de conexión se rechaza, aunque esté
   aprobado.

Un saludo sin certificado de cliente se tira antes de que fluya ningún dato.

### El certificado raíz de la estación {#the-stations-root-certificate}

| Qué | Valor |
|---|---|
| La raíz | Se crea una vez por perfil, la primera vez que arranca el sistema central o el servidor de red LoRaWAN. Su sujeto es `Ganter Lab Connector (<station>)`, donde `<station>` es el nombre de red ese día. Nunca caduca y nunca se reemplaza sola: cambiar el nombre de la computadora, el nombre de red o las direcciones de la estación la deja como está. |
| El archivo | `GanterLabConnector-<station>.pem`, solo la parte pública, en la carpeta de datos, en `ua\pki\station`. Es el mismo archivo para un punto de recarga y para una puerta de enlace LoRaWAN, que lo instala como `tc.trust`. |
| El certificado que presenta el sistema central | Firmado por esa raíz. Nombra el nombre de red de la estación (el "Nombre de red" de la configuración del servidor OPC UA integrado; el nombre de la computadora mientras está vacío), `localhost` y cada dirección IPv4 de la estación, así que un punto de recarga que verifica el nombre del servidor (perfil de seguridad 3) lo acepta. Cuando cambia el nombre de red o una dirección, solo se emite de nuevo este certificado, por sí solo, sin nada que hacer en el punto de recarga. |
| El certificado del servidor OPC UA | No se usa aquí. El servidor OPC UA integrado conserva su propio certificado para los clientes OPC UA. |

Una raíz guardada que ya no se puede abrir, por ejemplo porque la escribió otra cuenta de
Windows, se reemplaza por una nueva. Todo punto de recarga necesita entonces el archivo
nuevo, una vez, y la tarjeta lo dice.

### Acceso a los equipos {#equipment-access}

Un punto de recarga cuyo certificado no avala ninguna raíz instalada en Windows, porque es
autofirmado o lo emitió la autoridad del propio fabricante, no necesita que esa raíz se
instale en esta computadora. Su primera conexión se rechaza, y su certificado espera en
**Acceso a los equipos**, al final de la página del driver OCPP, la misma tarjeta que lleva
la página del driver OPC UA, hasta que usted decida:

| Grupo | Qué muestra | Qué puede hacer |
|---|---|---|
| A la espera de aprobación | Cada certificado rechazado, bajo el id del punto de recarga con el que se conectó: su huella digital SHA-256, cuándo lo intentó por última vez y cuántas veces, y sus detalles (sujeto, emisor, nombres de dominio, fechas de validez). | **Aprobar** admite el certificado a partir de la próxima conexión del punto de recarga. **Bloquear** lo sigue rechazando sin volver a listarlo aquí. **Descartar todos los certificados pendientes** vacía la lista sin aprobar ni bloquear nada. |
| Equipos aprobados | Los certificados que usted aprobó o importó, con quién decidió y cuándo. | **Retirar la aprobación** cierra la conexión del punto de recarga y devuelve su certificado a la lista. **Importar certificado** aprueba el certificado público de un punto de recarga antes de su primera conexión. |
| Equipos bloqueados | Los certificados que usted bloqueó. Un certificado bloqueado se rechaza aunque Windows confíe en él. | **Desbloquear** devuelve el certificado a la lista, sin aprobarlo. |

Cada certificado se aprueba por sí mismo, nunca la autoridad que lo firmó, así que un
segundo punto de recarga del mismo fabricante espera su propia aprobación. Compare la huella
digital con la que indica el punto de recarga antes de aprobarlo. Aprobar no cambia qué punto
de recarga es el certificado: se sigue admitiendo solo bajo el id del punto de recarga que
nombra, y solo dentro de sus fechas de validez. Un certificado en el que Windows ya confía se
admite como antes y nunca aparece aquí; nada se aprueba de forma automática.

Las decisiones se guardan en la carpeta de datos de la estación, en `ua\pki\ocpp`, y
sobreviven a un reinicio. Solo a un rol que puede configurar el Connector se le dibujan los
comandos, y estos actúan solo en la ventana de la propia estación: un navegador en otro
dispositivo lee la tarjeta sin cambiarla, y ninguna herramienta de un agente aprueba un
certificado. La lista guarda hasta 100 certificados a la espera de aprobación; cuando está
llena, uno nuevo se sigue rechazando pero no se lista, y la tarjeta lo dice.

## Los campos de conexión {#connection-fields}

| Campo | Qué es | Formato | Valor inicial |
|---|---|---|---|
| Identificador | El **id del punto de recarga** que representa este dispositivo: el mismo id que el cargador pone al final de su URL de conexión y que lleva en su certificado. | Texto libre, comparado sin distinguir mayúsculas. Vacío cae en el nombre higienizado del dispositivo. | vacío |

No hay campos de host, de puerto ni de credenciales: el cargador tiene los datos de la
conexión, y esta estación solo necesita saber a qué punto de recarga se refiere el
dispositivo. Tampoco hay campos de intervalo de sondeo. OCPP es de empuje (el punto de
recarga manda mensajes MeterValues y StatusNotification según su propio calendario) y los
tags se refrescan desde los últimos datos recibidos en un ciclo fijo de un segundo.

Por eso un punto de recarga que todavía no se ha conectado, o un conector que todavía no ha
reportado, **no tiene lectura**, no tiene una lectura fallida. Sus tags se quedan vacíos y
no se registra ninguna falla: un valor que el punto de recarga todavía no ha mandado es el
protocolo funcionando.

### El estado de salud del punto de recarga {#the-charge-points-health}

Como un punto de recarga manda sus valores cuando los tiene, el silencio de sus tags no puede
distinguir uno que todavía no ha reportado de uno que ya no está. Su estado de salud, el
punto en su fila del árbol y la columna **Estado de salud** en la página del driver, sigue
en cambio su conexión al sistema central de esta estación:

| Situación | Estado de salud |
|---|---|
| Configurado, y no se ha conectado desde que se abrió la estación | **Sin conexión** |
| Conectado, todavía sin mandar nada | **En línea** |
| Conectado y mandando | **En línea**, o **Parcialmente en línea** cuando algunos de los valores que mandó no se pueden leer |
| Se cayó: detenido, desenchufado o aislado de la red | **Sin conexión**, hasta que vuelva a conectarse |
| El sistema central sin escuchar | **Sin conexión** |
| Desactivado | **Desactivado** |

Mientras el punto de recarga está conectado, un conector que todavía no ha reportado no
cuenta en su contra. Durante hasta diez segundos después de guardar un cambio en el punto
de recarga, o de que el Connector arranque, se lee **Aún sin determinar**: volver a poner el
dispositivo puede reiniciar el sistema central, y el punto de recarga tarda un momento en
volver a conectarse.

## Los tags {#tags}

Un tag de OCPP lee un **conector** del punto de recarga (conector en el sentido de OCPP: una
posición de enchufe, numerada desde 1). En OCPP 2.0, 2.0.1 y 2.1 el número es el del **EVSE**, porque ahí
los conectores se vuelven a numerar desde 1 dentro de cada EVSE. Existen tres clases de tag, distinguidas por el
**sufijo del nombre del tag**, que se valida:

| El nombre del tag termina en | Qué lee | Tipo razonable |
|---|---|---|
| `Meter` | El valor de medidor muestreado más reciente que reportó el conector (MeterValues de OCPP; en OCPP 2.x, también los valores que trae un TransactionEvent durante una recarga). La unidad es la que mande el cargador, normalmente Wh. El servidor guarda las últimas 10 muestras y el tag lee la más nueva. Un conector que nunca ha reportado se lee como un valor vacío, no como cero. | Float o Double |
| `Status` | El texto de estado del conector de la última StatusNotification (por ejemplo `Available`, `Faulted`). En OCPP 2.x, un EVSE con más de un conector se lee como el más revelador de ellos: `Faulted` gana sobre `Occupied`, `Occupied` sobre `Reserved`, `Reserved` sobre `Available`, y `Available` sobre `Unavailable`. Un EVSE que todavía no reporta un estado se lee como un valor vacío. | String |
| `Transaction` | El número de la transacción en curso en el conector, que es lo que piden los comandos RemoteStopTransaction y GetTransactionStatus: en OCPP 1.6, el número que esta estación dio a la transacción al empezar; en OCPP 2.x, el identificador propio de la estación de recarga, tal cual lo envió. Se llena cuando empieza una transacción y se vacía cuando termina, así que sin ninguna en curso se lee como texto vacío. Hasta que una transacción empiece o termine después de que el punto de recarga se conecte, se lee como valor vacío, porque puede que ya hubiera una en curso. | String |

Un nombre sin ninguno de estos sufijos lo rechaza la validación: nombre los tags como
`Connector1Meter`, `Connector1Status` y `Connector1Transaction`.

| Campo | Qué hace | Valores | Valor inicial |
|---|---|---|---|
| Conector | El número que lee este tag: el del conector en OCPP 1.6, el del EVSE en OCPP 2.x. | 1 o mayor | 1 |
| Tipo de dato | El tipo OPC UA con el que se expone el valor. | Int32, Float, Double, String | Float |

Los tags de OCPP son de **solo lectura**: el campo de acceso no ofrece ninguna opción
escribible, y una escritura se rechaza en lugar de fingirse. Mandar a un punto de recarga es
un comando propio, descrito enseguida, no un valor escrito en un tag.

## Comandos {#commands}

A un punto de recarga se le manda además de leerlo. Cada dispositivo OCPP lleva los comandos
de abajo como **métodos del dispositivo** en el espacio de direcciones OPC UA propio de esta
estación, así que un cliente OPC UA conectado a esta estación lanza uno llamando al método.

Cada comando toma el **id del punto de recarga** como su primer argumento, y devuelve como
resultado la respuesta propia del punto de recarga.

| Comando | Otros argumentos | Qué hace |
|---|---|---|
| ChangeAvailability | ConnectorId, Type (`Operative` o `Inoperative`) | Pone un conector en servicio o lo saca de servicio. |
| ChangeConfiguration | Key, Value | Pone una clave de configuración en el punto de recarga (OCPP 1.6). |
| ClearCache | ninguno | Limpia la caché de autorización del punto de recarga. |
| GetConfiguration | Key | Lee una clave de configuración (OCPP 1.6). |
| RemoteStartTransaction | IdTag | Arranca una sesión de recarga para una credencial. |
| RemoteStopTransaction | TransactionId | Detiene una sesión en marcha. |
| GetTransactionStatus | TransactionId | Pregunta si una transacción sigue en marcha (OCPP 2.x). |
| Reset | ninguno | Reinicia el punto de recarga. |
| UnlockConnector | ConnectorId | Libera el cable de un conector. |
| SetChargingProfile | ConnectorId, Limit, NumberOfPhases | Pone un límite de potencia de recarga, en watts. ConnectorId 0 limita todo el punto de recarga; otro número pone el límite predeterminado de las sesiones que carga ese conector. |
| SetVariables | ComponentName, VariableName, AttributeType, AttributeValue | Pone una variable de un componente (OCPP 2.x). |
| GetVariables | ComponentName, VariableName, AttributeType | Lee una variable de un componente (OCPP 2.x). |

`AttributeType` es uno de `Actual`, `Target`, `MinSet`, `MaxSet`.

**De dónde sale el TransactionId.** RemoteStopTransaction y GetTransactionStatus actúan sobre una transacción, nombrada por su número. Léalo en el tag `Transaction` del conector en el que carga la sesión (el EVSE en OCPP 2.x), por ejemplo `Connector1Transaction`, y páselo tal como se lee. Un texto vacío ahí significa que no hay ninguna transacción en curso en ese conector.

**Un solo catálogo para cualquier versión.** Los comandos conservan los nombres de arriba sin
importar qué versión hable el punto de recarga, y la estación manda cada uno en la forma que
define esa versión. En OCPP 2.0, 2.0.1 y 2.1 los conectores se agrupan bajo EVSE, y el número
que se pasa como ConnectorId indica el EVSE.

| Comando | En OCPP 1.6 | En OCPP 2.0, 2.0.1 y 2.1 |
|---|---|---|
| ChangeAvailability | Actúa sobre el conector indicado; 0 es todo el punto de recarga. | Actúa sobre el EVSE indicado; 0 es toda la estación de recarga. |
| RemoteStartTransaction | Manda el IdTag, y el punto de recarga elige el conector. | Sale como RequestStartTransaction, con el IdTag como credencial central y su propio identificador de arranque; la estación de recarga elige el EVSE. |
| RemoteStopTransaction | El TransactionId es el número que esta estación le dio a la sesión al empezar. | Sale como RequestStopTransaction; el TransactionId es el identificador propio de la estación de recarga, que se pasa tal cual como texto. |
| Reset | Un reinicio completo. | Un reinicio inmediato. |
| UnlockConnector | Libera el conector indicado. | Libera el primer conector del EVSE indicado. |
| SetChargingProfile | 0 pone el perfil máximo del punto de recarga; otro conector recibe un perfil predeterminado. | 0 pone el perfil máximo de la estación de recarga; otro EVSE recibe un perfil predeterminado. |
| ChangeConfiguration, GetConfiguration | Como en la tabla de arriba. | No existen en estas versiones: la estación de recarga contesta con un error, y el comando falla. |
| GetTransactionStatus, SetVariables, GetVariables | No existen en esta versión: el punto de recarga contesta con un error, y el comando falla. | Como en la tabla de arriba. |

**Esperar la respuesta.** Un comando no termina cuando la estación lo mandó. La estación
mantiene la llamada abierta hasta que el punto de recarga conteste exactamente la orden que
se le envió, emparejada por el identificador de correlación que viaja con ella, y solo
entonces reporta éxito y devuelve la respuesta. Tres cosas lo terminan de otra manera, y cada
una se reporta como una falla con su motivo:

- El punto de recarga no está conectado, o su conexión no está abierta. No se envía nada.
- El punto de recarga contesta con un error de OCPP, por ejemplo por un comando que no
  implementa. El código de error es el motivo.
- Pasan **30 segundos** sin ninguna respuesta. Un comando que nadie contestó es una falla,
  nunca un éxito.

Un comando lanzado para un punto de recarga que ningún dispositivo lleva, o que no está
conectado, se rechaza de inmediato en lugar de encolarse.

## El descubrimiento {#discovery}

**Descubrir** en el driver OCPP lista los puntos de recarga **conectados en ese momento** al
sistema central, y leer los canales de un candidato propone un tag `Meter`, un tag `Status`
y un tag `Transaction` por cada conector que el punto de recarga haya reportado hasta ahí.

El **primer punto de recarga siempre se configura a mano**. Nada se puede conectar antes de
que el sistema central escuche, y escucha solo una vez que existe aquí un dispositivo OCPP,
así que un escaneo de una instalación sin ningún punto de recarga configurado no encuentra
nada y lo dice. Agregue ese primer dispositivo con el id con el que se conectará el cargador;
después de eso, un cargador que ya se conectó se puede descubrir. El flujo general del
descubrimiento se describe en la página del [Connector](connector).

El id se compara **sin distinguir mayúsculas**, en el certificado, en la ruta de conexión y
contra el dispositivo: un cargador que se conecta como `cp-a` con un certificado que nombra
`CP-A` es el mismo punto de recarga que un dispositivo cuyo Identificador dice `CP-A`.

Un punto de recarga que ya tiene vuelve a leer sus conectores desde su propia página: **Descubrir tags**, en el encabezado de su tarjeta de tags, ofrece los tags `Meter`, `Status` y `Transaction` de cada conector que reportó mientras estaba conectado y para el que el dispositivo todavía no tiene tag (vea [Descubrir los tags de un dispositivo](connector-discovery#discovering-a-devices-tags)).