andresramirez991228/hprt-open-bridge repository overview

⁠hprt-open-bridge

HTTP bridge for HPRT CP4x Wi‑Fi photo printers (CP4100 and family).

Web browsers cannot open raw TCP/UDP sockets, and these printers only speak a binary protocol over TCP and UDP. This service speaks that protocol for you and exposes a simple HTTP + SSE API, so a web app (like PhotoPrint) can find, connect to and print on the printer.

Web app ── HTTP + SSE ──► hprt-open-bridge ── TCP 9901 / 9100 · UDP 6000 ──► printer

⁠Features

• Discovery: finds printers on the local network with the UDP probe of the vendor app.
• Connect and keep alive:
  • wakes printers that are in Wi‑Fi power saving;
  • sends a heartbeat every 3 s;
  • reconnects on its own when the link drops.
• Printing:
  • sends a ready-to-print JPEG and answers when the printer finishes;
  • follows every stage: yellow, magenta, cyan, laminate;
  • retries once if the link dropped before the photo was sent;
  • can cancel the running job.
• Live events over Server‑Sent Events: printer state, job progress and protocol log.
• Printer status: battery, firmware, serial number, print counter, paper/ribbon errors, reservation.
• Link quality: latency of each heartbeat, average, peak and packet loss.
• Network diagnostics of the host:
  • ping to the printer;
  • Wi‑Fi network in use;
  • gateway (also in printer hotspot mode);
  • scan of the 2.4 GHz networks.
• Printer IP changed? If the connection fails, the bridge looks for the printer on the LAN by its serial number.
• Graceful shutdown: docker stop closes the streams, waits for running requests and releases the printer.

⁠Quick start

The container needs the host network: UDP discovery and the printer on your LAN cannot be reached through Docker's NAT network.

docker run -d --name hprt-open-bridge --network host andresramirez991228/hprt-open-bridge
curl http://localhost:8787/api/state

With the Wi‑Fi diagnostics (they talk to the NetworkManager of the host through D‑Bus):

docker run -d --name hprt-open-bridge --network host \
  --security-opt apparmor=unconfined \
  -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket \
  andresramirez991228/hprt-open-bridge

⁠Docker Compose

 bridge:
    container_name: bridge
    image: andresramirez991228/hprt-open-bridge:v1.1.0
    network_mode: host # UDP discovery and the printer on the LAN need the host network
    environment:
      BRIDGE_APP_REST_ADDR: 0.0.0.0:8787
    volumes:
      # nmcli in the container asks the NetworkManager of the Raspberry through D-Bus (Wi-Fi scan, host Wi-Fi, hotspot gateway)
      - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket
    security_opt:
      # The default AppArmor profile of Docker blocks D-Bus (harmless where AppArmor is not active)
      - apparmor:unconfined
    restart: unless-stopped

⁠Configuration

Every setting can be changed with an environment variable BRIDGE_<SECTION>_<KEY>:

You can also mount your own file at /app/config.yaml.

⁠API

Example:

curl -X POST localhost:8787/api/connect -H 'Content-Type: application/json' -d '{"ip":"192.168.1.50"}'
curl -X POST localhost:8787/api/print -H 'Content-Type: image/jpeg' --data-binary @photo.jpg

The JPEG must already have the size of the page: 1232 × 1786 px (100 × 148 mm at 300 dpi). Most models expect the image rotated 180°.

Errors always have the same shape:

{"error": "No printer connected", "module": "printer", "internal_code": 1003, "message": "No printer connected", "http_code": 409}

⁠Notes

• Ports used on the printer: TCP 9100 (image), TCP 9901 (commands), UDP 6000 (discovery).
• The printers only join 2.4 GHz Wi‑Fi networks.
• Bluetooth setup of the printer (changing its Wi‑Fi network, hotspot mode) is done by the web app with Web Bluetooth, not by this image.
• Linux hosts only (network_mode: host).