node-red-contrib-octopus-intelligent 1.2.1

Node-RED integration for Octopus Energy Intelligent Octopus Go with Home Assistant MQTT discovery

npm install node-red-contrib-octopus-intelligent

node-red-contrib-octopus-intelligent

Node-RED integration for Octopus Energy Intelligent Octopus Go with automatic Home Assistant MQTT discovery

Monitor your EV charging slots, control charge limits, and manage ready times directly from Home Assistant - all automatically configured via MQTT discovery.

---

🤝 Support This Project

Found this useful? Support continued development:

⭐ GitHub Star Star the repository to show your support! ⭐ Star on GitHub

💖 Sponsor Support ongoing development and maintenance Become a Sponsor

☕ Buy Me a Coffee If this project has helped you!

Your support helps with: Bug fixes and maintenance • New feature development • Documentation improvements • Community support • Feeding my children

---

✨ Features

🎮 Smart Controls

• Target Charge Slider (50-100%) - Set your desired battery level
• Ready Time Dropdown (04:00-11:00) - When your car needs to be ready
• Apply Changes Button - Prevents API spam while adjusting settings
• Confirmed Values - See your current API-validated settings

⚡ Real-Time Charging Data

• Next Charge Time - When your next slot starts
• Total Planned Energy - Total kWh across all upcoming slots
• Individual Slot Times - Up to 3 slots with start/end times
• Charging Window - Overall window from first to last slot
• Charge Source - Smart-charge vs bump-charge indicator

🔧 Advanced Features

• Manual Refresh Button - Force API refresh from Home Assistant (30s cooldown)
• Next Poll Timer - See when the next automatic refresh will occur
• API Usage Tracking - Monitor requests and complexity in diagnostics
• Raw Timestamps - Exact API responses in Diagnostics section
• Exponential Backoff - Smart retry prevents sensor unavailability
• Comprehensive Debugging - Full API call tracking in msg.debug
• Active Slot Detection - Shows currently running sessions
• Entity Categories - Organized Controls, Sensors, and Diagnostics

🏠 Home Assistant Integration

• Zero Configuration - MQTT auto-discovery sets everything up
• Clean Organization - Controls, sensors, and diagnostics neatly grouped
• Professional Layout - Organized entity categories in device card
• Suggested Area - Auto-suggests "Energy" area

⚡ Smart Charging Control

• Smart Charging Toggle — suspend or resume Octopus intelligent charging from Node-RED or Home Assistant
• HA MQTT Switch — "Smart Charging" switch entity auto-discovered in Home Assistant
• smart_charging field — live state in every payload (true = active, false = suspended, null = unknown)

🌍 Timezone Support

• Locale Timestamps (*_locale fields) — always in server auto-detected timezone
• Resolved Display Fields — slot and window times in your configured timezone
• HA Timezone Select — change timezone from Home Assistant without redeploying
• Node Config Override — set IANA timezone directly in the node editor
• Zero Dependencies — native Intl API, no new packages

---

📸 Screenshots

Node-RED Flow Examples

Basic Monitoring & Control

This example flow demonstrates three key usage patterns:

1. Basic Monitoring

   • The Octopus Intelligent Node automaticaly refreshes every 5 minutes
   • Octopus Intelligent node fetches latest charging data
   • Debug node displays all charging slots and settings

2. Setting Preferences

   • Inject node with JSON payload: {"set_limit": 85, "set_time": "07:30"} ommit a key:value if you don't want to change it
   • Sends charge limit +/ ready time to the node
   • Debug shows confirmed values from API

How to use: Import any of these flows, configure your Account Number and API Key in the Octopus Intelligent node, and deploy!

MQTT Integration with Home Assistant

This flow shows the complete MQTT setup:

• MQTT Broker Configuration: Connected to Home Assistant (localhost:1883)
• Enable MQTT toggle: Activated in node settings
• Auto-Discovery: Node automatically creates all entities in Home Assistant on first run
• Real-time Updates: Every 5 minutes, charging data is published to MQTT and updates HA sensors

What you get in Home Assistant: All controls and sensors appear automatically - no manual YAML configuration needed!

Home Assistant Auto-Configured Entities

After enabling MQTT in the Node-RED node, Home Assistant automatically creates:

Home Assistant Controls Configuration

The Controls section of the device card includes the Timezone select and the new Smart Charging toggle, letting you suspend or resume intelligent charging directly from Home Assistant.

Controls (Top Section)

• Target Charge - Number slider (50-100%) to set desired battery level
• Ready Time - Dropdown selector (04:00-11:00) for when car needs to be ready
• Apply Changes - Button to submit new settings (prevents API spam while adjusting)
• Refresh API - Button to force manual refresh (30-second cooldown prevents spam)
• Timezone — Select entity for choosing display timezone (15 IANA options, persists across restarts)
• Smart Charging — Switch to suspend or resume Octopus intelligent charging

Sensors (Main Section)

• Confirmed Charge Limit - Current API-validated charge limit
• Confirmed Ready Time - Current API-validated ready time
• Next Charge Time - When your next charging slot starts (formatted for your timezone)
• Next Poll Time - When the next automatic refresh will occur
• Total Planned Energy - Total kWh across all upcoming slots
• Slot 1, 2, 3 Start/End - Individual charging slot times
• Overall Window Start/End - First slot start to last slot end
• Slot 1, 2, 3 Start/End (Locale) — Same slots in server auto-detected timezone
• Overall Window Start/End (Locale) — Window times in server auto-detected timezone
• Next Charge Time (Locale) — Next charge start in server auto-detected timezone
• Charging Now - Binary sensor (ON/OFF) showing if actively charging

Diagnostics (Raw timestamps and monitoring)

• Refresh Available At - Countdown timestamp showing when manual refresh becomes available
• API Requests (Last Hour) - Number of API calls in the last 60 minutes
• API Complexity (Last Hour) - Total complexity used (max 50,000/hour)
• API Complexity Usage - Percentage of hourly API limit used
• Timezone Detected — Server's auto-detected timezone (e.g. Europe/London)
• Timezone Applied — Active timezone used for display fields
• Raw timestamp sensors - Exact API responses for all sensors
• Useful for debugging, advanced automations, and monitoring API usage

All entities are automatically organized under a single "Octopus Intelligent" device!

---

📋 Requirements

• Node-RED v2.0+
• Octopus Energy Account with Intelligent Octopus Go tariff
• API Key - Generate here
• MQTT Broker (optional, for Home Assistant integration)
• Home Assistant (optional, for MQTT features)

---

🚀 Quick Start

1. Install via Node-RED Palette

1. Open Node-RED → Menu → Manage Palette
2. Install tab → Search node-red-contrib-octopus-intelligent
3. Click Install

2. Get Your Credentials

Account Number (format: A-XXXXXXXX):

• Found at https://octopus.energy/dashboard/

API Key (format: sk_live_...):

• Get from https://octopus.energy/dashboard/new/accounts/personal-details/api-access
• Click "Generate API Key"

3. Configure the Node

1. Drag Octopus Intelligent into your flow
2. Double-click to configure:
   • Account Number
   • API Key (stored securely)
   • Refresh Interval (default: 5 min)
   • Enable MQTT if using Home Assistant
3. Deploy

4. Home Assistant (Optional)

If MQTT enabled:

1. Wait ~5 seconds after deploy
2. Settings → Devices & Services → MQTT
3. Find "Octopus Intelligent" device
4. All entities created automatically!

---

📊 Home Assistant Entities

Controls

number.octopus_target_charge       Battery charge limit (50-100%)
select.octopus_ready_time          Ready by time (04:00-11:00)
button.octopus_apply_changes       Submit changes to API
button.octopus_refresh_api         Manual refresh (30s cooldown)
select.octopus_timezone            Display timezone (15 IANA options)
switch.octopus_smart_charging      Enable/disable smart charging

Main Sensors

sensor.octopus_confirmed_charge_limit     API-confirmed charge limit
sensor.octopus_confirmed_ready_time       API-confirmed ready time
sensor.octopus_next_charge_time          Next charging slot start
sensor.octopus_next_poll_time            Next automatic refresh time
sensor.octopus_total_planned_energy      Total kWh planned
sensor.octopus_next_slot_energy          Energy in next slot
sensor.octopus_charge_source             smart-charge/bump-charge
sensor.octopus_slot_[1-3]_start          Individual slot starts
sensor.octopus_slot_[1-3]_end            Individual slot ends
sensor.octopus_overall_window_start      First slot start
sensor.octopus_overall_window_end        Last slot end
sensor.octopus_next_charge_locale        Next charge start (server TZ)
sensor.octopus_slot_[1-3]_start_locale  Individual slot starts (server TZ)
sensor.octopus_slot_[1-3]_end_locale    Individual slot ends (server TZ)
sensor.octopus_overall_window_start_locale  Window start (server TZ)
sensor.octopus_overall_window_end_locale    Window end (server TZ)

Diagnostics (Raw Timestamps & Monitoring)

# Refresh & Polling
sensor.octopus_refresh_available_at      When manual refresh becomes available
sensor.octopus_next_poll_time_raw        Raw next poll timestamp

# API Usage Tracking
sensor.octopus_api_requests_hour         API calls in last 60 minutes
sensor.octopus_api_complexity_hour       Total complexity used
sensor.octopus_api_complexity_usage      Percentage of 50,000/hour limit

# Raw Timestamps
sensor.octopus_next_charge_time_raw      Exact API timestamp
sensor.octopus_slot_[1-3]_start_raw      Raw slot start times
sensor.octopus_slot_[1-3]_end_raw        Raw slot end times
sensor.octopus_overall_window_start_raw  Raw window start
sensor.octopus_overall_window_end_raw    Raw window end

# Timezone Diagnostics
sensor.octopus_timezone_detected     Server auto-detected timezone
sensor.octopus_timezone_applied      Active timezone used for display fields

---

🌍 Timezone Configuration

By default, slot and window times are converted to the server's auto-detected timezone (wherever Node-RED is running). Three ways to configure:

Option 1: Node Config (static)

Set a fixed IANA timezone in the node editor:

• Open node → Timezone field → type Australia/Sydney
• Applies to all display fields (slot1_start, window_start, etc.)
• Leave blank to use server auto-detect

Option 2: Home Assistant Select (dynamic, persists across restarts)

Use the Timezone select entity in Home Assistant:

• Home Assistant → Octopus Intelligent device → Timezone
• Change takes effect on next poll
• Persists across Node-RED restarts

Option 3: set_timezone Input Command

msg.payload = { set_timezone: "Europe/London" };
// Send to Octopus Intelligent node input

Saved to node context, applies on next poll.

Timestamp Tiers

Field suffix	Timezone	Configurable?
*_raw	Always UTC (exact API string)	Never
*_locale	Server auto-detected	Never (always server TZ)
Display fields (slot1_start, window_start, etc.)	Resolved TZ	Yes — via HA, config, or command

Supported Timezones (HA select)

Europe/London, Europe/Berlin, Europe/Madrid, Australia/Sydney, Australia/Melbourne, Australia/Brisbane, Australia/Perth, Australia/Adelaide, Pacific/Auckland, America/New_York, America/Chicago, America/Denver, America/Los_Angeles, Asia/Tokyo, UTC

Any valid IANA timezone works in the node config field or set_timezone command.

---

💡 Node-RED Usage

Basic Monitoring

[Inject: Every 5 min] → [Octopus Intelligent] → [Debug]

Set Preferences from Flow

msg.payload = {
    set_limit: 85,        // 85% charge
    set_time: "07:30"     // Ready by 07:30
};
return msg;

Set Timezone from Flow

msg.payload = { set_timezone: "Australia/Sydney" };
return msg;

Toggle Smart Charging from Flow

Send a boolean to enable or disable Octopus intelligent charging:

msg.payload = { set_smart_charging: true };   // enable (unsuspend)
msg.payload = { set_smart_charging: false };  // disable (suspend)
return msg;

Wire an Inject node with a JSON payload, or build this in a function node and connect it to the Octopus Intelligent node's input. Non-boolean values are silently ignored.

Example: suspend charging when home battery is in use

[Inject: suspend] → [Function: set_smart_charging=false] → [Octopus Intelligent]
[Inject: resume]  → [Function: set_smart_charging=true]  → [Octopus Intelligent]

The node fetches your device ID at startup — if it hasn't been fetched yet (first few seconds after deploy), the command will log a warning and be ignored. The current smart charging state is always available in msg.payload.smart_charging (true = active, false = suspended, null = startup pending).

Output Format

{
  "payload": {
    "next_start": "2025-11-29 01:30:00+00:00",
    "total_energy": 42.5,
    "next_kwh": "15.20",
    "next_source": "smart-charge",
    "confirmed_limit": 80,
    "confirmed_time": "07:00",
    "pending_limit": 80,
    "pending_time": "07:00",
    "charging_now": false,
    "next_poll": "2025-11-29T10:35:00Z",
    "refresh_available_at": null,
    "api_requests_hour": 12,
    "api_complexity_hour": 3600,
    "api_complexity_percent": 7.2,
    "slot1_start": "2025-11-29 01:30:00+00:00",
    "slot1_end": "2025-11-29 05:30:00+00:00",
    "timezone_detected": "Europe/London",
    "timezone_applied": "Europe/London",
    "smart_charging": true,
    "next_start_locale": "2025-11-29 01:30:00+00:00",
    "slot1_start_locale": "2025-11-29 01:30:00+00:00",
    "slot1_end_locale": "2025-11-29 05:30:00+00:00",
    "window_start_locale": "2025-11-29 01:30:00+00:00",
    "window_end_locale": "2025-11-29 05:30:00+00:00"
  },
  "debug": {
    "success": true,
    "step": "complete",
    "apiCalls": [
      {
        "name": "data_query",
        "responseHeaders": {...},
        "extensions": null
      }
    ],
    "api_usage": {
      "requests_last_hour": 12,
      "complexity_last_hour": 3600,
      "complexity_percent_used": "7.2",
      "api_limit_hourly": 50000,
      "request_complexity": 300,
      "complexity_source": "estimated"
    }
  }
}

---

🏡 Home Assistant Automation Examples

Notify When Charging Starts

automation:
  - alias: "EV Charging Starting"
    trigger:
      platform: state
      entity_id: sensor.octopus_next_charge_time
    condition:
      condition: template
      value_template: "{{ trigger.to_state.state != 'None' }}"
    action:
      service: notify.mobile_app
      data:
        message: "EV charging at {{ states('sensor.octopus_next_charge_time') }}"

Run Dishwasher During Cheap Rate

automation:
  - alias: "Dishwasher During Cheap Window"
    trigger:
      platform: time_pattern
      minutes: "/5"
    condition:
      - condition: template
        value_template: >
          {% set start = as_timestamp(states('sensor.octopus_slot1_start')) %}
          {% set end = as_timestamp(states('sensor.octopus_slot1_end')) %}
          {% set now = as_timestamp(now()) %}
          {{ start <= now <= end }}
    action:
      service: switch.turn_on
      target:
        entity_id: switch.dishwasher

---

🔍 Troubleshooting

No Data (All Sensors Null/0)

Check msg.debug output in a Debug node:

Common issues:

• ❌ Account format must include A- prefix
• ❌ Invalid API key - regenerate at Octopus dashboard
• ❌ Not on Intelligent Octopus tariff
• ❌ Car not plugged in (no slots scheduled)

Authentication Failing

Check msg.debug.apiCalls[0].errors for details.

Solution: Regenerate API key and update node configuration.

Sensors Unavailable in Home Assistant

1. Verify MQTT broker is running
2. Check Node-RED can connect to MQTT
3. Deploy the flow to trigger discovery
4. Confirm Home Assistant MQTT integration is enabled

Raw Sensors Not in Diagnostics

If entities existed before v1.0:

1. Delete "Octopus Intelligent" device in Home Assistant
2. Redeploy Node-RED flow
3. Entities will be rediscovered with proper categories

Changes Not Applying

Working as designed! Use the Apply Changes button to submit.

This prevents API spam when making multiple adjustments.

---

🛠️ How It Works

Authentication Flow

1. Get Token - Exchange API key for token
2. Fetch Data - Query planned dispatches & preferences
3. Process - Filter active/future slots, calculate totals
4. Publish - Send to Node-RED + MQTT

Exponential Backoff

When changing preferences:

Mutation sent → Wait 15s → Validate
             ↓ If not confirmed
             → Wait 30s → Validate
             ↓ If not confirmed
             → Wait 60s → Validate
             ↓ If not confirmed
             → Wait 120s → Final check
             ↓ Then normal interval resumes

This prevents sensors becoming "unavailable" during updates.

Debug Information

Every message includes msg.debug:

{
  "timestamp": "2025-11-29T10:30:00Z",
  "success": true,
  "step": "complete",
  "apiCalls": [
    {"name": "authentication", "tokenObtained": true},
    {"name": "data_query", "slotsFound": 3}
  ]
}

---

📝 License

MIT License - Copyright (c) 2025 Andrew Somerharju Neale

See LICENSE file for full details.

---

⚠️ Disclaimer

This is an unofficial integration and is not affiliated with, endorsed by, or connected to Octopus Energy Ltd.

Use at your own risk. The Octopus Energy name and logo are trademarks of Octopus Energy Ltd.

---

🔗 Links

• npm: https://www.npmjs.com/package/node-red-contrib-octopus-intelligent
• GitHub: https://github.com/ASomerN/node-red-contrib-octopus-intelligent
• Issues: https://github.com/ASomerN/node-red-contrib-octopus-intelligent/issues
• Octopus Intelligent: https://octopus.energy/intelligent/
• API Docs: https://developer.octopus.energy/docs/api/

---

📜 Changelog

See CHANGELOG.md for detailed version history and release notes.

Latest Release: v1.2.0 (2026-04-26)

• Smart Charging Toggle — suspend/resume Octopus intelligent charging from Node-RED or Home Assistant
• HA MQTT Switch — auto-discovered Smart Charging switch entity
• smart_charging payload field — live state in every message

Previous Release: v1.0.5 (2025-12-31)

• Documentation Fix - Corrected misleading "branded device cards" claim in README

Previous Release: v1.0.4 (2025-12-11)

• Manual Refresh Button - Force API refresh via Home Assistant with 30s cooldown
• Next Poll Timer - See when next automatic refresh occurs
• API Complexity Monitoring - Track API usage against 50,000/hour limit
• Enhanced State Output - Every poll outputs full state to Node-RED
• Rate Limiting - MQTT button (30s cooldown), Node-RED input (no limit)
• Improved Debugging - Response headers and extensions captured

Previous Release: v1.0.3 (2025-12-04)

• State reconciliation loop for charging detection
• Fixed Home Assistant sensors going "unknown"
• Flow Library scorecard compliance

---

Made with ⚡ for the Octopus Energy & Home Assistant communities