Serial Protocol Inspector

Advanced serial protocol debugger with live decoding and visualization. Cross-platform desktop GUI built using PyQt5 for debugging and analyzing serial communication protocols.

Features

Core Functionality

• 🔌 Multi-Port Support: Connect to multiple serial ports simultaneously
• 📊 Live Packet Decoding: Real-time decoding in ASCII, HEX, Binary, JSON, and Mixed formats
• 🔍 Advanced Filtering: Filter packets by port, direction, content, and size
• ⏱️ Timestamp Tracking: Precise timestamps for all packets (millisecond accuracy)
• 📈 Data Visualization: Real-time charts showing data flow over time
• 💾 Session Recording: Record and replay communication sessions
• 📤 Export Tools: Export data to JSON, CSV, or plain text formats
• 🎨 Protocol Profiles: Save and load custom protocol configurations
• 🔌 Plugin Architecture: Extensible plugin system for custom decoders and analyzers
• 🎯 Custom Frame Support: Configure custom frame delimiters for protocol parsing

User Interface

• Modern Qt-based interface with Fusion theme
• Resizable panels and tabbed views
• Color-coded RX/TX packets
• Real-time statistics dashboard
• Context menus and keyboard shortcuts
• Cross-platform compatibility (Windows, Linux, macOS)

Installation

Requirements

• Python 3.7 or higher
• PyQt5 5.15+
• pyserial 3.5+
• matplotlib 3.5+
• numpy 1.21+

Setup

1. Clone the repository:

git clone https://github.com/BaseMax/qt-serial-protocol-inspector.git
cd qt-serial-protocol-inspector

2. Install dependencies:

pip install -r requirements.txt

3. Run the application:

python main.py

Usage

Connecting to a Serial Port

1. Click "Connect Port" button or use the toolbar
2. Select your serial port from the dropdown
3. Configure connection settings:
   • Baud rate (9600, 19200, 38400, 57600, 115200, or custom)
   • Data bits (5, 6, 7, 8)
   • Parity (None, Even, Odd, Mark, Space)
   • Stop bits (1, 1.5, 2)
4. Click OK to connect

Viewing Data

The application provides multiple views for analyzing data:

• Data View Tab: Tabular view with timestamp, port, direction, size, and decoded data
• Raw Data Tab: Scrolling text view with detailed packet information
• Charts Tab: Real-time visualization of data flow
• Statistics Tab: Session statistics including packet counts and byte totals

Decoding Formats

Select from multiple decoding formats:

• ASCII: Plain text representation
• HEX: Hexadecimal byte values (e.g., "48 65 6C 6C 6F")
• Mixed: ASCII for printable characters, HEX for non-printable
• JSON: Pretty-printed JSON (validates JSON structure)
• Binary: Binary representation (e.g., "01001000 01100101")

Filtering Data

Use filters to focus on specific packets:

1. Text Search: Enter text in the search box to filter packets
2. Direction Filter: Check/uncheck RX and TX checkboxes
3. Port Filter: Filter by specific port (via Filter menu)
4. Size Filter: Filter by packet size range

Recording Sessions

1. Click "Start Recording" to begin session recording
2. All packets will be captured with full metadata
3. Click "Stop Recording" when finished
4. Export the session using File → Export Session

Sending Data

1. Enter data in the "Send Data" field at the bottom
2. Select format (ASCII or HEX)
3. Click "Send" to transmit to all active ports

Examples:

• ASCII: Hello World
• HEX: 48 65 6C 6C 6F or 48656C6C6F

Protocol Profiles

Protocol profiles allow you to save custom settings:

1. Go to Tools → Manage Profiles
2. Create or edit profiles with custom settings
3. Configure frame delimiters, default format, and parsing rules
4. Select active profile from the dropdown

Built-in Profiles:

• Default: Standard ASCII protocol
• JSON: JSON message decoder
• HEX: Hexadecimal-only view

Exporting Data

Export session data in multiple formats:

1. File → Export Session
2. Choose format:
   • JSON: Machine-readable with full metadata
   • CSV: Spreadsheet-compatible format
   • TXT: Human-readable plain text

Plugin Development

The application supports custom plugins for extending functionality.

Creating a Plugin

1. Create a Python file in the plugins/ directory

2. Inherit from one of the plugin base classes:

   • DecoderPlugin: For custom data decoders
   • ExporterPlugin: For custom export formats
   • AnalyzerPlugin: For packet analysis tools

3. Implement required methods:

from plugin_manager import AnalyzerPlugin

class MyAnalyzerPlugin(AnalyzerPlugin):
    def get_name(self):
        return "My Analyzer"
    
    def get_description(self):
        return "Custom packet analyzer"
    
    def get_version(self):
        return "1.0.0"
    
    def initialize(self, app_context):
        self.app_context = app_context
    
    def execute(self, data):
        return self.analyze(data)
    
    def analyze(self, packets):
        # Your analysis logic here
        return results

4. Restart the application to load the plugin

Example Plugins

See plugins/checksum_analyzer.py for a complete example that calculates various checksums for packet data.

Architecture

Core Modules

• main.py: Main GUI application and event handling
• serial_comm.py: Serial port communication and management
• protocol_decoder.py: Data decoding and packet representation
• session_recorder.py: Session recording and data filtering
• protocol_profiles.py: Protocol profile management
• plugin_manager.py: Plugin system architecture

Design Patterns

• Observer Pattern: Event-driven architecture with Qt signals/slots
• Strategy Pattern: Pluggable decoders and exporters
• Factory Pattern: Protocol profile creation
• Plugin Pattern: Extensible plugin system

Configuration

Application settings are stored in config.json (auto-created on first run).

Session recordings are saved in the sessions/ directory.

Protocol profiles are stored in the profiles/ directory.

Troubleshooting

Port Access Issues

Linux: Add your user to the dialout group:

sudo usermod -a -G dialout $USER

Then log out and log back in.

Windows: Ensure you have proper permissions and no other application is using the port.

macOS: No special configuration usually needed, but check System Preferences → Security & Privacy if issues occur.

Dependencies Issues

If you encounter dependency issues:

pip install --upgrade pip
pip install -r requirements.txt --upgrade

Display Issues

If the GUI doesn't render properly, try setting the Qt style:

export QT_STYLE_OVERRIDE=Fusion  # Linux/macOS
set QT_STYLE_OVERRIDE=Fusion     # Windows

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Code Style

• Follow PEP 8 guidelines
• Use meaningful variable names
• Add docstrings to all classes and functions
• Keep functions focused and modular

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Max Base

Acknowledgments

• PyQt5 for the excellent GUI framework
• pyserial for reliable serial communication
• matplotlib for data visualization
• The open-source community for inspiration and tools

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing documentation
• Review example plugins

Roadmap

Future enhancements:

• Protocol script recorder/playback
• Advanced statistics and analytics
• Network serial support (TCP/UDP)
• Packet injection and fuzzing tools
• Custom color schemes
• Multi-language support
• Advanced protocol parsers (Modbus, CAN, etc.)
• Automated testing framework

---

Happy Debugging! 🔧