PrintMQTTify is a Docker-based solution that bridges MQTT messages to a CUPS printer, allowing you to print messages from your MQTT broker seamlessly. This is particularly useful in smart home setups for automating printing tasks, such as printing shopping lists or event reminders directly from Home Assistant. This project provides an easy way to connect printers to your smart home system, such as Home Assistant, and send print commands using MQTT.
-
CUPS Integration: Provides a fully functional CUPS server, capable of managing multiple printers and supporting advanced configurations.
-
MQTT Print Jobs: Listens for MQTT messages to process print jobs efficiently.
-
USB Printer Support: Compatible with USB printers and supports custom drivers.
-
Customizable Output: Allows for tailored print outputs, such as formatted receipts or shopping lists.
-
Web-Based Control Panel: Includes an optional web interface for managing basic settings and monitoring.
-
Designed for Home Automation: Perfect for smart home environments like Home Assistant.
Here are some scenarios where PrintMQTTify shines:
-
Smart Home Shopping Lists:
-
Automatically print unchecked items from a Home Assistant shopping list.
-
Example scripts are available in the HA Script Examples.
-
-
Event Reminders:
- Print reminders or daily schedules directly from your smart home system.
-
Custom Receipts:
- Generate and print receipts with tailored formatting for events or transactions.
-
Dynamic Content Printing:
- Send custom messages, recipes, or instructions directly to your printer via MQTT.
-
Docker: Ensure Docker is installed and running on your system.
-
Git: Ensure Git is installed to clone the repository.
-
MQTT Broker: A working MQTT broker (e.g., Mosquitto) is required. Note the broker's IP address, username, and password.
-
USB Printer Identification:
-
Use
lsusbanddmesg | grep usbto locate the device path of your printer. -
Ensure the path (e.g.,
/dev/usb/lp0) is passed to the container.
Example:
Bash
lsusb dmesg | grep usb -
Before cloning, ensure you have installed Docker, Git, and have a working MQTT broker. Clone the PrintMQTTify repository to your local machine:
Bash
git clone https://github.com/Aesgarth/PrintMQTTify.git
cd PrintMQTTify
Build the Docker image using the included Dockerfile:
Bash
docker build -t printmqttify .
Start the container with the following command:
The docker run command includes the following flags:
-
--name printmqttify_container: Names the container for easier management. -
-d: Runs the container in detached mode. -
--privileged: Grants the container extended privileges, necessary for USB access. -
-p 631:631: Maps the container's CUPS web interface port to the host. -
--device=/dev/usb/lp0:/dev/usb/lp0: Maps the USB printer device to the container. -
--ulimit nofile=65536:65536: Sets the open file limit to prevent issues with newer Docker versions. -
-e: Sets environment variables like MQTT broker credentials and admin user details for CUPS.
Bash
docker run --name printmqttify_container\
-d\
--privileged\
-p 631:631\
--device=/dev/usb/lp0:/dev/usb/lp0\
--ulimit nofile=65536:65536\
-e MQTT_BROKER="<your-mqtt-broker-ip>"\
-e MQTT_USERNAME="<your-mqtt-username>"\
-e MQTT_PASSWORD="<your-mqtt-password>"\
-e MQTT_TOPIC="printer/commands"\
-e ADMIN_USER="admin"\
-e ADMIN_PASS="adminpassword"\
printmqttify
Replace the placeholders (<your-mqtt-broker-ip>, <your-mqtt-username>, etc.) with your actual MQTT broker details.
Alternatively, you can use Docker Compose to manage the container. Create a docker-compose.yml file with the following content:
YAML
version: '3.8'
services:
printmqttify:
image: printmqttify
container_name: printmqttify_container
privileged: true
ports:
- "631:631"
devices:
- "/dev/usb/lp0:/dev/usb/lp0"
environment:
- MQTT_BROKER=<your-mqtt-broker-ip>
- MQTT_USERNAME=<your-mqtt-username>
- MQTT_PASSWORD=<your-mqtt-password>
- MQTT_TOPIC=printer/commands
- ADMIN_USER=admin
- ADMIN_PASS=adminpassword
ulimits:
nofile:
soft: 65536
hard: 65536
stdin_open: true
tty: true
Then start the container with:
Bash
docker-compose up -d
-
Open a browser and navigate to:
https://<host-ip>:631Replace
<host-ip>with the IP address of the machine running the container. -
Log in using the CUPS admin credentials:
-
Username:
admin(or as set inADMIN_USER) -
Password:
adminpassword(or as set inADMIN_PASS)
-
-
In the CUPS interface, go to Administration > Add Printer.
-
Select the connected USB printer.
-
Choose the appropriate driver (e.g., SEWOO LKT-Series).
-
Complete the setup and test the printer by printing a test page.
If your printer doesn't print the message, ensure the following:
-
The
printer_namein the payload matches the name configured in the CUPS web interface. -
The MQTT broker details in the container are correct.
-
The printer is connected and has no pending errors in the CUPS interface.
-
Check the logs for any errors:
Bash
docker logs printmqttify_container
Use Home Assistant to send a message to your printer via MQTT:
-
Go to Developer Tools > Services in Home Assistant.
-
Select the
mqtt.publishservice. -
Enter the following data:
YAML
service: mqtt.publish data: topic: "printer/commands" payload: '{"printer_name": "SEWOO_LK-T100", "message": "Hello, World!"}' -
Click Call Service.
Check your printer to confirm that the message has been printed. If the message does not print, check the container logs for errors:
Bash
docker logs printmqttify_container
For troubleshooting steps and common issues, see the Troubleshooting Documentation.
By default, PrintMQTTify forces all printouts into a "portrait" orientation. This ensures that even very short lists are printed with the text oriented vertically. However, if you prefer short lists to be printed in "landscape" (horizontally), you can revert to the old behavior by making a small change to the code.
Follow these steps to allow landscape printing:
-
Open the handler file: Edit the
app/printer_mqtt_handler.pyfile in the repository. -
Locate the
generate_pdffunction: Find the function namedgenerate_pdf. -
Modify the
page_heightcalculation: Inside this function, find the following line:Python
page_height = max(calculated_height, page_width + 1) -
Change the line: Replace the line above with the original calculation:
Python
page_height = calculated_height -
Rebuild the Docker image: After saving your changes, rebuild the Docker image for the changes to take effect:
Bash
docker build -t printmqttify . -
Restart the container: Stop and restart your Docker container to apply the new image.
Contributions are welcome! Feel free to submit issues or pull requests on GitHub.
This project is licensed under the Creative Commons Zero v1.0 Universal (CC0 1.0) License. See the LICENSE file for more details.