Correções Críticas de Concorrência, Otimização de Telemetria e Inclusão de Testes

.github/worklflows/ci.yml

@@ -0,0 +1,30 @@
+name: TelloZune CI
+
+on:
+  push:
+    branches: [ "main", "master" ]
+  pull_request:
+    branches: [ "main", "master" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout do código
+      uses: actions/checkout@v4
+
+    - name: Configurar o Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.14"
+
+    - name: Instalar dependências
+      run: |
+        python -m pip install --upgrade pip
+
+        pip install -r requirements.txt
+
+    - name: Rodar testes unitários (unittest)
+      run: |
+        python -m unittest discover -s test -v

README.md

@@ -1,27 +1,58 @@
-# tello_zune
-Library used by the Zune Drones team to control the DJI Tello drone. In the examples folder, there are some simple usage examples of the tello_zune module, which is also present in the folder.
+# Tello Zune (v0.7.7)
 
+Uma biblioteca Python orientada a eventos thread-safe para o controle, leitura de telemetria e streaming de vídeo do drone DJI Tello. 
 
-To create the library, adaptations were made from two other existing libraries:
-* [fvilmos](https://github.com/fvilmos/tello_object_tracking)
-* [damiafuentes](https://github.com/damiafuentes/DJITelloPy)
+A Tello Zune gerencia filas de comandos assíncronas, faz monitoramento contínuo de estado em background e bloqueios de segurança para garantir que o seu drone responda de forma previsível e estável, mesmo durante a execução de rotas complexas.
 
-# Requeriments
+## Funcionalidades Principais
 
-* Python >= 3.9.0
+* **Comunicação Thread-Safe:** Uso de `Locks` e `Queues` para evitar colisões de pacotes UDP.
+* **Telemetria Contínua:** Leitura de sensores (bateria, altura, velocidade, temperatura) passiva pela porta 8890, sem bloquear o envio de comandos de voo.
+* **Streaming de Vídeo Integrado:** Captura e redimensionamento de frames em tempo real usando OpenCV.
+* **Rotas e Eventos Periódicos:** Capacidade de programar sequências de movimentos (ex: patrulhas) com intervalos de tempo precisos usando o comando customizado `delay`.
+* **Modo Interativo de Terminal:** Controle o drone enviando comandos de texto direto pelo console enquanto o script de vídeo roda em paralelo.
+* **Parada de Emergência:** Limpeza instantânea da fila de comandos e corte de motores com o método `emergency_stop()`.
 
-```bash
-pip install numpy
-```
+## Pré-requisitos e Instalação
 
+Certifique-se de ter o Python 3 instalado. As dependências principais da biblioteca estão no requirements.txt.
+
+Instale a Tello Zune:
 ```bash
-pip install opencv-python
+pip install tello-zune
 ```
 
-# How to use
+Conecte o seu computador à rede Wi-Fi do drone Tello antes de executar os scripts.
+
+---
+
+## Como Usar (Exemplos)
+
+Na pasta `examples/` você encontra scripts prontos para testar as capacidades da Tello Zune.
+
+### 1. Controle por Terminal de Texto (`text_commands.py`)
+Este exemplo inicia a câmera do Tello com um HUD de telemetria na tela. Ao mesmo tempo, ele habilita o terminal para que você digite comandos de voo (como `takeoff`, `forward 50`, `cw 90`) manualmente.
 
-To use the library, install with:
+### 2. Rotas e Comandos Periódicos (`periodic_commands.py`)
+Neste exemplo, o drone é programado para executar uma rota periódica de "Vigilância". Ele se moverá para frente 50cm e girará 90 graus a cada intervalo de tempo determinado, operando de forma autônoma.
+
+---
+
+## Métodos Principais da API
+
+Aqui estão algumas das funções mais úteis para controlar o Tello programaticamente:
+
+* `add_command(cmd: str)`: Enfileira um comando oficial do SDK do Tello (ex: `up 50`, `flip b`) para ser executado de forma segura na próxima janela disponível.
+* `get_speed() -> tuple`: Retorna a velocidade atual em tempo real nos eixos X, Y e Z `(vx, vy, vz)` em cm/s.
+* `get_battery() -> int`: Retorna a porcentagem atual da bateria (0-100).
+* `emergency_stop()`: Esvazia a fila de comandos imediatamente e corta os motores do drone. Ideal para evitar colisões iminentes.
+* `clear_command_queue()`: Limpa todos os comandos pendentes na fila sem derrubar o drone.
+* `end_tello()`: Pousa o drone com retentativas automáticas em caso de falha na rede, encerra o streaming de vídeo e fecha os sockets de comunicação corretamente.
+
+## Estrutura e Testes
+
+A biblioteca possui cobertura de testes unitários para garantir a estabilidade das funções de rede e de concorrência. Para executar os testes na raiz do projeto, utilize:
 
 ```bash
-pip install tello-zune
-```
+python -m unittest discover -s test -v
+```

test/main.py → examples/periodic_commands.py

@@ -1,26 +1,14 @@
 import cv2
-import os
-import sys
-
-current_dir = os.path.dirname(os.path.abspath(__file__))
-
-project_root = os.path.dirname(current_dir)
-
-sys.path.insert(0, project_root)
 
 from tello_zune.tello_zune import TelloZune
 
-
-cap = cv2.VideoCapture(0) # Captura de vídeo da webcam
-# tello.start_communication() # Este método deve ser chamado apenas se for usar a câmera do drone
 tello = TelloZune() # Cria objeto da classe TelloZune
 tello.start_tello() # Inicia a comunicação com o drone
 tello.add_periodic_event("forward 50 e cw 90", 100, "Vigilância", 10) # Adiciona evento periódico
 
 try:
     while True:
         # Captura
-        # ret, frame = cap.read() # Captura de vídeo da webcam
         frame = tello.get_frame()
 
         # Tratamento
@@ -39,6 +27,5 @@
             break
 finally:
     # Finalização
-    #cap.release()
     tello.end_tello()
     cv2.destroyAllWindows()

examples/text_commands.py

@@ -0,0 +1,31 @@
+import cv2
+
+from tello_zune.tello_zune import TelloZune
+
+tello = TelloZune() # Cria objeto da classe TelloZune
+tello.start_tello() # Inicia a comunicação com o drone
+tello.enable_text_input = True # Habilita o input de texto para enviar comandos manualmente
+
+try:
+    while True:
+        # Captura
+        frame = tello.get_frame()
+
+        # Tratamento
+        bat, height, temph, pres, time_elapsed = tello.get_info()
+        fps = tello.calc_fps()
+        cv2.putText(frame, f"FPS: {fps}", (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (10, 255, 0), 2)
+        cv2.putText(frame, f"Bat: {bat}%", (10, 60), cv2.FONT_HERSHEY_SIMPLEX, 1, (10, 255, 0), 2)
+        cv2.putText(frame, f"Height: {height}cm", (10, 90), cv2.FONT_HERSHEY_SIMPLEX, 1, (10, 255, 0), 2)
+        cv2.putText(frame, f"Max. Temp.: {temph}C", (10, 120), cv2.FONT_HERSHEY_SIMPLEX, 1, (10, 255, 0), 2)
+        cv2.putText(frame, f"Press.: {pres}", (10, 150), cv2.FONT_HERSHEY_SIMPLEX, 1, (10, 255, 0), 2)
+        cv2.putText(frame, f"TOF: {time_elapsed}s", (10, 180), cv2.FONT_HERSHEY_SIMPLEX, 1, (10, 255, 0), 2)
+
+        # Exibição
+        cv2.imshow('QR Code', frame)
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+finally:
+    # Finalização
+    tello.end_tello()
+    cv2.destroyAllWindows()