serial-spy 1.0.0b0__tar.gz

serial_spy-1.0.0b0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: serial-spy
+Version: 1.0.0b0
+Summary: Universal Telemetry & NMEA Monitor API
+Author: Lucas H. M. Costa
+Author-email: dacosta.lhm@gmail.com
+Requires-Dist: pyserial>=3.5
+Dynamic: author
+Dynamic: author-email
+Dynamic: requires-dist
+Dynamic: summary

serial_spy-1.0.0b0/README.md

@@ -0,0 +1,100 @@
+# SERIAL SPY: Universal Telemetry & NMEA Monitor
+
+## Current Version: 1.0.0-beta
+
+SERIAL SPY has evolved into an advanced, modular, and highly scalable universal monitoring tool for Windows. Originally conceived as a strict serial monitor, it now boasts comprehensive support for network protocols, providing four distinct operational modes: an automated Command Line Interface (CLI), a graphical user interface (GUI), a fully decoupled Application Programming Interface (API) for seamless third-party integration, and a dedicated hardware-free simulation environment.
+
+## Comprehensive Overview
+
+This project delivers a robust, multi-protocol data acquisition and diagnostic platform, allowing engineers and developers to:
+
+* **Establish Multi-Protocol Connections:** Configure traditional hardware serial communications or connect via modern network protocols by acting as a TCP Client or a UDP Server.
+* **Monitor Live Telemetry:** Visualize incoming data streams (RX) in real-time, with automatic decoding of ASCII NMEA sentences and fallback hexadecimal representations.
+* **Execute Bidirectional Communication:** Transmit (TX) standard text commands or dispatch precise hexadecimal byte sequences directly to the connected equipment.
+* **Perform Multi-Format Auditing:** Persist event logs directly to the disk in text, CSV, or JSONL formats.
+* **Operate via Intuitive Interfaces:** Utilize a lightweight, native Tkinter-based GUI for diagnostics, or leverage the parameterized terminal executable for headless server environments.
+* **Integrate via OOP API:** Consume the monitoring engine natively within larger Python architectures.
+
+## Distribution & Installation
+
+The 1.0.0 release introduces compiled binaries, eliminating the need for end-users to install Python or manage environment dependencies.
+
+* **For Desktop Users (GUI):** Download and run `SerialSpy_Setup.exe`. This standard Windows installer handles all background dependencies, directory structures, and creates a desktop shortcut with the official application icon.
+* **For Sysadmins (CLI):** Download the standalone `serialspy.exe` binary. It is completely portable and can be executed natively from PowerShell or integrated into automated scripts.
+* **For Developers (API):** The core classes can be distributed as pre-compiled bytecode (`.pyc`) or Cython-compiled dynamic extensions (`.pyd`) to protect the underlying source architecture.
+
+## Mode 1: Automated Command Line Interface (CLI)
+
+The CLI has been completely refactored to support direct argument parsing (`argparse`), making it ideal for automation, background services, and pipeline integration.
+
+To launch the CLI, execute the portable binary with your required parameters:
+
+```powershell
+.\serialspy.exe --mode serial --port COM11 --baud 4800 --format jsonl --out data.jsonl
+```
+
+**Available Arguments:**
+
+* \--mode: Connection protocol (serial, tcp, udp).
+
+* \--port: Serial port (e.g., COM11) or Network port (e.g., 8080).
+
+* \--baud, --bits, --parity, --stopbits, --timeout: Complete architecture control for serial connections.
+
+* \--host: Target IP address for TCP/UDP connections.
+
+* \--format and --out: Logging configuration (Text, CSV, JSON).
+
+* \--silent: Hides stdout rendering for headless, resource-efficient background execution.
+
+Graceful shutdown is fully supported. Pressing Ctrl+C safely flushes the disk buffers and releases the system ports.
+
+Mode 2: Graphical User Interface (GUI)
+--------------------------------------
+
+The GUI provides a consolidated, single-window dashboard featuring a modern, flat-design dark mode (VS Code inspired).
+
+* **Independent Multi-Threading:** Utilize the "+ New Connection" feature to open multiple tabs side-by-side. Each panel operates its own background thread, meaning you can monitor a UDP port and a Serial COM port simultaneously without blocking the UI.
+
+***Dynamic Styling:** A native custom stylesheet replaces standard Windows elements with professional data-science aesthetics, featuring pure black terminal outputs for maximum contrast.
+
+* **Embedded Documentation:** The interface includes a comprehensive rich-text Help menu and an About section displaying versioning and developer credits.
+
+Mode 3: Application Programming Interface (API) Integration
+-----------------------------------------------------------
+
+By importing the connection classes, developers can instantiate background monitors that feed data seamlessly into external databases.
+
+**Implementation Example:**
+
+```python 
+from serial_spy_api import SerialMonitor  
+def process_telemetry(event):
+      if event.direction == "RX":
+                print(f"[{event.timestamp_iso}] Sensor Payload: {event.payload}")  
+                # The API runs asynchronously, decoupling data acquisition from the main thread
+                monitor = SerialMonitor(      port="COM11",      baudrate=4800,      bytesize=8,      parity='N',      stopbits=1,      timeout=1,      print_output=False,      event_callback=process_telemetry  )  with monitor:      monitor.send_text("$PMTK605*31") # Example NMEA query command 
+```
+
+Persistent Auditing & Logs
+--------------------------
+
+The storage engine is heavily optimized for zero-packet-loss high-frequency writes:
+
+* **text:** Generates sequential lines optimized for tailing.
+
+* **csv:** Comma-separated values strictly ordered.
+
+* **json:** Adheres to the JSON Lines (JSONL) standard, emitting exactly one complete, independent JSON object per line.
+
+Automated Unit Testing
+----------------------
+
+All structural tests reside in tests/test\_serial\_monitor.py and implement the unittest framework utilizing a FakeSerial mock class, eliminating the need for system-level hardware hooks during CI pipelines.
+
+`PowerShell python -m unittest discover -s tests -p "test_*.py" -v`
+
+Issues & Support
+----------------
+
+This project is currently under active development. Suggestions, issues, and bug reports can be directed to the primary developer: <dacosta.lhm@gmail.com>.

serial_spy-1.0.0b0/serial_spy.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: serial-spy
+Version: 1.0.0b0
+Summary: Universal Telemetry & NMEA Monitor API
+Author: Lucas H. M. Costa
+Author-email: dacosta.lhm@gmail.com
+Requires-Dist: pyserial>=3.5
+Dynamic: author
+Dynamic: author-email
+Dynamic: requires-dist
+Dynamic: summary

serial_spy-1.0.0b0/serial_spy.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+setup.py
+serial_spy.egg-info/PKG-INFO
+serial_spy.egg-info/SOURCES.txt
+serial_spy.egg-info/dependency_links.txt
+serial_spy.egg-info/requires.txt
+serial_spy.egg-info/top_level.txt
+serial_spy_api/__init__.py
+serial_spy_api/base_monitor.py
+serial_spy_api/serial_connection.py
+serial_spy_api/serial_spy_api.py
+serial_spy_api/tcp_connection.py
+serial_spy_api/udp_connection.py
+tests/test_serial_monitor.py

serial_spy-1.0.0b0/serial_spy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

serial_spy-1.0.0b0/serial_spy.egg-info/requires.txt

@@ -0,0 +1 @@
+pyserial>=3.5

serial_spy-1.0.0b0/serial_spy.egg-info/top_level.txt

@@ -0,0 +1 @@
+serial_spy_api

serial_spy-1.0.0b0/serial_spy_api/__init__.py

@@ -0,0 +1,3 @@
+from .serial_connection import SerialConnection as SerialMonitor
+from .tcp_connection import TCPConnection
+from .udp_connection import UDPConnection

serial_spy-1.0.0b0/serial_spy_api/base_monitor.py

@@ -0,0 +1,169 @@
+"""
+Purpose: Abstract core engine for the SERIAL_SPY project.
+Objective: Manages event queues, thread synchronization, millisecond-precision 
+timestamp generation, file I/O operations (Text, CSV, JSONL), and generic 
+payload processing. It serves as the base class for all connection protocols.
+"""
+
+
+import csv
+import json
+import os
+import queue
+import threading
+import time
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from typing import Callable, List, Optional
+
+@dataclass
+class ConnectionEvent:
+    timestamp_iso: str
+    timestamp_ms: int
+    direction: str
+    payload: str
+
+class BaseMonitor(ABC):
+    def __init__(self, log_file=None, log_format="text", print_output=True, event_callback: Optional[Callable[[ConnectionEvent], None]] = None):
+        self.log_file = log_file
+        self.log_format = log_format
+        self.print_output = print_output
+        self.is_running = False
+        self.file_obj = None
+        self.csv_writer = None
+        self.stop_event = threading.Event()
+        self.text_buffer = ""
+        self.write_lock = threading.Lock()
+        self.event_queue = queue.Queue()
+        self.event_callbacks: List[Callable[[ConnectionEvent], None]] = []
+        
+        if event_callback is not None:
+            self.event_callbacks.append(event_callback)
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, exc_type, exc, tb):
+        self.stop()
+
+    def start_simulation(self):
+            self.is_running = True
+            self.stop_event.clear()
+            if self.log_file:
+                self._open_log_output()
+            if self.print_output:
+                print("Monitor started in simulation mode (no hardware required).")
+            return self
+        
+    def emit_simulated_rx(self, payload):
+        self._emit_log("RX", payload)
+
+    def emit_simulated_tx(self, payload):
+        self._emit_log("TX", payload)
+        
+    def _open_log_output(self):
+        if self.log_format == "csv":
+            file_exists = os.path.exists(self.log_file)
+            file_is_empty = (not file_exists) or os.path.getsize(self.log_file) == 0
+            self.file_obj = open(self.log_file, "a", encoding="utf-8", newline="")
+            self.csv_writer = csv.writer(self.file_obj)
+            if file_is_empty:
+                self.csv_writer.writerow(["timestamp_iso", "timestamp_ms", "direction", "payload"])
+                self.file_obj.flush()
+            return
+        self.file_obj = open(self.log_file, "a", encoding="utf-8")
+
+    def on_data_received(self, data: bytes):
+        try:
+            decoded_data = data.decode("ascii", errors="strict").replace("\r", "")
+        except UnicodeDecodeError:
+            if self.text_buffer:
+                self._emit_log("RX", self.text_buffer)
+                self.text_buffer = ""
+            self._emit_log("RX", data.hex(" ").upper())
+            return
+
+        self.text_buffer += decoded_data
+        lines = self.text_buffer.split("\n")
+        self.text_buffer = lines.pop()
+
+        for line in lines:
+            if line:
+                self._emit_log("RX", line)
+
+    def _current_timestamps(self):
+        now = datetime.now()
+        timestamp_iso = now.strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+        timestamp_ms = int(now.timestamp() * 1000)
+        return timestamp_iso, timestamp_ms
+
+    def _emit_log(self, direction: str, payload: str):
+        timestamp_iso, timestamp_ms = self._current_timestamps()
+        event = ConnectionEvent(
+            timestamp_iso=timestamp_iso,
+            timestamp_ms=timestamp_ms,
+            direction=direction,
+            payload=payload,
+        )
+
+        self.event_queue.put(event)
+
+        for callback in self.event_callbacks:
+            try:
+                callback(event)
+            except Exception as e:
+                if self.print_output:
+                    print(f"Error in event callback: {e}")
+
+        if self.print_output:
+            print(f"[{timestamp_iso}] {direction}: {payload}")
+
+        if self.file_obj and not self.file_obj.closed:
+            try:
+                if self.log_format == "csv":
+                    self.csv_writer.writerow(
+                        [event.timestamp_iso, event.timestamp_ms, event.direction, event.payload]
+                    )
+                elif self.log_format == "json":
+                    self.file_obj.write(json.dumps(asdict(event), ensure_ascii=True) + "\n")
+                else:
+                    self.file_obj.write(f"[{event.timestamp_iso}] {event.direction}: {event.payload}\n")
+                self.file_obj.flush()
+            except IOError as e:
+                if self.print_output:
+                    print(f"File write error: {e}")
+
+    def add_event_callback(self, callback: Callable[[ConnectionEvent], None]):
+        self.event_callbacks.append(callback)
+
+    def get_event(self, timeout=None):
+        try:
+            return self.event_queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def drain_events(self, max_items=None):
+        events = []
+        while max_items is None or len(events) < max_items:
+            event = self.get_event(timeout=0)
+            if event is None:
+                break
+            events.append(event)
+        return events
+
+    @abstractmethod
+    def start(self):
+        pass
+
+    @abstractmethod
+    def stop(self):
+        pass
+
+    @abstractmethod
+    def send_text(self, message: str):
+        pass
+
+    @abstractmethod
+    def send_hex(self, hex_string: str):
+        pass

serial_spy-1.0.0b0/serial_spy_api/serial_connection.py

@@ -0,0 +1,152 @@
+
+"""
+Purpose: Specialized hardware module for COM port communications.
+Objective: Inherits from BaseMonitor to handle physical and virtual serial ports 
+using the 'pyserial' library. It manages hardware buffer states and continuous 
+background reading loops.
+"""
+
+import threading
+import time
+import serial
+from base_monitor import BaseMonitor, ConnectionEvent
+
+class SerialConnection(BaseMonitor):
+    def __init__(self, port, baudrate, bytesize, parity, stopbits, timeout, tx_append_newline=True, serial_instance=None, **kwargs):
+        # Repassa log_file, log_format e event_callback para a classe BaseMonitor
+        super().__init__(**kwargs)
+        self.port = port
+        self.baudrate = baudrate
+        self.bytesize = bytesize
+        self.parity = parity
+        self.stopbits = stopbits
+        self.timeout = timeout
+        self.tx_append_newline = tx_append_newline
+        
+        # Aceita a porta falsa injetada pelos testes unitarios
+        self.serial_instance = serial_instance 
+        self.serial_port = None
+        self.read_thread = None
+
+    def start(self):
+        try:
+            # Se um FakeSerial foi passado (durante os testes), use-o. 
+            # Caso contrario, inicie a biblioteca serial normalmente.
+            if self.serial_instance is not None:
+                self.serial_port = self.serial_instance
+            else:
+                self.serial_port = serial.Serial(
+                    port=self.port,
+                    baudrate=self.baudrate,
+                    bytesize=self.bytesize,
+                    parity=self.parity,
+                    stopbits=self.stopbits,
+                    timeout=self.timeout
+                )
+                
+            self.is_running = True
+            self.stop_event.clear()
+
+            if self.log_file:
+                self._open_log_output()
+
+            # Inicia a thread exclusiva para leitura de hardware
+            self.read_thread = threading.Thread(target=self._read_serial, daemon=True)
+            self.read_thread.start()
+
+            if self.print_output:
+                print(f"Connected to {self.port} at {self.baudrate} baud. Config: {self.bytesize},{self.parity},{self.stopbits}")
+        except serial.SerialException as e:
+            raise RuntimeError(f"Error opening port {self.port}: {e}") from e
+        except IOError as e:
+            raise RuntimeError(f"Error creating log file: {e}") from e
+
+        return self
+
+    def _read_serial(self):
+        if hasattr(self.serial_port, "reset_input_buffer"):
+            try:
+                self.serial_port.reset_input_buffer()
+            except Exception:
+                pass
+
+        while self.is_running and not self.stop_event.is_set():
+            try:
+                waiting = getattr(self.serial_port, "in_waiting", 0)
+                if callable(waiting):
+                    waiting = waiting()
+                waiting = int(waiting)
+
+                if waiting > 0:
+                    raw_data = self.serial_port.read(waiting)
+                    if raw_data:
+                        self.on_data_received(raw_data)
+            except Exception as e:
+                if self.print_output:
+                    print(f"\nCritical read error (hardware disconnected): {e}")
+                self.is_running = False
+                self.stop_event.set()
+                break
+
+            time.sleep(0.01)
+
+    def stop(self):
+        self.is_running = False
+        self.stop_event.set()
+
+        if self.text_buffer:
+            self._emit_log("RX", self.text_buffer)
+            self.text_buffer = ""
+
+        if self.read_thread and self.read_thread.is_alive():
+            self.read_thread.join(timeout=2)
+        if self.serial_port and getattr(self.serial_port, "is_open", False):
+            self.serial_port.close()
+        if self.file_obj and not self.file_obj.closed:
+            self.file_obj.close()
+
+        if self.print_output:
+            print("Operation stopped.")
+
+    def send_text(self, message: str):
+        if not self.serial_port or not getattr(self.serial_port, "is_open", True):
+            if self.print_output:
+                print("Serial port is not open for sending.")
+            return
+
+        payload = message
+        encoded = message.encode("utf-8", errors="replace")
+        if self.tx_append_newline:
+            encoded += b"\r\n"
+
+        try:
+            with self.write_lock:
+                self.serial_port.write(encoded)
+            self._emit_log("TX", payload)
+        except Exception as e:
+            if self.print_output:
+                print(f"Error sending data: {e}")
+
+    def send_hex(self, hex_string: str):
+        if not self.serial_port or not getattr(self.serial_port, "is_open", True):
+            if self.print_output:
+                print("Serial port is not open for sending.")
+            return
+
+        cleaned = hex_string.replace(" ", "")
+        if len(cleaned) % 2 != 0:
+            if self.print_output:
+                print("Invalid HEX: character count must be even.")
+            return
+
+        try:
+            data = bytes.fromhex(cleaned)
+            with self.write_lock:
+                self.serial_port.write(data)
+            self._emit_log("TX", data.hex(" ").upper())
+        except ValueError:
+            if self.print_output:
+                print("Invalid HEX: use only 0-9 and A-F characters.")
+        except Exception as e:
+            if self.print_output:
+                print(f"Error sending HEX: {e}")

serial_spy-1.0.0b0/serial_spy_api/serial_spy_api.py

@@ -0,0 +1,31 @@
+"""
+Purpose: The API Facade of the SERIAL_SPY project.
+Objective: Unifies the underlying connection modules and provides helper functions 
+(such as listing available COM ports) to ensure backward compatibility and 
+provide a clean entry point for third-party integrations.
+"""
+
+import serial.tools.list_ports
+
+# Importa a estrutura de eventos genérica
+from base_monitor import ConnectionEvent
+
+# Importa TODAS as conexões disponíveis no sistema
+from serial_connection import SerialConnection as SerialMonitor
+from tcp_connection import TCPConnection
+from udp_connection import UDPConnection
+
+# Mantém as funções utilitárias que listam as portas físicas ou virtuais
+def get_serial_ports():
+    return sorted(serial.tools.list_ports.comports(), key=lambda p: p.device)
+
+def list_serial_ports():
+    ports = get_serial_ports()
+    if not ports:
+        print("Nenhuma porta serial detectada automaticamente.")
+        return
+
+    print("Portas seriais detectadas:")
+    for idx, port in enumerate(ports, start=1):
+        desc = port.description or "Sem descricao"
+        print(f"  {idx}. {port.device} - {desc}")

serial_spy-1.0.0b0/serial_spy_api/tcp_connection.py

@@ -0,0 +1,129 @@
+"""
+Purpose: Specialized network module for TCP communications.
+Objective: Acts as a TCP Client, establishing a connection-oriented socket stream 
+to a remote server. Inherits from BaseMonitor to process network bytes exactly 
+like hardware serial data.
+"""
+
+import socket
+import threading
+from base_monitor import BaseMonitor, ConnectionEvent
+
+class TCPConnection(BaseMonitor):
+    def __init__(self, host: str, port: int, tx_append_newline=True, **kwargs):
+        super().__init__(**kwargs)
+        self.host = host
+        self.port = port
+        self.tx_append_newline = tx_append_newline
+        
+        self.tcp_socket = None
+        self.read_thread = None
+
+    def start(self):
+        try:
+            self.tcp_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.tcp_socket.settimeout(1.0) 
+            self.tcp_socket.connect((self.host, self.port))
+            
+            self.is_running = True
+            self.stop_event.clear()
+
+            if self.log_file:
+                self._open_log_output()
+
+            self.read_thread = threading.Thread(target=self._read_tcp, daemon=True)
+            self.read_thread.start()
+
+            if self.print_output:
+                print(f"Connected via TCP to host {self.host}:{self.port}")
+        except Exception as e:
+            raise RuntimeError(f"Error connecting via TCP to {self.host}:{self.port}: {e}") from e
+
+        return self
+
+    def _read_tcp(self):
+        while self.is_running and not self.stop_event.is_set():
+            try:
+                raw_data = self.tcp_socket.recv(4096)
+                if raw_data:
+                    self.on_data_received(raw_data)
+                else:
+                    if self.print_output:
+                        print("\nTCP connection closed by remote server.")
+                    self.is_running = False
+                    self.stop_event.set()
+                    break
+            except socket.timeout:
+                continue
+            except Exception as e:
+                if self.print_output:
+                    print(f"\nCritical network read error: {e}")
+                self.is_running = False
+                self.stop_event.set()
+                break
+
+    def stop(self):
+        self.is_running = False
+        self.stop_event.set()
+
+        if self.text_buffer:
+            self._emit_log("RX", self.text_buffer)
+            self.text_buffer = ""
+
+        if self.read_thread and self.read_thread.is_alive():
+            self.read_thread.join(timeout=2)
+            
+        if self.tcp_socket:
+            try:
+                self.tcp_socket.close()
+            except Exception:
+                pass
+                
+        if self.file_obj and not self.file_obj.closed:
+            self.file_obj.close()
+
+        if self.print_output:
+            print("TCP operation stopped.")
+
+    def send_text(self, message: str):
+        if not self.tcp_socket:
+            if self.print_output:
+                print("TCP socket is not open for sending.")
+            return
+
+        payload = message
+        encoded = message.encode("utf-8", errors="replace")
+        if self.tx_append_newline:
+            encoded += b"\r\n"
+
+        try:
+            with self.write_lock:
+                self.tcp_socket.sendall(encoded)
+            self._emit_log("TX", payload)
+        except Exception as e:
+            if self.print_output:
+                print(f"Error sending data via network: {e}")
+
+    def send_hex(self, hex_string: str):
+        if not self.tcp_socket:
+            if self.print_output:
+                print("TCP socket is not open for sending.")
+            return
+
+        cleaned = hex_string.replace(" ", "")
+        if len(cleaned) % 2 != 0:
+            if self.print_output:
+                print("Invalid HEX: character count must be even.")
+            return
+
+        try:
+            data = bytes.fromhex(cleaned)
+            with self.write_lock:
+                self.tcp_socket.sendall(data)
+            self._emit_log("TX", data.hex(" ").upper())
+        except ValueError:
+            if self.print_output:
+                print("Invalid HEX: use only 0-9 and A-F characters.")
+        except Exception as e:
+            if self.print_output:
+                print(f"Error sending HEX via network: {e}")

serial_spy-1.0.0b0/serial_spy_api/udp_connection.py

@@ -0,0 +1,130 @@
+"""
+Purpose: Specialized network module for UDP communications.
+Objective: Acts as a passive UDP listener/server for datagram broadcasts. 
+It tracks the origin IP address of incoming packets to enable bidirectional 
+communication without a fixed connection state.
+"""
+
+import socket
+import threading
+from base_monitor import BaseMonitor, ConnectionEvent
+
+class UDPConnection(BaseMonitor):
+    def __init__(self, host: str, port: int, tx_append_newline=True, **kwargs):
+        super().__init__(**kwargs)
+        self.host = host
+        self.port = port
+        self.tx_append_newline = tx_append_newline
+        
+        self.udp_socket = None
+        self.read_thread = None
+        # Armazena a origem do ultimo pacote para sabermos para onde enviar respostas
+        self.last_client_address = None 
+
+    def start(self):
+        try:
+            self.udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            self.udp_socket.settimeout(1.0)
+            
+            # Permite reutilizar a porta, evitando erros se o script for reiniciado rapidamente
+            self.udp_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            self.udp_socket.bind((self.host, self.port))
+            
+            self.is_running = True
+            self.stop_event.clear()
+
+            if self.log_file:
+                self._open_log_output()
+
+            self.read_thread = threading.Thread(target=self._read_udp, daemon=True)
+            self.read_thread.start()
+
+            if self.print_output:
+                print(f"Escutando pacotes UDP em {self.host}:{self.port}")
+        except Exception as e:
+            raise RuntimeError(f"Erro ao abrir porta UDP {self.host}:{self.port}: {e}") from e
+
+        return self
+
+    def _read_udp(self):
+        while self.is_running and not self.stop_event.is_set():
+            try:
+                # No UDP, recvfrom entrega os bytes e o endereco (IP, Porta) da origem
+                raw_data, address = self.udp_socket.recvfrom(4096)
+                if raw_data:
+                    self.last_client_address = address
+                    self.on_data_received(raw_data)
+            except socket.timeout:
+                continue
+            except Exception as e:
+                if self.print_output:
+                    print(f"\nErro critico de leitura na rede UDP: {e}")
+                self.is_running = False
+                self.stop_event.set()
+                break
+
+    def stop(self):
+        self.is_running = False
+        self.stop_event.set()
+
+        if self.text_buffer:
+            self._emit_log("RX", self.text_buffer)
+            self.text_buffer = ""
+
+        if self.read_thread and self.read_thread.is_alive():
+            self.read_thread.join(timeout=2)
+            
+        if self.udp_socket:
+            try:
+                self.udp_socket.close()
+            except Exception:
+                pass
+                
+        if self.file_obj and not self.file_obj.closed:
+            self.file_obj.close()
+
+        if self.print_output:
+            print("Operacao UDP encerrada.")
+
+    def send_text(self, message: str):
+        if not self.udp_socket or not self.last_client_address:
+            if self.print_output:
+                print("UDP indisponivel ou nenhum destino mapeado (aguarde receber dados primeiro).")
+            return
+
+        payload = message
+        encoded = message.encode("utf-8", errors="replace")
+        if self.tx_append_newline:
+            encoded += b"\r\n"
+
+        try:
+            with self.write_lock:
+                self.udp_socket.sendto(encoded, self.last_client_address)
+            self._emit_log("TX", payload)
+        except Exception as e:
+            if self.print_output:
+                print(f"Erro ao enviar dados via UDP: {e}")
+
+    def send_hex(self, hex_string: str):
+        if not self.udp_socket or not self.last_client_address:
+            if self.print_output:
+                print("UDP indisponivel ou destino nao mapeado.")
+            return
+
+        cleaned = hex_string.replace(" ", "")
+        if len(cleaned) % 2 != 0:
+            if self.print_output:
+                print("HEX invalido: a quantidade de caracteres deve ser par.")
+            return
+
+        try:
+            data = bytes.fromhex(cleaned)
+            with self.write_lock:
+                self.udp_socket.sendto(data, self.last_client_address)
+            self._emit_log("TX", data.hex(" ").upper())
+        except ValueError:
+            if self.print_output:
+                print("HEX invalido: use apenas caracteres 0-9 e A-F.")
+        except Exception as e:
+            if self.print_output:
+                print(f"Erro ao enviar HEX via UDP: {e}")

serial_spy-1.0.0b0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

serial_spy-1.0.0b0/setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup, Distribution
+
+# Força o setuptools a tratar o pacote como binário pré-compilado (Wheel não-puro)
+class BinaryDistribution(Distribution):
+    def has_ext_modules(self):
+        return True
+
+setup(
+    name="serial-spy",
+    version="1.0.0-beta",
+    description="Universal Telemetry & NMEA Monitor API",
+    author="Lucas H. M. Costa",
+    author_email="dacosta.lhm@gmail.com",
+    
+    # Define o nome da pasta onde seus arquivos compilados vão ficar
+    packages=["serial_spy_api"], 
+    
+    # Instrui o pip a baixar dependências externas automaticamente
+    install_requires=[
+        "pyserial>=3.5"
+    ],
+    
+    # Garante que ele empacote os binários e ignore código fonte solto
+    package_data={
+        "serial_spy_api": ["*.pyc", "*.pyd"],
+    },
+    include_package_data=True,
+    distclass=BinaryDistribution
+)

serial_spy-1.0.0b0/tests/test_serial_monitor.py

@@ -0,0 +1,222 @@
+"""
+Purpose: Automated unit testing suite.
+Objective: Validates thread lifecycles, file formatting (JSONL/CSV), and data 
+fragmentation handling using a mocked 'FakeSerial' instance, ensuring the 
+architecture remains stable without requiring physical hardware.
+"""
+
+import sys
+import os
+import csv
+import json
+import tempfile
+import unittest
+from pathlib import Path
+import serial
+
+# Força o Python a enxergar a pasta raiz para importar a API corretamente
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from serial_spy_api import SerialMonitor
+
+class FakeSerial:
+    def __init__(self):
+        self.is_open = True
+        self.written = []
+        self._in_waiting = 0
+
+    @property
+    def in_waiting(self):
+        return self._in_waiting
+
+    def read(self, size):
+        return b""
+
+    def write(self, data):
+        self.written.append(data)
+        return len(data)
+
+    def reset_input_buffer(self):
+        return None
+
+    def close(self):
+        self.is_open = False
+
+
+class SerialMonitorTests(unittest.TestCase):
+    def _create_monitor(self, **overrides):
+        base = {
+            "port": "COM_TEST",
+            "baudrate": 115200,
+            "bytesize": serial.EIGHTBITS,
+            "parity": serial.PARITY_NONE,
+            "stopbits": serial.STOPBITS_ONE,
+            "timeout": 1,
+            "log_file": None,
+            "log_format": "text",
+            "tx_append_newline": True,
+            "print_output": False,
+        }
+        base.update(overrides)
+        return SerialMonitor(**base)
+
+    def test_start_and_stop_with_fake_serial_instance(self):
+        fake = FakeSerial()
+        monitor = self._create_monitor(serial_instance=fake)
+
+        try:
+            monitor.start()
+            self.assertTrue(monitor.is_running)
+            self.assertTrue(monitor.read_thread.is_alive())
+        finally:
+            monitor.stop()
+            
+        self.assertFalse(monitor.is_running)
+        self.assertFalse(fake.is_open)
+
+    def test_send_text_appends_crlf_and_logs_tx_event(self):
+        fake = FakeSerial()
+        monitor = self._create_monitor(serial_instance=fake, tx_append_newline=True)
+
+        try:
+            monitor.start()
+            monitor.send_text("HELLO")
+        finally:
+            monitor.stop()
+
+        self.assertEqual(fake.written[-1], b"HELLO\r\n")
+        events = monitor.drain_events()
+        tx_events = [e for e in events if e.direction == "TX"]
+        self.assertEqual(len(tx_events), 1)
+        self.assertEqual(tx_events[0].payload, "HELLO")
+
+    def test_on_data_received_buffers_partial_lines(self):
+        monitor = self._create_monitor()
+        try:
+            monitor.start_simulation()
+            monitor.on_data_received(b"abc")
+            self.assertEqual(monitor.drain_events(), [])
+            monitor.on_data_received(b"123\nxyz\n")
+        finally:
+            monitor.stop()
+
+        events = monitor.drain_events()
+        rx_payloads = [e.payload for e in events if e.direction == "RX"]
+        self.assertIn("abc123", rx_payloads)
+        self.assertIn("xyz", rx_payloads)
+
+    def test_non_ascii_payload_is_logged_as_hex(self):
+        monitor = self._create_monitor()
+        try:
+            monitor.start_simulation()
+            monitor.on_data_received(bytes([0xFF, 0x01, 0xAA]))
+        finally:
+            monitor.stop()
+
+        events = monitor.drain_events()
+        rx_events = [e for e in events if e.direction == "RX"]
+        self.assertEqual(len(rx_events), 1)
+        self.assertEqual(rx_events[0].payload, "FF 01 AA")
+
+    def test_json_log_format_writes_jsonl_events(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            log_path = Path(tmp_dir) / "events.jsonl"
+            monitor = self._create_monitor(log_file=str(log_path), log_format="json")
+            
+            try:
+                monitor.start_simulation()
+                monitor.emit_simulated_rx("RX_SAMPLE")
+                monitor.emit_simulated_tx("TX_SAMPLE")
+            finally:
+                # O finally garante que o arquivo seja fechado ANTES do tmp_dir ser deletado
+                monitor.stop()
+
+            lines = log_path.read_text(encoding="utf-8").strip().splitlines()
+            self.assertEqual(len(lines), 2)
+            payloads = []
+            for line in lines:
+                entry = json.loads(line)
+                self.assertIn("timestamp_iso", entry)
+                self.assertIn("timestamp_ms", entry)
+                self.assertIn("direction", entry)
+                self.assertIn("payload", entry)
+                payloads.append(entry["payload"])
+            self.assertEqual(payloads, ["RX_SAMPLE", "TX_SAMPLE"])
+
+    def test_csv_log_format_writes_header_once_and_rows(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            log_path = Path(tmp_dir) / "events.csv"
+            monitor = self._create_monitor(log_file=str(log_path), log_format="csv")
+            
+            try:
+                monitor.start_simulation()
+                monitor.emit_simulated_rx("ROW1")
+                monitor.emit_simulated_tx("ROW2")
+            finally:
+                monitor.stop()
+
+            with log_path.open("r", encoding="utf-8", newline="") as f:
+                rows = list(csv.reader(f))
+
+            self.assertEqual(rows[0], ["timestamp_iso", "timestamp_ms", "direction", "payload"])
+            self.assertEqual(rows[1][2:], ["RX", "ROW1"])
+            self.assertEqual(rows[2][2:], ["TX", "ROW2"])
+    def test_generate_persistent_execution_log(self):
+        """Gera log da execucao do teste E salva os dados reais do simulate_serial.py"""
+        import subprocess
+        import sys
+        import os
+        from datetime import datetime
+
+        # Define caminhos absolutos na raiz do projeto
+        script_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'simulate_serial.py'))
+        data_log_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'test_data_output.jsonl'))
+        test_log_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'test_execution_steps.log'))
+
+        # Limpa os logs antigos para um teste limpo
+        for path in [data_log_path, test_log_path]:
+            if os.path.exists(path):
+                os.remove(path)
+
+        # Funcao auxiliar para gravar as acoes do teste
+        def log_step(msg):
+            with open(test_log_path, "a", encoding="utf-8") as f:
+                f.write(f"[{datetime.now().isoformat()}] {msg}\n")
+
+        log_step("=== INICIANDO TESTE DE CAPTURA REAL ===")
+
+        # Cria o monitor configurado para salvar os dados em JSONL
+        monitor = self._create_monitor(log_file=data_log_path, log_format="json")
+
+        try:
+            log_step("Monitor instanciado no modo simulacao (offline).")
+            monitor.start_simulation()
+
+            log_step(f"Iniciando execucao em background do script: {script_path}")
+            # Roda o seu simulador e captura tudo que ele imprimir na tela
+            resultado = subprocess.run([sys.executable, script_path], capture_output=True, text=True)
+
+            self.assertEqual(resultado.returncode, 0, f"O script simulador falhou: {resultado.stderr}")
+            linhas = resultado.stdout.strip().splitlines()
+            
+            log_step(f"Sucesso. {len(linhas)} linhas de dados foram geradas pelo simulador.")
+            log_step("Injetando dados capturados no SerialMonitor...")
+
+            for linha in linhas:
+                if linha.strip():
+                    # Pega a linha real gerada pelo script e injeta na API
+                    monitor.emit_simulated_rx(linha)
+
+            log_step("Injecao de telemetria concluida.")
+        except Exception as e:
+            log_step(f"FALHA CRITICA NO TESTE: {str(e)}")
+            raise
+        finally:
+            log_step("Encerrando monitor e salvando arquivos em disco.")
+            monitor.stop()
+
+        # Garante que os DOIS arquivos estao no seu computador
+        self.assertTrue(os.path.exists(data_log_path), "Arquivo JSONL nao gerado.")
+        self.assertTrue(os.path.exists(test_log_path), "Log de passos do teste nao gerado.")
+if __name__ == "__main__":
+    unittest.main()