{"id":34786815,"url":"https://github.com/zacs/ha-receipt_printer","last_synced_at":"2026-01-13T20:43:45.239Z","repository":{"id":330401627,"uuid":"1111571479","full_name":"zacs/ha-receipt_printer","owner":"zacs","description":"Epson receipt printer custom component for Home Assistant","archived":false,"fork":false,"pushed_at":"2025-12-28T07:10:30.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-03T06:53:05.115Z","etag":null,"topics":["epson","epson-printer","home-assistant","home-assistant-component","home-assistant-integration","homeassistant","homeassistant-custom-component"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zacs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-07T07:56:31.000Z","updated_at":"2025-12-28T07:09:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zacs/ha-receipt_printer","commit_stats":null,"previous_names":["zacs/ha-receipt_printer"],"tags_count":7,"template":false,"template_full_name":"ludeeus/integration_blueprint","purl":"pkg:github/zacs/ha-receipt_printer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacs%2Fha-receipt_printer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacs%2Fha-receipt_printer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacs%2Fha-receipt_printer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacs%2Fha-receipt_printer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zacs","download_url":"https://codeload.github.com/zacs/ha-receipt_printer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacs%2Fha-receipt_printer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["epson","epson-printer","home-assistant","home-assistant-component","home-assistant-integration","homeassistant","homeassistant-custom-component"],"created_at":"2025-12-25T09:27:49.941Z","updated_at":"2026-01-13T20:43:45.234Z","avatar_url":"https://github.com/zacs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Receipt Printer for Home Assistant\r\n\r\n[![GitHub Release][releases-shield]][releases]\r\n[![GitHub Activity][commits-shield]][commits]\r\n[![License][license-shield]](LICENSE)\r\n\r\n[![hacs][hacsbadge]][hacs]\r\n\r\nIntegration to control Epson (or anything supported by the ESCPOS library) receipt printers from Home Assistant.\r\n\n_Disclaimer: This was vibe coded. It's a very straightforward and scoped component though, which makes me comfortable releasing it. It has been reviewed, and works well for me. But I want to be up front about that._\n\r\n## Features\r\n\r\n- **Print Services**: Three convenient services for printing:\r\n  - Print text with customizable formatting (alignment, font, bold, double height/width, word wrapping)\r\n  - Print local and remote images (PNG, JPG, GIF, BMP) with automatic resizing\r\n  - Print QR codes\r\n- **Remote Image Support**: Automatically downloads and prints images from URLs\r\n- **Automatic Resizing**: Images are automatically resized to fit your printer's width while maintaining aspect ratio\r\n- **Paper Cutting**: Optional automatic paper cutting after each print job\r\n- **Status Monitoring**: \r\n  - Binary sensor for online/offline status\r\n  - Sensor for paper status (ok, low, out)\r\n- **Configurable Printer Settings**: Support for different printer models with customizable column widths and dot/pixel widths (for images). \r\n\r\n## Installation\r\n\r\n### HACS (Recommended)\r\n\r\n1. In HACS, click on \"Integrations\"\r\n2. Click the three dots in the top right corner\r\n3. Select \"Custom repositories\"\r\n4. Add the URL `https://github.com/zacs/ha-receipt_printer` and select the category \"Integration\"\r\n5. Click the \"+\" button in the bottom right corner\r\n6. Search for \"Receipt Printer\"\r\n7. Click \"Install\"\r\n8. Restart Home Assistant\r\n\r\n### Manual Installation\r\n\r\n1. Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`)\r\n2. If you do not have a `custom_components` directory there, you need to create it\r\n3. In the `custom_components` directory create a new folder called `receipt_printer`\r\n4. Download all the files from the `custom_components/receipt_printer/` directory in this repository\r\n5. Place the files you downloaded in the new `receipt_printer` directory you created\r\n6. Restart Home Assistant\r\n\r\n## Configuration\r\n\r\n1. In the Home Assistant UI, navigate to \"Configuration\" -\u003e \"Integrations\"\r\n2. Click the \"+\" button to add a new integration\r\n3. Search for \"Receipt Printer\"\r\n4. Enter the following information:\r\n   - **Printer Name**: A friendly name for your printer (e.g., \"Kitchen Receipt Printer\")\r\n   - **Printer IP Address**: The IP address of your receipt printer on your network\r\n   - **Columns (Font A)**: Number of text columns for font A (default: 42, suitable for TM-T88V)\r\n   - **Columns (Font B)**: Number of text columns for font B (default: 56, suitable for TM-T88V)\r\n   - **Image Max Width**: Maximum image width in pixels (default: 512, suitable for TM-T88V)\r\n\r\nThe integration will attempt to connect to the printer and verify it's accessible. The column and image settings can be adjusted to match your specific printer model.\r\n\r\n### Printer Configuration Notes\r\n\r\nDifferent printer models support different widths:\r\n- **Epson TM-T88V/VI** (80mm): Font A = 42 columns, Font B = 56 columns, Image width = 512 pixels\r\n- For other models, consult your printer's documentation or the [python-escpos printer profiles](https://python-escpos.readthedocs.io/en/latest/printer_profiles/available-profiles.html)\r\n\r\n## Supported Printers\r\n\r\nThis integration uses the [python-escpos](https://github.com/python-escpos/python-escpos) library and supports **Epson ESC/POS compatible receipt printers** with network (TCP/IP) connectivity. \r\n\r\nTested models:\r\n- Epson TM-T88VI\r\n\r\nOther ESC/POS compatible printers should work but may require adjusting the column widths and image size settings during configuration.\r\n\r\n**Note**: USB and serial printers are not currently supported.\r\n\r\n## Usage\r\n\r\n### Status Monitoring\r\n\r\nOnce configured, the integration creates two entities for status monitoring:\r\n\r\n#### Binary Sensor: Online Status\r\n- **Connected**: Printer is online and accessible\r\n- **Disconnected**: Cannot communicate with printer\r\n\r\n#### Sensor: Paper Status\r\n- **ok**: Printer has adequate paper\r\n- **low**: Paper is running low (near-end sensor triggered)\r\n- **out**: Printer is out of paper\r\n\r\nThe paper status sensor will be unavailable when the printer is offline.\r\n\r\n### Services\r\n\r\nThe integration provides three services for printing:\r\n\r\n#### `receipt_printer.print_text`\r\n\r\nPrint text to the receipt printer with formatting options.\r\n\r\n**Service Data:**\r\n```yaml\r\nservice: receipt_printer.print_text\r\ndata:\r\n  text: \"Hello World!\\nThis is a test receipt.\"\r\n  align: center  # Options: left, center, right\r\n  font: a  # Options: a, b\r\n  bold: false\r\n  double_height: false\r\n  double_width: false\r\n  wrap: true  # Enable automatic word wrapping (default: true)\r\n  cut: true  # Cut paper after printing\r\n```\r\n\r\n**Word Wrapping**: When `wrap: true` (default), text will automatically wrap at word boundaries to fit the printer's configured column width. Set to `false` to disable wrapping and print text as-is.\r\n\r\n#### `receipt_printer.print_image`\r\n\r\nPrint an image file to the receipt printer. Images can be local file paths or remote URLs.\r\n\r\n**Service Data:**\r\n```yaml\r\nservice: receipt_printer.print_image\r\ndata:\r\n  image_path: \"/config/www/logo.png\"  # or \"https://example.com/image.jpg\"\r\n  center: true\r\n  cut: true\r\n```\r\n\r\n**Supported formats**: PNG, JPG, GIF, BMP\r\n\r\n**Image Handling**:\r\n- Local files: Use absolute paths (e.g., `/config/www/image.png`)\r\n- Remote images: Use full URLs (e.g., `https://example.com/image.jpg`)\r\n- Images wider than the configured max width are automatically resized while maintaining aspect ratio\r\n- Images smaller than the max width are printed at their original size\r\n\r\n#### `receipt_printer.print_qr`\r\n\r\nPrint a QR code to the receipt printer.\r\n\r\n**Service Data:**\r\n```yaml\r\nservice: receipt_printer.print_qr\r\ndata:\r\n  content: \"https://www.home-assistant.io\"\r\n  size: 3  # Size from 1-16\r\n  center: true\r\n  cut: true\r\n```\r\n\r\n## Example Automations\r\n\r\n### Print a welcome message when someone arrives home\r\n\r\n```yaml\r\nautomation:\r\n  - alias: \"Print Welcome Receipt\"\r\n    trigger:\r\n      - platform: state\r\n        entity_id: person.john\r\n        to: \"home\"\r\n    action:\r\n      - service: receipt_printer.print_text\r\n        data:\r\n          text: |\r\n            ================================\r\n                 WELCOME HOME JOHN!\r\n            ================================\r\n            \r\n            Time: {{ now().strftime('%H:%M:%S') }}\r\n            Date: {{ now().strftime('%Y-%m-%d') }}\r\n            \r\n            Temperature: {{ states('sensor.living_room_temperature') }}°C\r\n            \r\n            ================================\r\n          align: center\r\n          cut: true\r\n```\r\n\r\n### Print a shopping list QR code\r\n\r\n```yaml\r\nautomation:\r\n  - alias: \"Print Shopping List QR\"\r\n    trigger:\r\n      - platform: tag\r\n        tag_id: shopping_list\r\n    action:\r\n      - service: receipt_printer.print_text\r\n        data:\r\n          text: \"Scan for Shopping List:\"\r\n          align: center\r\n          bold: true\r\n          cut: false\r\n      - service: receipt_printer.print_qr\r\n        data:\r\n          content: \"https://your-shopping-list-url.com\"\r\n          size: 5\r\n          center: true\r\n          cut: true\r\n```\r\n\r\n### Print door access notification\r\n\r\n```yaml\r\nautomation:\r\n  - alias: \"Print Door Access Log\"\r\n    trigger:\r\n      - platform: state\r\n        entity_id: lock.front_door\r\n        to: \"unlocked\"\r\n    action:\r\n      - service: receipt_printer.print_text\r\n        data:\r\n          text: |\r\n            DOOR ACCESS LOG\r\n            {{ now().strftime('%Y-%m-%d %H:%M:%S') }}\r\n            \r\n            Front door unlocked\r\n            {% if trigger.to_state.attributes.user_id %}\r\n            User: {{ trigger.to_state.attributes.user_id }}\r\n            {% endif %}\r\n          align: left\r\n          cut: true\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Printer not connecting\r\n\r\n1. Verify the printer's IP address is correct\r\n2. Ensure the printer is powered on and connected to your network\r\n3. Check that your Home Assistant instance can reach the printer's IP (try pinging it)\r\n4. Verify no firewall is blocking communication on the printer's port (typically 9100)\r\n\r\n### Print quality issues\r\n\r\n- Clean the printer's print head according to manufacturer instructions\r\n- Check paper quality and ensure it's compatible with thermal printing\r\n- Verify paper is loaded correctly\r\n\r\n### Paper status not updating\r\n\r\nThe paper status depends on the printer's sensors. Some printer models may not support all status queries. The integration will still function for printing even if status updates are unavailable.\r\n\r\n## Development\r\n\r\nThis integration is built using the [python-escpos](https://python-escpos.readthedocs.io/) library. Contributions are welcome!\r\n\r\n## Support\r\n\r\n- [Report a Bug](https://github.com/zacs/ha-receipt_printer/issues/new?template=bug_report.yml)\r\n- [Request a Feature](https://github.com/zacs/ha-receipt_printer/issues/new?template=feature_request.yml)\r\n\r\n## Credits\r\n\r\n- Built on top of the [python-escpos](https://github.com/python-escpos/python-escpos) library\r\n- Integration structure based on [integration_blueprint](https://github.com/ludeeus/integration_blueprint)\r\n\r\n### Notes\r\n\r\nEpson spec sheet for the TM-T88VI (the only model I have): https://download4.epson.biz/sec_pubs/pos/reference_en/epos_and/ref_epos_sdk_and_en_printer-specificsupportinformation_tm-t88vi.html\r\n\r\n---\r\n\r\n[commits-shield]: https://img.shields.io/github/commit-activity/y/zacs/ha-receipt_printer.svg?style=for-the-badge\r\n[commits]: https://github.com/zacs/ha-receipt_printer/commits/main\r\n[hacs]: https://github.com/hacs/integration\r\n[hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge\r\n[license-shield]: https://img.shields.io/github/license/zacs/ha-receipt_printer.svg?style=for-the-badge\r\n[releases-shield]: https://img.shields.io/github/release/zacs/ha-receipt_printer.svg?style=for-the-badge\r\n[releases]: https://github.com/zacs/ha-receipt_printer/releases\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzacs%2Fha-receipt_printer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzacs%2Fha-receipt_printer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzacs%2Fha-receipt_printer/lists"}