WP9529 label printer

Print labels on a VSON WP9529 Bluetooth label printer from a PC, without the phone app: a Python package (pip install wp9529-printer) and a command-line tool.

Labels can mix a QR code (URL, Wi-Fi details, any text), a large title, smaller text and a Material Design Icon.

The printer's Bluetooth protocol, reverse engineered from the iLabel app, is documented in PROTOCOL.md.

For Home Assistant, see HA-WP9529, an integration built on this package's label renderer. For Homebox asset tags, see Homebox-labeler, which uses this package.

Requirements

• Windows, macOS or Linux with Bluetooth LE
• Python 3.12+
• A WP9529 with 30 × 12 mm die-cut labels (other sizes work with --length/--gap)

Install

pip install wp9529-printer

This installs the wp9529 module (import wp9529) and the wp9529-label command. To work on the code instead, clone this repository and install it editable in a virtual environment:

python -m venv .venv

.venv\Scripts\python -m pip install -e .

On macOS/Linux use .venv/bin/python instead of .venv\Scripts\python.

Turn the printer on and close the phone app or disconnect it from the printer, because the printer only accepts one connection at a time. It doesn't need pairing; the tool finds it automatically.

wp9529-label --info

printer 95:29:12:C2:09:0C: firmware V50
auto power-off after 96 minutes

Printing labels

Any mix of --title (large text), --text, --qr and --icon:

wp9529-label --title Router --text "admin password in the vault" --icon mdi:router-wireless

wp9529-label --qr "WIFI:T:WPA;S:Home;P:secret;;" --text "Guest Wi-Fi"

wp9529-label --title Spices --preview previews

Layout, along the label: QR code, then icon, then text. With no text, the QR code and icon are centred. On a 30 mm label, an icon next to both a QR code and text shrinks to about 6 mm, and long text gets shortened with "…". Use --length 40 on longer labels for more room.

Your own image works too. It must be exactly 96 px wide (the print head); for a 30 mm label it should be 240 px tall, and the top prints first:

wp9529-label --image my_label.png

Options

python -m wp9529 works the same as wp9529-label.

Using it from Python

import asyncio
from wp9529 import WP9529, asset_tag, render_label

async def main():
    img = render_label(title="Router", qr="https://example.com", icon="mdi:router-wireless")
    async with WP9529() as printer:  # scans for the printer; or WP9529("95:29:12:C2:09:0C")
        await printer.print_image(img, density="normal", label_mm=30, gap_mm=8.5)
        print(await printer.firmware_version(), await printer.power_off_minutes())

asyncio.run(main())

asset_tag(asset_id, name, url, icon=...) renders the ID + name + QR layout used for inventory tags.

Home Assistant

The Home Assistant integration lives in its own repository, HA-WP9529: sensors, settings, a print form with live preview, a notify entity and the wp9529.print_label action.

Development

The label renderer and its icon font live in src/wp9529/label.py and src/wp9529/assets/. HA-WP9529 can't install this package inside Home Assistant, so it carries an identical copy; after changing the renderer, copy it there too. HA-WP9529's tests fail if the copies differ while both projects sit side by side.

The tests cover the renderer and the CLI:

pip install -e . pytest

pytest

Releasing

Releases go to PyPI through the Publish workflow, with trusted publishing (no API tokens):

1. Bump version in pyproject.toml and push.
2. Optional: Actions → Publish → Run workflow uploads that build to TestPyPI; try it with pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ wp9529-printer. TestPyPI refuses a version it already has, so bump again to re-test.
3. Publish a GitHub release with the tag v + the version (e.g. v0.1.1). The workflow checks the tag matches, builds, smoke-tests the wheel and uploads it to PyPI.

Troubleshooting

"No WP9529 found": the printer is off, asleep, or connected to the phone app (or Home Assistant). Turn it on, close the app and try again.

Labels are shifted or run into the gap: the printer has lost its place on the roll. Use the printer's own re-align (feed) button, then print again. This can happen after a job that is longer than the label. Don't change --length or --gap to compensate.

Text is upside down: add --rotate 270.

Print is too faint or too dark: use --density dark or --density light.

"unknown MDI icon": check the name at pictogrammers.com. The bundled font is version 7.4.47, so icons added after it aren't available.

Files