Skip to content

implementation.md

Latest commit

 

History

History
361 lines (262 loc) · 10.9 KB

implementation.md

File metadata and controls

361 lines (262 loc) · 10.9 KB

Implementation Phases

This document outlines the implementation plan for snap7-gui, broken into incremental phases.

Phase 1: Project Setup and Core Models

Goal: Establish project structure and define core data models.

Tasks

  1. Create project structure with src/ directory layout
  2. Set up requirements.txt with dependencies:
    • python-snap7>=1.3
    • PySide6>=6.6
  3. Create main.py entry point
  4. Implement src/models/variable.py:
    • DataType enum with BOOL, BYTE, INT, DINT, REAL
    • Variable dataclass with name, data_type, db_number, offset, bit_offset, value
  5. Implement src/plc/data_types.py:
    • Type size constants
    • Reader/writer function mappings for snap7.util functions

Deliverable

Runnable project skeleton with data models that can be imported and tested.

Phase 2: PLC Communication Layer

Goal: Implement reliable PLC communication with connection management.

Tasks

  1. Implement src/plc/client.py:
    • PLCClient class wrapping snap7.client.Client
    • connect(ip, rack, slot) method with error handling
    • disconnect() method
    • is_connected property
    • read_variables(variables: list[Variable]) method
      • Group variables by DB number
      • Calculate byte ranges for optimized reads
      • Parse values using data_types mappings
    • write_variable(variable: Variable, value) method
  2. Add reconnection logic with configurable retry attempts
  3. Implement error translation (snap7 error codes to user-friendly messages)

Deliverable

PLC client that can connect to a real or simulated PLC and read/write variables.

Phase 3: Polling Thread

Goal: Implement background polling with thread-safe GUI updates.

Tasks

  1. Implement src/plc/poller.py:
    • PLCPoller(QThread) class
    • Constructor accepts PLCClient, variable list, poll interval
    • data_updated = Signal(dict) emitting {var_name: value}
    • connection_lost = Signal(str) emitting error message
    • error_occurred = Signal(str) for non-fatal errors
    • run() method with polling loop
    • stop() method for graceful shutdown
    • request_write(variable, value) method using thread-safe queue
  2. Handle write requests within polling loop
  3. Implement connection state tracking

Deliverable

Background thread that polls PLC and emits signals for GUI consumption.

Phase 4: Configuration Storage

Goal: Persist variable configurations to JSON files.

Tasks

  1. Implement src/storage/config_store.py:
    • save_config(variables: list[Variable], filepath: str)
    • load_config(filepath: str) -> list[Variable]
    • JSON schema for variable serialization
  2. Add default config file location (user's app data directory)
  3. Handle file errors gracefully (missing file, invalid JSON, schema errors)

Deliverable

Configuration persistence that survives application restarts.

Phase 5: Main Window Shell

Goal: Create the main application window with navigation.

Tasks

  1. Implement src/app.py:
    • create_app() function setting up QApplication
    • Application-wide styling
  2. Implement src/ui/main_window.py:
    • MainWindow(QMainWindow) class
    • QStackedWidget for screen switching
    • Navigation between config and monitor screens
    • Status bar for connection state
  3. Update main.py to launch the GUI

Deliverable

Running application window that can switch between placeholder screens.

Phase 6: Configuration Screen

Goal: Implement the variable configuration interface.

Tasks

  1. Implement src/ui/config_screen.py:
    • ConfigScreen(QWidget) class
    • QTableWidget with columns: Name, Type, DB, Offset, Bit, Actions
    • "Add Variable" button opening inline row or dialog
    • Edit button per row
    • Delete button per row with confirmation
    • Type dropdown (BOOL, BYTE, INT, DINT, REAL)
    • Bit offset column enabled only when Type is BOOL
    • Input validation (numeric fields, required fields)
  2. Add "Save" and "Load" buttons connected to config_store
  3. Add "Go to Monitor" navigation button
  4. Emit signal when configuration changes

Deliverable

Fully functional configuration screen where users can define PLC variables.

Phase 7: Monitor Screen

Goal: Implement the live monitoring interface.

Tasks

  1. Implement src/ui/monitor_screen.py:
    • MonitorScreen(QWidget) class
    • Connection panel: IP input, Rack spinbox, Slot spinbox, Connect button
    • Connection status indicator (colored dot + text)
    • QTableWidget with columns: Name, Type, DB, Offset, Value, Action
    • Value column updates from data_updated signal
    • Format values appropriately (BOOL as ON/OFF, REAL with decimals)
  2. Connect/disconnect button logic
  3. Add "Configuration" navigation button
  4. Poll interval setting (optional)

Deliverable

Monitor screen that displays live PLC values (read-only).

Phase 8: Write Functionality

Goal: Enable writing values to PLC variables.

Tasks

  1. Implement src/ui/dialogs/write_value.py:
    • WriteValueDialog(QDialog) for all data types
    • BOOL: ON/OFF buttons for clear intent (no ambiguity with live value)
    • Numeric types: Input field with validation based on data type
    • OK/Cancel buttons for numeric types
    • Returns entered value or None if cancelled
  2. Add action column widgets to monitor screen:
    • All types: Write button opening WriteValueDialog
    • Consistent UI across all data types
  3. Connect write actions to poller's write queue
  4. Show write success/failure feedback in diagnostics console

Deliverable

Complete read/write functionality for all supported data types.

Phase 9: Polish and Error Handling

Goal: Improve user experience and handle edge cases.

Tasks

  1. Add comprehensive error messages for common issues:
    • PLC unreachable
    • PUT/GET not enabled
    • Invalid DB or offset
    • Connection timeout
  2. Add loading indicators during connection
  3. Disable write controls when disconnected
  4. Add keyboard shortcuts (Ctrl+S to save config, etc.)
  5. Remember last used IP address
  6. Add window title with connection status
  7. Handle application close (stop poller, disconnect cleanly)

Deliverable

Production-ready application with good UX.

Phase 10: Testing and Documentation

Goal: Ensure reliability and provide user documentation.

Tasks

  1. Add unit tests for:
    • Variable model serialization
    • Data type conversions
    • Config store save/load
  2. Add integration tests with snap7 server simulator
  3. Update README with:
    • Installation instructions
    • Usage guide with screenshots
    • PLC configuration requirements
  4. Add inline code documentation where non-obvious

Deliverable

Tested, documented application ready for distribution.

Phase 11: Menu Bar and CSV Import/Export

Goal: Add a standard menu bar with file operations and CSV import/export.

Tasks

  1. Add menu bar to MainWindow:
    • File menu:
      • New (Ctrl+N) - Clear current configuration
      • Open... (Ctrl+O) - Load configuration from JSON
      • Save (Ctrl+S) - Save current configuration
      • Save As... (Ctrl+Shift+S) - Save to new file
      • Import CSV... - Import variables from CSV
      • Export CSV... - Export variables to CSV
      • Quit (Ctrl+Q) - Exit application
    • View menu:
      • Configuration (Ctrl+1) - Show config screen
      • Monitor (Ctrl+2) - Show monitor screen
      • Diagnostics Panel (Ctrl+D) - Toggle diagnostics
    • Help menu:
      • About - Show application info
  2. Implement CSV import functionality:
    • Parse CSV with columns: Name, Type, DB, Offset, Bit
    • Validate data types and values
    • Handle duplicate variable names
    • Show import summary/errors
  3. Implement CSV export functionality:
    • Export current variables to CSV format
    • Include all variable properties
    • Allow user to choose file location

Deliverable

Application with standard menu bar and CSV import/export capability for easier variable configuration.

Phase 12: Verbose Diagnostics ✅

Goal: Enhance diagnostics console to show detailed PLC communication messages.

Status: Complete

Tasks

  1. ✅ Add verbose logging option to diagnostics panel:
    • Toggle button or checkbox for verbose mode
    • When enabled, show raw S7 protocol details
  2. ✅ Log detailed read operations:
    • DB number, start offset, byte count
    • Raw bytes received (hex format)
    • Parsed values for each variable
    • Timing information (request/response duration)
  3. ✅ Log detailed write operations:
    • Variable name, address, value being written
    • Raw bytes sent (hex format)
    • Write confirmation/error response
  4. Log connection details (partial - basic connection logging):
    • TSAP parameters
    • PDU size negotiation
    • Connection timing
  5. ✅ Add log filtering options:
    • Filter by log level (DEBUG, INFO, WARNING, ERROR)
    • Filter by operation type (via log level)
  6. ✅ Add log export:
    • Export diagnostics log to text file
    • Include timestamps and all details

Implementation Details

  • DiagnosticsPanel: Enhanced with verbose mode toggle, log level filter dropdown, and export button
  • PLCClient: Added ReadResult and WriteResult dataclasses with debug info
  • PLCClient._read_db_variables_verbose(): Captures timing and raw bytes for read operations
  • PLCClient._write_bool_verbose() and _write_value_verbose(): Capture timing and raw bytes for writes
  • PLCPoller: Added debug_log signal and set_verbose() method to enable verbose logging

Deliverable

Comprehensive diagnostics console for debugging PLC communication issues.

Phase 13: Future Enhancements (Post-MVP)

Goal: Add advanced features to enhance the application's capabilities.

Tasks

  1. Multiple connections: Connect to multiple PLCs simultaneously

    • Add connection manager to handle multiple PLC clients
    • Tab-based UI for switching between connections
    • Independent polling for each connection

  2. Variable groups: Organize variables into named groups/tabs

    • Add group/folder support in configuration
    • Collapsible groups in monitor view
    • Group-based filtering and operations

  3. Data logging: Record values over time to CSV

    • Configurable logging interval
    • Select which variables to log
    • Start/stop logging controls
    • Automatic file rotation

  4. Alarm configuration: Set thresholds and alert on value changes

    • Define high/low limits per variable
    • Visual indicators for alarm states
    • Alarm history log
    • Optional sound notifications

  5. Import from TIA Portal: Parse exported symbol tables

    • Support TIA Portal CSV/XML exports
    • Map DB symbols to variables automatically
    • Handle nested data structures

  6. Trend charts: Visualize value changes over time

    • Real-time line charts for numeric variables
    • Configurable time window
    • Multiple variables on same chart
    • Export chart as image

Deliverable

Feature-rich PLC monitoring application with advanced capabilities for industrial use.