CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

GSModbus is a universal, configuration-driven C# Windows Forms application for Modbus TCP communication between PLC and MES systems. The system supports dynamic configuration through JSON files, making it adaptable to different PLC setups and address mappings without code changes.

Development Environment

Framework: .NET 8.0
Platform: Windows desktop application
UI: Windows Forms
Target: x64 Windows
Dependencies: EasyModbusTCP, System.Text.Json, SqlSugar

Database Environment

Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production

PL/SQL Release 11.2.0.1.0 - Production
CORE 11.2.0.1.0 Production
TNS for 64-bit Windows: Version 11.2.0.1.0 - Production
NLSRTL Version 11.2.0.1.0 - Production

IMPORTANT: All code must be compatible with Oracle 11g Release 11.2.0.1.0
所有的回答都需要基于这个版本可以兼容的做法

Common Commands

Build and Run

# Build the project
dotnet build

# Run the application
dotnet run

# Run configuration demo
dotnet run --project . -- demo

# Build for release
dotnet build -c Release

# Clean build artifacts
dotnet clean

Development

# Restore dependencies
dotnet restore

# Build and run in one command
dotnet run

Project Architecture

Core Components

1. Configuration System (`Config/`)

ModbusConfiguration.cs: Configuration data models including database settings
ConfigurationManager.cs: Config loading, validation, and management
modbus_config.json: Demo JSON configuration template
production_config.json: Production configuration based on actual requirements

2. Universal Communication (`UniversalModbusManager.cs`)

Configuration-driven: Uses JSON config for all settings
Dynamic data parsing: Supports multiple data types (string, integer, timestamp, etc.)
Automatic reconnection: Configurable retry logic
Real-time statistics: Connection and communication metrics
Database integration: Automatic data logging to database

3. Data Processing

DynamicModbusData.cs: Dynamic data container with type-safe access
ModbusDataParser.cs: Configuration-based data parsing and formatting

4. Database Layer (`Database/`)

DatabaseManager.cs: SqlSugar-based database operations
DatabaseEntities.cs: Entity models for data storage
Supports: Oracle 11g, SQL Server, MySQL, SQLite

5. User Interface

Form1.cs: Simplified Windows Forms UI with log-based data display
ConfigDemo.cs: Console demo for testing configuration system

6. Legacy Components (for reference)

ModbusManager.cs: Original hardcoded implementation

Configuration-Driven Design

The system uses JSON configuration files to define:

Connection Settings: IP address, port, timeouts
Communication Parameters: Heartbeat intervals, polling rates
Address Mappings: Dynamic field definitions with:

Register addresses
Data types (Byte, Integer, String, Timestamp, Float, Boolean)
Parsing rules (encoding, scaling, decimal places)
Display formatting (units, value mappings)

Database Configuration: Connection strings, table names, retention policies

Example Configuration Structure:

{
  "Connection": {
    "IpAddress": "192.168.3.250",
    "Port": 502
  },
  "InputAddresses": {
    "ProductData": {
      "ProductModel": {
        "Address": 6004,
        "DataType": "String",
        "Length": 10,
        "DisplayName": "产品型号"
      }
    },
    "MeasurementData": {
      "WorkingVoltage": {
        "Address": 6041,
        "DataType": "Integer", 
        "Scale": 0.01,
        "Unit": "V",
        "DisplayName": "工作电压"
      }
    }
  }
}

Key Features

Universal Compatibility: Works with any PLC by changing configuration
Dynamic Data Types: Supports strings, integers, timestamps, floats, booleans
Flexible Encoding: Big-endian/little-endian support for multi-byte data
Value Mapping: Configurable display formatting (e.g., 0="失败", 1="成功")
Automatic Scaling: Convert raw values to engineering units
Database Integration: Automatic data logging with SqlSugar ORM
Multi-Database Support: Oracle 11g, SQL Server, MySQL, SQLite
Robust Error Handling: Validation, retry logic, and detailed logging
Simplified UI: Log-based data display instead of hardcoded controls

Data Types Supported

Byte: Single byte values (0-255)
Integer: Multi-register integers with scaling (e.g., 12345 → 123.45)
String: ASCII strings with configurable encoding
Timestamp: Date/time parsing with custom formats
Float: IEEE 754 floating point
Boolean: True/false values

Usage Examples

1. Production Configuration Loading

var configManager = new ConfigurationManager();
await configManager.LoadConfigurationAsync("config/production_config.json");
var config = configManager.CurrentConfiguration;

2. Universal Modbus Manager with Database

using var modbusManager = new UniversalModbusManager(config);
modbusManager.DataReceived += (sender, data) => {
    var voltage = data.GetDouble("WorkingVoltage");
    var productModel = data.GetString("ProductModel");
    // Data automatically saved to database
};
modbusManager.DatabaseLogOccurred += (sender, log) => Console.WriteLine(log);
await modbusManager.ConnectAsync();

3. Dynamic Data Access

// Type-safe access
var testResult = data.GetBool("TestResult");
var timestamp = data.GetDateTime("RecordTime");
var productCode = data.GetString("ProductCode");

// Formatted display
var displayValue = ModbusDataParser.FormatDisplayValue(
    data.GetFieldValue("WorkingVoltage"), 
    fieldConfig
); // Returns "24.5 V"

4. Database Operations

// Database manager is automatically created and managed
// Manual access if needed:
var dbManager = new DatabaseManager(config.Database, projectName, plcIp);
await dbManager.SaveModbusDataAsync(dynamicData);
await dbManager.LogCommunicationAsync("Connected", "Successfully connected to PLC");

Configuration Files

Production Configuration (Recommended)

Path: config/production_config.json
Based on: Actual requirements from docu/需求.txt
PLC Address: 192.168.3.250:502
Database: Oracle 11g (configurable)
Address Mapping: Complete D6000-D6048 register mapping

Demo Configuration

Path: config/modbus_config.json
Purpose: Learning and testing
Template: Generic configuration example

Configuration Loading

Create new JSON file in config/ directory
Use ConfigurationManager to load: LoadConfigurationAsync("path/to/config.json")
System validates configuration on load

Migration from Legacy System

The project maintains backward compatibility:
- Original ModbusManager.cs still works with hardcoded settings
- New UniversalModbusManager.cs provides configuration-driven approach
- Same UI can work with either manager

Implementation Notes

Thread Safety: All communication operations are async-safe
Error Recovery: Automatic reconnection with configurable retry limits
Performance: Efficient register reading with batch operations
Database Performance: Connection pooling and batch inserts
Logging: Detailed debug information for troubleshooting
Memory Management: Proper disposal of resources and timers
UI Architecture: Simplified log-based display, removed hardcoded controls

Database Integration

Supported Databases

Oracle 11g (primary, production-ready)
SQL Server
MySQL
SQLite

Database Tables (Auto-created)

PRODUCTION_DATA: Main Modbus data storage
COMMUNICATION_LOG: Connection events and status
ERROR_LOG: Error tracking and resolution
STATISTICS: Communication performance metrics

Database Configuration

{
  "Database": {
    "Enabled": true,
    "Type": "Oracle",
    "ConnectionString": "Data Source=localhost:1521/XE;User Id=PRODUCTION_MES;Password=your_password;",
    "AutoCreateTables": true,
    "DataRetentionDays": 90
  }
}

Documentation

config/production_config.json: Production configuration based on actual requirements
config/Oracle使用指南.md: Oracle 11g setup and usage guide
docu/需求.txt: Original requirements and protocol specification
docu/MES地址.xlsx: Address mapping reference
ConfigDemo.cs: Complete usage examples and demonstrations