This guide walks you through everything needed to get Pivot running on a Home Assistant Voice Preview Edition (VPE) device. Setup takes around 15–30 minutes depending on your familiarity with Home Assistant and ESPHome.

Want to understand the specifics of what Pivot does before installing? The Architecture page explains exactly what the firmware and integration do, what they read, what they write, and what they don’t do.

Pivot runs alongside your existing voice setup without interfering with it. The ESPHome integration remains unchanged, and any settings already configured on your VPE (such as the voice assistant, wake word, volume, or listening-mode LED colour) are left exactly as they are. Pivot cannot read or modify those settings; it simply adds a separate layer of control on top.

What you need

  • A Home Assistant Voice Preview Edition (VPE)
  • Home Assistant with the ESPHome integration installed
  • The ESPHome Device Builder app (formerly the ESPHome add-on) with version 2026.5.0 or later installed
  • HACS installed in Home Assistant
  • Your WiFi credentials

What you’ll end up with

Once set up, your Voice Preview Edition will:

  • Control up to four entities using the dial
  • Let you switch between them using press + turn
  • Show their current value on the LED ring
  • Continue to respond to voice commands as normal
  • Allow you to switch back to the standard behaviour at any time (double press)

Step 1. Set up your VPE in Home Assistant

Your VPE must already be connected to your WiFi and added to Home Assistant via the ESPHome integration before you can flash Pivot firmware.

If you haven’t done this yet, follow Home Assistant’s official VPE setup guide first, then come back here.

If your VPE is already showing up in Home Assistant under ESPHome, you’re ready to continue.

Step 2. Enable Home Assistant actions

While you’re in the ESPHome integration, enable this now before flashing the firmware:

  1. Go to Settings → Devices & Services → ESPHome
  2. Find your VPE and click ⚙️ Configure
  3. Enable Allow the device to perform Home Assistant actions

This permission allows the ESPHome device to call Home Assistant services and fire events — specifically, it is what lets the knob control entities, the button toggle them, and Pivot fire its pivot_bank_changed, pivot_knob_turn, and pivot_button_press events. Without it, the firmware can connect to Home Assistant but cannot do anything useful. It does not grant access to credentials, configuration files, or anything outside the scope of normal service calls.

Step 3. Flash the Pivot firmware

Installing custom firmware is safe and reversible. Pivot firmware is based on the official Home Assistant Voice PE firmware and has been tested extensively, but as with any custom firmware there is a small element of risk. If anything goes wrong, you can always restore the original stock firmware by visiting esphome.github.io/home-assistant-voice-pe and flashing it from your browser – no tools required.

  1. Take control of your VPE in ESPHome Device Builder.
    If you don't already have ESPHome Device Builder installed, install it via Settings → Applications → Add Application.

    When you open ESPHome Device Builder, your VPE may appear hidden under Discovered Devices – click Show in the top right corner if you don't see it.

    Not sure which device is yours? If you have multiple VPEs, ESPHome names them by the last 6 characters of their MAC address (e.g. Home-Assistant-Voice-052B5D). To find the MAC address of a specific device, go to Settings → Devices & Services → ESPHome, select the device, and look in the left column.

    Click Take Control and give it a name. ESPHome will offer to install its own firmware – you can skip this as it will be replaced by Pivot firmware in the next step.

    Save your encryption key. When you take control, ESPHome shows the device's API encryption key. Copy this and keep it somewhere safe – you'll need it in the next step. Alternatively, generate a fresh one at esphome.io.

  2. Create your per-device config.
    Copy the template from devices/example.yaml in the firmware repo (or the code block below) and paste it into ESPHome, replacing the stock YAML. Fill in your device-specific values:

    substitutions:
  # =======================================================================
  # PIVOT DEVICE CONFIGURATION – fill in these values for each device
  # =======================================================================

  # ESPHome device name (use dashes not underscores)
  device_name: home-assistant-voice-lounge

  # Friendly name shown in HA and ESPHome
  device_friendly_name: Lounge VPE

  # Pivot device suffix – unique per device, no spaces or dashes
  # Must match exactly what you enter in the Pivot integration
  device_suffix: ha_voice_lounge

  # WiFi credentials – add these lines to your ESPHome secrets.yaml:
  #   wifi_ssid: "Your Network Name"
  #   wifi_password: "Your Password"
  wifi_ssid: !secret wifi_ssid
  wifi_password: !secret wifi_password

  # API encryption key – use the one from Take Control, or generate one at:
  # https://esphome.io/components/api.html#configuration-variables
  api_encryption_key: "your-key-here"

  # LED orientation:
  #   '6'  flat on a surface, cable facing away (default)
  #   '0'  upright on a stand, cable at the bottom
  led_offset: '6'

  # =======================================================================

packages:
  pivot:
    url: https://github.com/alistairmerritt/pivot-firmware
    ref: main
    file: home-assistant-voice.yaml
    refresh: 1d

    The packages: block at the bottom tells ESPHome to fetch the full firmware from GitHub automatically – do not paste the contents of home-assistant-voice.yaml directly.

    The device_suffix must be unique per device with no spaces or dashes. You will enter this exact value when setting up the Pivot integration.

    WiFi credentials: The config uses !secret to keep credentials out of the YAML. Add wifi_ssid and wifi_password to your ESPHome Secrets file (the key icon in ESPHome Device Builder). If you prefer, you can paste the values directly as plain text instead.
    Tip: Note down your device_suffix and api_encryption_key somewhere safe. You will need both – the suffix when adding the Pivot integration, and the key if Home Assistant ever asks for it.

  3. Connect your VPE via USB for the initial flash – use a good quality cable. OTA (wireless) is used for all future updates once the device is running Pivot firmware.

    Tip: There is a small switch inside the VPE case labelled USB SELECT with two positions: ESP32 and XU316. It should be in the ESP32 position by default. If your device is not detected when connected via USB, open the case and check this switch. Follow Step 1 of the Nabu Casa disassembly guide to access it.
  4. Click Install → Plug into this computer. ESPHome will fetch the firmware from GitHub, compile it, and flash it. This may take 5–10 minutes the first time.
  5. Once flashed, fully power cycle your VPE – disconnect from power, wait a few seconds, then reconnect. The device will reconnect to Home Assistant automatically.

Future updates – once your device is running Pivot firmware and is online, all future updates are wireless. When a new firmware version is released, just open the device in ESPHome Device Builder and click Install → Wirelessly.

Step 4. Install the Pivot integration

  1. In HACS, go to Integrations → ⋮ → Custom repositories
  2. Add https://github.com/alistairmerritt/pivot-integration, category: Integration
  3. Search for Pivot and install
  4. Restart Home Assistant

Step 5. Add your device to the Pivot integration

  1. Go to Settings → Devices & Services → Add Integration and search for Pivot
  2. Select your VPE from the dropdown
  3. Confirm the firmware and enter the device_suffix you used in the firmware YAML
  4. Optionally configure announcements – enable spoken announcements, then select a text-to-speech service (TTS) and speaker. This allows Pivot to speak feedback such as bank changes. These settings are also used by the Timer blueprint.

Pivot will now connect to your device and enable control of the entities you assign in Step 6.

Do not rename Pivot entity IDs. The firmware and integration use your device_suffix to build entity IDs (e.g. number.{device_suffix}_bank_1_value). Renaming these entities in Home Assistant will break the connection between the firmware and the integration. If you need to label entities more clearly, change the entity’s Name – not its Entity ID.

Step 6. Assign entities to banks

  1. Go to Settings → Devices & Services → Pivot → your device → Configure
  2. Assign Home Assistant entities to the banks you want to use
  3. Save

The knob will now control each bank’s assigned entity value. Button presses will toggle or activate the assigned entity.

Optional timer support: A timer can be set up per device using the Timer banks selector on the bank assignment screen. See the Timer page for full setup instructions. Timers are not enabled by default – you’ll need to enable them manually. If this is your first time setting up Pivot, you can come back to timer support later. Configuration can be changed at any time.

Skipped the entity assignment screen? You can still assign entities at any time by either setting the text.{device_suffix}_bank_N_entity entities directly from your Pivot device page or in your device configuration settings.

Pivot is now set up and ready to use. Turn the knob to control the active bank’s assigned entity, press the button to toggle or activate it, and press + turn to switch banks.

Step 7. Optional: Set up a timer

Pivot includes optional timer blueprints. These are not required for normal Pivot control. Blueprints are hosted on GitHub and imported via URL into Home Assistant – when you first add a Pivot device, a notification appears with the import links.

Timers are not enabled by default. Before setting up these blueprints, go to your Pivot device in Home Assistant and enable the required timer entities. See the Timer page for full setup instructions.

Blueprint Type Required? What it does
Pivot - Timer Control Automation Yes Required for the timer alarm to fire. Also handles start, pause, resume, LED countdown gauge, and physical button control when a bank is assigned. Set Bank Number to 0 for voice-only use with no bank assigned.
Pivot - Timer - Voice Automation Optional Voice control for the timer via Home Assistant Assist – set, pause, resume, cancel, and query remaining time by voice. Requires Timer Control. Bank assignment not required.
Pivot - Timer Toggle Script Script Optional Dashboard helper that lets a card start, pause, resume, or dismiss a timer the same way the physical button does

Pivot - Timer Control is required for the timer alarm to fire. Set Bank Number to 0 if you have no bank assigned – the alarm and TTS still work, but the LED gauge and physical button control are not available.
Pivot - Timer - Voice is optional – install it if you want to control the timer by voice. Requires Timer Control to be running (for the alarm to fire), but does not require a bank to be assigned.
Pivot - Timer Toggle Script is optional – install it if you want to control the timer from a dashboard card.

Next steps