Homebridge Gremlin Tank

A Homebridge plugin that brings your Gremlin (Angus Energy) heating-oil or propane tank monitor into HomeKit. It polls the Brite2 cloud that the Gremlin mobile app uses, and exposes each tank as an accessory so you can glance at the level and get a native low-oil notification from the Home app.

Compatibility: Works with any Gremlin monitor, whatever fuel company installed it — Gremlin/Brite2 is Angus Energy's own platform, shared across all its dealers, so any account that signs into the Gremlin app works here. It does not work with other brands' monitors (Tank Utility, Kingspan/SENSiT, Smart Oil Gauge), which run on separate clouds.

⚠️ Disclaimer

This plugin is not affiliated with, endorsed by, or associated with Angus Energy, Angus Monitoring Service, or GREMLIN in any way. It is an independent, unofficial plugin developed by the community for personal use. GREMLIN is a trademark of Angus Monitoring Service, LLC.

Use at your own risk. The author assumes no liability for any damage, data loss, or issues that may arise from using this plugin. The Gremlin / Brite2 API is undocumented and was observed from the mobile app's own network traffic; it may change or stop working at any time. By using this plugin, you acknowledge that you do so entirely at your own discretion and risk.

Features

• Each tank as a HomeKit accessory — level shown as a percentage tile, updated automatically
• Native low-oil notification — a Battery service reports "low battery" at your chosen threshold, so the Home app notifies you when the tank runs low
• Gentle polling — the monitor only updates about once a day, so the plugin polls every 6 hours by default (configurable, minimum 1 hour)
• Multi-tank support — every tank on your account is discovered automatically
• Sturdy by design — re-authenticates each poll, keeps the last-good reading on any error, and never crashes Homebridge on a cloud hiccup
• No runtime dependencies — uses the Node 18+ built-in fetch

Installation

Prerequisites

• Node.js (v18.0.0 or higher)
• Homebridge (v1.6.0 or higher, including v2.x)
• A Gremlin tank monitor and the Brite2 account (username/password) you use in the Gremlin app

Install from NPM

npm install -g homebridge-gremlin-tank

Install from Source

git clone https://github.com/burtherman/homebridge-gremlin-tank.git
cd homebridge-gremlin-tank
npm install
npm run build
npm link

Configuration

Add the following to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "GremlinTank",
      "name": "Gremlin",
      "username": "your-brite2-username",
      "password": "your-brite2-password"
    }
  ]
}

Or configure it through the Homebridge UI — the plugin ships a config.schema.json with a "Gremlin Credentials" section and an expandable "Advanced" section.

Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | platform | string | Yes | Must be GremlinTank | | name | string | No | Platform name (default: "Gremlin") | | username | string | Yes | Your Gremlin / Brite2 username | | password | string | Yes | Your Gremlin / Brite2 password | | pollInterval | number | No | Seconds between cloud polls (default: 21600 = 6h, minimum: 3600 = 1h). The monitor updates ~once/day, so 6h is plenty. | | lowThreshold | number | No | Low-oil alert threshold, % full (default: 20, min: 5, max: 90). At or below this level the tank reports low battery, firing the Home app's notification. | | debug | boolean | No | Log each poll's tank readings at info level (default: false) |

How It Works

1. Sign in — each poll, the plugin signs in to the Brite2 cloud with your username/password and gets a short-lived access token. (Re-logging in every poll is simpler and sturdier than caching a token; at a 6-hour cadence there's no cost to it.)
2. List tanks — it fetches your account and its tanks (key, name, serial, capacity).
3. Read levels — for each tank it requests the last ~35 days of daily level readings and takes the newest one.
4. Update HomeKit — the newest reading's percent-full is pushed onto the tank's accessory. Any error along the way is logged as a warning and the last-good values are kept.

Supported Characteristics

HomeKit has no native "tank level" characteristic, so each tank's percent-full is mapped onto two standard services the Home app already renders and notifies on:

• Humidity Sensor → Current Relative Humidity = percent full (0–100). This gives a clean percentage tile you can glance at and chart over time. (It is not really humidity — it is the tank level; HomeKit simply has no better home for a 0–100 gauge.)
• Battery → Battery Level = percent full, with Status Low Battery flipping to "low" at or below your lowThreshold. This is the piece that gives you a native low-oil push notification from the Home app. Charging State is reported as "not chargeable".
• Accessory Information — Manufacturer Angus Energy (GREMLIN), Model Gremlin Tank Monitor, Serial Number = the tank's monitor serial. Name: the tank's own name when it's descriptive; a bare-number or blank name (Angus labels tanks "1", "2", …) becomes a fuel-type label — "Oil Tank" or "Propane Tank", detected from the tank's safe-fill capacity (100% = oil, ~80% = propane), or "Tank Level" when undetectable. HomeKit remembers the name an accessory was first added with, so rename an existing tile in the Home app if you want to change it.

API Endpoints Used

There is no public or documented Gremlin API. The three endpoints below were observed from the Gremlin iOS app's own network traffic and are used here as-is. They may change or stop working at any time. Base URL: https://api-v1.brite2.com.

| Method | Path | Auth | Purpose | |--------|------|------|---------| | POST | /consumer/signIn | none (body: { username, password }) | Returns an access token | | GET | /consumer/api | x-access-token header | Account + list of tanks | | GET | /consumer/api/tanks/{key}/levels?startDate=MM/DD/YYYY&endDate=MM/DD/YYYY | x-access-token header | Daily level readings (newest first) |

Note the token is sent in an x-access-token header, not Authorization: Bearer.

Troubleshooting

The plugin isn't discovering my tank(s).

• Verify your username/password are exactly what works in the Gremlin app.
• Check the Homebridge log for a "sign-in failed" or "tank list failed" warning.
• Confirm the tank shows up in the Gremlin app itself.

The level looks stale.

• That's expected — the Gremlin monitor typically reports once per day. The plugin can't show data the cloud doesn't have yet. Polling faster won't help.

I'm not getting a low-oil notification.

• Make sure the tank's accessory is added to the Home app and notifications are enabled for it.
• Confirm the level is at or below your lowThreshold. Lower thresholds mean later alerts.

Enable debug to log each poll's readings at info level while diagnosing.

License

MIT. See LICENSE.

Credits

Built by burtherman. Talks to the Brite2 cloud behind the Gremlin tank monitor by Angus Monitoring Service. This project is unofficial and not affiliated with Angus Energy in any way.