GA Modbus Python Application

Overview

The GA Modbus Python Application is a comprehensive software suite for production and RMA test management, monitoring and logging data for GA P3E battery systems via serial Modbus RTU communication. The project supports multiple modes of operation including CLI logging, web dashboard visualization, and the P3E Test Manager for complete battery pack testing workflows.

Quick Start

First-Time Setup

If you've just cloned this repository, you need to create runtime configuration files from templates:

# Copy configuration templates
cp modbus-standalone-cli-config.toml.example modbus-standalone-cli-config.toml
cp modbus-logger-history.json.example modbus-logger-history.json
cp P3E-Report/p3e_test_manager_settings.json.example P3E-Report/p3e_test_manager_settings.json

📖 For detailed setup instructions, see SETUP.md

📖 For development guidelines and architecture details, see CLAUDE.md

Application Modes

The application supports multiple modes of operation:

1. Standalone CLI Logger (src/modbus_standalone_logger.py) - Command-line data logging with extended register support
2. Web Dashboard (src/modbus_dashboard.py) - Real-time web-based visualization with WebSocket support
3. P3E Test Manager (P3E-Report/p3e_test_manager_dev.ps1) - PowerShell/Python script for complete testing workflows

For detailed usage of each mode, see CLAUDE.md

P3E Test Manager - Complete Battery Testing Workflow

The P3E Test Manager orchestrates a complete battery pack testing workflow that includes:

• Data Collection: Extended register logging with real-time WebSocket streaming
• Automatic Termination: Low voltage cut-off detection for discharge tests with configurable thresholds
• Visualization: Dashboard monitoring with historical and real-time modes
• Screenshot Generation: Automated dashboard screenshot capture with current-based naming
• CSV Consolidation: Automatic consolidation of incomplete test files
• CSV Validation: Comprehensive validation with Excel export integration
• SOC Delta Plot Generation: Automatic voltage delta vs SOC visualization
• Runaway Analysis: Intelligent cell runaway detection with configurable thresholds

System Architecture

graph TB
    subgraph "User Interface"
        P3E[P3E Test Manager<br/>PowerShell/Python CLI]
        DASH[Web Dashboard<br/>Plotly/Dash]
    end

    subgraph "Core Services"
        LOGGER[Standalone Logger<br/>Modbus RTU]
        WS[WebSocket Server<br/>Real-time Streaming]
        ANALYZER[Runaway Analyzer<br/>Cell Detection]
        VALIDATOR[CSV Validator<br/>Completeness Check]
        CONSOLIDATOR[CSV Consolidator<br/>File Merging]
    end

    subgraph "Data Processing"
        PLOTTER[SOC Delta Plotter<br/>Visualization]
        SCREENSHOT[Screenshot Generator<br/>Dashboard Export]
    end

    subgraph "Configuration"
        CONFIG[TOML/JSON Config<br/>Settings Management]
        REGISTRY[Session Registry<br/>WebSocket Tracking]
    end

    subgraph "External Systems"
        BMS[BMS Hardware<br/>Modbus RTU]
    end

    subgraph "Data Storage"
        CSV[(CSV Files<br/>Test Data)]
        PNG[(Screenshots<br/>PNG Images)]
        MD[(Reports<br/>Markdown)]
        XLSX[(Excel<br/>Validation)]
    end

    %% User interactions
    P3E -->|Launch| LOGGER
    P3E -->|Launch| DASH
    P3E -->|Run| ANALYZER
    P3E -->|Validate| VALIDATOR
    P3E -->|Consolidate| CONSOLIDATOR
    P3E -->|Generate| SCREENSHOT

    %% Logger connections
    LOGGER -->|Read| BMS
    LOGGER -->|Stream| WS
    LOGGER -->|Write| CSV

    %% Dashboard connections
    DASH -->|Connect| WS
    DASH -->|Read| CSV
    DASH -->|Export| PNG

    %% Analyzer connections
    ANALYZER -->|Read| CSV
    ANALYZER -->|Generate| PLOTTER
    ANALYZER -->|Write| MD

    %% Validator connections
    VALIDATOR -->|Read| CSV
    VALIDATOR -->|Export| XLSX

    %% Consolidator connections
    CONSOLIDATOR -->|Read| CSV
    CONSOLIDATOR -->|Write| CSV

    %% Plotter connections
    PLOTTER -->|Read| CSV
    PLOTTER -->|Write| PNG

    %% Configuration
    P3E -->|Load| CONFIG
    WS -->|Update| REGISTRY
    LOGGER -->|Load| CONFIG

    %% Styling
    classDef ui fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef service fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef process fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef config fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef external fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    classDef storage fill:#fff9c4,stroke:#f57f17,stroke-width:2px

    class P3E,DASH ui
    class LOGGER,WS,ANALYZER,VALIDATOR,CONSOLIDATOR service
    class PLOTTER,SCREENSHOT process
    class CONFIG,REGISTRY config
    class BMS external
    class CSV,PNG,MD,XLSX storage

Loading

Workflow Sequence

sequenceDiagram
    participant User
    participant P3E as P3E Test Manager
    participant Logger as Standalone Logger
    participant BMS as BMS Hardware
    participant WS as WebSocket Server
    participant Dashboard as Web Dashboard
    participant Analyzer as Runaway Analyzer
    participant FileSystem as File System

    Note over User,FileSystem: Complete Battery Pack Testing Workflow

    %% Data Collection Phase
    rect rgb(230, 245, 255)
        Note over User,FileSystem: Phase 1: Data Collection
        User->>P3E: Launch Test Manager
        P3E->>User: Display menu options
        User->>P3E: Select "Run Standalone Logger"
        P3E->>User: Prompt for serial number, RMA, COM port
        User->>P3E: Enter test parameters
        P3E->>Logger: Launch with parameters
        Logger->>BMS: Connect via Modbus RTU
        BMS-->>Logger: Register data (voltages, current, SOC, temps)
        
        loop Continuous Logging (0.5s interval)
            Logger->>BMS: Read extended registers
            BMS-->>Logger: Return 83 columns of data
            Logger->>Logger: Check low voltage cut-off (discharge only)
            Logger->>FileSystem: Write CSV row
            Logger->>WS: Stream real-time data (if enabled)
            
            alt Low Voltage Cut-off Detected
                Logger->>Logger: Terminate session automatically
                Logger->>FileSystem: Save CSV file
                Logger->>Logger: Stop BK8500 discharge
                Logger->>Logger: End Notion sync
                Logger-->>P3E: Session terminated (low voltage cut-off)
            end
        end
        
        opt Manual Stop
            User->>Logger: Stop logging (Ctrl+C)
            Logger->>FileSystem: Close CSV file
            Logger-->>P3E: Logging complete
        end
    end

    %% Visualization Phase
    rect rgb(255, 245, 230)
        Note over User,FileSystem: Phase 2: Visualization
        User->>P3E: Select "Run Dashboard"
        P3E->>Dashboard: Launch with CSV file
        Dashboard->>FileSystem: Read CSV data
        Dashboard->>Dashboard: Generate plots (voltages, current, SOC, deltas)
        Dashboard->>User: Display web interface
        
        opt Screenshot Mode
            User->>Dashboard: Capture screenshot
            Dashboard->>FileSystem: Save PNG (serial-test-currentA.png)
        end
    end

    %% Analysis Phase
    rect rgb(245, 255, 245)
        Note over User,FileSystem: Phase 3: Analysis
        User->>P3E: Select "Run Runaway Analysis"
        P3E->>Analyzer: Launch with configuration
        Analyzer->>FileSystem: Scan test-artifacts directory
        
        loop For each serial number
            Analyzer->>FileSystem: Read CSV files (charge + discharge)
            Analyzer->>Analyzer: Detect cell runaway (>200mV threshold)
            Analyzer->>Analyzer: Generate SOC delta plots
            Analyzer->>FileSystem: Save individual report (RMA_serial_analysis.md)
        end
        
        Analyzer->>Analyzer: Generate consolidated report
        Analyzer->>FileSystem: Save consolidated report
        Analyzer-->>P3E: Analysis complete
        P3E->>User: Reports generated
    end

    %% Validation Phase (Optional)
    rect rgb(255, 240, 245)
        Note over User,FileSystem: Phase 4: Validation (Optional)
        User->>P3E: Select "Validate CSV Test Artifacts"
        P3E->>FileSystem: Scan all serial directories
        P3E->>P3E: Check SOC coverage (0-100% charge, 100-0% discharge)
        P3E->>User: Display validation results
        
        opt Consolidation Needed
            User->>P3E: Confirm consolidation
            P3E->>FileSystem: Consolidate incomplete files
            P3E->>User: Consolidation complete
        end
    end

Loading

Quick Start

P3E Test Manager:

# Interactive menu
scripts\p3e_test_manager_dev.bat

# Or Python CLI
python -m src.cli

Standalone Logger:

python src/modbus_standalone_logger.py --port COM3 --serial 1234 --output log/

Web Dashboard:

python src/modbus_dashboard.py --config-path config.toml

Key Features

Multi-Instance WebSocket Architecture

The P3E system supports multiple concurrent logger instances, each with its own WebSocket server for real-time data streaming.

Start logger with WebSocket:

python -m src.cli logger --serial 0595 --port COM3 --enable-websocket

List active sessions:

python -m src.cli sessions

Connect dashboard:

python -m src.cli dashboard --serial 0595

Configuration System

The P3E Test Manager system uses several configuration files to maintain settings and provide flexibility.

⚠️ Important: Configuration Templates

Runtime configuration files are not tracked in git (they're in .gitignore) because they contain machine-specific and runtime-generated data. Template files (.example) are provided for fresh clones:

Runtime File (git-ignored)	Template (tracked in git)	Auto-generated
modbus-standalone-cli-config.toml	✅ modbus-standalone-cli-config.toml.example	No - copy from template
modbus-logger-history.json	✅ modbus-logger-history.json.example	Yes - by logger
p3e_test_manager_settings.json	✅ p3e_test_manager_settings.json.example	Yes - by test manager

First-time setup: Copy the .example files to create your runtime configs (see SETUP.md)

Core Configuration Files

1. p3e_test_manager_settings.json (Runtime)

   • Stores user preferences and last-used settings
   • Contains recent serial numbers, RMA numbers, COM ports
   • Manages WebSocket settings and register options
   • Automatically updated during operations

2. modbus-standalone-cli-config.toml (Runtime)

   • Modbus connection parameters (baudrate, parity, timeout)
   • Logging intervals and output paths
   • Filter settings for cell delta smoothing
   • Extended register configuration options
   • Termination settings including low voltage cut-off thresholds (configurable via P3E Test Manager Option 14)

3. modbus-logger-history.json (Runtime)

   • Historical data for previous logging sessions
   • Track record counts, durations, file paths
   • Maintains audit trail of testing activities

4. runaway_config.toml (Optional)

   • Analysis threshold settings (default: 200mV)
   • Serial number include/exclude filters
   • Report formatting options (color coding, timing details)
   • Screenshot filtering preferences

5. config.toml (Optional - Dashboard)

   • Dashboard visualization settings
   • Plot themes and scaling factors
   • WebSocket connection parameters

Installation

Dependencies

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# For web dashboard features
pip install plotly dash pandas numpy dash-bootstrap-components websockets

Key Features

Automatic Low Voltage Cut-off Detection

During discharge tests, the logger automatically detects when the battery pack reaches low voltage cut-off conditions and gracefully terminates the session. This prevents unnecessary logging after the BMS has cut off output.

Detection Criteria:

• Pack voltage drops below configured threshold (default: 20V) AND
• Current drops to near zero (below configured threshold, default: 0.1A) AND
• SOC is at or near 0% (within configured threshold, default: 2%)

All three conditions must be met simultaneously. The system prefers BK8500 load tester readings (more reliable when BMS cuts off) and falls back to BMS readings if BK8500 is unavailable.

Configuration:

• Access via P3E Test Manager: Option 14 → Option 2 (Modify Discharge Termination Settings)
• Three configurable thresholds (all must be met):
  • Low Voltage Threshold (V) - Pack voltage below this value
  • Low Voltage Current Threshold (A) - Current below this absolute value
  • Low Voltage SOC Threshold (%) - SOC at or below this value
• Settings persist in modbus-standalone-cli-config.toml under [termination] section

Automatic Cleanup: When low voltage cut-off is detected, the logger automatically:

• Saves the CSV file with all collected data
• Stops the BK8500 discharge session
• Ends Notion sync connection
• Displays clear termination message to user

Key Benefits

1. Complete Traceability: Every test generates CSV data, screenshots, and analysis reports
2. Automatic Safety Termination: Low voltage cut-off detection prevents unnecessary logging and ensures proper cleanup
3. Real-time Monitoring: WebSocket integration for live dashboard updates
4. Automated Analysis: Intelligent detection of cell runaway conditions
5. Standardized Reporting: Consistent markdown reports with color coding
6. Scalable Processing: Batch operations for multiple battery packs
7. Quality Assurance: Configurable threshold detection for manufacturing defects (default: 200mV)
8. Configuration Management: Persistent settings and flexible customization
9. Historical Tracking: Complete audit trail of testing sessions

Documentation

• SETUP.md - Detailed setup instructions
• CLAUDE.md - Development guidelines and architecture
• CHANGELOG.md - Complete change history
• RELEASE_NOTES_v1.0.0.md - First official release notes

Workflow Overview

This workflow enables comprehensive battery pack testing from data collection through final quality assessment, providing complete documentation for RMA analysis and manufacturing process improvement. The integrated configuration system ensures consistency and allows for easy customization based on specific testing requirements.

Typical Test Cycle

1. Data Collection: Extended register logging captures 83 total columns including cell voltages, temperatures, fuel gauge data, coil controls, AFE status, and configuration registers
   • Discharge Tests: Automatic low voltage cut-off detection terminates session when BMS cuts off output
   • Charge Tests: Manual termination or configurable SOC/current thresholds
2. Visualization: Multiple modes including historical analysis, real-time monitoring, and WebSocket streaming with comprehensive plots
3. Analysis: Multi-file analysis processes all CSV files per RMA with cell-level detection and enhanced timing tracking
4. Reporting: Individual RMA reports and consolidated analysis with standardized markdown format

Additional Resources

• Session Registry Guide
• WebSocket Server Guide
• Dashboard Connection Guide
• Error Handling Guide
• Testing Guide

---

Note: This is the first official release (v1.0.0). Future releases will follow semantic versioning (MAJOR.MINOR.PATCH).