Brother QL Label Printer for Home Assistant

A HACS custom integration that lets Home Assistant print text labels on network-connected Brother QL label printers. Add each printer by its IP address and model through the UI, then print from automations or scripts with the brother_ql.print_text service.

Label rendering and the printer protocol are handled by the brother_ql Python library — the same library used by brother_ql_web.

Requirements

• A Brother QL printer reachable over the network (e.g. a QL-820NWB, QL-720NW, QL-800, ...) with its Ethernet/Wi-Fi print service enabled on TCP port 9100 (the Brother default — most QL printers with LAN/Wi-Fi support this out of the box).
• Home Assistant with HACS installed.

Installation

Via HACS

1. In HACS, go to Integrations → the ⋮ menu → Custom repositories.
2. Add https://github.com/segadora/brother_ql with category Integration.
3. Install "Brother QL Label Printer" and restart Home Assistant.

Note: HACS only supports repositories hosted on GitHub.

Manual

Copy custom_components/brother_ql into your Home Assistant config/custom_components/ directory and restart Home Assistant.

Adding a printer

1. Go to Settings → Devices & Services → Add Integration and search for "Brother QL Label Printer".
2. Enter a name, the printer's IP address, port (default 9100), model, and the label size currently loaded in the printer.
3. Home Assistant will attempt a TCP connection to confirm the printer is reachable before adding it.

Repeat for each printer you own. Model and label size can be changed later from the integration's Configure option.

Each printer device also gets these entities:

• button.<printer>_test_print — prints a one-line test label so you can confirm the printer is wired up correctly, no service call needed.
• sensor.<printer>_device_id (diagnostic) — its state is the exact device_id value to use with brother_ql.print_text in YAML. Find it on the device's page under Diagnostic, or via Developer Tools → States.
• binary_sensor.<printer>_connectivity (diagnostic) — on/off based on whether the printer currently accepts a TCP connection, checked every 60 seconds. Useful for automations/alerts when the printer is powered off or unreachable.

Printing a label

Call the brother_ql.print_text service, targeting the printer device:

action: brother_ql.print_text
data:
  device_id: <your printer's device id>
  text: |
    Hello world
    Second line
  font: sans_bold
  font_size: 90
  align: center
  orientation: standard
  label_count: 1
  cut: true

All fields besides device_id and text are optional. See the service description in Developer Tools → Actions for the full list of options (font, font size, alignment, orientation, margin, black/white threshold, number of copies, and whether to cut after printing).

Text is rendered with a bundled DejaVu font (license included in custom_components/brother_ql/fonts/LICENSE.txt), which fully supports Danish/Nordic characters (æ, ø, å). Choose one of:

• sans / sans_bold (default)
• serif / serif_bold
• mono / mono_bold

Supported models

QL-500, QL-550, QL-560, QL-570, QL-580N, QL-650TD, QL-700, QL-710W, QL-720NW, QL-800, QL-810W, QL-820NWB, QL-1050, QL-1060N, QL-1100, QL-1110NWB, QL-1115NWB, PT-P750W, PT-P900W — this is the full model list from the brother_ql library.

Localization

The config flow, options flow, entities, and service description are available in English and Danish (da), following Home Assistant's own language setting.

Notes

• Only network (Wi-Fi/Ethernet) printers are supported — this integration talks to the printer over TCP, not USB.
• Only plain text labels are supported for now.

Maintainer

@segadora — issues and PRs: github.com/segadora/brother_ql

License

MIT