Niimbot Label Printer Home Assistant Integration

B1 / B1 Pro	B21 Pro	D110

• Found a bug? Open an issue
• Questions or ideas? Join the discussion

Stash can print labels via this Home Assistant integration.

1. Install with HACS (custom repository required), or copy this repo into custom_components/niimbot.
2. Restart Home Assistant.
3. Go to Settings → Integrations and add Niimbot.
4. Select a discovered printer from the list.

It is strongly recommended to use a Bluetooth proxy instead of a built-in Bluetooth adapter for more stable connections and better range.

When using a proxy, keep the scan interval reasonable. Example ESPHome config:

esp32_ble_tracker:
  scan_parameters:
    active: true

bluetooth_proxy:
  active: true

Configure via Settings → Devices & Services → Niimbot → Configure:

From version 2.0.0, labels are rendered with imagespec — a declarative YAML/JSON list of drawing elements that becomes a bitmap sent to the printer.

Documentation (maintained in imagespec, not duplicated here):

Niimbot-specific behaviour:

• Palette: black & white only. Off-palette colors (e.g. red, orange) are quantized to the nearest supported color.
• Rotation: rotate: 90/180/270 rotates the drawing and swaps output width/height (label-printer mode).
• Default font: ppb.ttf in custom_components/niimbot/fonts/. Custom fonts also work from www/fonts/.
• plot element: reads history from Home Assistant Recorder.
• dither: set on the service call (or per element in the payload) to halftone photos/charts on a 2-color printer. Keep text and barcodes undithered for sharp edges — see imagespec dithering docs.
• Layout: prefer row / column / stack for stacked content instead of hand-calculated coordinates.

Use response_variable in scripts to receive the generated image as a data: URL when preview: true.

action: niimbot.print
target:
  device_id: <your device>
data:
  payload:
    - type: text
      value: Hello World!
      font: ppb.ttf
      x: 10
      y: 10
      size: 40
    - type: qrcode
      data: "https://www.home-assistant.io"
      x: 280
      y: 10
      width: 80
      height: 80
  width: 400
  height: 240

D110 (small label, often rotated):

action: niimbot.print
target:
  device_id: <your device>
data:
  payload:
    - type: text
      value: "Hello World!"
      font: ppb.ttf
      x: 10
      y: 10
      size: 30
  rotate: 90
  width: 240
  height: 96

B21 Pro (large label, high density):

action: niimbot.print
target:
  area_id: kitchen
data:
  payload:
    - type: rectangle
      x_start: 0
      x_end: 584
      y_start: 0
      y_end: 354
      fill: black
  width: 584
  height: 354
  density: 5

Use preview: true while designing labels so nothing is sent to the printer. The Niimbot Payload Layout Editor can generate YAML via drag-and-drop — paste the result here and preview first.

action: niimbot.print
target:
  device_id: <your device>
data:
  preview: true
  payload:
    - type: text
      value: Preview Test
      x: 10
      y: 10
      size: 30
  width: 400
  height: 240

Every print or preview updates image.<device>_last_label_made (disable in entity settings if unwanted).

new_multiline with fit: true shrinks text to fit the label box — useful for shipping addresses:

alias: Print label with multiple lines of text
fields:
  contents:
    selector:
      text:
        multiline: true
    name: Contents
    required: true
sequence:
  - action: niimbot.print
    target:
      area_id: kitchen
    data:
      payload:
        - type: new_multiline
          x: 0
          y: 20
          size: 100
          width: 520
          height: 300
          fit: true
          font: rbm.ttf
          value: "{{ contents }}"
      width: 584
      height: 350
      density: 5

See new_multiline in imagespec for fit_width, fit_height, and spacing options.

The printer receives data line by line. Over Bluetooth proxies, waiting for a response on every line adds up — especially on dense labels.

Tune per call first:

action: niimbot.print
target:
  device_id: <your device>
data:
  payload:
    - type: rectangle
      x_start: 0
      x_end: 10
      y_start: 0
      y_end: 600
      fill: black
  width: 584
  height: 350
  density: 5
  wait_between_print_lines: 0.01
  print_line_batch_size: 16

Then persist working values in the integration Configure dialog (wait_between_print_lines × 1000 → ms for Wait Between Each Print Line).

Anecdotally, B21 Pro on a busy network is reliable at 10 ms wait and batch size 16 (~4× faster on complex labels). Report what works for your setup in issues.

With preview: true and response_variable, a script can save the rendered image to disk and show it on a dashboard camera card.

1. Add to configuration.yaml:

shell_command:
  update_label: >-
    bash -c 'set -o pipefail; echo "$0" | cut -d, -f2 | base64 -d >/config/www/label.png' {{ image_data }}

2. Add a Local file camera pointing at /config/www/label.png.

3. Script to preview and update the file:

alias: Iterate on a label
fields:
  payload:
    selector:
      object: {}
    name: Payload
sequence:
  - action: niimbot.print
    target:
      device_id: <your device id>
    data:
      payload: "{{ payload }}"
      width: 584
      height: 350
      density: 5
      preview: true
    response_variable: previewed
  - action: shell_command.update_label
    data:
      image_data: "{{ previewed.image }}"

Niimbot Payload Layout Editor — drag-and-drop layout designer; exports YAML for niimbot.print.

Place .ttf files in custom_components/niimbot/fonts/ or config/www/fonts/ and reference by filename (e.g. ppb.ttf, rbm.ttf).

• imagespec — rendering engine
• MultiMote/niimblue
• OpenEPaperLink