node-red-contrib-huawei-solar/README.md

Node-RED nodes for reading data from Huawei SmartLogger 3000 and SUN2000 inverters via Modbus TCP

# Node-RED Contrib Huawei Solar

Node-RED nodes for reading data from Huawei SmartLogger 3000 and SUN2000 inverters via Modbus TCP.

Converted from the proven [n8n-nodes-huaweisolar](https://github.com/Edward-Tollemache/n8n-nodes-huaweisolar) project with full functionality preservation.

## Installation

### Via Node-RED Palette Manager
1. Open Node-RED in your browser
2. Go to Menu → Manage palette → Install
3. Search for `node-red-contrib-huawei-solar`
4. Click Install

### Via npm
```bash
cd ~/.node-red
npm install node-red-contrib-huawei-solar
```

## Nodes

### 🌐 SmartLogger 3000 Node
Connects to Huawei SmartLogger 3000 devices to:
- **Read Data**: System status, power data, environmental sensors, alarms
- **Discover Devices**: Scan for connected inverters and smart meters
- **Parallel Processing**: Fast device discovery with configurable concurrency
- **Flexible Output**: Choose between descriptive or IEC 61850 field naming

#### Configuration
- **Host/Port**: SmartLogger IP address and Modbus port (typically 502)
- **Unit ID**: Modbus unit ID (typically 3 for SmartLogger)
- **Data Categories**: Select system, power, environmental, or alarm data
- **Discovery Range**: Unit ID ranges to scan (e.g., "1-50" or "12,13,14,15")
- **Timeout/Retries**: Connection resilience settings

### ⚡ SUN2000 Inverter Node
Reads detailed data from Huawei SUN2000 inverters with two operation modes:

#### 1. Read From Discovery (Recommended)
- Input: SmartLogger discovery data
- Automatically reads all discovered inverters
- Optional filtering to inverters only
- Maintains connection metadata

#### 2. Specify Devices  
- Manually specify inverter addresses
- Direct connection parameters
- Custom device naming support
- Address range parsing (e.g., "12-15" or "1,3,5,7")

#### Data Categories
- **Device Information**: Model, serial number, firmware, specifications
- **Power & Energy**: Real-time power, daily/total energy, efficiency
- **Grid Voltages**: Line and phase voltages (UAB, UBC, UCA, Ua, Ub, Uc)
- **Grid Currents**: Phase currents and frequency
- **PV String Data**: Individual string voltages, currents, and power
- **Status & Temperature**: Device status, temperatures, insulation resistance  
- **Alarms & Faults**: Comprehensive alarm decoding with human-readable messages

## Usage Examples

### Basic SmartLogger Data Reading
```javascript
// Inject → SmartLogger → Debug
SmartLogger Config:
- Operation: "Read Data"
- Data Categories: ["power", "alarms"]
- Host: "192.168.1.10"
```

### Complete System Monitoring
```javascript
// Inject → SmartLogger (Discovery) → SUN2000 → Debug
//            ↓
//         Debug (Discovery Results)

SmartLogger Config:
- Operation: "Discover Devices" 
- Discovery Range: "1-50"
- Parallel Scans: 10

SUN2000 Config:
- Operation: "Read From Discovery"
- Filter Inverters: true
- Data Categories: ["power", "voltages", "status"]
```

### Manual Inverter Reading
```javascript
// Inject → SUN2000 → Debug

SUN2000 Config:
- Operation: "Specify Devices"
- Host: "192.168.1.10"
- Inverter Addresses: "12,13,14,15"
- Data Categories: ["power", "alarms"]
```

## Data Output Structure

### SmartLogger Output
```json
{
  "system": {
    "datetime": 1642780800,
    "dstEnable": false
  },
  "power": {
    "activePowerTotal": 25.4,
    "dailyEnergy": 45.2,
    "plantStatus": "Unlimited"
  },
  "_metadata": {
    "operation": "readData",
    "host": "192.168.1.10",
    "timestamp": "2024-01-21T10:00:00.000Z",
    "success": true
  }
}
```

### SUN2000 Output (per inverter)
```json
{
  "ts": "2024-01-21T10:00:00.000Z",
  "unitId": 12,
  "deviceName": "SUN2000-10KTL-M1",
  "telemetry": {
    "activePower": 8.5,
    "phaseAVoltage": 230.1,
    "phaseACurrent": 12.3,
    "efficiency": 97.8,
    "pvStrings": [
      {
        "stringNumber": 1,
        "voltage": 380.5,
        "current": 8.2,
        "power": 3120.1
      }
    ]
  },
  "status": {
    "deviceStatus": 512,
    "deviceStatusText": "On-grid",
    "internalTemperature": 45.2,
    "alarmTexts": []
  }
}
```

## Field Naming Conventions

### Descriptive Names (Default)
```javascript
activePower, reactivePower, phaseAVoltage, 
internalTemperature, dailyEnergyYield
```

### IEC 61850 Standard
```javascript
P, Q, Ua, TempInt, EPId
```

## Network Configuration

### Typical Setup
- **SmartLogger IP**: 192.168.1.10 (or your network's gateway)
- **Modbus Port**: 502 (standard)
- **SmartLogger Unit ID**: 3
- **Inverter Addresses**: Usually 12, 13, 14, 15, etc.

### Firewall Requirements
- Allow TCP connections to SmartLogger on port 502
- Ensure Node-RED host can reach SmartLogger network segment

## Troubleshooting

### Connection Issues
1. **Verify Network**: Ping the SmartLogger IP address
2. **Check Port**: Ensure port 502 is open and not blocked
3. **Unit ID**: Confirm SmartLogger uses unit ID 3 (not 0 as in some docs)
4. **Timeout**: Increase timeout for slow networks

### No Devices Discovered
1. **Range**: Expand discovery range (try "1-100")
2. **Timeout**: Increase discovery timeout to 3000ms
3. **Concurrency**: Reduce parallel scans if network is overwhelmed

### Missing Inverter Data
1. **Filter**: Disable inverter filtering to see all devices  
2. **Categories**: Enable more data categories to get complete data
3. **Addresses**: Verify inverter addresses are correct

### Performance Optimization
- Use discovery mode for dynamic setups
- Use manual mode for fixed installations
- Adjust parallel scan count based on network capacity
- Implement caching with function nodes for high-frequency reads

## Advanced Features

### Custom Device Naming
```javascript
// In SUN2000 "Specify Devices" mode
Device Mappings:
- Address: 12, Name: "East Roof Array"
- Address: 13, Name: "West Roof Array"  
- Address: 14, Name: "South Wall Array"
```

### Error Handling
- Enable "Continue on fail" to receive error objects instead of flow stops
- Errors include connection details and specific failure reasons
- Node status indicators show connection state

### Integration Examples
- **InfluxDB**: Store time-series data for monitoring dashboards
- **MQTT**: Publish data to IoT platforms
- **Dashboard**: Real-time visualization with Node-RED dashboard
- **Alerts**: Set up email/SMS notifications for alarms

## Requirements

- **Node.js**: >= 18.0
- **Node-RED**: >= 3.0
- **Network**: TCP access to SmartLogger on port 502
- **Hardware**: Huawei SmartLogger 3000 with connected SUN2000 inverters

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Credits

Converted from the [n8n-nodes-huaweisolar](https://github.com/Edward-Tollemache/n8n-nodes-huaweisolar) project by Edward Tollemache.

All Modbus register mappings, data processing logic, and device communication protocols have been preserved from the original implementation.