Control a stock JBL PartyBox 1000 from Home Assistant using an original ESP32 and ESPHome's encrypted native API. The ESP32 joins the speaker's Classic Bluetooth TWS session and uses SPP for input selection and firmware queries. No speaker modification, speaker firmware flash, MQTT broker or audio wiring is required. Use one ESP32 per speaker.
TWS limitation: The ESP32 acts as a second speaker and occupies the JBL's TWS connection. While using this project, that JBL cannot also pair with another physical speaker over TWS for wireless stereo or audio sharing. Multiple JBLs can still be controlled together through Home Assistant, each with its own ESP32 and audio feed.
Beta. Tested with speaker software 75/32/17/15/7, ESPHome 2026.9.1
and ESP-IDF 5.5.5. Keep these versions pinned: the component hooks internal
Bluetooth stack functions. ESP32-WROOM-32/32E and ESP32-PICO-D4 support the
required Bluetooth Classic transport. ESP32-S3, C3 and C6 do not.
| Entity | Support |
|---|---|
| Media player | Volume in 33 steps (0–32), application mute/unmute, guarded standby/wake |
| Source select | Bluetooth, USB, AUX, LINE IN |
| Bass select | Off, Level 1, Level 2 |
| Lighting select | Off, Pattern 1–4; visual names remain unmapped |
| Signal activity | Selected AUX/LINE IN/USB electrical signal; Bluetooth unknown |
| Per-input signal flags | Last reported AUX, LINE IN, USB and Bluetooth bits, independent of selected-source confidence; inactive-input flags may be stale |
| Diagnostics | Link status, field confidence, power estimate, firmware version, last command, heap and counters |
The player exposes no play/pause, track controls or metadata. Signal activity
does not establish audible music. Power is an estimate: OFF means requested
standby; neutral IDLE means power/link state is unknown. A Bluetooth connection
alone cannot establish whether the speaker is awake.
State confidence is observed after speaker readback, assumed after an accepted
command, or unknown after a gap. Mute readback is available in a startup
snapshot, with no demonstrated harmless on-demand getter. Native ESPHome cannot
make individual controls unavailable while its API remains connected, or clear
the player's individual volume/mute fields. Inspect confidence entities when
those retained values matter. See protocol and state semantics.
For source selection and bass sound modes inside a single HA media player, use the optional Home Assistant wrapper.
For multiple speakers, the expandable mixer dashboard provides a master volume fader, individual faders and speaker controls. Adding a player to one group helper expands the dashboard automatically.
The firmware volume curve maps all 33 levels to relative dB gain, verified offline against V63, V64 and V75. It can support zone gain matching; room loudness still requires calibration.
The current checkout adds a Pair speaker button in HA. Put the intended JBL into TWS search, then press it: a single discovery window finds compatible PartyBox 1000 candidates and saves the only match. Multiple matches require a choice. The saved target can also be edited in HA without reflashing.
Use examples/pairing.yaml and the pairing guide. This feature is not yet in the published beta tag. Single-speaker discovery, saved-target restart and TWS/SPP admission have been verified on hardware. Normal operation keeps active scanning disabled. Changing targets restarts the bridge and requires TWS pairing.
The supplied SDATEKIT ESP32-WROOM-32E schematic connects a WS2812B to
GPIO16. Add the
LED package alongside the base package;
examples/rgb.yaml shows the local-checkout configuration.
This package currently requires the repository checkout; the tagged beta predates
RGB support. Boards without this LED need no changes. Other boards can override
partybox_status_led_pin.
| LED | Meaning |
|---|---|
| Dim green | Wi-Fi, an API state subscriber, TWS and enabled SPP are connected; standby is healthy too |
| Pulsing amber | Wi-Fi or API state subscriber missing |
| Pulsing blue | Required speaker transport missing |
| Brief cyan | A command was written to the Bluetooth transport |
| Three red flashes | A command was refused, rejected, failed or timed out |
| Steady red | PartyBox component failed |
The schematic also places a 0-ohm RGB link in the data line. Our tested SDATEKIT board shipped with that position empty, leaving the LED disconnected. Check that link before troubleshooting GPIO settings; driver health cannot detect an open connection or a different LED part.
Brightness defaults to 8%; override partybox.status_brightness if desired.
A transport write does not prove the speaker applied a command. The LED is
internal and does not add a Home Assistant light entity or Bluetooth traffic.
Use an original ESP32 with USB power, one per speaker. Install ESPHome 2026.9.1; the package supplies the tested framework and radio settings. Create a device configuration in ESPHome with your own node name:
substitutions:
name: office-partybox
friendly_name: Office PartyBox
packages:
partybox: github://CampusTech/esphome-partybox-1000/packages/partybox-1000.yaml@v0.1.0-beta.1
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
password: !secret setup_password
api:
encryption:
key: !secret api_key
ota:
- platform: esphome
encryption:
key: !secret api_key
partybox:
mac_address: !secret speaker_macAdd these values to your private secrets.yaml:
wifi_ssid: "Your Wi-Fi"
wifi_password: "Your Wi-Fi password"
setup_password: "A private recovery AP password"
api_key: "BASE64_32_BYTE_KEY"
speaker_mac: "AA:BB:CC:DD:EE:FF"Use the speaker's Classic Bluetooth address, which may differ from its BLE
address. Generate the API/OTA key with
python3 -c 'import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())'.
The recovery password must contain 8–63 characters. Do not commit secrets.
The package defaults to 4 MB flash. For a board fitted with 8 MB, add
partybox_flash_size: 8MB under substitutions. Extra flash adds no RAM.
Use the ESPHome dashboard to install over USB, then add the discovered node to
Home Assistant with its API key. Later updates support encrypted OTA. The
recovery AP and captive portal allow Wi-Fi recovery; BLE provisioning/proxy cannot
share this Bluetooth controller.
Turn the JBL on and hold only Bluetooth for about five seconds to start TWS
search. Wait for TWS connected and SPP connected. Follow the short
pairing guide for the first control test and reconnection.
A physical rejoin may be required after either device reboots or the speaker
fully powers off. Connect Bluetooth makes an ordinary A2DP attempt, not a
guaranteed TWS rejoin. Standby/wake require a known power estimate and a retained
TWS link; they are never sent on boot or retried automatically. A dark, fully
powered-off speaker was not woken by this path.
All entities have built-in names, units and precision. Add a section only to
override settings, or use false to omit an entity:
partybox:
mac_address: !secret speaker_mac
media_player:
name: Player override
free_heap:
disabled_by_default: false
last_word: falseEveryday controls, link/activity status and the firmware version are visible by default. Low-level counters, confidence fields, raw words and service diagnostics start disabled in HA; enable them on the device page when needed. HA can retain existing entity enable/disable choices across updates. Empty entity sections keep defaults, and existing explicit names still work.
Firmware contains your speaker address and private credentials. To export verified USB and OTA files, clone this release, install requirements.txt, and configure the local example with your private secrets:
git clone --branch v0.1.0-beta.1 https://github.com/CampusTech/esphome-partybox-1000.git
cd esphome-partybox-1000
python3.13 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Create examples/secrets.yaml with your private values before building.
.venv/bin/python tools/build_firmware.py examples/partybox-1000.yaml --output dist/office-partyboxThe export contains firmware.factory.bin (merged USB image, offset 0x0),
firmware.ota.bin (OTA image), build verification metadata and SHA256SUMS.
Keep that directory private. It is ignored by Git. Both images must agree, and
all three linked Bluetooth hooks must pass verification before anything is
exported. Install directly with
.venv/bin/esphome run examples/partybox-1000.yaml if separate files are unnecessary.
The minimal example keeps only the player and link status. The local examples import the same package with a local component source; the GitHub import above pins both the package and component to this release. See the changelog for release notes and contributors.
With periodic post-connect Wi-Fi roaming disabled, one quiet LINE IN window passed 17 minutes with SPP disabled; a separate music-playing window passed 10 minutes 45 seconds with SPP enabled. Both retained TWS and the native API without reset or dropped protocol events. Home Assistant standby/wake was also physically confirmed. These are bounded tests, not an overnight reliability claim.
Older speaker hardware, prolonged unattended operation, third-device Bluetooth audio coexistence and speaker USB power retention in standby remain unverified. Use an independent USB supply until retention is measured. See troubleshooting for pairing, unknown state and link loss.
Run the checks from the repository root:
python3 tools/check.py
.venv/bin/python tools/check_config.py
.venv/bin/python tools/check_config.py --example full --compileThese run host tests, validate/generate both examples, then build the full example
and verify its linked hooks. Add --flash 8MB for that build variant. The
protocol notes explain why
compilation alone is insufficient. Archived firmware references are
listed in reference/README.md; they are not needed to use
the component. Project code is MIT licensed.