A custom Home Assistant integration for monitoring propane tanks via the mySuperior customer portals. Supports both Superior Plus Propane (United States) and Superior Propane (Canada) with automatic consumption tracking for the Energy Dashboard.
| Region | Provider | Portal | Units |
|---|---|---|---|
| United States | Superior Plus Propane | mysuperioraccountlogin.com | Gallons, ft³ |
| Canada | Superior Propane | mysuperior.superiorpropane.com | Litres, m³ |
Both providers operate under the Superior Plus LP umbrella. Each has its own customer portal with separate login credentials.
- US and Canadian Support: Works with both Superior Plus Propane (US) and Superior Propane (CA) accounts
- Multi-Tank Support: Automatically discovers and monitors all tanks on your account
- Energy Dashboard Integration: Consumption tracking with
state_class: total_increasingfor Home Assistant's Energy Dashboard - Consumption Tracking: Monitors usage between readings, detects refills, flags anomalies
- Configurable Thresholds: Dynamic consumption thresholds that adapt to tank size and polling interval, or set your own
- Persistent Totals: Consumption data survives Home Assistant restarts
- HACS Compatible: Install and update through HACS
For each propane tank on your account, the integration creates the following sensors:
| Sensor | US Unit | CA Unit | Description |
|---|---|---|---|
| Tank Level | % | % | Current fill percentage |
| Current Volume | gal | L | Volume currently in tank |
| Tank Capacity | gal | L | Total tank size |
| Sensor | Description |
|---|---|
| Reading Date | When the level was last measured |
| Last Delivery | Date of most recent propane delivery |
| Days Since Delivery | Calculated days since last fill |
| Price per Unit | Current pricing in USD/ft³ (US only) |
| Average Price | Average price paid from order history (CAD/L for CA, USD/ft³ for US) |
| Sensor | US Unit | CA Unit | State Class | Description |
|---|---|---|---|---|
| Total Consumption | ft³ | L | total_increasing |
Cumulative gas usage |
| Consumption Rate | ft³/h | L/h | measurement |
Current usage rate |
| Sensor | Description |
|---|---|
| Data Quality | Validation status: Good, Invalid Tank Size, Invalid Level, Inconsistent Values, or Calculation Error |
- Open HACS in Home Assistant
- Go to "Integrations"
- Click the three dots menu, then "Custom repositories"
- Add this repository URL:
https://github.com/connorgallopo/Superior-Plus-Propane - Category: "Integration"
- Click "Add"
- Search for "Superior Plus Propane" in HACS and click "Download"
- Restart Home Assistant
- Go to Settings > Devices & Services > Add Integration
- Search for "Superior Plus Propane"
If you already have the custom repository added (e.g., from a previous install), skip steps 3-6 and search HACS directly.
- Download the latest release from GitHub Releases
- Copy the
custom_components/superior_plus_propanefolder to your Home Assistantcustom_componentsdirectory - Restart Home Assistant
- Add the integration through Settings, then Devices & Services, then Add Integration
- An active account with one of:
- Email address and password for your portal account
- Add Integration: Settings, then Devices & Services, then Add Integration
- Search: Look for "Superior Plus Propane"
- Select Region: Choose United States or Canada
- Enter Credentials: Your mySuperior portal email and password
- Configure Options: Update interval, threshold settings, unmonitored tank visibility
- Done: The integration discovers all tanks on your account
| Option | Default | Description |
|---|---|---|
| Update Interval | 3600s (US) / 7200s (CA) | How often to poll for new data (300-86400 seconds) |
| Include Unmonitored Tanks | Off | Show tanks not on a delivery plan |
| Dynamic Consumption Thresholds | On | Automatically adjust thresholds based on tank size. Recommended for most users. |
| Min Consumption Threshold | 0.01 | Per-reading minimum (only used when dynamic thresholds are off) |
| Max Consumption Threshold | 25.0 | Per-reading maximum (only used when dynamic thresholds are off) |
All options can be changed after setup through the integration's "Configure" button in Settings, then Devices & Services.
US entities use the full integration domain and tank address:
sensor.superior_plus_propane_123_main_street_level
sensor.superior_plus_propane_123_main_street_current_volume
sensor.superior_plus_propane_123_main_street_capacity
sensor.superior_plus_propane_123_main_street_reading_date
sensor.superior_plus_propane_123_main_street_last_delivery
sensor.superior_plus_propane_123_main_street_price_per_unit
sensor.superior_plus_propane_123_main_street_days_since_delivery
sensor.superior_plus_propane_123_main_street_total_consumption
sensor.superior_plus_propane_123_main_street_consumption_rate
sensor.superior_plus_propane_123_main_street_data_quality
sensor.superior_plus_propane_123_main_street_average_price
CA entities use Home Assistant's has_entity_name convention. Entity IDs are derived from the tank name shown in the mySuperior portal (e.g., "Tank Number 1"):
sensor.tank_number_1_level
sensor.tank_number_1_current_volume
sensor.tank_number_1_capacity
sensor.tank_number_1_reading_date
sensor.tank_number_1_last_delivery
sensor.tank_number_1_days_since_delivery
sensor.tank_number_1_total_consumption
sensor.tank_number_1_consumption_rate
sensor.tank_number_1_data_quality
sensor.tank_number_1_average_price
Your actual entity IDs depend on how your tanks are named in the CA portal. Check Settings > Devices & Services to see your exact entity IDs.
The integration creates consumption sensors compatible with Home Assistant's Energy Dashboard:
- Go to Settings, then Dashboards, then Energy
- Add a Gas source
- Select your tank's "Total Consumption" sensor
- View your propane usage alongside other energy sources
How consumption tracking works:
- Compares volume readings between polls to calculate usage
- Converts to the appropriate energy unit (ft³ for US, litres for CA)
- Detects refills (volume increase) and excludes them from totals
- Validates consumption against configurable thresholds
- Persists totals to Home Assistant storage so they survive restarts
Each propane tank appears as a separate device in Home Assistant:
| Field | US | CA |
|---|---|---|
| Device Name | Propane Tank - [Address] | [Tank name from portal] (e.g., "Tank Number 1") |
| Manufacturer | Superior Plus Propane | Superior Propane |
| Model | e.g. "500 Gallon Tank" | e.g. "1000 Litre Tank" |
All sensors for a tank are grouped under its device.
Replace the entity IDs below with your actual entity IDs. You can find them in Settings > Devices & Services, or create automations through the visual editor in Settings > Automations which will fill in the entity IDs for you.
automation:
- alias: "Propane Tank Low"
trigger:
- platform: numeric_state
entity_id: sensor.superior_plus_propane_123_main_street_level
below: 20
action:
- service: notify.mobile_app
data:
message: "Propane tank is at {{ states('sensor.superior_plus_propane_123_main_street_level') }}%"automation:
- alias: "Propane Tank Low"
trigger:
- platform: numeric_state
entity_id: sensor.tank_number_1_level
below: 20
action:
- service: notify.mobile_app
data:
message: "Propane tank is at {{ states('sensor.tank_number_1_level') }}%"automation:
- alias: "Propane Delivery Overdue"
trigger:
- platform: numeric_state
entity_id: sensor.superior_plus_propane_123_main_street_days_since_delivery
# For CA, use: sensor.tank_number_1_days_since_delivery
above: 365
action:
- service: persistent_notification.create
data:
message: "It's been over a year since your last propane delivery."- US customers: Verify your credentials at mysuperioraccountlogin.com
- CA customers: Verify your credentials at mysuperior.superiorpropane.com
- Make sure you selected the correct region during setup
- Check for account restrictions or two-factor authentication
- Confirm your tanks appear when you log into the mySuperior portal directly
- Verify you have active propane service
- Check that tank monitoring is enabled on your account
- Check Home Assistant logs: Settings, then System, then Logs
- If the integration loaded without errors but shows no sensors, try removing and re-adding it
- CA accounts may need a longer update interval (the default 7200s is recommended)
- Check your internet connection
- Verify the mySuperior portal is accessible in your browser
- The integration backs off automatically on connection errors and retries at a shorter interval
- If the portal is under maintenance, the integration returns cached data for up to 4 hours
- Fully async — runs on Home Assistant's event loop with
aiohttpfor HTTP - Region-specific API clients handle authentication and HTML parsing for each portal
- A shared
DataUpdateCoordinatormanages polling, consumption calculation, and threshold validation - Persistent storage via Home Assistant's
Storefor consumption totals across restarts
- Credentials are stored using Home Assistant's config entry storage
- No data is sent to third parties
- All communication goes directly to the respective mySuperior portal servers
Contributions are welcome.
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Make your changes
- Run linting:
scripts/lint - Commit and push
- Open a Pull Request
git clone https://github.com/connorgallopo/Superior-Plus-Propane.git
cd Superior-Plus-Propane
pip install -r requirements.txt
scripts/lint- Issues: GitHub Issues
- Discussions: GitHub Discussions
- US Account Issues: Contact Superior Plus Propane
- CA Account Issues: Contact Superior Propane
This project is licensed under the MIT License - see the LICENSE file for details.
This integration is not affiliated with, endorsed by, or officially supported by Superior Plus Propane or Superior Propane. It is an independent project that interfaces with customer portal data. Use at your own risk.
Superior Plus Propane, Superior Propane, and mySuperior are trademarks of Superior Plus LP.
propane, propane tank, propane monitoring, Superior Plus, Superior Plus Propane, Superior Propane, mySuperior, tank level, propane delivery, energy dashboard, home assistant, propane automation, tank monitoring, fuel monitoring, propane sensor, Canada propane, US propane