Integração com sistemas de automação

1.Visão geral

O MTerminal é um aplicativo Android que emula um microterminal de pedidos (visor LCD de caracteres + teclado numérico) conectado por TCP/IP ao servidor de microterminais do seu sistema. Ele se comporta como um terminal "burro": toda a lógica fica no servidor.

Se o seu servidor já atende microterminais VT100 em rede (Ethernet/TCP), normalmente o MTerminal funciona sem nenhuma alteração: basta cadastrar o aparelho como mais um terminal.

2.Requisitos de rede

• O aparelho Android e o servidor na mesma rede local (Wi-Fi do estabelecimento), ou com rota IP entre eles.
• O servidor escutando numa porta TCP (qualquer porta; as mais comuns são 1001 e 23), com o firewall liberando conexões de entrada nela.
• Recomendado: IP fixo para cada aparelho (reserva de DHCP no roteador), já que a maioria dos servidores identifica o terminal pelo IP.
• A comunicação é TCP puro, sem criptografia (como os microterminais físicos). Use apenas em redes confiáveis; o app não expõe portas nem aceita conexões de entrada.

3.Conexão TCP e sessão

4.Identificação do terminal

O MTerminal suporta as duas formas usuais:

4.1 Pelo IP de origem (padrão, recomendado)

O app não envia nada ao conectar. O servidor identifica o terminal pelo endereço IP remoto da conexão, como faz com microterminais físicos. O IP do aparelho aparece para o usuário em Configurações → IP deste aparelho, para ser cadastrado no seu sistema.

4.2 Por identificador enviado ao conectar (opcional)

Com a opção “Enviar identificador ao conectar” ligada, logo após o connect o app envia o campo Identificador do Terminal seguido de CR:

<identificador> 0x0D        ex.: "01\r" → 30 31 0D

5.Modelo do visor

• Formatos: 2×16, 2×20 (padrão), 2×40 e 4×20 (linhas × colunas), escolhidos pelo usuário. Configure no app o mesmo formato do terminal cadastrado no seu sistema.
• Coordenadas das sequências VT100 são 1-based: linha 1 e coluna 1 são o canto superior esquerdo. Valores fora do visor são limitados à borda (ex.: coluna 30 num visor de 20 colunas vira coluna 20).
• Ao escrever na última coluna, o cursor vai para o início da linha seguinte.
• O visor não rola. Passando da última linha (por texto ou LF), o cursor volta para a linha 1. Posicione o cursor explicitamente e limpe as linhas em vez de depender de rolagem.
• O cursor é exibido como um bloco piscando na posição atual.
• Sem eco local: o app não escreve no visor o que é digitado. O servidor deve ecoar cada caractere que quiser mostrar (como nos microterminais físicos).

6.Sequências VT100/ANSI suportadas

O interpretador é contínuo: sequências divididas entre pacotes TCP são tratadas corretamente. Notação: ESC = 0x1B; CSI = ESC [; n omitido assume o padrão indicado.

7.Caracteres de controle e texto

8.Enquadramento STX/ETX

Definido pelo usuário em Configurações → Protocolo:

8.1 “VT100 / ANSI” (padrão)

STX (0x02) e ETX (0x03) são apenas delimitadores e são descartados; o conteúdo segue como VT100. Um eventual byte de verificação (LRC) após o ETX seria tratado como texto, então não o envie nesse modo.

8.2 “STX/ETX com comandos”

Para sistemas que usam quadros STX <comando> <dados> ETX:

Sequências VT100 fora de quadros continuam funcionando nesse modo. Quadros com mais de 512 bytes sem ETX são exibidos como texto.

9.Teclado: bytes enviados

Cada toque envia imediatamente (sem buffer de linha) os bytes abaixo. Enter, Del e Bck são configuráveis pelo usuário; os valores padrão estão em destaque.

10.Leitor de código de barras

A leitura pela câmera envia o conteúdo do código seguido da sequência configurada para Enter, como um leitor de teclado:

7891000012345 + CR  →  37 38 39 31 30 30 30 30 31 32 33 34 35 0D

• Formatos: EAN-13, EAN-8, UPC-A/E, Code 128, Code 39, Code 93, ITF, Codabar, QR Code, Data Matrix, PDF417 e Aztec (Google ML Kit, processado no aparelho).
• Uma leitura por abertura do leitor; o conteúdo é enviado exatamente como lido (sem prefixo/sufixo além do Enter).

11.Exemplo de sessão

Login do operador “125” num visor 2×20, com eco feito pelo servidor:

# servidor → app: limpa e pede o operador
ESC[2J ESC[1;1H "OPERADOR:"            1B 5B 32 4A 1B 5B 31 3B 31 48 4F 50 45 ...

# usuário digita 1, 2, 5 (um byte por toque); o servidor ecoa cada um
app → servidor: 31          servidor → app: 31
app → servidor: 32          servidor → app: 32
app → servidor: 35          servidor → app: 35

# usuário corrige com Bck: o servidor ecoa BS (o app apaga o "5")
app → servidor: 08          servidor → app: 08

# Enter confirma; servidor responde na linha 2
app → servidor: 0D
servidor → app: ESC[2;1H ESC[K "BEM-VINDO JOAO"

12.Servidor de teste

Para testar sem o sistema completo, rode este servidor mínimo (Python 3) no computador e aponte o app para o IP dele, porta 1001. Ele desenha uma tela, ecoa os dígitos, trata Bck e responde ao Enter:

import socket, threading

ESC = "\x1b"

def atender(conn, addr):
    print("terminal conectado:", addr[0])
    def envia(texto):
        conn.sendall(texto.encode("latin-1"))
    envia(f"{ESC}[2J{ESC}[1;1HMTERMINAL TESTE{ESC}[2;1HDIGITE: ")
    digitado = ""
    while True:
        dados = conn.recv(64)
        if not dados:
            break
        for b in dados:
            ch = chr(b)
            if ch.isdigit():
                digitado += ch
                envia(ch)                      # eco
            elif b == 0x08 and digitado:       # Bck
                digitado = digitado[:-1]
                envia("\x08")
            elif b == 0x0D:                    # Enter
                envia(f"{ESC}[1;1H{ESC}[KRECEBIDO: {digitado}"
                      f"{ESC}[2;1H{ESC}[KDIGITE: ")
                digitado = ""
            elif b == 0x1B:                    # Del
                digitado = ""
                envia(f"{ESC}[2;1H{ESC}[KDIGITE: ")
    conn.close()

srv = socket.socket()
srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
srv.bind(("0.0.0.0", 1001))
srv.listen()
while True:
    threading.Thread(target=atender, args=srv.accept(), daemon=True).start()

Alternativa rápida para ver apenas a exibição: ncat -l 1001 (ou nc -l -p 1001 no Linux) e digite o texto a enviar.

13.Boas práticas do servidor

1. Aceite várias conexões simultâneas, uma por aparelho.
2. Reconexão do mesmo IP: ao receber uma nova conexão de um IP que já tem sessão, encerre a sessão antiga e continue na nova. O app nunca mantém duas conexões, então a antiga está morta.
3. Redesenhe a tela inteira no início de cada conexão (ESC[2J + conteúdo), porque o visor mantém o conteúdo anterior.
4. Posicione o cursor explicitamente (ESC[l;cH) e limpe com ESC[K, em vez de depender de LF e rolagem.
5. Faça o eco dos caracteres digitados que devem aparecer no visor, e ecoe BS ao apagar.
6. Trate a entrada como fluxo: não assuma um toque por pacote.
7. Não derrube conexões ociosas muito cedo: o operador pode passar vários minutos sem digitar. Detecte conexões mortas por falha de envio ou pela chegada de uma nova conexão do mesmo IP.
8. Mantenha o texto dentro do formato configurado (ex.: 20 colunas no 2×20) e use Latin-1 para acentos.

14.Checklist de homologação

15.Configurações do app (referência)

Para orientar o cliente final, estes são os campos em Configurações e os valores padrão:

16.Limitações conhecidas

• Sem impressora, porta serial ou balança acopladas ao terminal: dados enviados a elas (media copy, quadros P/S) são descartados.
• Sem vídeo reverso, piscante ou sublinhado no visor.
• Sem rolagem de tela (seção 5).
• Sem teclas de função dedicadas (F1–F4) no teclado atual.
• Sem TLS; uso previsto em rede local.
• Com o app em segundo plano ou a tela desligada, o Android pode encerrar a conexão; o app reconecta ao voltar.

17.Contato técnico

Dúvidas de integração, relatos de incompatibilidade ou pedidos de novas sequências: suporte.dns.apps@gmail.com. Ajuda informar o sistema, a versão, o formato do visor e, se possível, uma captura dos bytes enviados pelo servidor.

Para orientar seus clientes no uso diário, indique o Manual do Usuário.