wp9529-printer 0.1.0__py3-none-any.whl

wp9529/cli.py

@@ -0,0 +1,109 @@
+"""Print labels on a VSON WP9529 from the command line.
+
+Examples:
+    wp9529-label --info                                     # printer status
+    wp9529-label --power-off 30                             # switch off after 30 idle minutes
+    wp9529-label --title Router --text "admin / see vault" --icon mdi:router-wireless
+    wp9529-label --qr "WIFI:T:WPA;S:Home;P:secret;;" --text "Guest Wi-Fi"
+    wp9529-label --qr https://example.com --icon mdi:link --copies 3
+    wp9529-label --title Spices --preview previews          # render a PNG only
+    wp9529-label --image my_label.png                       # an image 96 px wide
+"""
+import argparse
+import asyncio
+import logging
+from pathlib import Path
+
+from PIL import Image
+
+from .driver import DENSITY, POWER_OFF_MAX, POWER_OFF_MIN, WP9529, PrinterError
+from .label import render_label
+
+
+def power_off_minutes(value: str) -> int:
+    minutes = int(value)
+    if not POWER_OFF_MIN <= minutes <= POWER_OFF_MAX:
+        raise argparse.ArgumentTypeError(f"must be {POWER_OFF_MIN}-{POWER_OFF_MAX} minutes")
+    return minutes
+
+
+def add_print_options(p: argparse.ArgumentParser) -> None:
+    """Options about the roll and the printer, shared with other label tools."""
+    p.add_argument("--length", type=float, default=30, help="label length in mm (default 30)")
+    p.add_argument("--gap", type=float, default=8.5, help="gap between labels in mm (default 8.5)")
+    p.add_argument("--continuous", action="store_true", help="continuous tape instead of die-cut labels")
+    p.add_argument("--rotate", type=int, default=90, choices=[90, 270], help="flip if text prints upside down")
+    p.add_argument("--density", default="normal", choices=list(DENSITY))
+    p.add_argument("--feed", type=int, default=0, help="extra blank lines after the label")
+    p.add_argument("--copies", type=int, default=1, help="copies of each label")
+    p.add_argument("--preview", metavar="DIR", help="save rendered labels as PNGs in DIR instead of printing")
+    p.add_argument("--address", help="printer BLE address (default: scan for it)")
+    p.add_argument("-v", "--verbose", action="store_true", help="log every Bluetooth packet")
+
+
+def save_previews(jobs: list[tuple[str, Image.Image]], directory: str) -> None:
+    out = Path(directory)
+    out.mkdir(parents=True, exist_ok=True)
+    for name, img in jobs:
+        img.save(out / f"{name}.png")
+    print(f"saved {len(jobs)} preview(s) to {out}")
+
+
+async def print_jobs(jobs: list[tuple[str, Image.Image]], args, info: bool = False,
+                     power_off: int | None = None) -> None:
+    """Connect once and print each (name, image) job `args.copies` times."""
+    async with WP9529(args.address) as printer:
+        print(f"printer {printer.address}: firmware {await printer.firmware_version()}")
+        if power_off is not None:
+            stored = await printer.set_power_off_minutes(power_off)
+            print(f"auto power-off set to {stored} minutes")
+        elif info:
+            print(f"auto power-off after {await printer.power_off_minutes()} minutes")
+        for name, img in jobs:
+            for _ in range(args.copies):
+                await printer.print_image(img, density=args.density, feed_lines=args.feed,
+                                          label_mm=None if args.continuous else args.length,
+                                          gap_mm=args.gap)
+            print(f"printed {name}" + (f" x{args.copies}" if args.copies > 1 else ""))
+
+
+async def run(args) -> None:
+    jobs: list[tuple[str, Image.Image]] = []
+    if args.image:
+        jobs.append((Path(args.image).stem, Image.open(args.image)))
+    elif args.title or args.text or args.qr or args.icon:
+        img = render_label(title=args.title, text=args.text, qr=args.qr, icon=args.icon,
+                           length_mm=args.length, rotate=args.rotate)
+        jobs.append(("label", img))
+    if args.preview:
+        if not jobs:
+            raise ValueError("nothing to preview: give --title, --text, --qr, --icon or --image")
+        save_previews(jobs, args.preview)
+        return
+    if not jobs and not args.info and args.power_off is None:
+        raise ValueError("nothing to do: give --title, --text, --qr, --icon, --image, --info or --power-off")
+    await print_jobs(jobs, args, info=args.info, power_off=args.power_off)
+
+
+def main(argv: list[str] | None = None) -> None:
+    p = argparse.ArgumentParser(prog="wp9529-label", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--title", default="", help="large text")
+    p.add_argument("--text", default="", help="smaller text (or the only text)")
+    p.add_argument("--qr", help="any text to encode as a QR code")
+    p.add_argument("--icon", help="MDI icon, e.g. mdi:tools (https://pictogrammers.com/library/mdi/)")
+    p.add_argument("--image", help="print an existing image (must be 96 px wide)")
+    p.add_argument("--info", action="store_true", help="show the printer's firmware and auto power-off time")
+    p.add_argument("--power-off", type=power_off_minutes, metavar="MIN",
+                   help=f"set the printer's auto power-off time ({POWER_OFF_MIN}-{POWER_OFF_MAX} minutes)")
+    add_print_options(p)
+    args = p.parse_args(argv)
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.WARNING, format="%(message)s")
+    try:
+        asyncio.run(run(args))
+    except (PrinterError, ValueError, OSError) as e:
+        raise SystemExit(f"error: {e}") from None
+
+
+if __name__ == "__main__":
+    main()

wp9529/driver.py

@@ -0,0 +1,241 @@
+"""Driver for the VSON WP9529 Bluetooth LE label printer.
+
+Protocol reverse engineered from the iLabel Android app (com.vson.ilabel):
+
+  * GATT service 0xFFF0. Commands are written to 0xFFF1 (write without
+    response); replies arrive as notifications on 0xFFF4.
+  * Every command and reply starts with a one-byte opcode.
+
+    01                                 device info / status
+      <- 01 width_mm(LE16) width_dots(LE16) state err_a err_b err_c err_d ...
+    04                                 reset / cancel the current job
+    02 lines(LE16) offset(LE16) 00 01 density
+                                       job header, continuous paper (density 24/32/39)
+    02 lines(LE16) offset(LE16) 00 02 density label_mm gap_mm*10 copies
+                                       job header, die-cut labels with gaps
+    03 line(LE16) n data[n*width/8]    raster packet, n lines from `line`
+      <- a4 / a5                       printer accepted the header
+      <- a7 / a8                       pause / resume the data stream
+    b1                                 MAC address
+    b2                                 firmware version (the app shows it as "V" + hex)
+    b4                                 auto power-off time
+      <- b4 minutes ..
+    b5 minutes 00                      set the auto power-off time (10-180 minutes)
+      <- b5 minutes ..
+
+  Raster data is 1 bit per pixel, MSB first, 1 = black, one print-head
+  width (96 px = 12 mm at 203 dpi) per line.
+"""
+import asyncio
+import logging
+
+from bleak import BleakClient, BleakScanner
+from PIL import Image, ImageOps
+
+log = logging.getLogger("wp9529")
+
+WRITE_UUID = "0000fff1-0000-1000-8000-00805f9b34fb"
+NOTIFY_UUID = "0000fff4-0000-1000-8000-00805f9b34fb"
+NAME_PREFIX = "9529"
+
+DOTS_PER_MM = 8
+DENSITY = {"light": 24, "normal": 32, "dark": 39}
+POWER_OFF_MIN, POWER_OFF_MAX = 10, 180  # minutes, the range the iLabel app allows
+LINES_PER_PACKET = 4
+
+
+class PrinterError(Exception):
+    pass
+
+
+class Info:
+    def __init__(self, raw: bytes):
+        self.raw = raw
+        self.width_mm = int.from_bytes(raw[1:3], "little")
+        self.width = int.from_bytes(raw[3:5], "little")
+        self.state = raw[5]
+        self.errors = tuple(raw[6:10])
+
+    @property
+    def busy(self):
+        return self.state != 0
+
+    @property
+    def has_error(self):
+        return any(self.errors)
+
+    def __repr__(self):
+        return (f"Info(width={self.width_mm} mm/{self.width} dots, state={self.state}, "
+                f"errors={self.errors}, raw={self.raw.hex(' ')})")
+
+
+async def find_printer(timeout=8.0):
+    """Return the address of the first WP9529 found nearby."""
+    dev = await BleakScanner.find_device_by_filter(
+        lambda d, adv: (adv.local_name or d.name or "").startswith(NAME_PREFIX),
+        timeout=timeout,
+    )
+    if dev is None:
+        raise PrinterError("No WP9529 found. Is it on and disconnected from the phone app?")
+    return dev.address
+
+
+def rasterize(img: Image.Image, width: int) -> list[bytes]:
+    """Turn an image `width` px wide into rows of packed 1-bit data (1 = black)."""
+    if img.width != width:
+        raise ValueError(f"image must be {width} px wide, got {img.width}")
+    bw = ImageOps.invert(img.convert("L")).point(lambda p: 255 if p >= 128 else 0, "1")
+    data = bw.tobytes()
+    stride = width // 8
+    return [data[i:i + stride] for i in range(0, len(data), stride)]
+
+
+def build_packets(rows: list[bytes], lines_per_packet=LINES_PER_PACKET) -> list[bytes]:
+    packets = []
+    for start in range(0, len(rows), lines_per_packet):
+        chunk = rows[start:start + lines_per_packet]
+        packets.append(bytes([0x03, start & 0xFF, start >> 8, len(chunk)]) + b"".join(chunk))
+    return packets
+
+
+class WP9529:
+    def __init__(self, address: str | None = None):
+        self.address = address
+        self.client: BleakClient | None = None
+        self.info: Info | None = None
+        self._replies: asyncio.Queue[bytes] = asyncio.Queue()
+        self._resume = asyncio.Event()
+        self._resume.set()
+
+    async def __aenter__(self):
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.disconnect()
+
+    async def connect(self):
+        if self.address is None:
+            self.address = await find_printer()
+        self.client = BleakClient(self.address, timeout=20.0)
+        await self.client.connect()
+        await self.client.start_notify(NOTIFY_UUID, self._on_notify)
+        self.info = await self.get_info()
+        log.info("connected to %s: %r", self.address, self.info)
+
+    async def disconnect(self):
+        if self.client and self.client.is_connected:
+            await self.client.disconnect()
+
+    def _on_notify(self, _, data: bytearray):
+        data = bytes(data)
+        log.debug("<- %s", data.hex(" "))
+        if data[:1] == b"\xa7":
+            self._resume.clear()
+        elif data[:1] == b"\xa8":
+            self._resume.set()
+        self._replies.put_nowait(data)
+
+    async def _send(self, data: bytes):
+        log.debug("-> %s", data.hex(" ") if len(data) <= 16 else f"{data[:16].hex(' ')} ... ({len(data)} B)")
+        await self.client.write_gatt_char(WRITE_UUID, data, response=False)
+
+    async def _request(self, data: bytes, opcodes: bytes, timeout=3.0) -> bytes:
+        """Send a command and wait for a reply starting with one of `opcodes`."""
+        while not self._replies.empty():
+            self._replies.get_nowait()
+        await self._send(data)
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while True:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                raise PrinterError(f"no reply to {data[:1].hex()} (wanted {opcodes.hex()})")
+            try:
+                reply = await asyncio.wait_for(self._replies.get(), remaining)
+            except TimeoutError:
+                raise PrinterError(f"no reply to {data[:1].hex()} (wanted {opcodes.hex()})") from None
+            if reply[0] in opcodes:
+                return reply
+
+    async def get_info(self) -> Info:
+        return Info(await self._request(b"\x01", b"\x01"))
+
+    async def firmware_version(self) -> str:
+        return f"V{(await self._request(b'\xb2', b'\xb2'))[1]:x}"
+
+    async def power_off_minutes(self) -> int:
+        """Minutes of inactivity before the printer switches itself off."""
+        return (await self._request(b"\xb4", b"\xb4"))[1]
+
+    async def set_power_off_minutes(self, minutes: int) -> int:
+        """Set the auto power-off time (10-180 minutes); returns what the printer stored."""
+        minutes = max(POWER_OFF_MIN, min(POWER_OFF_MAX, int(minutes)))
+        return (await self._request(bytes([0xB5, minutes, 0]), b"\xb5"))[1]
+
+    async def print_image(self, img: Image.Image, density="normal", feed_lines=0,
+                          label_mm: float | None = 30, gap_mm: float = 8.5):
+        """Print one label. `img` must be exactly print-head wide (see .width).
+
+        With `label_mm` set the job is sent as gap paper so the printer lines up
+        with the die-cut labels; pass label_mm=None for continuous tape.
+        """
+        level = DENSITY.get(density, density)
+        rows = rasterize(img, self.width)
+        rows += [bytes(self.width // 8)] * feed_lines
+        packets = build_packets(rows)
+
+        await self._send(b"\x04")
+        await asyncio.sleep(0.3)
+        info = await self.get_info()
+        if info.has_error:
+            raise PrinterError(f"printer reports an error (out of paper / cover open?): {info!r}")
+        if info.busy:
+            raise PrinterError(f"printer is busy: {info!r}")
+
+        total = len(rows)
+        if label_mm:
+            header = bytes([0x02, total & 0xFF, total >> 8, 0, 0, 0, 0x02, level,
+                            round(label_mm), round(gap_mm * 10), 1])
+        else:
+            header = bytes([0x02, total & 0xFF, total >> 8, 0, 0, 0, 0x01, level])
+        reply = await self._request(header, b"\xa4\xa5", timeout=5.0)
+        log.info("header accepted: %s", reply.hex(" "))
+
+        self._resume.set()
+        await asyncio.sleep(2.0)  # the app waits this long before the first packet
+        for i, pkt in enumerate(packets):
+            await self._wait_resume()
+            await self._send(pkt)
+            if i and (i * LINES_PER_PACKET) % 500 == 0:
+                await asyncio.sleep(2.0)
+        log.info("sent %d lines in %d packets", total, len(packets))
+
+        await self._wait_done()
+
+    async def _wait_resume(self, timeout=30.0):
+        try:
+            await asyncio.wait_for(self._resume.wait(), timeout)
+        except TimeoutError:
+            raise PrinterError("printer paused the data stream and never resumed") from None
+
+    async def _wait_done(self, timeout=60.0):
+        await asyncio.sleep(2.0)
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while loop.time() < deadline:
+            try:
+                info = await self.get_info()
+            except PrinterError:
+                log.debug("status poll got no reply while printing, retrying")
+                continue
+            if info.has_error:
+                raise PrinterError(f"printer error during print: {info!r}")
+            if not info.busy:
+                return
+            await asyncio.sleep(1.0)
+        raise PrinterError("timed out waiting for the print to finish")
+
+    @property
+    def width(self) -> int:
+        return self.info.width if self.info else 96

wp9529/label.py

@@ -0,0 +1,213 @@
+"""Render labels as print-ready images for a 12 mm (96-dot) print head.
+
+Part of the wp9529 package, and copied unchanged into the Home Assistant
+integration (HA-WP9529), so it must not import anything from Home Assistant.
+
+Layout, left to right along the label: [QR code] [MDI icon] [title / text].
+Every part is optional; with no text, the QR code and icon are centred.
+"""
+import json
+from functools import lru_cache
+from pathlib import Path
+
+import qrcode
+from PIL import Image, ImageDraw, ImageFont
+
+DOTS_PER_MM = 8
+ASSETS = Path(__file__).with_name("assets")
+MDI_FONT = ASSETS / "materialdesignicons-webfont.ttf"
+MDI_CODEPOINTS = ASSETS / "mdi-codepoints.json"
+FONT_CANDIDATES = ["arialbd.ttf", "DejaVuSans-Bold.ttf", "LiberationSans-Bold.ttf"]
+
+
+@lru_cache(maxsize=64)
+def _font(size: int) -> ImageFont.FreeTypeFont:
+    for name in FONT_CANDIDATES:
+        try:
+            return ImageFont.truetype(name, size)
+        except OSError:
+            continue
+    return ImageFont.load_default(size)
+
+
+@lru_cache(maxsize=1)
+def _mdi_codepoints() -> dict[str, int]:
+    return json.loads(MDI_CODEPOINTS.read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=8)
+def _mdi_font(size: int) -> ImageFont.FreeTypeFont:
+    return ImageFont.truetype(str(MDI_FONT), size)
+
+
+def mdi_glyph(icon: str) -> str:
+    """Character for an MDI icon given as "mdi:tools" or "tools"."""
+    name = icon.removeprefix("mdi:").strip()
+    try:
+        return chr(_mdi_codepoints()[name])
+    except KeyError:
+        raise ValueError(f"unknown MDI icon: {icon!r}") from None
+
+
+def _fit_font(draw, text, max_w, max_h, start=48):
+    size = start
+    while size > 8:
+        font = _font(size)
+        l, t, r, b = draw.textbbox((0, 0), text, font=font)
+        if r - l <= max_w and b - t <= max_h:
+            return font
+        size -= 1
+    return _font(8)
+
+
+def _line_height(font) -> int:
+    l, t, r, b = font.getbbox("Ag")
+    return b - t + 2
+
+
+def _split_long_word(draw, word, font, max_w) -> list[str]:
+    """Break a word wider than max_w into pieces that fit ("Korttisuoj", "at")."""
+    pieces, piece = [], ""
+    for ch in word:
+        if piece and draw.textlength(piece + ch, font=font) > max_w:
+            pieces.append(piece)
+            piece = ch
+        else:
+            piece += ch
+    return pieces + [piece] if piece else pieces
+
+
+def _wrap(draw, text, font, max_w, break_words=False) -> list[str]:
+    words = []
+    for word in text.split():
+        too_wide = break_words and draw.textlength(word, font=font) > max_w
+        words += _split_long_word(draw, word, font, max_w) if too_wide else [word]
+    lines, line = [], ""
+    for word in words:
+        trial = f"{line} {word}".strip()
+        if draw.textlength(trial, font=font) <= max_w or not line:
+            line = trial
+        else:
+            lines.append(line)
+            line = word
+    return lines + [line] if line else lines
+
+
+def _ellipsize(draw, text, font, max_w) -> str:
+    if draw.textlength(text, font=font) <= max_w:
+        return text
+    while text and draw.textlength(text + "…", font=font) > max_w:
+        text = text[:-1]
+    return text.rstrip() + "…"
+
+
+def _fit_lines(draw, text, max_w, max_h, largest=22, smallest=12, max_lines=2):
+    """Largest font (not below `smallest`) that fits `text` in at most `max_lines`
+    lines; at the smallest size, overflow is cut with an ellipsis.
+
+    Words are only broken when whole words cannot fit at any size, and then into
+    as few lines as possible ("Korttisuo / jat", not "Kort / tisu / ojat").
+    """
+    attempts = [(False, max_lines)] + [(True, n) for n in range(1, max_lines + 1)]
+    for break_words, n_lines in attempts:
+        for size in range(largest, smallest - 1, -1):
+            font = _font(size)
+            lines = _wrap(draw, text, font, max_w, break_words)
+            if (len(lines) <= n_lines and _line_height(font) * len(lines) <= max_h
+                    and all(draw.textlength(ln, font=font) <= max_w for ln in lines)):
+                return lines, font
+    font = _font(smallest)
+    n = max(1, min(max_lines, max_h // _line_height(font)))
+    lines = _wrap(draw, text, font, max_w, break_words=True)
+    head, rest = lines[:n - 1], " ".join(lines[n - 1:])
+    return [_ellipsize(draw, ln, font, max_w) for ln in head] + [_ellipsize(draw, rest, font, max_w)], font
+
+
+def qr_image(data: str, size: int) -> Image.Image:
+    qr = qrcode.QRCode(error_correction=qrcode.constants.ERROR_CORRECT_M, border=0, box_size=1)
+    qr.add_data(data)
+    qr.make(fit=True)
+    img = qr.make_image(fill_color="black", back_color="white").convert("L")
+    if img.width > size:
+        raise ValueError(f"QR data too long for a 12 mm label ({len(data)} characters)")
+    scale = max(1, size // img.width)  # integer scaling keeps modules crisp
+    return img.resize((img.width * scale, img.height * scale), Image.NEAREST)
+
+
+def icon_image(icon: str, size: int) -> Image.Image:
+    glyph = mdi_glyph(icon)
+    img = Image.new("L", (size, size), 255)
+    ImageDraw.Draw(img).text((size / 2, size / 2), glyph, font=_mdi_font(size), fill=0, anchor="mm")
+    return img
+
+
+def render_label(title: str = "", text: str = "", qr: str | None = None, icon: str | None = None,
+                 length_mm: float = 30, head_px: int = 96, margin_px: int = 4,
+                 end_margin_mm: float = 1.5, rotate: int = 90) -> Image.Image:
+    """Build a label image `head_px` wide and `length_mm` long, ready for print_image().
+
+    `title` is drawn large, `text` below it (or on its own, up to 3 lines),
+    `qr` is any string to encode, `icon` an MDI name like "mdi:tools".
+    `end_margin_mm` keeps content off the label's rounded ends.
+    """
+    if not (title or text or qr or icon):
+        raise ValueError("nothing to print: give a title, text, QR data or an icon")
+    length_px = int(length_mm * DOTS_PER_MM)
+    end_px = int(end_margin_mm * DOTS_PER_MM)
+    box = head_px - 2 * margin_px
+    canvas = Image.new("L", (length_px, head_px), 255)
+    draw = ImageDraw.Draw(canvas)
+
+    has_text = bool(title or text)
+    blocks = []
+    if qr:
+        blocks.append(qr_image(qr, box))
+    if icon:
+        # Sharing the label with a QR code and text, a full-height icon would
+        # leave almost no room for the text, so it shrinks to about 6 mm.
+        icon_px = 6 * DOTS_PER_MM if (qr and has_text) else box
+        blocks.append(icon_image(icon, icon_px))
+    blocks_w = sum(b.width for b in blocks) + 2 * margin_px * max(0, len(blocks) - 1)
+
+    x = end_px if has_text else max(end_px, (length_px - blocks_w) // 2)
+    for b in blocks:
+        canvas.paste(b, (x, (head_px - b.height) // 2))
+        x += b.width + margin_px * 2
+
+    text_w = length_px - x - end_px
+    if has_text and text_w < 3 * DOTS_PER_MM:
+        raise ValueError(f"no room for text on a {length_mm:g} mm label; drop the QR or the icon")
+
+    if title and text:
+        gap = 5
+        title_font = _fit_font(draw, title, text_w, head_px * 0.42)
+        tb = draw.textbbox((0, 0), title, font=title_font)
+        title_h = tb[3] - tb[1]
+        lines, text_font = _fit_lines(draw, text, text_w, box - title_h - gap)
+        line_h = _line_height(text_font)
+        y = (head_px - title_h - gap - line_h * len(lines)) // 2
+        draw.text((x - tb[0], y - tb[1]), title, font=title_font, fill=0)
+        y += title_h + gap
+        for line in lines:
+            draw.text((x, y), line, font=text_font, fill=0, anchor="lt")
+            y += line_h
+    elif title:
+        font = _fit_font(draw, title, text_w, box, start=64)
+        tb = draw.textbbox((0, 0), title, font=font)
+        draw.text((x - tb[0], (head_px - (tb[3] - tb[1])) // 2 - tb[1]), title, font=font, fill=0)
+    elif text:
+        lines, font = _fit_lines(draw, text, text_w, box, largest=40, max_lines=3)
+        line_h = _line_height(font)
+        y = (head_px - line_h * len(lines)) // 2
+        for line in lines:
+            draw.text((x, y), line, font=font, fill=0, anchor="lt")
+            y += line_h
+
+    return canvas.rotate(rotate, expand=True)
+
+
+def asset_tag(asset_id: str, name: str = "", url: str | None = None, icon: str | None = None,
+              length_mm: float = 30, rotate: int = 90) -> Image.Image:
+    """Homebox tag: QR link, optional icon, asset ID large with the item name below."""
+    return render_label(title=asset_id, text=name, qr=url, icon=icon,
+                        length_mm=length_mm, rotate=rotate)