aionepviewer

Async Python library for the NEP solar inverter cloud API (api.nepviewer.net).

Built for Home Assistant integrations, following the Home Assistant API library guidelines.

Single-session limit

The NEP API allows only one active session per account. Logging in from a second device or client invalidates earlier sessions, and subsequent requests return HTTP 401.

Do not use the same account simultaneously from the web portal, mobile app, and this library. If a session is invalidated, the library raises NepAuthError and clears the stored token so the next request can re-authenticate.

Features

• Async client built on aiohttp, accepting an externally managed ClientSession
• Endpoints for authentication, sites, devices, modules, statistics, playback, weather, and reports
• Per-panel microinverter data by PLC serial number
• Power flow across PV panels, home, grid, battery, and generator
• Production statistics for today, yesterday, current month, year, and lifetime
• Environmental savings: CO₂, tree equivalent, vehicle kilometers avoided, lighting hours, and oil barrels
• Intraday (5-minute), daily, monthly, and yearly chart data
• 7-day weather forecasts per site
• Email report configuration (daily, weekly, and monthly)
• Token management with automatic re-authentication before expiry
• Automatic request signing with MD5
• Type annotations across all models and methods

Installation

pip install aionepviewer

Or with uv:

uv add aionepviewer

To also install the CLI tool:

pip install aionepviewer[cli]

Quick start

import asyncio
import aiohttp
from aionepviewer import NepViewer


async def main():
    async with aiohttp.ClientSession() as session:
        client = NepViewer(session, "your-email@example.com", "your-password")

        # Authenticate (also called automatically on first request)
        auth = await client.authenticate()
        print(f"Logged in as {auth.user_info.email}, {auth.site_count} site(s)")

        # List all sites
        sites = await client.get_sites()
        for site in sites:
            print(f"Site: {site.site_name} ({site.sid})")
            print(f"  Current power: {site.now} {site.now_unit}")
            print(f"  Today: {site.today_power} {site.today_power_unit}")
            print(f"  Total: {site.total_power} {site.total_power_unit}")

            # Get detailed overview with energy flow
            overview = await client.get_site_overview(site.sid)
            print(f"  PV → Home: {overview.energy.pv_panel.power} W")
            print(f"  Grid: {overview.energy.grid.power} W")
            print(f"  CO₂ saved: {overview.benefit.co2} {overview.benefit.co2_unit}")

            # Get module-level data
            modules = await client.get_site_modules(site.sid)
            for device in modules.devices:
                print(f"  Device {device.sn} ({device.model_name}):")
                for module in device.modules:
                    print(f"    Panel {module.plc_sn}: {module.now} {module.now_unit}")


asyncio.run(main())

Home Assistant integration

Pass Home Assistant's shared aiohttp.ClientSession when creating the client:

from homeassistant.helpers.aiohttp_client import async_get_clientsession
from aionepviewer import NepViewer, NepAuthError


async def async_setup_entry(hass, entry):
    session = async_get_clientsession(hass)
    client = NepViewer(
        session,
        entry.data["email"],
        entry.data["password"],
    )

    try:
        await client.authenticate()
    except NepAuthError:
        raise ConfigEntryAuthFailed("Invalid credentials")

    # Use with DataUpdateCoordinator
    async def async_update_data():
        sites = await client.get_sites()
        result = {}
        for site in sites:
            overview = await client.get_site_overview(site.sid)
            modules = await client.get_site_modules(site.sid)
            result[site.sid] = {
                "site": site,
                "overview": overview,
                "modules": modules,
            }
        return result

    coordinator = DataUpdateCoordinator(
        hass,
        logger,
        name="nep",
        update_method=async_update_data,
        update_interval=timedelta(seconds=300),
    )
    await coordinator.async_config_entry_first_refresh()

API reference

NepViewer(session, email, password, host=DEFAULT_HOST)

Main client class.

Authentication and account

Global overview

Sites

Devices

Report settings

Chart types

Exceptions

CLI

The package includes a command-line tool with three subcommands:

• api: JSON output mapped directly to API endpoints
• chart: terminal bar charts rendered with termgraph
• status and weather: formatted status displays with optional --watch auto-refresh

Configuration

Run configure once to save your credentials. It will prompt for host, email, and password, verify the credentials against the API, and then save:

aionepviewer configure

This creates a TOML config file at the standard user config location:

You can also check the path with aionepviewer config-path.

The config file format:

email = "user@example.com"
password = "secret"
host = "https://api.nepviewer.net"   # optional, only if non-default

Authentication precedence

Credentials are resolved in this order (first non-empty value wins):

1. CLI flags: --email / --password / --host
2. Environment variables: AIONEPVIEWER_EMAIL / AIONEPVIEWER_PASSWORD
3. Config file (see above)
4. Interactive prompt (fallback for email and password)

# Uses config file (after running 'configure')
aionepviewer status

# Override email from config with a flag
aionepviewer -e other@example.com status

# Override with environment variables
export AIONEPVIEWER_EMAIL=user@example.com
export AIONEPVIEWER_PASSWORD=secret
aionepviewer status

Dashboard commands

aionepviewer status                    # Full dashboard: overview + all sites with panels
aionepviewer status --site <sid>       # Dashboard for a specific site only
aionepviewer status --watch            # Auto-refresh every 5 minutes

aionepviewer weather [sid]             # 7-day weather forecast with icons

Site ID is auto-detected if omitted (uses the first site on your account).

Chart commands

# Device production charts
aionepviewer chart production                          # Today's intraday power (W)
aionepviewer chart production --sn AABB1122            # Specific device
aionepviewer chart production --period month           # Daily bars for current month (kWh)
aionepviewer chart production --period year             # Monthly bars for current year
aionepviewer chart production --date 2026-05-20        # Specific date

# Parameter charts (Temperature, AC Voltage, etc.)
aionepviewer chart params                              # List available parameters
aionepviewer chart params Temperature "AC Voltage"     # Intraday parameter chart
aionepviewer chart params --sn AABB1122 Temperature    # Specific device

# Site production charts
aionepviewer chart site                                # Today's site production
aionepviewer chart site --period month                 # Daily bars for current month

Device SN and Site ID are auto-detected if omitted.

API commands

All API commands output raw JSON. Use these for scripting or piping to jq.

aionepviewer api login                                 # Authenticate, return token info
aionepviewer api logout                                # Invalidate session token
aionepviewer api account-info                          # User profile details
aionepviewer api overview                              # Global production summary
aionepviewer api site-status-counts                    # Online/offline site counts

aionepviewer api sites                                 # List all sites
aionepviewer api site-detail <sid>                     # Full site information
aionepviewer api site-overview <sid>                   # Production, energy flow, alerts
aionepviewer api site-modules <sid>                    # Per-panel module data
aionepviewer api site-weather <sid>                    # 7-day forecast
aionepviewer api site-layout <sid>                     # Site layout picture info
aionepviewer api site-chart <sid> --type 1             # Site chart data

aionepviewer api devices                               # List all devices
aionepviewer api device-detail <sid> <sn>              # Full device information
aionepviewer api device-stats <sn>                     # Device statistics overview
aionepviewer api device-params <sn>                    # Available power parameters
aionepviewer api device-chart <sn> --type 1            # Device chart data
aionepviewer api device-energy <sn> 2026-05-20         # Day energy stats
aionepviewer api device-energy <sn> 2026-05            # Month energy stats
aionepviewer api device-playback <sn>                  # Today's 5-min playback
aionepviewer api product-info <sn...>                  # Product model info
aionepviewer api device-wifi-ota <sn...>               # WiFi OTA status
aionepviewer api report-settings <sid> <sn>            # Report notification settings
aionepviewer api report-setup <sn> --daily --monthly   # Configure reports

Development

# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Type checking
uv run mypy src/aionepviewer

License

MIT