{"id":31829518,"url":"https://github.com/ju-sants/communication-protocol-translator","last_synced_at":"2026-05-17T15:34:15.492Z","repository":{"id":314891703,"uuid":"1045208945","full_name":"ju-sants/communication-protocol-translator","owner":"ju-sants","description":" Servidor gateway poliglota para rastreamento veicular, atuando como uma ponte universal entre diversos protocolos de rastreadores (GT06, JT808, VL01, NT40, etc.) e uma plataforma central. Adiciona inteligência aos dados brutos e gerencia o fluxo de comandos de forma bidirecional. ","archived":false,"fork":false,"pushed_at":"2025-09-23T19:20:57.000Z","size":547,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-23T20:23:04.751Z","etag":null,"topics":["api-restful","gateway-server","gt06","iot","jt808","modular-architecture","nt40","python","redis","tcp-server","telematics","vehicle-tracking","vl01"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ju-sants.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-26T20:15:30.000Z","updated_at":"2025-09-23T18:18:53.000Z","dependencies_parsed_at":"2025-09-15T13:26:36.327Z","dependency_job_id":"e627c69a-e84f-4ff4-bec9-a7dbbd3ccdb0","html_url":"https://github.com/ju-sants/communication-protocol-translator","commit_stats":null,"previous_names":["ju-sants/communication-protocol-translator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ju-sants/communication-protocol-translator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ju-sants%2Fcommunication-protocol-translator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ju-sants%2Fcommunication-protocol-translator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ju-sants%2Fcommunication-protocol-translator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ju-sants%2Fcommunication-protocol-translator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ju-sants","download_url":"https://codeload.github.com/ju-sants/communication-protocol-translator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ju-sants%2Fcommunication-protocol-translator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279008619,"owners_count":26084480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-restful","gateway-server","gt06","iot","jt808","modular-architecture","nt40","python","redis","tcp-server","telematics","vehicle-tracking","vl01"],"created_at":"2025-10-11T20:28:12.858Z","updated_at":"2026-05-17T15:34:15.478Z","avatar_url":"https://github.com/ju-sants.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Servidor Gateway Poliglota para Rastreamento Veicular\n\nEste projeto é um **gateway de tradução universal** para o setor de telemétria, projetado para resolver o desafio da **fragmentação de protocolos**. Com uma arquitetura modular e de alto desempenho, ele atua como uma ponte entre diversos modelos de rastreadores e uma plataforma central.\n\n## Tabela de Conteúdos\n- [Visão Geral](#visão-geral)\n- [Principais Funcionalidades](#principais-funcionalidades)\n- [Arquitetura do Sistema](#arquitetura-do-sistema)\n  - [Fluxo de Dados (Uplink)](#fluxo-de-dados-uplink-dispositivo---plataforma)\n  - [Fluxo de Comandos (Downlink)](#fluxo-de-comandos-downlink-plataforma---dispositivo)\n- [Dados Persistidos no Redis](#dados-persistidos-no-redis)\n- [Gerenciamento de Sessões TCP](#gerenciamento-de-sessões-tcp)\n- [Gerenciamento de Rastreadores Híbridos (GSM/Satélite)](#gerenciamento-de-rastreadores-híbridos-gsm-satélite)\n- [Rastreabilidade de Logs Aprimorada](#rastreabilidade-de-logs-aprimorada)\n- [Streaming de Logs em Tempo Real (WebSocket)](#streaming-de-logs-em-tempo-real-websocket)\n- [Protocolos Suportados](#protocolos-suportados)\n- [Endpoints da API](#endpoints-da-api)\n- [Como Começar](#como-começar)\n- [Como Adicionar um Novo Protocolo](#como-adicionar-um-novo-protocolo)\n- [Estrutura do Projeto (Árvore de Diretórios)](#estrutura-do-projeto)\n- [Tecnologias Utilizadas](#tecnologias-utilizadas)\n\n## Visão Geral\n\nA força deste projeto reside em sua arquitetura inteligente e desacoplada, que oferece funcionalidades muito além de uma simples tradução de dados. Ele foi desenhado para ser uma solução \"plug-and-play\", onde adicionar suporte a novos protocolos de entrada ou saída exige o mínimo de esforço, sem impactar a estabilidade do sistema existente. O objetivo é fornecer uma base robusta e flexível para qualquer plataforma de rastreamento.\n\n## Principais Funcionalidades\n\n*   **Arquitetura Modular \"Plug-and-Play\"**: Adicionar suporte a um novo protocolo é tão simples quanto criar um novo módulo. A estrutura isola a lógica de cada protocolo, permitindo que o sistema evolua sem aumento de complexidade. O orquestrador em [`main.py`](main.py) carrega dinamicamente cada protocolo, iniciando listeners dedicados em threads separadas.\n\n*   **Tradução Bidirecional (N x N)**: O sistema traduz múltiplos protocolos de entrada para múltiplos protocolos de saída. Cada `mapper` de entrada converte o dialeto do dispositivo para um **dicionário Python padronizado**. A camada de `output` (ex: [`app/src/output/suntech4g/builder.py`](app/src/output/suntech4g/builder.py)) utiliza esse dicionário para construir pacotes nos formatos de saída desejados, garantindo um desacoplamento total.\n\n*   **Inteligência Agregada com Gestão de Estado**: O gateway utiliza o Redis ([`app/services/redis_service.py`](app/services/redis_service.py)) para armazenar o estado de cada dispositivo. Ao receber um novo pacote, ele compara o estado atual com o anterior e pode **gerar novos eventos de alerta** (ex: \"Alerta de Ignição Ligada\") que não existiam no protocolo original, agregando valor e inteligência aos dados.\n\n*   **Roteamento Reverso de Comandos**: O fluxo de comandos (downlink) é igualmente robusto. Comandos recebidos pela plataforma são traduzidos por um `mapper` de saída (ex: [`app/src/output/suntech4g/mapper.py`](app/src/output/suntech4g/mapper.py)) para um formato universal. O sistema então identifica o protocolo de origem do dispositivo e invoca o `builder` correspondente (ex: [`app/src/input/j16x_j16/builder.py`](app/src/input/j16x_j16/builder.py)) para enviar o comando no formato nativo do rastreador.\n\n*   **Logs Contextualizados e Rastreáveis**: O sistema de log foi aprimorado para incluir um `log_label` em cada registro. Utilizando `logger.contextualize`, cada thread de comunicação de um rastreador é \"marcada\" com sua identidade, garantindo que todas as operações subsequentes, de qualquer função ou módulo, sejam registradas com o ID correto. Isso simplifica drasticamente a depuração e o monitoramento de dispositivos específicos em um ambiente de alta concorrência.\n\n*   **Streaming de Logs em Tempo Real via WebSocket**: Para facilitar a depuração e o monitoramento ao vivo, foi implementado um servidor WebSocket ([`app/websocket/ws.py`](app/websocket/ws.py)). Clientes podem se conectar a este servidor para receber um fluxo contínuo de logs filtrados por um `log_label` específico, permitindo uma análise detalhada do comportamento de um dispositivo em tempo real.\n\n## Arquitetura do Sistema\n\nA arquitetura foi desenhada para máxima clareza, escalabilidade e manutenibilidade. A seguir, os fluxos de dados e comandos são detalhados para ilustrar o funcionamento interno do gateway.\n\n### Fluxo de Dados (Uplink: Dispositivo -\u003e Plataforma)\n\nEste diagrama mostra como os dados de um rastreador são recebidos, traduzidos e encaminhados para a plataforma final.\n\n```mermaid\ngraph TD\n    A[Dispositivo Rastreador] -- Pacote TCP --\u003e B(Listener de Protocolo de Entrada);\n    B -- Bytes Brutos --\u003e C{Handler};\n    C -- Pacote Bruto --\u003e D(Processor);\n    D -- Dados Dissecados --\u003e E(Input Mapper);\n    E -- Dicionário Padrão --\u003e F(send_to_main_server);\n    F -- Dicionário Padrão --\u003e G{Output Builder};\n    G -- Pacote de Saída Formatado --\u003e H(Main Server Connection);\n    H -- Pacote TCP --\u003e I[Plataforma Principal];\n\n    subgraph \"Módulo de Protocolo de Entrada (Ex: j16x_j16, vl01)\"\n        C\n        D\n        E\n    end\n\n    subgraph \"Módulo de Protocolo de Saída (Ex: Suntech4G, GT06)\"\n        G\n    end\n\n    subgraph \"Serviços Centrais\"\n        F\n        H\n    end\n```\n\n### Fluxo de Comandos (Downlink: Plataforma -\u003e Dispositivo)\n\nEste diagrama ilustra como os comandos são enviados da plataforma de volta para o dispositivo correto, na linguagem correta.\n\n```mermaid\ngraph TD\n    A[Plataforma Principal] -- Pacote TCP --\u003e B(Main Server Connection);\n    B -- Bytes Brutos --\u003e C{Output Mapper};\n    C -- Comando Universal --\u003e D(Roteador de Comandos);\n    D -- Consulta Protocolo de Entrada (DevID) --\u003e E{Redis};\n    E -- Retorna Protocolo (ex: 'j16x_j16') --\u003e D;\n    D -- Comando Universal para Builder Específico --\u003e F{Input Builder};\n    F -- Pacote Binário Nativo --\u003e G(Socket do Dispositivo);\n    G -- Pacote TCP --\u003e H[Dispositivo Rastreador];\n\n    subgraph \"Módulo de Protocolo de Saída (Ex: Suntech4G, GT06)\"\n        C\n    end\n\n    subgraph \"Módulo de Protocolo de Entrada (Ex: j16x_j16, vl01)\"\n        F\n    end\n\n    subgraph \"Serviços Centrais\"\n        B\n        D\n        E\n    end\n```\n\n## Dados Persistidos no Redis\n\nO Redis é utilizado como um armazenamento de estado de curto prazo e cache para otimizar as operações do gateway. As chaves são categorizadas principalmente por `device_id` (IMEI) para dados do rastreador e chaves `history:\u003cdevice_id\u003e` para o histórico de pacotes.\n\n### Estrutura de Dados do Dispositivo (`\u003cdevice_id\u003e`)\n\nPara cada rastreador conectado ou que já se conectou, um hash é mantido no Redis sob a chave sendo o `device_id` (geralmente o IMEI em formato hexadecimal ou string, dependendo do protocolo).\n\n| Campo                  | Tipo      | Descrição                                                                         | Exemplo             |\n| :--------------------- | :-------- | :-------------------------------------------------------------------------------- | :------------------ |\n| `protocol`             | `string`  | O protocolo que o dispositivo utiliza (ex: `j16x_j16`, `jt808`, `vl01`, `nt40`).        | `\"j16x_j16\"`            |\n| `output_protocol`      | `string`  | O protocolo de saída que o dispositivo utiliza (ex: `suntech4g`, `gt06`).        | `\"suntech4g\"`            |\n| `imei`                 | `string`  | O IMEI do dispositivo.                                                            | `\"358204012345678\"` |\n| `last_serial`          | `integer` | O último número de série do pacote recebido do dispositivo.                       | `\"12345\"`           |\n| `last_active_timestamp`| `string`  | Timestamp UTC da última vez que o dispositivo enviou qualquer tipo de pacote (ISO 8601). | `\"2023-10-27T10:35:00.123456+00:00\"` |\n| `last_event_type`      | `string`  | O tipo do último evento recebido (`location`, `heartbeat`, `alarm`, `information`). | `\"location\"`        |\n| `total_packets_received`| `integer` | Contador total de pacotes recebidos do dispositivo desde o início.               | `\"1501\"`            |\n| `last_packet_data`   | `JSON string` | Dados da última localização decodificada do protocolo, usados internamente para alertas (menos campos). | `{\"latitude\": -23.55, ...}` |\n| `last_full_location`   | `JSON string` | Dados completos da última localização reportada, incluindo todos os detalhes.    | `{\"timestamp\": \"2023-10-27T...\", \"latitude\": -23.55, \"speed_kmh\": 60, ...}` |\n| `odometer`             | `float`   | Odômetro calculado pelo servidor (em metros), baseado na distância Haversine. | `\"12345678.90\"`     |\n| `acc_status`           | `integer` | Status da ignição (0: OFF, 1: ON).                                                | `\"1\"`               |\n| `power_status`         | `integer` | Status da alimentação principal (0: Conectada, 1: Desconectada).                  | `\"0\"`               |\n| `last_voltage`         | `float`   | Última voltagem da bateria do dispositivo reportada.                              | `\"12.8\"`            |\n| `last_output_status`   | `integer` | Último estado da saída de controle (ex: bloqueio) (0: Desligado, 1: Ligado).     | `\"1\"`               |\n| `last_command_sent`    | `JSON string` | Detalhes do último comando enviado do servidor para o dispositivo.             | `{\"command\": \"RELAY 0\", \"timestamp\": \"...\", \"packet_hex\": \"...\"}` |\n| `last_command_response`| `JSON string` | Detalhes da última resposta de comando recebida do dispositivo. (Atualmente não implementado para todos os protocolos) | `{\"response\": \"OK\", \"timestamp\": \"...\"}` |\n\n### Gerenciamento Avançado de Dados (Exemplo: Protocolo VL01)\n\nO sistema permite a implementação de lógicas avançadas de gerenciamento de dados diretamente no gateway. O protocolo VL01, por exemplo, utiliza o [`mapper.py`](app/src/input/vl01/mapper.py) para enriquecer os dados brutos com informações calculadas pelo servidor.\n\n#### Estratégias de Gerenciamento de Pacotes:\n\n*   **Fila Persistente de Pacotes (Redis)**: Pacotes de localização, alarme e informação recebidos do protocolo VL01 são adicionados a uma fila persistente no Redis (`vl01_persistent_packet_queue`). Isso garante que os dados não sejam perdidos em caso de falha do servidor e permite o processamento ordenado.\n*   **Processamento em Lotes**: A fila processa os pacotes em lotes de 30, garantindo que sejam tratados na ordem cronológica de seus timestamps (extraídos do próprio pacote quando disponíveis).\n\n#### Informações Gerenciadas Exclusivamente pelo Servidor:\n\nAlguns dados cruciais são calculados ou mantidos inteiramente no servidor, agregando inteligência aos dados brutos:\n\n*   **Odômetro (`gps_odometer`)**: O valor do odômetro é calculado pelo servidor utilizando a fórmula de Haversine com base nas coordenadas de localização recebidas. Este valor é persistido no Redis e acumulado ao longo do tempo.\n*   **Voltagem (`last_voltage`)**: A voltagem da bateria do dispositivo é extraída de pacotes de informação específicos e armazenada no Redis, permitindo um acompanhamento preciso do estado de energia do rastreador.\n\n### Histórico de Pacotes (`history:\u003cdevice_id\u003e`)\n\nPara cada dispositivo, uma lista é mantida no Redis contendo os pacotes brutos e seus respectivos pacotes Suntech4G traduzidos. Esta lista é limitada a `HISTORY_LIMIT` (definido em [`app/services/history_service.py`](app/services/history_service.py)) entradas.\n\n| Campo            | Tipo      | Descrição                                         | Exemplo                       |\n| :--------------- | :-------- | :------------------------------------------------ | :---------------------------- |\n| `raw_packet`     | `string`  | O pacote original recebido do rastreador (hex).   | `\"78780d01...\"`               |\n| `translated_packet` | `string`  | O pacote traduzido para o formato de saída.        | `\"\u003eSTT,IMEI,...\"` ou `\"7878...\"` |\n\n## Gerenciamento de Sessões TCP\n\nO gateway gerencia ativamente as conexões TCP para garantir a comunicação bidirecional de forma eficiente e resiliente. A lógica é dividida em dois componentes principais, localizados em `app/src/session/`.\n\n### Sessões de Entrada (Rastreador -\u003e Gateway)\n\n-   **Componente**: [`app/src/session/input_sessions_manager.py`](app/src/session/input_sessions_manager.py:10)\n-   **Responsabilidade**: Manter um registro de todas as conexões TCP ativas vindas dos rastreadores.\n-   **Funcionamento**: Utiliza um singleton (`InputSessionsManager`) que armazena os objetos de socket em um dicionário, usando o `device_id` como chave. Esse gerenciador é vital para o fluxo de **downlink**, pois permite que o sistema encontre rapidamente a conexão exata de um dispositivo para enviar comandos recebidos da plataforma principal.\n\n### Sessões de Saída (Gateway -\u003e Plataforma Principal)\n\n-   **Componente**: [`app/src/session/output_sessions_manager.py`](app/src/session/output_sessions_manager.py:16)\n-   **Responsabilidade**: Gerenciar as conexões de saída do gateway para a plataforma de rastreamento principal.\n-   **Funcionamento**: Também implementado como um singleton (`OutputSessionsManager`), este módulo gerencia objetos de `MainServerSession`. Cada sessão representa uma conexão persistente para um `device_id` específico com o servidor final. Ele é responsável por:\n    -   Estabelecer a conexão e autenticar o dispositivo (enviando pacotes de login).\n    -   Manter a conexão ativa e reconectar em caso de falha.\n    -   Encaminhar os pacotes de dados já traduzidos.\n    -   Manter uma thread de escuta (`_reader_loop`) para receber comandos da plataforma (downlink) e roteá-los para o `builder` do protocolo de entrada correto.\n\nEssa arquitetura de sessões desacoplada garante que o núcleo do sistema seja robusto a falhas de conexão e que o fluxo de comandos seja tratado de forma assíncrona e eficiente.\n\n### Gerenciamento de Rastreadores Híbridos (GSM/Satélite)\n\nO sistema possui uma lógica especializada para lidar com rastreadores \"híbridos\", que combinam comunicação GSM/GPRS com um rastreador satelital secundário. Em vez de tratar os dois como dispositivos separados, o gateway os unifica sob uma única identidade, enriquecendo os dados de um com o outro.\n\n#### Fluxo de Dados Satelital:\n\n1.  **Recepção e Mapeamento**: Um listener dedicado em [`app/src/input/satellital/handler.py`](app/src/input/satellital/handler.py:14) aguarda conexões de dispositivos satelitais. Ao receber um pacote, ele o encaminha para o [`mapper.py`](app/src/input/satellital/mapper.py:12).\n\n2.  **Associação GSM**: O `mapper` extrai o Identificador Único do Equipamento (ESN) e consulta o Redis para encontrar o `device_id` (IMEI) do rastreador GSM correspondente. Essa associação é crucial, pois o dispositivo satelital atua como um \"anexo\" do GSM.\n\n3.  **Fusão de Dados**: O sistema recupera a última localização enviada pelo rastreador GSM e a funde com os dados recebidos do satélite. Para diferenciar os pacotes, ele **sobrescreve** os seguintes campos:\n    *   `voltage`: Alterado para `2.22` como um indicador de que a posição veio do módulo satelital.\n    *   `satellites`: Alterado para `2` para sinalizar a origem satelital.\n\n4.  **Envio Unificado**: O pacote híbrido resultante é enviado para a plataforma principal através da conexão e sessão já estabelecida pelo rastreador GSM ([`output_sessions_manager.py`](app/src/session/output_sessions_manager.py:269)), garantindo que a plataforma veja apenas um dispositivo, mas com dados enriquecidos de ambas as fontes.\n\n## Rastreabilidade de Logs Aprimorada\n\nO sistema utiliza um mecanismo de log contextual para garantir que cada operação possa ser rastreada até um dispositivo específico. Isso é alcançado através da injeção de um `log_label` (geralmente o IMEI do dispositivo) no contexto do logger.\n\n### Como Funciona:\n\nA função `logger.contextualize(log_label=dev_id)` é usada no início de cada thread de conexão de um rastreador (ex: em [`app/src/input/nt40/handler.py`](app/src/input/nt40/handler.py:22)). Uma vez que o contexto é definido, qualquer chamada subsequente ao logger (`logger.info`, `logger.error`, etc.), não importa de qual módulo ou função, incluirá automaticamente o `log_label` no registro de log.\n\n**Exemplo de linha de log:**\n```\nINFO     | __main__: ✅ Protocol listener iniciado com sucesso na porta 7028 extra={'log_label': 'SERVIDOR'}\nINFO     | app.src.input.nt40.handler: Nova conexão NT40 recebida endereco=('127.0.0.1', 49774) extra={'log_label': '358204012345678'}\n```\n\nIsso torna a análise de logs e a depuração de problemas de um dispositivo específico extremamente eficiente.\n\n## Streaming de Logs em Tempo Real (WebSocket)\n\nPara complementar a rastreabilidade dos logs, o sistema inclui um servidor WebSocket que transmite logs em tempo real para clientes conectados. Isso é ideal para depuração ao vivo e monitoramento do comportamento de um rastreador.\n\n### Como Usar:\n\n1.  **Conecte-se ao Servidor WebSocket**: O servidor é iniciado por padrão em `ws://\u003cseu-host\u003e:8575`.\n2.  **Envie a Mensagem de Inscrição**: Após a conexão, envie uma mensagem no formato `\"\u003ctracker_id\u003e|\u003cnumero_de_linhas\u003e\"`.\n   *   `\u003ctracker_id\u003e`: O ID do dispositivo que você deseja monitorar.\n   *   `\u003cnumero_de_linhas\u003e`: O número de linhas de log históricas a serem exibidas no início do streaming (ex: `100`).\n\nO servidor ([`app/websocket/ws.py`](app/websocket/ws.py:1)) então começará a transmitir todas as novas linhas de log que correspondem ao `tracker_id` fornecido.\n\n## Protocolos Suportados\n\n### Entrada\n\n*   **GT06**: Um dos protocolos mais comuns em dispositivos de rastreamento genéricos.\n*   **JT/T 808**: Um protocolo padrão robusto, amplamente utilizado em veículos comerciais.\n*   **VL01**: Protocolo específico com gerenciamento avançado de dados no servidor.\n\n### Saída\n\n*   **Suntech4G**\n*   **GT06**\n\n\n## Endpoints da API\n\nO servidor gateway expõe uma API RESTful para consulta de dados em tempo real e gerenciamento de sessões, facilitando a integração com outras plataformas e painéis de monitoramento. A lógica de gerenciamento de sessões de socket foi centralizada no diretório [`app/src/session/`](app/src/session/).\n\n### `GET /trackers`\nRetorna um dicionário com todos os dados dos rastreadores salvos no Redis, incluindo o status de conexão (`is_connected`).\nExemplo de Resposta:\n```json\n{\n  \"IMEI_DO_RASTREADOR_1\": {\n    \"protocol\": \"j16x_j16\",\n    \"last_active_timestamp\": \"2023-10-27T10:30:00.000000+00:00\",\n    \"is_connected\": true,\n    \"last_packet_data\": \"{\\\"latitude\\\": -23.55052, ...}\",\n    \"odometer\": \"12345.67\",\n    \"acc_status\": \"1\",\n    \"power_status\": \"0\",\n    \"last_voltage\": \"12.5\",\n    \"imei\": \"IMEI_DO_RASTREADOR_1\",\n    \"last_full_location\": \"{\\\"latitude\\\": -23.55052, ...}\",\n    \"last_event_type\": \"location\",\n    \"total_packets_received\": \"1500\"\n  },\n  \"IMEI_DO_RASTREADOR_2\": {\n    \"protocol\": \"nt40\",\n    \"is_connected\": false,\n    \"last_active_timestamp\": \"2023-10-27T09:45:00.000000+00:00\",\n    \"...\": \"...\"\n  }\n}\n```\n\n### `GET /trackers/summary`\nFornece estatísticas de alto nível sobre os rastreadores no sistema.\nExemplo de Resposta:\n```json\n{\n  \"total_registered_trackers\": 50,\n  \"total_active_translator_sessions\": 25,\n  \"total_active_main_server_sessions\": 20,\n  \"protocol_distribution\": {\n    \"j16x_j16\": 30,\n    \"jt808\": 15,\n    \"vl01\": 5\n  },\n  \"total_packets_in_history\": 120000,\n  \"most_recent_active_trackers\": [\n    {\"device_id\": \"IMEI_RECENTE_1\", \"last_active_timestamp\": \"2023-10-27T10:35:00.000000+00:00\"},\n    {\"device_id\": \"IMEI_RECENTE_2\", \"last_active_timestamp\": \"2023-10-27T10:34:00.000000+00:00\"}\n  ]\n}\n```\n\n### `GET /trackers/\u003cdev_id\u003e/details`\nRetorna detalhes abrangentes para um rastreador específico, incluindo dados do Redis e status de conexão.\nExemplo de Resposta:\n```json\n{\n  \"device_id\": \"IMEI_DO_RASTREADOR\",\n  \"imei\": \"IMEI_DO_RASTREADOR\",\n  \"protocol\": \"j16x_j16\",\n  \"is_connected_translator\": true,\n  \"is_connected_main_server\": true,\n  \"last_active_timestamp\": \"2023-10-27T10:35:00.000000+00:00\",\n  \"last_event_type\": \"location\",\n  \"total_packets_received\": 1501,\n  \"last_packet_data\": { /* ... */ },\n  \"last_full_location\": {\n    \"timestamp\": \"2023-10-27T10:35:00+00:00\",\n    \"satellites\": 8,\n    \"latitude\": -23.55052,\n    \"longitude\": -46.63330,\n    \"speed_kmh\": 60,\n    \"direction\": 90,\n    \"gps_fixed\": 1,\n    \"acc_status\": 1,\n    \"is_realtime\": true,\n    \"gps_odometer\": 12345.67,\n    \"voltage\": 12.8\n  },\n  \"odometer\": 12345.67,\n  \"acc_status\": 1,\n  \"power_status\": 0,\n  \"last_voltage\": 12.8,\n  \"last_command_sent\": {\n    \"command\": \"RELAY 0\",\n    \"timestamp\": \"2023-10-27T10:30:00.000000+00:00\",\n    \"packet_hex\": \"...\"\n  },\n  \"last_command_response\": {},\n  \"device_status\": \"Moving (Ignition On)\"\n}\n```\n\n### `POST /trackers/\u003cdev_id\u003e/command`\nEnvia um comando nativo para um rastreador específico através de sua conexão ativa.\n**Corpo da Requisição:**\n```json\n{\n  \"command\": \"RELAY 0\"\n}\n```\nExemplo de Resposta:\n```json\n{\n  \"status\": \"Command sent successfully\",\n  \"device_id\": \"IMEI_DO_RASTREADOR\",\n  \"command\": \"RELAY 0\",\n  \"packet_hex\": \"...\"\n}\n```\n\n### `GET /trackers/\u003cdev_id\u003e/history`\nRecupera o histórico de pacotes (brutos e traduzidos) para um rastreador específico.\nExemplo de Resposta:\n```json\n[\n  {\n    \"raw_packet\": \"7878...\",\n    \"translated_packet\": \"\u003eSTT...\"\n  },\n  {\n    \"raw_packet\": \"7878...\",\n    \"translated_packet\": \"\u003eALT...\"\n  }\n]\n```\n\n### `GET /sessions/trackers`\nRetorna uma lista dos IDs de dispositivos com sessões de socket ativas com o gateway tradutor.\nExemplo de Resposta:\n```json\n[\"IMEI_RASTREADOR_1\", \"IMEI_RASTREADOR_2\"]\n```\n\n### `GET /sessions/main-server`\nRetorna uma lista dos IDs de dispositivos com sessões ativas com o servidor principal.\nExemplo de Resposta:\n```json\n[\"IMEI_RASTREADOR_1\", \"IMEI_RASTREADOR_3\"]\n```\n\n## Como Começar\n\nSiga os passos abaixo para configurar e executar o servidor em seu ambiente de desenvolvimento.\n\n### Pré-requisitos\n\n*   Python 3.9+\n*   Redis\n\n### Instalação e Configuração\n\n1.  **Clone o repositório:**\n    ```bash\n    git clone \u003curl-do-seu-repositorio\u003e\n    cd \u003cnome-do-repositorio\u003e\n    ```\n\n2.  **Crie e ative um ambiente virtual:**\n    ```bash\n    python -m venv venv\n    source venv/bin/activate  # No Windows: `venv\\Scripts\\activate`\n    ```\n\n3.  **Instale as dependências:**\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n4.  **Configure seu ambiente:**\n    Crie um arquivo `.env` na raiz do projeto e preencha as variáveis de ambiente. Você pode usar o arquivo `.env.example` como modelo.\n    ```\n    LOG_LEVEL=INFO\n    SUNTECH_MAIN_SERVER_HOST=127.0.0.1\n    SUNTECH_MAIN_SERVER_PORT=12345\n    GT06_MAIN_SERVER_HOST=127.0.0.1\n    GT06_MAIN_SERVER_PORT=54321\n    REDIS_DB_MAIN=2\n    REDIS_PASSWORD=...\n    REDIS_HOST=127.0.0.1\n    REDIS_PORT=6379\n    ```\n\n### Executando o Servidor\n\nPara iniciar o servidor, execute o arquivo [`main.py`](main.py):\n\n```bash\npython main.py\n```\nO servidor iniciará os listeners para todos os protocolos definidos em [`app/config/settings.py`](app/config/settings.py).\n\n## Como Adicionar um Novo Protocolo\n\n### Protocolo de Entrada\n\n1.  **Crie o Diretório do Protocolo:**\n    Dentro de `app/src/input/`, crie um novo diretório com o nome do seu protocolo (ex: `novo_protocolo`).\n\n2.  **Implemente os Módulos Essenciais:**\n    Crie os seguintes arquivos dentro do novo diretório, seguindo a estrutura dos módulos `j16x_j16` ou `jt808`:\n    *   `handler.py`: Gerencia o ciclo de vida da conexão TCP.\n    *   `processor.py`: Valida a integridade e disseca a estrutura dos pacotes.\n    *   `mapper.py`: **O coração da tradução**. Converte os dados do protocolo para o dicionário Python padronizado.\n    *   `builder.py`: Constrói pacotes no idioma nativo do protocolo para enviar respostas e comandos.\n\n3.  **Registre o Protocolo:**\n    Abra o arquivo [`app/config/settings.py`](app/config/settings.py) e adicione a configuração do seu novo protocolo no dicionário `INPUT_PROTOCOL_HANDLERS`:\n    ```python\n    INPUT_PROTOCOL_HANDLERS = {\n        # ... protocolos existentes\n        \"novo_protocolo\": {\n            \"port\": 65434,  # Escolha uma porta livre\n            \"handler_path\": \"app.src.input.novo_protocolo.handler.handle_connection\"\n        }\n    }\n    ```\n\n4.  **Habilite a Tradução Reversa de Comandos:**\n    Em [`app/config/settings.py`](app/config/settings.py), importe a função `process_command` do seu novo `builder` e adicione-a ao dicionário `OUTPUT_PROTOCOL_COMMAND_PROCESSORS`.\n\n### Protocolo de Saída\n\n1.  **Crie o Diretório do Protocolo:**\n    Dentro de `app/src/output/`, crie um novo diretório com o nome do seu protocolo (ex: `novo_protocolo`).\n\n2.  **Implemente os Módulos Essenciais:**\n    Crie os arquivos `builder.py` e `mapper.py` dentro do novo diretório, seguindo a estrutura dos módulos `suntech4g` ou `gt06`.\n    *   `builder.py`: Deve conter as funções para construir os diferentes tipos de pacotes de saída (login, localização, heartbeat, etc.).\n    *   `mapper.py`: Deve conter a função `map_to_universal_command` para traduzir comandos recebidos da plataforma principal para o formato universal.\n\n3.  **Registre o Protocolo:**\n    Abra o arquivo [`app/config/output_protocol_settings.py`](app/config/output_protocol_settings.py) e adicione a configuração do seu novo protocolo nos dicionários `OUTPUT_PROTOCOL_PACKET_BUILDERS`, `OUTPUT_PROTOCOL_COMMAND_MAPPERS`, e `OUTPUT_PROTOCOL_HOST_ADRESSES`.\n\n## Estrutura do Projeto\n\nA estrutura de diretórios foi organizada para separar claramente as responsabilidades, facilitando a manutenção e a adição de novas funcionalidades.\n\n```\n/\n├── app/\n│   ├── api/              # Módulo da API RESTful (endpoints para consulta)\n│   ├── config/           # Arquivos de configuração (portas, protocolos, etc.)\n│   ├── core/             # Componentes centrais (logger)\n│   ├── services/         # Serviços de background (Redis, histórico)\n│   └── src/              # Lógica principal da aplicação\n│       ├── input/        # Módulos de protocolos de entrada (rastreadores)\n│       │   ├── j16x_j16/\n│       │   ├── nt40/\n│       │   ├── satellital/\n│       │   └── vl01/\n│       ├── output/       # Módulos de protocolos de saída (plataforma)\n│       │   ├── gt06/\n│       │   └── suntech4g/\n│       └── session/      # Gerenciamento de sessões TCP\n├── main.py               # Ponto de entrada da aplicação\n└── README.md             # Documentação do projeto\n```\n\n### Principais Componentes:\n\n-   **`main.py`**: Orquestrador principal. Carrega as configurações, inicializa os listeners de protocolo em threads separadas e inicia a API.\n-   **`app/config/settings.py`**: Define quais protocolos de entrada são carregados e em quais portas.\n-   **`app/config/output_protocol_settings.py`**: Mapeia os protocolos de saída para seus respectivos `builders` e `mappers` de comando.\n-   **`app/src/input/{protocolo}/`**: Cada diretório aqui representa um \"dialeto\" de rastreador.\n   -   `handler.py`: Ponto de entrada da conexão TCP.\n   -   `processor.py`: Valida e extrai dados do pacote bruto.\n   -   `mapper.py`: Converte os dados para o formato padronizado do sistema.\n   -   `builder.py`: Constrói comandos no formato nativo do rastreador (downlink).\n-   **`app/src/output/{protocolo}/`**: Cada diretório representa um formato de saída para a plataforma.\n   -   `builder.py`: Constrói pacotes (login, localização, etc.) no formato de saída.\n   -   `mapper.py`: Converte comandos da plataforma para o formato universal.\n-   **`app/src/session/`**: Contém os singletons que gerenciam as sessões de socket ativas, tanto de entrada quanto de saída, essenciais para a comunicação bidirecional.\n\n## Tecnologias Utilizadas\n\n*   **Python**: Linguagem principal do projeto.\n*   **Redis**: Utilizado como uma memória de curto prazo para gerenciamento de estado das sessões e dos dispositivos.\n*   **Pydantic**: Para gerenciamento de configurações e validação de dados.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fju-sants%2Fcommunication-protocol-translator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fju-sants%2Fcommunication-protocol-translator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fju-sants%2Fcommunication-protocol-translator/lists"}