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. It is also printed on the sticker on the underside of the VPE itself, which is the easier option if the device is in front of you.

    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"

  # OTA update password – REQUIRED. One password can be shared by all
  # your Pivot devices.
  # Generate one with:  openssl rand -hex 16
  # Then add it to your ESPHome secrets.yaml, e.g.:
  #   pivot_ota_password: "a1b2c3d4e5f6a7b8c9d0e1f2"
  ota_password: !secret pivot_ota_password

  # 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.
    OTA password is required for security purposes. Once your device runs Pivot firmware, all future updates can happen wirelessly (though USB is still acceptable too). Without a password, anyone who can reach the device on your network could install their own firmware onto it.

    Wireless updates can also be authenticated with your api_encryption_key instead of the password, so keep that key just as safe. The Firmware page covers both in full.

    You can create/apply a password yourself, and if you have more than one Pivot device, they can share the same password. Ensure passwords are at least 12 characters, using only letters, digits, hyphens or underscores (avoid quotes or other special characters). If you'd rather generate a random one, open a terminal and run openssl rand -hex 16, which prints a random value you can copy. Add your chosen password to your ESPHome Secrets file as pivot_ota_password, and reference it as shown above. (Any name works, as long as the Secrets entry and the !secret line match.)

    If you do not save a password, the build will stop with an error. Pivot refuses to build firmware without a password rather than quietly producing an unprotected device.
    Tip: Note down your device_suffix, api_encryption_key and ota_password somewhere safe. You will need the suffix when adding the Pivot integration, the key if Home Assistant ever asks for it, and the OTA password for future wireless updates. If you lose the password you can still update using the key; lose both and it's a USB reflash.

  3. Connect your VPE via USB for the initial flash – use a good quality cable. OTA (wireless) can be 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, future updates can be wireless. When a new firmware version is released, just open the device in ESPHome Device Builder and click Install → Wirelessly (or connect via USB, as before).

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. You can ignore this if you wish.

Installing Pivot does not replace the Voice PE’s built-in timers. If you do not install the timer blueprints, commands such as “set a timer for 10 minutes” continue to work exactly as they do on the standard Voice PE, including the LED ring countdown and alarm on the device.

Installing the Pivot - Timer - Voice blueprint deliberately ‘takes over’ those timer phrases and routes them through Pivot’s timer instead. This is what enables the extra Pivot features, including knob control of the timer duration, dashboard controls, and voice commands to pause, resume, cancel, or check the remaining time. See the Timer page for setup details.

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 for timer functionality? 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 Not needed from v0.0.93 Dashboard helper for Pivot v0.0.92 and earlier. The Pivot dashboard cards and the pivot.timer_toggle action replace it

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 only needed on Pivot v0.0.92 and earlier. From v0.0.93 the Pivot dashboard cards have timer controls built in.

Next steps