homebridge-envirovent

Homebridge plugin for Envirovent Atmos PIV (Positive Input Ventilation) units. Provides local network control via HomeKit — no cloud, no account, no internet required.

Features

• Fan speed control — continuous slider mapped to the unit's 24–100% airflow range
• Boost mode — toggle switch, usable in HomeKit scenes and automations
• Filter status — shows filter life remaining and alerts when replacement is needed
• Local-only — communicates directly with the unit over your LAN (TCP port 1337)
• No polling flood — configurable poll interval with debounced commands

Requirements

• Node.js 24+
• Homebridge 1.8+ or 2.0 beta
• Envirovent Atmos PIV unit connected to your home WiFi

Installation

npm install -g homebridge-envirovent

Or search for homebridge-envirovent in the Homebridge UI plugins tab.

Configuration

Add to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "EnviroventPIV",
      "name": "Envirovent PIV",
      "host": "192.168.1.160",
      "pollInterval": 5,
      "showBoostSwitch": true
    }
  ]
}

| Option | Required | Default | Description | |---|---|---|---| | platform | Yes | — | Must be "EnviroventPIV" | | name | No | "Envirovent PIV" | Display name in HomeKit | | host | Yes | — | IP address of your unit | | port | No | 1337 | TCP port | | pollInterval | No | 5 | Seconds between status polls (min: 5) | | showBoostSwitch | No | true | Expose boost as a separate switch for scenes/automations |

Finding your unit's IP

Your Atmos PIV unit advertises itself via mDNS (_http._tcp). You can find its IP address through:

• Your router's DHCP client list
• The official myenvirovent app (under device info)
• Your UniFi controller's client list

Tip: Assign a static IP / DHCP reservation so the address doesn't change.

HomeKit services

| Service | Description | |---|---| | Fanv2 | Main fan tile with speed slider. 0% = unit minimum (24%), 100% = maximum airflow. | | Switch (Boost) | Toggles boost mode. Auto-turns off when the unit's boost timer expires. Great for scenes like "Cooking Mode". | | FilterMaintenance | Shows filter life percentage and alerts when the filter needs replacing. |

How it works

The Envirovent Atmos PIV runs a TCP server on port 1337 that accepts JSON commands. This plugin communicates directly with the unit — no cloud relay, no Envirovent account needed.

The protocol was reverse-engineered from the official myenvirovent Android app and verified against a real unit running firmware v2.5. Full protocol documentation is in API-FINDINGS.md.

Development

git clone https://github.com/lk9100/homebridge-envirovent.git
cd homebridge-envirovent
nvm use
npm install
npm test          # Run tests
npm run build     # Compile TypeScript
npm run typecheck # Type check without emitting
npm run lint      # Lint with ESLint

Project structure

src/
├── api/          # Standalone API client (zero homebridge deps)
│   ├── client.ts       # High-level EnviroventClient
│   ├── connection.ts   # TCP socket transport
│   ├── commands.ts     # Command builders + response parsers
│   ├── types.ts        # All TypeScript interfaces
│   └── errors.ts       # Typed error hierarchy
├── state/        # State management (zero homebridge deps)
│   ├── unit-state.ts   # Reactive state with polling + optimistic updates
│   └── command-queue.ts # Serialized command execution with retry
└── homebridge/   # Homebridge integration
    ├── platform.ts     # DynamicPlatformPlugin
    ├── accessory.ts    # Accessory orchestrator
    └── services/       # HomeKit service handlers
        ├── fan.ts      # Fanv2 — airflow speed
        ├── boost.ts    # Switch — boost toggle
        └── filter.ts   # FilterMaintenance — filter status

The api/ and state/ layers have no Homebridge dependencies and can be used as a standalone client library.

Testing against a real unit

# Read-only: fetch and display unit settings
npx tsx scripts/test-unit.ts 192.168.1.160

Releasing a new version

This project uses conventional commits (fix:, feat:, refactor:, etc.) which keep the changelog consistent.

Steps

1. Bump version in package.json
2. Update CHANGELOG.md — add a new ## vX.Y.Z section at the top with the changes since the last release
3. Commit — git commit -m "chore: bump version to X.Y.Z"
4. Tag — git tag vX.Y.Z
5. Push — git push && git push --tags
6. Create GitHub Release — gh release create vX.Y.Z --title "vX.Y.Z" --notes "release notes here" (the Homebridge UI reads this for its Release Notes tab)
7. Publish to npm — npm publish

Verifying the npm package

Before publishing, always check what will be included in the tarball:

npm pack --dry-run

The published package should be ~120 KB. If it's significantly larger, something is leaking through .npmignore.

AI agent guidelines

If you are an AI agent working on this project, keep this README up to date as you make changes. This includes updating the project structure tree, test commands, release steps, and any other sections affected by your work. This file is the single source of truth for contributors.

Acknowledgements

Protocol reverse-engineered from the myenvirovent Android app using jadx.

License

MIT