ABB/FIMER PVI VSN REST Integration

Home Assistant custom integration for ABB/FIMER/Power-One PVI inverters via VSN300/VSN700 datalogger REST API.

Overview

This integration connects to VSN300 or VSN700 dataloggers to monitor ABB/FIMER/Power-One PV inverters. It communicates via the datalogger's REST API and normalizes data to
SunSpec-compatible format for consistent Home Assistant entity creation.

Features

• ✅ Automatic Discovery: Detects VSN model (VSN300/VSN700) and discovers all connected devices
• ✅ VSN300 Support: HTTP Digest authentication with X-Digest scheme
• ✅ VSN700 Support: HTTP Basic authentication
• ✅ Multi-Device: Supports inverters, meters, batteries, and storage devices
• ✅ SunSpec Normalization: VSN data mapped to SunSpec standard format
• ✅ Device Hierarchy: Proper device relationships (inverters via datalogger)
• ✅ Complete Metadata: Model, manufacturer, firmware version, serial numbers
• ✅ Configuration UI: Easy setup through Home Assistant UI
• ✅ Multi-Language: English and Italian translations included

Supported Devices

VSN Dataloggers:

• VSN300 (WIFI LOGGER CARD)
• VSN700 (Ethernet/WiFi datalogger)

Inverters: (via datalogger)

• Single-phase: REACT2-3.6-TL, REACT2-5.0-TL, etc.
• Three-phase: PVI-10.0-OUTD, PVI-12.5-OUTD, etc.

Other Devices: (via datalogger)

• Energy meters
• Battery storage systems

Installation

HACS (Recommended)

1. Open HACS in your Home Assistant instance
2. Click on "Integrations"
3. Click the three dots menu in the top right corner
4. Select "Custom repositories"
5. Add https://github.com/alexdelprete/ha-abb-fimer-pvi-vsn-rest as an Integration
6. Click "Download" and install the integration
7. Restart Home Assistant

Manual Installation

1. Download the latest release from GitHub Releases
2. Extract the custom_components/abb_fimer_pvi_vsn_rest folder
3. Copy it to your Home Assistant config/custom_components/ directory
4. Restart Home Assistant

Configuration

Prerequisites

1. VSN300 or VSN700 datalogger connected to your network
2. Datalogger IP address or hostname
3. Valid credentials (check your datalogger's web interface for configured users)

Setup Steps

1. Go to Settings → Devices & Services
2. Click "+ Add Integration"
3. Search for "ABB FIMER PVI VSN REST"
4. Enter configuration:
   • Host: IP address or hostname (e.g., 192.168.1.100 or abb-vsn300.local)
   • Username: Authentication username (commonly guest, but check your device)
   • Password: Authentication password (may be empty or configured on your device)
5. Click "Submit"

The integration will:

• Detect VSN model (VSN300 or VSN700)
• Discover all connected devices (inverters, meters, batteries)
• Create Home Assistant entities for all data points

Configuration Options

After setup, click "Configure" on the integration card to access the options dialog. All configuration options are described below:

Polling Settings

Failure Notifications

Runtime vs Startup Notifications:

• Runtime: Monitors failures during normal operation after HA is running
• Startup: Monitors failures when HA starts/restarts and can't connect to the device

Tip for solar-only systems: If your inverter is offline at night and you restart HA at night,
disable "Enable startup failure notifications" to avoid unnecessary alerts.

Device Name Customization

Note: Only device types discovered in your system will appear in the options dialog.

See Custom Device Names below for detailed examples.

Connection Failure Notifications

The integration can notify you when the datalogger becomes unreachable and optionally execute a recovery script.

How It Works:

1. When the datalogger fails to respond, the integration tracks consecutive failures
2. After reaching the threshold (default: 3), a persistent notification appears
3. If configured, a recovery script executes automatically (e.g., script.restart_router)
4. When connection recovers, a recovery notification shows downtime details

Recovery Script Use Cases:

• Restart router/network equipment via smart plug
• Power cycle the datalogger
• Send alerts via external services
• Trigger any Home Assistant automation

Recovery Script Variables:

When your recovery script is called, the integration passes these variables that you can use:

Example Script:

# scripts.yaml
power_cycle_datalogger:
  alias: "Power Cycle Datalogger"
  sequence:
    - service: switch.turn_off
      target:
        entity_id: switch.datalogger_plug
    - delay:
        seconds: 10
    - service: switch.turn_on
      target:
        entity_id: switch.datalogger_plug
    - service: notify.mobile_app
      data:
        title: "Datalogger Recovery"
        message: "Power cycled {{ device_name }} after {{ failures_count }} failures"

Reconfiguration

If you need to change the hostname/IP or credentials:

1. Go to the integration card
2. Click the three dots menu → "Reconfigure"
3. Enter new settings

Entities

The integration creates sensor entities for all available data points from your devices.

Entity Naming

The integration uses Home Assistant's modern entity naming pattern (has_entity_name=True).

Device Names: Friendly format for beautiful UI display

• Format: {Manufacturer} {DeviceType} {Model} ({Serial})
• Examples:
  • Power-One Inverter PVI-10.0-OUTD (077909-3G82-3112)
  • ABB Datalogger VSN300 (111033-3N16-1421)
  • FIMER Inverter REACT2-3.6-TL (123456-ABCD-5678)

Entity IDs: Automatically generated by Home Assistant (slugified device name + measurement)

• Format: sensor.{manufacturer}_{device_type}_{model}_{serial}_{measurement}
• Examples:
  • sensor.power_one_inverter_pvi_10_0_outd_077909_3g82_3112_ac_power
  • sensor.abb_datalogger_vsn300_111033_3n16_1421_firmware_version
  • sensor.fimer_inverter_react2_3_6_tl_123456_abcd_5678_ac_energy

Entity Friendly Names: Shown in the UI (device name + measurement display name)

• Examples:
  • Power-One Inverter PVI-10.0-OUTD (077909-3G82-3112) AC Power
  • ABB Datalogger VSN300 (111033-3N16-1421) Firmware Version
  • FIMER Inverter REACT2-3.6-TL (123456-ABCD-5678) AC Energy

Notes:

• Entity IDs are stable and won't change once created
• Friendly names make entities easy to identify in the UI
• Device page groups all entities by device for easy management

Custom Device Names

You can customize device names for each device type through the integration options. This is useful if you want shorter, friendlier names for your devices.

To configure custom names:

1. Go to Settings → Devices & Services
2. Find the ABB/FIMER PVI VSN REST integration card
3. Click Configure
4. Enter custom names for any device type you want to customize
5. Leave fields empty to keep default naming

Example:

Dynamic Options Form: The configuration only shows prefix fields for device types that were actually discovered. For example, if you only have an inverter and datalogger, you
won't see fields for meter or battery.

Entity ID Behavior:

⚠️ Warning: The "Regenerate entity IDs" checkbox will update all entity IDs to match new device names. This will break existing automations, scripts, and dashboards that
reference these entities. Only use this option if you understand the implications and are prepared to update your automations.

Supported Languages

The integration includes native translations for entity names in 10 European languages:

Automatic Language Selection: Home Assistant automatically selects the appropriate language based on your system settings. No configuration needed!

Examples:

• English: Power-One Inverter PVI-10.0-OUTD (077909-3G82-3112) Power AC
• Italian: Power-One Inverter PVI-10.0-OUTD (077909-3G82-3112) Potenza AC
• French: Power-One Inverter PVI-10.0-OUTD (077909-3G82-3112) Puissance AC
• German: Power-One Inverter PVI-10.0-OUTD (077909-3G82-3112) AC-Leistung

Note: Device names (manufacturer, model, serial) remain in their original format. Only measurement names are translated.

Device Information

Each device includes complete metadata:

Typical Entities (Inverter)

Production:

• AC Power (W)
• AC Current (A)
• AC Voltage (V)
• AC Frequency (Hz)
• Total Energy (Wh)
• Daily Energy (Wh)

DC Inputs (per MPPT):

• DC Voltage (V)
• DC Current (A)
• DC Power (W)

Status:

• Operating State
• Cabinet Temperature
• Isolation Resistance

Architecture

Data Flow

VSN Datalogger
    ↓ (REST API)
VSN REST Client
    ↓ (Raw JSON)
Normalizer
    ↓ (SunSpec-compatible JSON)
Coordinator
    ↓ (Polling)
Sensor Platform
    ↓
Home Assistant Entities

Key Components

1. Discovery Module (discovery.py)

   • Detects VSN model (VSN300/VSN700)
   • Discovers all connected devices
   • Extracts metadata (model, manufacturer, firmware)
   • Handles device identification (S/N, MAC addresses)

2. REST Client (client.py)

   • Authenticates with VSN datalogger
   • Fetches data from REST API endpoints
   • Handles VSN300/VSN700 authentication differences

3. Normalizer (normalizer.py)

   • Transforms VSN proprietary format to SunSpec standard
   • Uses mapping definitions from mapping/ directory
   • Provides consistent data structure

4. Coordinator (coordinator.py)

   • Manages periodic data polling
   • Handles errors and retries
   • Distributes data to sensors

5. Config Flow (config_flow.py)

   • User interface for setup
   • Connection validation
   • Reconfiguration support

VSN Authentication

The integration automatically detects which VSN model you have and uses the appropriate authentication method.

Detection Process

1. Send unauthenticated request to /v1/status
2. Examine response:
   • HTTP 401 with WWW-Authenticate: X-Digest... → VSN300 (auth required)
   • HTTP 401 without digest → Try preemptive Basic auth → VSN700 (auth required)
   • HTTP 200 → Analyze status data → VSN300 or VSN700 (no auth required)

VSN300

• Scheme: Custom HTTP Digest (X-Digest header)
• Process:
  1. Request challenge from endpoint
  2. Compute MD5 digest response: MD5(MD5(username:realm:password):nonce:MD5(method:uri))
  3. Send request with Authorization: X-Digest username="...", realm="...", nonce="...", response="..."

VSN700

• Scheme: Preemptive HTTP Basic Authentication
• Process: Send Authorization: Basic {base64(username:password)} with every request
• Note: VSN700 accepts credentials immediately without requiring a challenge-response flow

Devices Without Authentication

Some VSN devices may have authentication disabled. The integration fully supports this:

• When the device returns HTTP 200 (no authentication required), the integration analyzes the status data structure to determine the model
• VSN300 indicators: logger.board_model = "WIFI LOGGER CARD", serial format XXXXXX-XXXX-XXXX, or many status keys (>10)
• VSN700 indicators: logger.loggerId in MAC address format, or minimal status keys (≤3)
• All subsequent requests are made without authentication headers

All authentication methods are handled automatically by the integration - no configuration needed!

Troubleshooting

Connection Issues

Symptom: "Cannot connect" error during setup

Solutions:

1. Verify datalogger IP/hostname is correct
2. Ensure datalogger is powered on and network-accessible
3. Check firewall rules allow HTTP (port 80)
4. Try accessing http://{host}/v1/status in browser

Authentication Issues

Symptom: "Authentication failed" error

Solutions:

1. Check your datalogger's web interface for valid credentials
2. Check credentials in datalogger web interface
3. Reset datalogger credentials if necessary

No Entities Created

Symptom: Integration loads but no sensors appear

Solutions:

1. Check Home Assistant logs for errors
2. Verify inverter is connected to datalogger
3. Check datalogger web interface shows inverter data
4. Enable debug logging (see below)

Debug Logging

To enable debug logging for this integration, add the following to your configuration.yaml:

logger:
  default: info
  logs:
    custom_components.abb_fimer_pvi_vsn_rest: debug

After adding this configuration:

1. Restart Home Assistant to apply the logging configuration
2. Reproduce the issue you're experiencing
3. Download the full logs using one of these methods:

Method 1: Home Assistant UI (Recommended)

1. Go to Settings → System → Logs
2. Click "Download Full Log" button in the top right
3. The downloaded file contains all log entries including debug messages

Method 2: Direct File Access

If you have access to your Home Assistant configuration directory:

# The log file is located at:
config/home-assistant.log

# To filter only this integration's logs:
grep "abb_fimer_pvi_vsn_rest" home-assistant.log > integration_debug.log

Method 3: SSH/Terminal Access

# View live logs filtered by integration:
ha core logs | grep "abb_fimer_pvi_vsn_rest"

# Or for Docker installations:
docker logs homeassistant 2>&1 | grep "abb_fimer_pvi_vsn_rest"

What to Include When Reporting Issues

When opening a GitHub issue, please include:

1. Full debug log (downloaded via Method 1 above)
2. Integration version (found in HACS or Settings → Devices & Services)
3. Home Assistant version (Settings → About)
4. VSN datalogger model (VSN300 or VSN700)
5. Inverter model (e.g., PVI-10.0-OUTD, REACT2-3.6-TL)
6. Steps to reproduce the issue

Privacy Note: Debug logs may contain your device's IP address and serial numbers. Review the log before sharing and redact sensitive information if needed.

Testing and Reporting Issues

If you're experiencing connection or authentication issues, you can use the standalone test script to diagnose the problem and provide detailed logs when reporting issues.

Using the VSN Test Script

The repository includes a standalone diagnostic script that mirrors the integration's client library. It can test your VSN device without installing the integration:

1. Download the script:

   wget https://raw.githubusercontent.com/alexdelprete/ha-abb-fimer-pvi-vsn-rest/master/scripts/vsn-rest-client/vsn_rest_client.py

2. Install dependencies:

   pip install aiohttp

3. Run the test:

   python vsn_rest_client.py --host 192.168.1.100

   Replace 192.168.1.100 with your datalogger's IP address. Additional options:

   # With credentials (if not using default guest access)
   python vsn_rest_client.py --host 192.168.1.100 --username admin --password mypass
   
   # With verbose output (includes raw status data)
   python vsn_rest_client.py --host 192.168.1.100 -v
   
   # With debug logging
   python vsn_rest_client.py --host 192.168.1.100 --debug
   
   # Custom timeout (default: 10s)
   python vsn_rest_client.py --host 192.168.1.100 --timeout 30

4. Review output:

   The script performs a complete diagnostic sequence:

   • Socket check - Verifies the device is reachable on port 80 (fast-fail)
   • Device discovery - Detects VSN300/VSN700, finds all connected devices (inverters, meters, batteries)
   • Data fetching - Retrieves status, livedata, and feeds from all REST API endpoints
   • Data normalization - Maps raw VSN points to SunSpec-compatible names with Home Assistant metadata
   • State translation - Translates Aurora protocol state codes to human-readable text

   Output files are automatically saved in the current directory:

   File	Content
   {model}_discovery.json	Device discovery results (logger info, connected devices)
   {model}_status.json	Raw status endpoint data
   {model}_livedata.json	Raw livedata endpoint data
   {model}_feeds.json	Raw feeds endpoint data
   {model}_normalized.json	Normalized data with SunSpec names and HA metadata

   Where {model} is vsn300 or vsn700.

5. When reporting issues:

   • Include the console output showing device detection and any errors
   • Attach the generated JSON files (especially _discovery.json and _status.json)
   • Specify your inverter model and VSN datalogger model

Common Test Results

Successful VSN300 detection:

[INFO] Checking socket connectivity to 192.168.1.100:80...
[INFO] Socket connection successful
[INFO] Running device discovery...
[INFO] Attempting /v1/status at http://192.168.1.100
[INFO] Got 401 - checking WWW-Authenticate header for X-Digest
[INFO] Detected VSN300 (X-Digest authentication required)

Successful VSN700 detection:

[INFO] Checking socket connectivity to 192.168.1.100:80...
[INFO] Socket connection successful
[INFO] Running device discovery...
[INFO] Attempting /v1/status at http://192.168.1.100
[INFO] No authentication required (HTTP 200)
[INFO] Detected VSN700 from status structure

Device unreachable:

[INFO] Checking socket connectivity to 192.168.1.100:80...
[ERROR] Socket connection failed: Connection timed out

If you see this, verify the device is powered on and the IP address is correct.

Authentication failure:

[ERROR] Authentication failed for VSN300: invalid credentials

If you see this, verify your credentials and ensure the device is a VSN300/VSN700 datalogger.

Data Mapping

VSN data points are mapped to SunSpec-compatible schema using definitions in the mapping/ directory.

The mapping includes:

• Device classification (inverter type, meter, battery, etc.)
• Point name translation (VSN → SunSpec)
• Unit conversions and scaling
• Device class and state class for Home Assistant
• Proper labels and descriptions

For details, see MAPPING_NOTES.md.

Translations

The integration includes complete translations for entity names in 10 European languages:

• 🇬🇧 English (en.json) - 258 sensors
• 🇮🇹 Italian (it.json) - 258 sensors
• 🇫🇷 French (fr.json) - 258 sensors
• 🇪🇸 Spanish (es.json) - 258 sensors
• 🇵🇹 Portuguese (pt.json) - 258 sensors
• 🇩🇪 German (de.json) - 258 sensors
• 🇸🇪 Swedish (sv.json) - 258 sensors
• 🇳🇴 Norwegian (nb.json) - 258 sensors
• 🇫🇮 Finnish (fi.json) - 258 sensors
• 🇪🇪 Estonian (et.json) - 258 sensors

The integration automatically uses the language configured in your Home Assistant instance. All UI strings, error messages, configuration flows, and entity names are fully
translated.

Contributing Translations

Want to add a new language or improve existing translations? Here's how:

For Entity Names (258 sensors in entity.sensor section):

1. Fork the repository

2. Copy translations/en.json to translations/[language_code].json

   • Use ISO 639-1 language codes (e.g., nl for Dutch, da for Danish)

3. Translate the entity.sensor section:

   "entity": {
     "sensor": {
       "watts": { "name": "Your Translation Here" },
       "dc_voltage_1": { "name": "Your Translation Here" },
       ...
     }
   }

4. Keep the config and options sections from en.json (or translate those too!)

5. Test with your Home Assistant instance (set HA language to your new language)

6. Submit a pull request

Translation Tips:

• Maintain technical accuracy (e.g., "Power AC" should remain related to AC power)
• Keep translations concise (they appear in entity names)
• Preserve measurement context (e.g., distinguish "Voltage DC - String 1" from "Voltage AC")
• Review existing languages for consistency

Questions? Open a GitHub Discussion - the community is happy to help!

See translations/ for existing translations.

Development

See CLAUDE.md for development guidelines and architecture details.

Project Structure

custom_components/abb_fimer_pvi_vsn_rest/
├── __init__.py              # Integration entry point
├── config_flow.py           # UI configuration
├── coordinator.py           # Data update coordinator
├── sensor.py                # Sensor platform
├── const.py                 # Constants and state mappings
├── manifest.json            # Integration manifest
├── translations/            # Entity name translations (10 languages)
│   ├── de.json             # German
│   ├── en.json             # English
│   ├── es.json             # Spanish
│   ├── et.json             # Estonian
│   ├── fi.json             # Finnish
│   ├── fr.json             # French
│   ├── it.json             # Italian
│   ├── nb.json             # Norwegian Bokmål
│   ├── pt.json             # Portuguese
│   └── sv.json             # Swedish
└── abb_fimer_vsn_rest_client/  # Client library
    ├── __init__.py         # Library exports
    ├── client.py           # REST API client
    ├── auth.py             # Authentication (VSN300/VSN700)
    ├── discovery.py        # VSN model and device discovery
    ├── normalizer.py       # VSN→SunSpec data normalization
    ├── mapping_loader.py   # Mapping file loader
    ├── models.py           # Data models
    ├── utils.py            # Helper utilities
    ├── exceptions.py       # Custom exceptions
    └── data/               # Client library resources
        └── vsn-sunspec-point-mapping.json  # VSN→SunSpec mapping (258 points)

Related Projects

• ha-abb-powerone-pvi-sunspec Legacy v4.x integration (Modbus only)

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

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

Credits

Developed by Alessandro Del Prete

SunSpec model definitions from SunSpec Models Repository (Apache-2.0 license)

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Run linting: uvx pre-commit run --all-files
5. Commit your changes (git commit -m "feat: add my feature")
6. Push to your branch (git push origin feature/my-feature)
7. Open a Pull Request

Please ensure all CI checks pass before requesting a review.

Coffee

If you like this integration, I'll gladly accept some quality coffee,
but please don't feel obliged. :)