# Comandos e Respostas do Protocolo

O **Protocolo CloudBox** é um conjunto de comandos e respostas projetados para controlar, configurar e monitorar o sistema de cronometragem do CloudBox. Esses comandos permitem gerenciar sessões de cronometragem, configurar as definições do sistema, verificar os status do sistema e executar várias funções de rede. Abaixo está uma explicação detalhada de todos os comandos, incluindo suas possíveis respostas e códigos de erro.

## Formato do Comando do Protocolo

Ao enviar comandos para o CloudBox via soquete TCP, os comandos devem sempre ser enviados como **texto simples** em um formato específico. A estrutura geral do comando segue estas regras:

1. **Nome do comando**: A primeira parte do comando é o nome da ação que você deseja executar (por exemplo, `CHANGESYSTEMIPADDRESS`).
2. **Argumentos**: Quaisquer argumentos obrigatórios ou opcionais devem ser passados **em ordem**, separados por **ponto e vírgula (`;`)**.
3. **Terminação**: cada comando deve ser terminado com os caracteres `\r` (retorno de carro e nova linha) para sinalizar o final do comando.

**Exemplo de Formato de Comando**

Por exemplo, ao enviar o comando `CHANGESYSTEMIPADDRESS` com os argumentos necessários para o endereço IP, porta e sub-rede, o formato seria:

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

Neste exemplo:

* `CHANGESYSTEMIPADDRESS`: O nome do comando.
* `192.168.1.100`: O novo endereço IP a ser atribuído ao sistema.
* `8080`: A nova porta a ser atribuída.
* `/24`: A máscara de sub-rede.
* `\r`: Marca o fim do comando.

## Formato de Resposta do Protocolo

No protocolo CloudBox, as respostas aos comandos são sempre estruturadas no formato **JSON**, seguindo um padrão consistente. Cada resposta contém duas chaves principais:

1. **comando**: Esta chave especifica o comando que foi enviado para o CloudBox. Ela confirma qual ação ou consulta foi solicitada.
2. **resultado**: Esta chave contém o resultado real ou os dados retornados pelo sistema com base no comando executado.

Aqui está um exemplo de uma resposta típica para o comando `GETSYSTEMTIME`:

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

## Comandos e Respostas Principais

### 1. INÍCIO

Inicia a sessão de cronometragem.

**Respostas**:

* `START_MODE`: O sistema já está no modo de temporização.
* `READERNOTOK`: O leitor RFID não está presente ou não está funcionando corretamente.
* `DEVICE_INTEGRITY_FAILED`: A verificação de integridade do dispositivo falhou.
* `INVALIDREADERMODEL`: O modelo de leitor configurado não é válido.
* `ERRREADER`: Erro geral de leitura.
* `OK`: A sessão de temporização foi iniciada com sucesso.

### 2. PARE

Interrompe a sessão de cronometragem atual.

**Respostas**:

* `READERNOTOK`: O leitor RFID não está presente ou não está funcionando corretamente.
* `INVALIDREADERMODEL`: O modelo de leitor configurado não é válido.
* `ERRREADER`: Erro geral de leitura.
* `OK`: A sessão foi encerrada com sucesso.

### 3. OBTERSTATUSDOSISTEMA

Retorna o estado atual do sistema, incluindo o nível da bateria, o estado da conexão de rede 4G, o estado do GPS e muito mais.

**Exemplo de resposta**:

```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. GETSYSTEMCONFIG

Obtém a configuração atual do sistema, incluindo as configurações de rede, a configuração do leitor e os parâmetros do sistema.

**Exemplo de resposta**:

```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;timestamp

Define a hora do sistema. O formato é `YYYY-MM-DD HH:mm:ss`.

**Respostas**:

* `BAD_FORMAT`: O formato da data ou da hora está incorreto.
* `START_MODE`: O sistema está no modo de temporização e o comando não pode ser executado.
* `NTPACTIVE`: A sincronização NTP está ativa e as alterações manuais de hora estão desativadas.
* `CMDERROR`: Erro geral de comando.
* `OK`: A hora do sistema foi definida com sucesso.

### 6. GETSYSTEMTIME

Retorna as configurações atuais de hora, fuso horário e sincronização do sistema.

**Exemplo de resposta**:

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

### 7. SETDATETIMESYNC;modoSincronização

Define o modo de sincronização de data e hora. As opções disponíveis são: `"DISABLED"`, `"GPS"`, `"NTP"`.

**Respostas**:

* `START_MODE`: O sistema está no modo de temporização e o comando não pode ser executado.
* `SYNCNOTAVAILABLE`: O modo de sincronização selecionado não está disponível.
* `OK`: O modo de sincronização foi definido com sucesso.

### 8. ALTERAR ENDEREÇO IP DO SISTEMA;ip;porta;sub-rede

Altera o endereço IP, a porta e a máscara de sub-rede do sistema.

**Respostas**:

* `START_MODE`: O sistema está no modo de temporização e o comando não pode ser executado.
* `INVALIDNETWORKCONFIGURATION`: A configuração de rede fornecida é inválida.
* `INVALIDNETWORKSUBNET`: A máscara de sub-rede é inválida.
* `RESERVEDIPADDRESS`: O endereço IP está reservado.
* `STDERROR`: Erro geral de aplicação.
* `OK`: Sucesso. O sistema será reiniciado para aplicar a nova configuração.

### 9. SETBUZZERPASSINGS;valor

Ativa ou desativa o sinal sonoro para detecções de passagem (verdadeiro/falso).

**Resposta**:

* `OK`: A configuração do sinal sonoro foi atualizada com sucesso.

### 10. SETBOUNCETIME;segundos

Define o tempo de repetição entre as leituras de RFID. Se segundos for `null` ou <= 0, o valor padrão será 5 segundos.

**Resposta**:

* `OK`: O tempo de ressalto foi definido com sucesso.

### 11. DESLIGAR

Desliga o sistema após 10-15 segundos.

**Respostas**:

* `START_MODE`: O sistema está no modo de temporização e o comando não pode ser executado.
* `OK`: O sistema será desligado.

### 12. LISTAR ARQUIVOS DE BACKUP

Retorna uma lista de arquivos de backup disponíveis. Exemplo: `["20240712-135902.txt"]`

**Respostas**:

* `ERROR`: Não foi possível recuperar os arquivos de backup.
* `OK`: A lista de arquivos foi recuperada com sucesso.

### 13. EXCLUIR ARQUIVOS DE BACKUP

Exclui todos os arquivos de backup do sistema.

**Respostas**:

* `START_MODE`: O sistema está no modo de temporização e o comando não pode ser executado.
* `ERROR`: Falha ao excluir os arquivos.
* `OK`: Os arquivos de backup foram excluídos com sucesso.

### 14. REBOBINAR;timestampInicial;timestampFinal

Rebobina os dados de passagem entre os carimbos de data/hora de início e fim especificados (`YYYY-MM-DD HH:mm:ss`) e os transmite para clientes TCP conectados.

**Resposta**:

* `OK`: Os dados de aprovação estão sendo transmitidos.

### 15. OBTERINFORMAÇÕESDEGPS

Retorna as informações do GPS, incluindo latitude, longitude, altitude e a hora da última sincronização.

**Exemplo de resposta**:

```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"
}
```