# Comandos y respuestas del protocolo

El **Protocolo CloudBox** es un conjunto de comandos y respuestas diseñados para controlar, configurar y supervisar el sistema de cronometraje de CloudBox. Estos comandos le permiten gestionar sesiones de cronometraje, configurar los ajustes del sistema, comprobar los estados del sistema y realizar diversas funciones de red. A continuación, se ofrece una explicación detallada de todos los comandos, incluidas sus posibles respuestas y códigos de error.

## Formato de comando del protocolo

Al enviar comandos a CloudBox a través de un socket TCP, los comandos siempre deben enviarse como **texto sin formato** en un formato específico. La estructura general del comando sigue estas reglas:

1. **Nombre del comando**: La primera parte del comando es el nombre de la acción que desea realizar (por ejemplo, `CHANGESYSTEMIPADDRESS`).
2. **Argumentos**: Cualquier argumento requerido u opcional debe pasarse **en orden**, separado por **puntos y coma (`;`)**.
3. **Terminación**: cada comando debe terminar con los caracteres `\r` (retorno de carro y salto de línea) para indicar el final del comando.

**Ejemplo de formato de comando**

Por ejemplo, al enviar el comando `CHANGESYSTEMIPADDRESS` con los argumentos necesarios para la dirección IP, el puerto y la subred, el formato sería:

```plaintext
CHANGESYSTEMIPADDRESS;192.168.1.100;8080;/24\r\n
```

En este ejemplo:

* `CHANGESYSTEMIPADDRESS`: El nombre del comando.
* `192.168.1.100`: La nueva dirección IP que se asignará al sistema.
* `8080`: El nuevo puerto que se asignará.
* `/24`: La máscara de subred.
* `\r`: Marca el final del comando.

## Formato de respuesta del protocolo

En el protocolo CloudBox, las respuestas a los comandos siempre se estructuran en un **formato JSON**, siguiendo un patrón consistente. Cada respuesta contiene dos claves principales:

1. **comando**: Esta clave especifica el comando que se envió a la CloudBox. Confirma qué acción o consulta se solicitó.
2. **resultado**: Esta clave contiene el resultado o los datos reales devueltos por el sistema en función del comando ejecutado.

A continuación, se muestra un ejemplo de una respuesta típica para el comando `GETSYSTEMTIME`:

```json
{
    "command": "GETSYSTEMTIME",
    "result": {
        "dateTimeSync": "NTP",
        "timezone": "Europe/Madrid (CEST, +0200)",
        "timestamp": "2024-09-17;18:44:11.649"
    }
}
```

## Comandos y respuestas clave

### 1. INICIO

Inicia la sesión de cronometraje.

**Respuestas**:

* `START_MODE`: El sistema ya está en modo de temporización.
* `READERNOTOK`: El lector RFID no está presente o no funciona correctamente.
* `DEVICE_INTEGRITY_FAILED`: La comprobación de la integridad del dispositivo ha fallado.
* `INVALIDREADERMODEL`: El modelo de lector configurado no es válido.
* `ERRREADER`: Error general del lector.
* `OK`: La sesión de temporización se ha iniciado correctamente.

### 2. DETENER

Detiene la sesión de cronometraje actual.

**Respuestas**:

* `READERNOTOK`: El lector RFID no está presente o no funciona correctamente.
* `INVALIDREADERMODEL`: El modelo de lector configurado no es válido.
* `ERRREADER`: Error general del lector.
* `OK`: La sesión se ha detenido correctamente.

### 3. OBTENER ESTADO DEL SISTEMA

Devuelve el estado actual del sistema, incluido el nivel de la batería, el estado de la conexión a la red 4G, el estado del GPS y más.

**Ejemplo de respuesta**:

```json
{
  "batteryVolts": "25.33",
  "batteryPercentage": "88.27",
  "cpuTemperature": "53.75",
  "hasPower": false,
  "hasInternet": true,
  "startMode": false,
  "sessionPassingCount": 0,
  "lastPassingTimestamp": null,
  "operator4G": null,
  "signal4G": null,
  "networkService4G": null,
  "status4G": {"status": "CME_ERROR", "message": "SIM not inserted"},
  "statusGps": {"status": "SEARCHING", "message": "No GPS data found. Searching..."},
  "statusIoT": {"status": true, "message": "Connected to IoT server"},
  "backupDownloadLink": "http://192.168.0.3:2999/download",
  "sessionToken": null,
  "cloudPassingCount": 0,
  "deviceIntegrity": "Device integrity check passed",
  "readerStatus": "RFID Reader not found",
  "updateInfo": null,
  "currentBackendVersion": "1.0.4",
  "currentFrontVersion": "1.0.4"
}
```

### 4. OBTENERCONFIGURACIÓNDELSISTEMA

Obtiene la configuración actual del sistema, incluidos los ajustes de red, la configuración del lector y los parámetros del sistema.

**Ejemplo de respuesta**:

```json
{
  "bounceTime": 1,
  "buzzerPassings": false,
  "readerModel": "R420",
  "readerHost": "10.0.0.2",
  "readerPort": "5084",
  "tcpHost": "192.168.0.3",
  "tcpSubnet": "/8",
  "tcpPort": "8080",
  "apName": "CLBX_192_168_0_3",
  "wifiSsid": "MOVISTAR_91DA",
  "disableStartButton": false,
  "dateTimeSync": "NTP",
  "timezone": "America/Argentina/Buenos_Aires",
  "simPin": "4509",
  "modemImei": "862636053313696",
  "deviceSerialNumber": "CLBX10001"
}
```

### 5. SETSYSTEMTIME;marca de tiempo

Establece la hora del sistema. El formato es `YYYY-MM-DD HH:mm:ss`.

**Respuestas**:

* `BAD_FORMAT`: El formato de fecha u hora es incorrecto.
* `START_MODE`: El sistema está en modo de temporización y el comando no se puede ejecutar.
* `NTPACTIVE`: La sincronización NTP está activa y los cambios manuales de hora están deshabilitados.
* `CMDERROR`: Error general de comando.
* `OK`: La hora del sistema se ha configurado correctamente.

### 6. GETSYSTEMTIME

Devuelve la hora actual del sistema, la zona horaria y la configuración de sincronización.

**Ejemplo de respuesta**:

```json
{
  "dateTimeSync": "NTP",
  "timezone": "Europe/Madrid (CEST, +0200)",
  "timestamp": "2024-09-17;18:44:11.649"   
}
```

### 7. SETDATETIMESYNC;syncMode

Establece el modo de sincronización de fecha y hora. Las opciones disponibles son: `"DISABLED"`, `"GPS"`, `"NTP"`.

**Respuestas**:

* `START_MODE`: El sistema está en modo de temporización y el comando no se puede ejecutar.
* `SYNCNOTAVAILABLE`: El modo de sincronización seleccionado no está disponible.
* `OK`: El modo de sincronización se ha configurado correctamente.

### 8. CAMBIAR LA DIRECCIÓN IP DEL SISTEMA;ip;puerto;subred

Cambia la dirección IP, el puerto y la máscara de subred del sistema.

**Respuestas**:

* `START_MODE`: El sistema está en modo de temporización y el comando no se puede ejecutar.
* `INVALIDNETWORKCONFIGURATION`: La configuración de red proporcionada no es válida.
* `INVALIDNETWORKSUBNET`: La máscara de subred no es válida.
* `RESERVEDIPADDRESS`: La dirección IP está reservada.
* `STDERROR`: Error general de aplicación.
* `OK`: Éxito. El sistema se reiniciará para aplicar la nueva configuración.

### 9. SETBUZZERPASSINGS;valor

Habilita o deshabilita el zumbador para las detecciones de paso (verdadero/falso).

**Respuesta**:

* `OK`: La configuración del zumbador se ha actualizado correctamente.

### 10. SETBOUNCETIME;segundos

Establece el tiempo de rebote entre las lecturas de RFID. Si los segundos son `null` o <= 0, el valor predeterminado es de 5 segundos.

**Respuesta**:

* `OK`: El tiempo de rebote se ha configurado correctamente.

### 11. APAGADO

Apaga el sistema después de 10-15 segundos.

**Respuestas**:

* `START_MODE`: El sistema está en modo de temporización y el comando no se puede ejecutar.
* `OK`: El sistema se apagará.

### 12. LISTAR ARCHIVOS DE COPIA DE SEGURIDAD

Devuelve una lista de los archivos de copia de seguridad disponibles. Ejemplo: `["20240712-135902.txt"]`

**Respuestas**:

* `ERROR`: No se pudieron recuperar los archivos de copia de seguridad.
* `OK`: Se ha recuperado correctamente la lista de archivos.

### 13. ELIMINAR ARCHIVOS DE COPIA DE SEGURIDAD

Elimina todos los archivos de copia de seguridad del sistema.

**Respuestas**:

* `START_MODE`: El sistema está en modo de temporización y el comando no se puede ejecutar.
* `ERROR`: No se pudieron eliminar los archivos.
* `OK`: Los archivos de copia de seguridad se han eliminado correctamente.

### 14. REBOBINAR;timestamp de inicio;timestamp de finalización

Rebobina los datos de paso entre las marcas de tiempo de inicio y finalización especificadas (`YYYY-MM-DD HH:mm:ss`) y los transmite a los clientes TCP conectados.

**Respuesta**:

* `OK`: Se están transmitiendo los datos.

### 15. OBTENERINFORMACIÓNDEGPS

Devuelve la información del GPS, incluyendo la latitud, la longitud, la altitud y la hora de la última sincronización.

**Ejemplo de respuesta**:

```json
{
  "latitudeDecimal": 41.28425,
  "longitudeDecimal": 1.98251,
  "googleMapsLink": "https://www.google.com/maps/place/41.28425,1.98251",
  "gpsTimezone": "Europe/Madrid",
  "altitude": 38.7,
  "speed": 0,
  "lastSync": "2024-07-24 20:27:02"
}
```