home-assistant-mercury-co-nz

KO | EN

gitlite — search

#python #react #typescript #llm #golang #machine-learning #deep-learning #nodejs #cli #kubernetes #awesome-list #vue #pytorch #openai

home-assistant-mercury-co-nz

(★ 25)

No description available.

home-assistant-mercury-co-nz Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Mercury Energy NZ - Home Assistant Integration

A custom Home Assistant integration that provides beautiful, interactive energy usage charts for Mercury Energy New Zealand customers.

## Demo

### Energy Usage

```yaml
type: custom:mercury-energy-usage-card
entity: sensor.mercury_nz_energy_usage
name: Energy Usage Charts
```

![Energy Usage](https://raw.githubusercontent.com/bkintanar/home-assistant-mercury-co-nz/main/assets/mercury-energy-usage.gif)

### Energy Weekly Summary

```yaml
type: custom:mercury-energy-weekly-summary-card
entity: sensor.mercury_nz_energy_usage
name: Weekly Summary
```

![Energy Weekly Summary](https://raw.githubusercontent.com/bkintanar/home-assistant-mercury-co-nz/main/assets/energy-weekly-summary.png)

### Energy Monthly Summary

```yaml
type: custom:mercury-energy-monthly-summary-card
entity: sensor.mercury_nz_current_period_cost
name: Monthly Summary
```

![Energy Monthly Summary](https://raw.githubusercontent.com/bkintanar/home-assistant-mercury-co-nz/main/assets/monthly-summary.png)

### Gas Monthly Usage (v1.6.0+)

```yaml
type: custom:mercury-gas-monthly-summary-card
entity: sensor.mercury_nz_gas_monthly_usage
name: Gas Monthly Usage
```

A bar chart of monthly gas consumption with the same prev/next nav as the
electricity card. **Yellow** bars are actual meter reads; **gray** bars are
Mercury estimates. Click any bar to see that period's invoice range, cost,
and kWh. Requires a Mercury account with gas service.

## ✨ Features

### 📊 Interactive Chart Card

- **Beautiful Chart.js Visualization**: Modern, responsive energy usage charts
- **Dual Data Display**: Shows both energy usage (kWh) and temperature data
- **Smart Pagination**: Navigate through historical data with intelligent 12-day pagination
- **Custom Styling**:
  - Bright yellow energy bars with rounded top corners
  - Custom temperature line color
  - Tooltip positioning above data points
- **Period Selection**: Toggle between Hourly, Daily, and Monthly views (Daily default)

### 📅 Monthly Summary Card

- **Billing Period Overview**: Current usage cost and consumption for the billing period
- **Progress Tracking**: Visual progress bar showing billing period completion
- **Date Information**: Billing period start/end dates and days remaining
- **Projected Billing**: Automatically extracts projected bill amounts from Mercury's notes
- **Responsive Design**: Adapts to different screen sizes and themes

### 🎨 Visual Features

- **Custom Colors**: Bright yellow (#FFF000) energy bars, custom temperature line
- **Responsive Design**: Adapts to different screen sizes and Home Assistant themes
- **Hidden Legend**: Clean interface without cluttering labels
- **Navigation Controls**: Previous/Next buttons with smart visibility
- **Date Labels**: Dynamic date display showing current page range

### 🔧 Smart Pagination

- **12-Day Default**: Shows 12 days of data per page for optimal viewing
- **Intelligent Navigation**: Automatically hides navigation buttons when no additional data available
- **Smart Date Ranges**: When limited data available, shows shifted date ranges for meaningful navigation
- **Tooltip Management**: Automatically hides tooltips during navigation

## 🔋 Energy Dashboard Integration

The integration writes two long-term statistics on every coordinator update so Mercury data appears in the Home Assistant Energy Dashboard:

- `mercury_co_nz:<id>_energy_consumption` (kWh) — picker label: `Mercury <id> consumption`
- `mercury_co_nz:<id>_energy_cost` (NZD) — picker label: `Mercury <id> cost`

`<id>` is your Mercury account ID with dashes/dots replaced by underscores. Until your bill summary is fetched (typically within ~5 minutes of integration setup), a temporary email-hash-based ID is used. **Do NOT add the temporary ID to the Energy Dashboard** — wait until the account-id-based ID appears.

Up to **180 days of historical data** are backfilled on first install (from the integration's persisted JSON cache). Mercury delivers data with a ~2-day lag, so the trailing edge of Energy Dashboard graphs will always be 2 days behind real time.

### Steps to enable

1. Open **Settings → Dashboards → Energy**.
2. Under **Electricity grid**, click **Add consumption**. Pick the `mercury_co_nz:...` consumption statistic.
3. Tick **Use an entity tracking the total costs**. Pick the `mercury_co_nz:...` cost statistic.
4. (Optional but recommended) Set `homeassistant.currency: NZD` in `configuration.yaml` and restart, otherwise the dashboard cost labels may show `$` instead of `NZ$`.

### Multi-ICP Support — v2.0.0+

If your Mercury account has multiple ICPs (Installation Control Points — separate electricity meters at different premises, or main + EV supply), v2.0.0+ exposes each ICP as a separate device with its own sensors and Energy Dashboard statistic series.

**For single-ICP users (the majority): zero changes.** Your existing entity_ids and Energy Dashboard data are preserved exactly. The "primary ICP" mechanism keeps `sensor.mercury_nz_*` and `mercury_co_nz:<acct>_energy_consumption` byte-identical to v1.5.x.

**For multi-ICP users:**

- **Devices**: 1 parent "Mercury Account" device + N child devices (one per ICP), linked via `via_device`. Account-scoped sensors (bill, weekly summary, monthly summary) attach to the parent; per-meter sensors (usage, cost, plan rate) attach to each ICP child.
- **Entity IDs**: primary ICP keeps the legacy unsuffixed form (`sensor.mercury_nz_total_usage`, etc.). Secondary ICPs get an ICP-token prefix (e.g., `sensor.mercury_nz_icp_002_total_usage`).
- **Energy Dashboard**: each ICP has its own selectable source. Add multiple sources under **Settings → Energy → Add electricity grid**.
- **Statistics**: primary keeps `mercury_co_nz:<acct>_energy_consumption`; secondary uses `mercury_co_nz:<acct>_<icp_token>_energy_consumption`. Same pattern for `_energy_cost`, `_gas_consumption`, `_gas_cost`.

**How "primary" is chosen**: deterministically — the first electricity service returned by Mercury's API. Persisted to the config entry's `_primary_service_id` so it survives HA restarts. To override it, pin an ICP (below).

#### Pin one ICP per HA instance — v2.1.0+

If you run **one Home Assistant instance per address** with all the meters on a single Mercury account, you can scope an instance to just its own ICP.

**Settings → Devices & services → Mercury NZ → Configure → ICP for this instance.** Pick an ICP (choices are labelled with the address Mercury reports) and submit; the integration reloads.

With an ICP pinned:

- Only that ICP's device and entities are created — the other ICPs disappear from this instance.
- The **weekly/monthly summary sensors and the usage charts** show that ICP's data instead of the primary/combined rollup, because the pinned ICP becomes the primary.
- Choosing **All ICPs (default)** clears the pin and restores full v2.0.0 behavior. The pin is stored in the entry's *options* and never overwrites the persisted discovery primary, so toggling it is reversible.

Caveats:

- **The bill sensors stay account-wide** (`bill_*`, amount due). Mercury issues one bill per account, so there is nothing to split per ICP.
- The pin covers **electricity** ICPs only; gas (normally a single service) is unaffected.
- The pinned ICP writes to the legacy account-based `statistic_id`. On a fresh per-address instance that's exactly what you want; if you pin a *different* ICP on an instance that already has history, that series will show a discontinuity.
- The picker needs the ICP list, so it's only available after the first poll (~1 coordinator cycle). Before that, Configure aborts with a "not discovered yet" message.

**Note for existing users**: the option defaults to unset, which is byte-for-byte v2.0.0 behavior. Nothing changes unless you pin.

**Gas + multi-ICP**: same model. Gas-primary = first gas service in Mercury's response.

**Verify detection** in HA logs after restart:

- `Mercury CO NZ: discovered N electricity ICP(s) + M gas ICP(s); primary_electricity=...; instantiated K importers`

**Single-ICP regression**: `mercury_co_nz:*_energy_consumption` and Store key (`{DOMAIN}_statistics_<email_hash>`) are byte-identical to v1.5.x. No "ID changed" ERROR; existing Energy Dashboard history continues accruing.

### Gas (auto-detected, monthly granularity) — v1.4.0+

If your Mercury account includes gas service (alongside electricity, or gas-only), v1.4.0+ automatically imports gas consumption + cost into Home Assistant's Energy Dashboard at **monthly granularity**.

**Electricity-only accounts get no gas entities at all** (v2.1.1+). Earlier versions created `gas_monthly_usage` and `bill_gas_amount` unconditionally, so electricity-only customers saw two sensors permanently stuck at `0`. After upgrading, those two become orphaned entities — HA will show them as unavailable/restored, and you can delete them from **Settings → Devices & services → Entities**.

**Why monthly only?** Mercury's gas API does not expose daily or hourly data — only monthly invoice-period aggregates. The integration emits one statistics entry per Mercury invoice period (typically one month), anchored at the end of the period.

**What this looks like in HA:**

- **Energy Dashboard → Monthly tab**: gas bars at correct totals per month — matches your Mercury bill. ✅
- **Energy Dashboard → Daily / Hourly tabs**: a single bar per Mercury invoice period at `invoice_to`. The daily/hourly views still work but show monthly granularity — this is an honest representation of what Mercury actually provides (no synthetic sub-monthly distribution).
- **Live `sensor.mercury_nz_gas_monthly_usage` entity** (v1.6.0+): exposes the per-period gas history (kWh, cost, invoice dates, `is_estimated` tag) as `extra_state_attributes` so the new `mercury-gas-monthly-summary-card` Lovelace card can render a bar chart with month-by-month nav. The entity itself reports the current rolling kWh total. Daily/hourly gas entities are still not available — Mercury simply doesn't expose sub-monthly data.

**Setup:**

1. Restart Home Assistant after upgrading.
2. Open **Settings → Energy → Add gas source**.
3. Select **`Mercury <account-id> gas consumption`** as your gas usage source.
4. (Optional) Select **`Mercury <account-id> gas cost`** as the gas cost stat.

Mercury reports gas in kWh natively (NZ gas billing is energy-based); HA accepts kWh-denominated gas statistics directly when paired with `device_class=energy` (the same pattern Octopus Energy uses for UK gas).

**Verify detection** in HA logs after restart:

- `Mercury CO NZ: gas service detected; enabling gas statistics importer`
- `Mercury CO NZ: gas_* keys merged into coordinator data: [...]`

Gas statistics use the same `mercury_co_nz:<id_prefix>_*` namespace as electricity, just with different suffixes (`_gas_consumption` and `_gas_cost` vs `_energy_consumption` and `_energy_cost`).

### Notes

- Mercury exposes per-hour usage in addition to daily totals. The integration prefers real per-hour values for the dashboard hourly view; days outside the hourly cache window fall back to a daily-total split evenly across 23/24/25 hours (DST-aware), so the trailing 180-day backfill is still smooth even before the hourly cache has filled.
- Mercury bill corrections within the trailing 3 days are absorbed automatically (recent days are re-imported on every poll).
- If you previously set up template-sensor + utility_meter workarounds for the Energy Dashboard, you can remove them after enabling these statistics.
- Gas statistics (v1.4.0+) are monthly-granularity only — see the "Gas (auto-detected, monthly granularity)" section above.

## 📊 Using with `dynamic_energy_cost` (per-appliance cost tracking)

Five new sensors are exposed for the current electricity plan:

| Entity                                     | Unit       | Notes                                               |
| ------------------------------------------ | ---------- | --------------------------------------------------- |
| `sensor.mercury_nz_current_rate`           | `NZD/kWh`  | Current per-kWh price (NZD, not cents)              |
| `sensor.mercury_nz_daily_fixed_charge`     | `NZD/day`  | Daily fixed charge from the active plan             |
| `sensor.mercury_nz_current_plan`           | text       | Plan name (e.g. "Anytime", "Low User")              |
| `sensor.mercury_nz_icp_number`             | text       | ICP / Installation Control Point identifier         |
| `sensor.mercury_nz_plan_change_pending`    | `yes`/`no` | Surfaces upcoming plan transitions                  |

To wire `sensor.mercury_nz_current_rate` into the [HACS dynamic_energy_cost](https://github.com/martinarva/dynamic_energy_cost) integration:

1. Install `dynamic_energy_cost` from HACS.
2. Add the integration. For each appliance you want to track:
   - **Power sensor**: a kWh-emitting entity (e.g. a Tapo P110M smart plug's `..._energy_kwh` entity).
   - **Price sensor**: `sensor.mercury_nz_current_rate`.
3. The resulting cost sensor reads `power × current_rate` and labels the output in `hass.config.currency`. Set `currency: NZD` in `configuration.yaml` under `homeassistant:` if you want the labels to read NZD.

**Note**: Mercury's API stores rates in NZ cents; this integration converts to NZD/kWh internally so dynamic_energy_cost computes correct values out of the box. Time-of-use (TOU) plans are not yet supported — only the "Anytime" rate is exposed in this release.

## 🚀 Installation

### Option 1: HACS (Recommended)

1. **Add Custom Repository**:

- Go to HACS → Integrations
   - Click the three dots (⋮) → Custom repositories
   - Add repository URL: `https://github.com/bkintanar/home-assistant-mercury-co-nz`
   - Category: Integration

2. **Install Integration**:
   - Search for "Mercury Energy NZ" in HACS
   - Click Install
   - Restart Home Assistant

### Option 2: Manual Installation

1. **Copy Files**:

```bash
   # Download and extract to your Home Assistant config directory
   mkdir -p /config/custom_components/mercury_co_nz/
   # Copy all files from custom_components/mercury_co_nz/
   ```

2. **Restart Home Assistant**

## ⚙️ Configuration

### 1. Add Integration

- Go to Configuration → Integrations
- Click "Add Integration"
- Search for "Mercury Energy NZ"
- Enter your Mercury Energy credentials

### 2. Add Chart Card

Add this to your Home Assistant dashboard:

```yaml
type: custom:mercury-energy-usage-card
entity: sensor.mercury_nz_energy_usage
name: Energy Usage Charts
```

### Configuration Options

| Option            | Type    | Default                  | Description                           |
| ----------------- | ------- | ------------------------ | ------------------------------------- |
| `entity`          | string  | **required**             | The Mercury Energy sensor entity      |
| `name`            | string  | "Energy Usage"           | Card title                            |
| `show_navigation` | boolean | `false`                  | Show previous/next navigation         |
| `period`          | string  | `hourly\|daily\|monthly` | Time periods to show (pipe-separated) |

## 📋 Requirements

- Home Assistant **2025.11** or newer (the Energy Dashboard integration uses the `unit_class` field on `StatisticMetaData`, which shipped in HA 2025.11)
- Mercury Energy New Zealand account
- Active internet connection for data retrieval

## 🐳 Docker Deployment

For Docker-based Home Assistant installations:

```bash
# Copy files to container
docker cp custom_components/mercury_co_nz/ homeassistant:/config/custom_components/

# Restart container
docker restart homeassistant
```

## 🎯 Usage Examples

### Basic Card

```yaml
type: custom:mercury-energy-usage-card
entity: sensor.mercury_nz_energy_usage
name: Daily Usage
```

> **Note**: For charting, use one of these sensors with full historical data:
>
> - `sensor.mercury_nz_energy_usage` (recommended)
> - `sensor.mercury_nz_total_usage_7_days`
> - `sensor.mercury_nz_current_bill_7_days`
>
> Other sensors (billing info, dates, etc.) have minimal attributes to optimize database performance.

### Advanced Card with Navigation

```yaml
type: custom:mercury-energy-usage-card
entity: sensor.mercury_nz_energy_usage
name: Energy Usage Charts
```

### Period Filtering Examples

Show only daily and monthly views:

```yaml
type: custom:mercury-energy-usage-card
entity: sensor.mercury_nz_energy_usage
name: Energy Usage Charts
period: daily|monthly
```

Show only hourly view:

```yaml
type: custom:mercury-energy-usage-card
entity: sensor.mercury_nz_energy_usage
name: Hourly Usage
period: hourly
```

Show all periods (default):

```yaml
type: custom:mercury-energy-usage-card
entity: sensor.mercury_nz_energy_usage
name: Energy Usage Charts
period: hourly|daily|monthly
```

### Monthly Summary Card

```yaml
type: custom:mercury-monthly-summary-card
entity: sensor.mercury_nz_current_period_cost
name: Monthly Summary
show_progress_bar: true
```

#### Monthly Summary Configuration

| Option              | Type    | Default           | Description                      |
| ------------------- | ------- | ----------------- | -------------------------------- |
| `entity`            | string  | **Required**      | Any Mercury NZ sensor entity     |
| `name`              | string  | "Monthly Summary" | Card title                       |
| `show_progress_bar` | boolean | true              | Show billing period progress bar |

The monthly summary card displays:

- **Current usage cost and consumption** for the billing period
- **Billing period dates** (start and end)
- **Days remaining** in the current billing period
- **Progress bar** showing how much of the billing period has elapsed
- **Projected bill amount** extracted from Mercury's billing notes

### Gas Monthly Usage Card (v1.6.0+)

```yaml
type: custom:mercury-gas-monthly-summary-card
entity: sensor.mercury_nz_gas_monthly_usage
name: Gas Monthly Usage
```

#### Gas Card Configuration

| Option            | Type    | Default             | Description                                  |
| ----------------- | ------- | ------------------- | -------------------------------------------- |
| `entity`          | string  | **Required**        | Must be `sensor.mercury_nz_gas_monthly_usage` |
| `name`            | string  | "Gas Monthly Usage" | Card title                                   |
| `show_navigation` | boolean | `true`              | Show previous/next page arrows               |

The gas card displays:

- **Bar chart** of monthly gas consumption (kWh) — one bar per Mercury invoice period
- **Per-bar coloring**: yellow `rgb(255, 240, 0)` for actual meter reads, gray `#727272` for Mercury estimates
- **Page navigation** with prev/next arrows when more than 6 periods of history are available
- **Click-to-select**: click any bar to see that period's invoice range (e.g. `27 Feb 2026 – 27 Mar 2026`), cost, and kWh — with an `(estimated)` annotation when applicable
- **Legend** showing both "Actual" and "Estimated" indicators

> **Requirements**: Mercury account with gas service AND `mercury-co-nz-api>=1.1.3` (auto-installed via `manifest.json`). The `is_estimated` flag on each period drives the color choice — comes from pymercury's `consumption_periods` collapse of Mercury's parallel estimate/actual pair structure.

> **Note**: After upgrading to v1.6.0 from an older version, perform a **full Home Assistant restart** (Settings → System → Restart) — not just a config-entry reload — so the new sensor entity and JS card load from disk. HACS-installed Python modules are not hot-swapped on file update.

## 🛠️ Development

### Setting Up Development Environment

```bash
# Clone repository
git clone https://github.com/bkintanar/home-assistant-mercury-co-nz.git
cd home-assistant-mercury-co-nz

# Install dependencies
pip install -r requirements_dev.txt
```

### Deployment Script

Use the included deployment script for easy testing:

```bash
./deploy.sh
```

This script:

- Detects Docker vs direct installation
- Copies files to appropriate locations
- Provides configuration examples

### File Structure

```
custom_components/mercury_co_nz/
├── __init__.py              # Integration setup
├── config_flow.py           # Configuration flow
├── const.py                 # Constants
├── coordinator.py           # Data coordinator
├── custom-chart-card.js     # Frontend chart card
├── manifest.json            # Integration manifest
├── mercury_api.py           # Mercury Energy API client
├── sensor.py                # Sensor entities
└── strings.json             # Translation strings
```

## 🔧 Features Implemented

### Chart Customizations

- ✅ Removed usage legend
- ✅ Bright yellow (#FFF000) bar colors
- ✅ Custom temperature line color (#69A2B9)
- ✅ Rounded top corners on bars
- ✅ Tooltip positioning above data points
- ✅ Hidden page numbers in navigation

### Smart Pagination

- ✅ 12-day default pagination
- ✅ Smart navigation button visibility
- ✅ Tooltip hiding during navigation
- ✅ Date label updates for current page
- ✅ Intelligent date range shifting for limited data

### User Interface

- ✅ Hourly/Daily/Monthly period buttons
- ✅ Clean navigation controls
- ✅ Responsive design
- ✅ Theme integration

## 🐛 Troubleshooting

### Chart Not Loading

1. Check browser console for JavaScript errors
2. Verify entity exists and has data
3. Hard refresh browser (Ctrl+F5 / Cmd+Shift+R)

### Navigation Not Working

1. Ensure ` in configuration
2. Verify sufficient historical data exists
3. Check Home Assistant logs for errors

### Data Not Updating

1. Check Mercury Energy API credentials
2. Verify internet connectivity
3. Restart Home Assistant integration

### Plan Sensors Not Showing in Statistics Tab

Three of the v1.2.0 plan sensors are **text-only** and won't appear in
**Developer Tools → Statistics** (which only lists numeric long-term-stat
sensors). They DO exist — look in **Developer Tools → States**:

| Entity ID | Where to find it | Example state |
|-----------|------------------|---------------|
| `sensor.mercury_nz_current_plan` | States tab | `"Anytime"` (your plan name) |
| `sensor.mercury_nz_icp_number` | States tab | `"0001263891UN390"` |
| `sensor.mercury_nz_plan_change_pending` | States tab | `"yes"` / `"no"` |
| `sensor.mercury_nz_current_rate` | States **and** Statistics tab | `0.2737` (NZD/kWh) |
| `sensor.mercury_nz_daily_fixed_charge` | States **and** Statistics tab | `1.49` (NZD/day) |

The first three have `state_class=None` and `unit=None` because their values
are categorical strings, not measurements. HA's Statistics tab is a
recorder-side feature for numeric sensors only; this is by design.

### Unit Warnings After Upgrading to v1.2.3 or Later

If you see warnings like:

```
The unit of sensor.mercury_nz_current_bill_7_days is changing, got multiple {None, '$'}
The unit of sensor.mercury_nz_total_usage_7_days (None) cannot be converted to the unit of previously compiled statistics (kWh)
The unit of sensor.mercury_nz_energy_usage (None) cannot be converted to the unit of previously compiled statistics (kWh)
```

…after upgrading to v1.2.3+, this is **expected residue** from prior versions where state attributes
exceeded HA's 16 KB cap and `unit_of_measurement` was being dropped from the recorder. v1.2.3 fixed the
upstream cause but stale state rows remain in HA's recorder DB until they age out (default ~10 days).

**Quick fix** (one-time):

1. Open **Developer Tools → Statistics** in Home Assistant.
2. Find each affected entity (typically: `sensor.mercury_nz_energy_usage`,
   `sensor.mercury_nz_total_usage_7_days`, `sensor.mercury_nz_current_bill_7_days`).
3. Click **"Fix Issue"** next to each.
4. Choose **"Update the unit"**.

The warnings disappear immediately. This does NOT delete your sensor history or the Energy Dashboard
statistics — those use a separate `mercury_co_nz:*` namespace and are unaffected.

Alternatively, the warnings will resolve on their own once the stale state rows age out of HA's recorder.

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 🙏 Acknowledgments

- Mercury Energy New Zealand for providing API access
- Home Assistant community for integration framework
- Chart.js for the excellent charting library

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/bkintanar/home-assistant-mercury-co-nz/issues)
- **Discussions**: [GitHub Discussions](https://github.com/bkintanar/home-assistant-mercury-co-nz/discussions)
- **Home Assistant Community**: [Community Forum](https://community.home-assistant.io/)

---

**Note**: This integration is not officially affiliated with Mercury Energy New Zealand. Use at your own discretion and ensure compliance with Mercury Energy's terms of service.

home-assistant-mercury-co-nz

home-assistant-mercury-co-nz Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

home-assistant-mercury-co-nz

home-assistant-mercury-co-nz Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README