Installation

Install the Exaviz PoE plugin for Home Assistant via HACS.

4 minute read

Prerequisites

Before installing the plugin, ensure you have the following:

Hardware

An Exaviz board with PoE support:
- Cruiser Carrier Board with built-in PoE ports, or
- Interceptor Carrier Board with one or two Interceptor PoE Boards
PoE hardware is powered and operational — verify with head -20 /dev/pse (Cruiser) or head -20 /proc/pse (Interceptor)

Software

Debian-based Linux (Raspberry Pi OS, Debian Trixie, Debian Bookworm, etc.)
Exaviz PoE packages installed from the Exaviz APT repository. Follow the instructions on that page to add the repository signing key and source, then install:
- All boards: exaviz-dkms and exaviz-netplan
- Interceptor boards additionally: exaviz-pse-dkms (IP808AR PoE driver — required for /proc/pse and PoE port control)
Verify with:
```
dpkg -l | grep exaviz
```
You should see exaviz-dkms and exaviz-netplan listed (plus exaviz-pse-dkms on Interceptor boards).

Home Assistant

Home Assistant 2024.12 or newer recommended, running on the same board as your PoE hardware. Older versions back to 2024.4 are supported but require manual Lovelace resource registration (see Troubleshooting).
HACS (Home Assistant Community Store) installed

Recommended: Docker Container Installation

We recommend running Home Assistant as a Docker Container on your Exaviz board. This provides the best compatibility and update path.

The container needs access to PoE hardware on the host. Use the docker-compose.yml for your board type below – copy the one that matches your board exactly:

Cruiser:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    network_mode: host
    privileged: true
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
      # Exaviz board detection and monitoring
      - /proc/device-tree:/proc/device-tree:ro                   # Board detection (Tier 1)
      - /boot/firmware/config.txt:/boot/firmware/config.txt:ro   # Board detection (Tier 2)
      - /sys/class/thermal:/sys/class/thermal:ro                 # SoC temperature
    devices:
      - /dev/pse:/dev/pse   # ESP32 serial for PoE control

Interceptor:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    network_mode: host
    privileged: true
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
      # Exaviz PoE hardware access
      - /proc/pse:/proc/pse                                      # PoE port control (read/write)
      # Exaviz board detection and monitoring
      - /proc/device-tree:/proc/device-tree:ro                   # Board detection (Tier 1)
      - /boot/firmware/config.txt:/boot/firmware/config.txt:ro   # Board detection (Tier 2)
      - /sys/class/thermal:/sys/class/thermal:ro                 # SoC temperature

Why these mounts matter

All mounts are required. Without them, the integration cannot detect your board type, read PoE port status, or monitor temperature. A minimal docker-compose.yml (e.g., only ./config:/config) will cause the integration to fail silently at startup.

Docker and /dev/pse: On Cruiser boards, /dev/pse is a udev symlink pointing to /dev/ttyAMA3. Docker’s device passthrough resolves symlinks, so the device appears as /dev/ttyAMA3 inside the container – not as /dev/pse. The plugin handles this automatically (it checks both paths).

Step 1: Install HACS (if not already installed)

If you don’t have HACS installed, follow the official guide at hacs.xyz.

After installation, restart Home Assistant and verify HACS appears in the sidebar.

Step 2: Install via HACS

Open Home Assistant and navigate to HACS in the sidebar
Search for Exaviz
Click on Exaviz PoE Plugin
Click Download and select the latest version (currently v1.0.5)
Restart Home Assistant when prompted

After restart, the integration backend and the custom Lovelace card will both be available.

Beta / Pre-release Versions

We publish beta and release candidate versions (e.g., v1.1.0-beta.1, v1.1.0-rc.1) for early testing. These are hidden in HACS by default. To install a beta:

Open HACS and find Exaviz PoE Plugin
Click the three-dot menu on the integration and enable Show beta versions
Select the beta version from the version dropdown and click Download

Beta versions are not recommended for production use. Switch back to the latest stable release at any time by disabling beta versions and updating.

Step 4: Verify Installation

After restarting Home Assistant:

Go to Settings > Devices & Services
Click Add Integration
Search for Exaviz – it should appear in the list

If you see “Exaviz PoE” in the integration list, the installation was successful. Proceed to Configuration to set up the integration.

Updating the Plugin

When a new version is available:

Open HACS in the sidebar
Navigate to Integrations
If an update is available, you’ll see a notification badge
Click on Exaviz PoE Plugin and click Update
Restart Home Assistant after updating

Uninstalling

To remove the plugin:

First, remove the integration from Settings > Devices & Services
Then, uninstall via HACS: HACS > Integrations > Exaviz PoE Plugin > Remove
Restart Home Assistant

Next Steps

Configuration – Set up the integration and explore entities
Dashboard – Add PoE monitoring cards to your dashboard

Last modified February 25, 2026