phomemo 0.3.0__py3-none-any.whl

phomemo/__init__.py

@@ -0,0 +1,82 @@
+# This file is part of phomemo.
+# Copyright (C) 2026 Paul Bütof, Passionate Bytes Solutions
+#
+# phomemo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# phomemo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with phomemo.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Async BLE driver library for Phomemo thermal printers.
+
+Provides a modular, profile-based API for communicating with Phomemo
+thermal printers over Bluetooth Low Energy.
+
+Basic usage::
+
+    from phomemo import Printer
+
+    async with Printer("m08f", "AA:BB:CC:DD:EE:FF") as printer:
+        # connect() must be called after entering the context
+        await printer.connect()
+        await printer.wait_for_ready()
+        await printer.print_image("photo.png")
+        await printer.eject_paper()
+"""
+
+from phomemo import profiles  # noqa F401  # auto-load profiles at import time
+from phomemo.discovery import discover
+from phomemo.events import (
+    BatteryEvent,
+    DeviceEvent,
+    EventKind,
+    FirmwareEvent,
+    LidEvent,
+    LidState,
+    MotorStopEvent,
+    PaperEvent,
+    PaperState,
+    SerialEvent,
+    TimerEvent,
+)
+from phomemo.imaging import DitherMode, ImageFit, image_to_bitmap, prepare_image
+from phomemo.printer import Printer
+from phomemo.protocol import Density
+from phomemo.registry import (
+    PrinterProfile,
+    get_profile,
+    list_profiles,
+    register_profile,
+)
+
+__all__ = [
+    "BatteryEvent",
+    "Density",
+    "DeviceEvent",
+    "DitherMode",
+    "EventKind",
+    "FirmwareEvent",
+    "ImageFit",
+    "LidEvent",
+    "LidState",
+    "MotorStopEvent",
+    "PaperEvent",
+    "PaperState",
+    "Printer",
+    "PrinterProfile",
+    "SerialEvent",
+    "TimerEvent",
+    "discover",
+    "get_profile",
+    "image_to_bitmap",
+    "list_profiles",
+    "prepare_image",
+    "register_profile",
+]

phomemo/bridge/__init__.py

@@ -0,0 +1,23 @@
+# This file is part of phomemo.
+# Copyright (C) 2026 Paul Bütof, Passionate Bytes Solutions
+#
+# phomemo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# phomemo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with phomemo.  If not, see <https://www.gnu.org/licenses/>.
+
+"""The bridge: drives a printer over a unix socket for the printer app.
+
+The bridge owns the device side (Bluetooth connection, raster encoding, tone
+conversion, sheet handling); a printer app owns the IPP side and
+talks to the bridge with a few JSON commands. See ``protocol`` for the wire
+format and ``server`` for the command set.
+"""

phomemo/bridge/__main__.py

@@ -0,0 +1,315 @@
+# This file is part of phomemo.
+# Copyright (C) 2026 Paul Bütof, Passionate Bytes Solutions
+#
+# phomemo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# phomemo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with phomemo.  If not, see <https://www.gnu.org/licenses/>.
+
+"""``phomemo-bridge`` command line: run the bridge or drive it directly.
+
+Sub-command names follow the printer app's where both do the same
+thing (``server``, ``devices``, ``status``).
+"""
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+import textwrap
+from importlib.metadata import version
+from pathlib import Path
+
+from phomemo.bridge.client import MEDIA, QUALITY, BridgeClient, BridgeError
+from phomemo.bridge.config import ConfigError, load_config
+from phomemo.bridge.server import serve
+from phomemo.imaging import ToneMode
+
+_PRINTER_CHOICE = (
+    "Which printer: the one given with --address, else the printer connectioned or "
+    "used last since the bridge started, else the only printer of a known model "
+    "a scan finds. With several printers in range and none of these, the "
+    'command refuses and lists them; pick one with --address (see "devices"). '
+    "The model comes from the printer's advertised name."
+)
+
+_COMMANDS: dict[str, tuple[str, str]] = {
+    "server": (
+        "run the bridge service",
+        "Run the bridge in the foreground: listen on the socket, own the "
+        "Bluetooth connection to the printer and serve the printer app and "
+        "this command line. The packaged system service runs this.",
+    ),
+    "devices": (
+        "list printers in range",
+        "Scan for printers of every known model and list each one's Bluetooth "
+        "address, model and advertised name. A printer shows up only while it "
+        "is switched on and not linked to another host.",
+    ),
+    "connect": (
+        "connect to the printer",
+        "Connect to the printer over Bluetooth. The bridge keeps the connection until "
+        "the printer switches off or leaves range, or until "
+        "idle_disconnect_minutes pass without a command (see the "
+        "configuration), so later commands and jobs skip the reconnect. At each "
+        "new connection the bridge sets the printer's "
+        "auto-off timer to auto_off_minutes when that key is set.\n\n"
+        + _PRINTER_CHOICE,
+    ),
+    "disconnect": (
+        "drop the connection now",
+        "Drop the Bluetooth connection right away instead of after the idle time, so "
+        "another host (a phone, another computer) can reach the printer.",
+    ),
+    "status": (
+        "show connection, sensors and device details",
+        "Show whether the bridge holds a connection and, when it does, the connected "
+        "printer's address, lid and paper sensors, battery, firmware, serial "
+        "number and auto-off timer. Without a connection, shows the values last read "
+        'from that printer under "last_seen", with the time they were read. Does '
+        'not connect by itself; run "connect" first. With --address, reports on '
+        "that printer.",
+    ),
+    "auto-off": (
+        "show or set the auto-off timer",
+        "Show the linked printer's auto-off timer, or set it first when MINUTES "
+        "is given (a multiple of 5 up to 1275; 0 = never switch off). When "
+        "auto_off_minutes is set in the configuration, the bridge writes that "
+        "value again at the next connection, so change the key for a lasting "
+        'setting. Needs a connection; run "connect" first.',
+    ),
+    "print": (
+        "print one image file as a page",
+        "Print an image file (PNG, JPEG, anything Pillow reads) as one page, "
+        "scaled to the media width, then eject the sheet.\n\n" + _PRINTER_CHOICE,
+    ),
+    "eject": (
+        "feed the sheet out",
+        "Feed the loaded sheet out of the printer.\n\n" + _PRINTER_CHOICE,
+    ),
+    "identify": (
+        "make the printer show itself",
+        "Eject a loaded sheet, then pulse the paper feed three times so you can "
+        "tell which printer this is.\n\n" + _PRINTER_CHOICE,
+    ),
+    "testpage": (
+        "print the test page",
+        "Print the test page: device details, millimetre scales, a gray ramp, "
+        "line widths and text samples.\n\n" + _PRINTER_CHOICE,
+    ),
+}
+
+
+def _parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="phomemo-bridge", description=__doc__)
+    ap.add_argument(
+        "--config", type=Path, help="read this TOML file instead of the defaults"
+    )
+    ap.add_argument("-v", "--verbose", action="store_true", help="debug logging")
+    ap.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('phomemo')}",
+        help="print the version and exit",
+    )
+    ap.set_defaults(address=None)
+    sub = ap.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    # Shared by every command that works on one printer.
+    printer_choice = argparse.ArgumentParser(add_help=False)
+    printer_choice.add_argument(
+        "-a",
+        "--address",
+        help="Bluetooth address of the printer to use (AA:BB:CC:DD:EE:FF)",
+    )
+
+    def add(name: str, targets_printer: bool = True) -> argparse.ArgumentParser:
+        summary, description = _COMMANDS[name]
+        paragraphs = description.split("\n\n")
+        return sub.add_parser(
+            name,
+            parents=[printer_choice] if targets_printer else [],
+            help=summary,
+            description="\n\n".join(textwrap.fill(p, 79) for p in paragraphs),
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+
+    add("server", targets_printer=False)
+    devices = add("devices", targets_printer=False)
+    devices.add_argument(
+        "--timeout", type=float, default=5.0, help="scan seconds (default: 5)"
+    )
+    add("connect")
+    add("disconnect", targets_printer=False)
+    add("status")
+    auto_off = add("auto-off")
+    auto_off.add_argument(
+        "minutes", type=int, nargs="?", help="new timeout in minutes, 0 = never"
+    )
+    pr = add("print")
+    pr.add_argument("file", type=Path, help="image file to print")
+    pr.add_argument(
+        "--media", choices=sorted(MEDIA), default="a4", help="sheet size (default: a4)"
+    )
+    pr.add_argument(
+        "--tone",
+        choices=["auto", *[t.value for t in ToneMode]],
+        default="auto",
+        help="how gray becomes dots (default: auto, chosen from the content)",
+    )
+    pr.add_argument(
+        "--quality",
+        choices=sorted(QUALITY),
+        default="normal",
+        help="print density (default: normal)",
+    )
+    pr.add_argument(
+        "--content",
+        choices=["auto", "text", "graphic", "photo"],
+        default="auto",
+        help="content hint for --tone auto (default: auto)",
+    )
+    pr.add_argument(
+        "--abort-after",
+        type=float,
+        metavar="SECONDS",
+        help="cancel the page this many seconds into the transfer (testing)",
+    )
+    add("eject")
+    add("identify")
+    tp = add("testpage")
+    tp.add_argument(
+        "--quality",
+        choices=sorted(QUALITY),
+        default="normal",
+        help="print density (default: normal)",
+    )
+    return ap
+
+
+def _fail(message: str) -> int:
+    print(f"error: {message}", file=sys.stderr)
+    return 1
+
+
+async def _linked(client: BridgeClient, address: str | None) -> dict | None:
+    """The bridge's status when connected to ``address`` (or any printer)."""
+    status = await client.status(address)
+    return status if status["connected"] else None
+
+
+async def _status(client: BridgeClient, address: str | None) -> dict:
+    status = await client.status(address)
+    if not status["connected"]:
+        return status
+    info = await client.info()
+    for key in ("firmware", "serial", "auto_off_minutes"):
+        status[key] = info[key]
+    return status
+
+
+async def _run_client(args: argparse.Namespace, socket_path: Path) -> int:
+    def show(event: dict) -> None:
+        print(json.dumps(event), file=sys.stderr)
+
+    async with BridgeClient(socket_path, on_event=show) as client:
+        if args.command in ("connect", "print", "eject", "identify", "testpage"):
+            opened = await client.open(args.address)
+            if not opened["connected"] and args.command != "print":
+                return _fail(f"not reachable: {opened.get('reason', 'unknown')}")
+        if args.command == "connect":
+            status = await client.status()
+            print(f"connected to {status.get('address')}")
+        elif args.command == "disconnect":
+            await client.drop_link()
+            print("disconnected")
+        elif args.command == "status":
+            print(json.dumps(await _status(client, args.address), indent=2))
+        elif args.command == "auto-off":
+            status = await _linked(client, args.address)
+            if status is None:
+                return _fail('not connected; run "phomemo-bridge connect" first')
+            minutes = await client.auto_off(args.minutes)
+            shown = "never" if minutes == 0 else f"{minutes} min"
+            print(f"{status['address']}: auto-off {shown}")
+        elif args.command == "print":
+            impressions = await client.print_image(
+                args.file,
+                media=args.media,
+                tone=args.tone,
+                quality=args.quality,
+                content=args.content,
+                abort_after=args.abort_after,
+            )
+            print(f"printed {impressions} page(s)")
+        elif args.command == "devices":
+            printers = await client.discover(args.timeout)
+            for printer in printers:
+                print(f"{printer['address']}  {printer['model']:<8}  {printer['name']}")
+            if not printers:
+                print("no printer in range", file=sys.stderr)
+                return 1
+        elif args.command == "eject":
+            print("ejected" if await client.eject() else "sheet still present")
+            await client.close()
+        elif args.command == "identify":
+            await client.identify()
+            await client.close()
+            print("identified")
+        elif args.command == "testpage":
+            impressions = await client.print_test_page(quality=args.quality)
+            print(f"printed {impressions} page(s)")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point.
+
+    Args:
+        argv: Arguments without the program name; ``None`` uses ``sys.argv``.
+
+    Returns:
+        Process exit status.
+    """
+    args = _parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    )
+    try:
+        config = load_config(
+            paths=[args.config] if args.config else None,
+            require_files=args.config is not None,
+        )
+    except ConfigError as exc:
+        print(f"configuration error: {exc}", file=sys.stderr)
+        return 2
+    try:
+        if args.command == "server":
+            asyncio.run(serve(config))
+            return 0
+        return asyncio.run(_run_client(args, config.socket_path))
+    except KeyboardInterrupt:
+        return 130
+    except BridgeError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except (ConnectionError, FileNotFoundError) as exc:
+        print(
+            f"cannot reach the bridge at {config.socket_path}: {exc}", file=sys.stderr
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())