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.
Found this useful? Support continued development:
|
Star the repository to show your support! |
Support ongoing development and maintenance |
If this project has helped you! |
Your support helps with: Bug fixes and maintenance • New feature development • Documentation improvements • Community support • Feeding my children
- 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
- 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
- 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
- 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
This example flow demonstrates three key usage patterns:
-
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
-
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
- Inject node with JSON payload:
How to use: Import any of these flows, configure your Account Number and API Key in the Octopus Intelligent node, and deploy!
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!
After enabling MQTT in the Node-RED node, Home Assistant automatically creates:
- 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)
- 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
- Charging Now - Binary sensor (ON/OFF) showing if actively charging
- 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
- 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!
- 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)
- Open Node-RED → Menu → Manage Palette
- Install tab → Search
node-red-contrib-octopus-intelligent - Click Install
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"
- Drag Octopus Intelligent into your flow
- Double-click to configure:
- Account Number
- API Key (stored securely)
- Refresh Interval (default: 5 min)
- Enable MQTT if using Home Assistant
- Deploy
If MQTT enabled:
- Wait ~5 seconds after deploy
- Settings → Devices & Services → MQTT
- Find "Octopus Intelligent" device
- All entities created automatically!
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)
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
# 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
[Inject: Every 5 min] → [Octopus Intelligent] → [Debug]
msg.payload = {
set_limit: 85, // 85% charge
set_time: "07:30" // Ready by 07:30
};
return msg;{
"payload": {
"next_start": "2025-11-29T01:30:00Z",
"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-29T01:30:00Z",
"slot1_end": "2025-11-29T05:30:00Z"
},
"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"
}
}
}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') }}"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.dishwasherCheck 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)
Check msg.debug.apiCalls[0].errors for details.
Solution: Regenerate API key and update node configuration.
- Verify MQTT broker is running
- Check Node-RED can connect to MQTT
- Deploy the flow to trigger discovery
- Confirm Home Assistant MQTT integration is enabled
If entities existed before v1.0:
- Delete "Octopus Intelligent" device in Home Assistant
- Redeploy Node-RED flow
- Entities will be rediscovered with proper categories
Working as designed! Use the Apply Changes button to submit.
This prevents API spam when making multiple adjustments.
- Get Token - Exchange API key for token
- Fetch Data - Query planned dispatches & preferences
- Process - Filter active/future slots, calculate totals
- Publish - Send to Node-RED + MQTT
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.
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}
]
}MIT License - Copyright (c) 2025 Andrew Somerharju Neale
See LICENSE file for full details.
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.
- 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/
See CHANGELOG.md for detailed version history and release notes.
- Documentation Fix - Corrected misleading "branded device cards" claim in README
- 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
- 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