{"id":33510151,"url":"https://github.com/adcondev/poster","last_synced_at":"2026-01-17T20:14:47.935Z","repository":{"id":310118099,"uuid":"1038735283","full_name":"adcondev/poster","owner":"adcondev","description":"(WIP) POS Printer is a Go library that provides a unified, developer-friendly interface for communicating with a wide range of POS (Point of Sale) printer models. Designed with a clean and modular architecture, it simplifies the process of sending commands to thermal printers, whether you need to print text, generate QR codes, or render images.","archived":false,"fork":false,"pushed_at":"2026-01-12T10:33:35.000Z","size":13697,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-13T10:37:16.260Z","etag":null,"topics":["api","barcode","escpos","escpos-image","escpos-printer","escpos-proxy","golang-library","json-api","json-parser","modular","point-of-sale","pos-system","qrcode","thermal-printer","wip","work-in-progress"],"latest_commit_sha":null,"homepage":"","language":"Go","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/adcondev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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-08-15T18:18:27.000Z","updated_at":"2026-01-08T20:38:24.000Z","dependencies_parsed_at":"2025-08-15T22:34:24.189Z","dependency_job_id":"44fa9c7d-cae0-47b8-b2b5-3b51f0800411","html_url":"https://github.com/adcondev/poster","commit_stats":null,"previous_names":["adcondev/pos-printer","adcondev/poster"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/adcondev/poster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adcondev%2Fposter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adcondev%2Fposter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adcondev%2Fposter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adcondev%2Fposter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adcondev","download_url":"https://codeload.github.com/adcondev/poster/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adcondev%2Fposter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28517429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T18:55:29.170Z","status":"ssl_error","status_checked_at":"2026-01-17T18:55:03.375Z","response_time":85,"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":["api","barcode","escpos","escpos-image","escpos-printer","escpos-proxy","golang-library","json-api","json-parser","modular","point-of-sale","pos-system","qrcode","thermal-printer","wip","work-in-progress"],"created_at":"2025-11-26T04:04:31.105Z","updated_at":"2026-01-17T20:14:47.923Z","avatar_url":"https://github.com/adcondev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Poster: Thermal Printer Driver \u0026 ESC/POS Utility\n\n![Go Version](https://img.shields.io/badge/go-1.24+-00ADD8?style=flat\u0026logo=go)\n![Platform](https://img.shields.io/badge/platform-windows-blue?style=flat\u0026logo=windows)\n![License](https://img.shields.io/badge/license-MIT-green)\n[![CI](https://github.com/adcondev/poster/actions/workflows/ci.yml/badge.svg)](https://github.com/adcondev/poster/actions/workflows/ci.yml)\n\n[![CodeQL](https://github.com/adcondev/poster/actions/workflows/codeql.yml/badge.svg)](https://github.com/adcondev/poster/security/code-scanning)\n[![Release](https://github.com/adcondev/poster/actions/workflows/release.yml/badge.svg)](https://github.com/adcondev/poster/actions/workflows/release.yml)\n\n[![codecov](https://codecov.io/github/adcondev/poster/graph/badge.svg?token=X9KVG99DDZ)](https://codecov.io/github/adcondev/poster)\n[![Go Report Card](https://goreportcard.com/badge/github.com/adcondev/poster)](https://goreportcard.com/report/github.com/adcondev/poster)\n[![Go Reference](https://pkg.go.dev/badge/github.com/adcondev/poster.svg)](https://pkg.go.dev/github.com/adcondev/poster)\n\n[![Dependabot Status](https://flat.badgen.net/github/dependabot/adcondev/poster)](https://github.com/adcondev/poster/network/updates)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat)](https://conventionalcommits.org)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/images/poster.png\" alt=\"POS Printer Logo\" width=\"576\"\u003e\n\u003c/p\u003e\n\nA professional, production-ready Go library and command-line utility for controlling ESC/POS thermal printers. Designed for high-reliability retail and POS environments, it features a robust JSON-based document protocol, native Windows Spooler integration, an advanced graphics engine, and a **visual emulator** for testing without physical hardware.\n\n## 🚀 Key Features\n\n- **JSON Document Protocol**: Define print jobs using a clean, versioned JSON schema (`v1.0`). Decouples business logic from hardware commands with full schema validation.\n- **Native Windows Integration**: Prints directly via the Windows Print Spooler API (`winspool.drv`), supporting USB, Serial, and Network printers installed in Windows.\n- **Advanced Graphics Engine**:\n    - High-quality image printing with **Atkinson Dithering**.\n    - Automatic scaling with bilinear interpolation.\n    - Supports PNG, JPG, BMP formats.\n- **Smart QR \u0026 Barcodes**: Automatically chooses between native printer firmware commands (fastest) or software rendering (maximum compatibility) based on the printer profile.\n- **Dynamic Table Layout**: Built-in engine for generating perfectly aligned receipts with word wrapping, multi-column\n  support, configurable spacing, **automatic overflow detection**, and **smart column auto-reduction** that preserves\n  small columns while shrinking larger ones to fit paper width.\n- **Visual Emulator**: Render print jobs as PNG images for preview and testing without physical hardware.\n- **Hardware Agnostic**: Includes profiles for standard 80mm (Epson-compatible), 58mm (generic), and PT-210 portable printers.\n- **Raw Command Support**: Send raw ESC/POS bytes when full control is needed.\n\n## 🏗️ Architecture\n\nThe project follows a layered architecture to ensure modularity and testability:\n\n```mermaid\ngraph TD\n    JSON[JSON Document] --\u003e Parser[Parser \u0026 Validator]\n    Parser --\u003e Executor[Command Executor]\n    Executor --\u003e Service[Printer Service]\n\n    subgraph Core Logic\n        Service --\u003e Protocol[ESC/POS Composer]\n        Service --\u003e Profile[Device Profile]\n        Service --\u003e Graphics[Graphics Engine]\n        Service --\u003e Tables[Table Engine]\n    end\n\n    Service --\u003e Connector[Connection Interface]\n\n    subgraph Output Layer\n        Connector --\u003e WinAPI[Windows Spooler API]\n        Connector --\u003e Emulator[Visual Emulator]\n        WinAPI --\u003e Device[Physical Printer]\n        Emulator --\u003e PNG[PNG Image]\n    end\n```\n\n### Package Structure\n\n| Package          | Description                                                                                                                         |\n|------------------|-------------------------------------------------------------------------------------------------------------------------------------|\n| `pkg/commands`   | ESC/POS command implementations (barcode, character, qrcode, etc.)                                                                  |\n| `pkg/composer`   | ESC/POS byte sequence generation                                                                                                    |\n| `pkg/connection` | Connection interfaces (Windows Spooler, Network, Serial, File)                                                                      |\n| `pkg/constants`  | Shared constants and unit conversions                                                                                               |\n| `pkg/document`   | Document parsing, building, and execution (schema, builder, executor)                                                               |\n| `pkg/emulator`   | Visual emulator for rendering print jobs as images                                                                                  |\n| `pkg/graphics`   | Image processing, dithering, and bitmap handling                                                                                    |\n| `pkg/profile`    | Printer profiles and character encoding tables                                                                                      |\n| `pkg/service`    | High-level printer service facade                                                                                                   |\n| `pkg/table`      | Create formatted tables with column alignment, word wrapping, header styling, and automatic width reduction for overflow protection |                                         |\n\n## 📦 Installation\n\n### Prerequisites\n\n- Go 1.24 or higher\n- Windows OS (for native spooler support)\n\n### Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/adcondev/poster.git\n\n# Navigate to the project directory\ncd poster\n\n# Build the binary\ngo build -o poster.exe ./cmd/poster\n```\n\n## 📖 Usage\n\n### Command Line Interface (CLI)\n\nThe `poster` utility takes a JSON document and sends it to a specified printer.\n\n```bash\n# Print a document to a specific printer\nposter.exe -file receipt.json -printer \"EPSON TM-T88V\"\n\n# Print via network\nposter.exe -t network -network 192.168.1.100:9100 receipt.json\n\n# Print via serial port\nposter.exe -t serial -serial COM1 -baud 115200 receipt.json\n\n# Output to file (for debugging or emulator)\nposter.exe -t file -output receipt.prn receipt.json\n\n# Dry-run (validate JSON without printing)\nposter.exe -file receipt.json --dry-run\n\n# Show version\nposter.exe -v\n\n# List available options\nposter.exe -h\n```\n\n### JSON Document Example\n\nCreate a file named `ticket.json`:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"profile\": {\n    \"model\": \"Generic 80mm\",\n    \"paper_width\": 80,\n    \"dpi\": 203,\n    \"has_qr\": true\n  },\n  \"commands\": [\n    {\n      \"type\": \"text\",\n      \"data\": {\n        \"content\": {\n          \"text\": \"STORE NAME\",\n          \"content_style\": {\n            \"bold\": true,\n            \"size\": \"2x2\",\n            \"align\": \"center\"\n          }\n        }\n      }\n    },\n    {\n      \"type\": \"separator\",\n      \"data\": {\n        \"char\": \"-\"\n      }\n    },\n    {\n      \"type\": \"table\",\n      \"data\": {\n        \"definition\": {\n          \"columns\": [\n            { \"header\": \"Item\", \"width\": 20, \"align\":  \"left\" },\n            { \"header\":  \"Price\", \"width\": 10, \"align\": \"right\" }\n          ]\n        },\n        \"show_headers\": true,\n        \"rows\": [\n          [\"Coffee\", \"$3.50\"],\n          [\"Sandwich\", \"$8.00\"]\n        ],\n        \"options\": {\n          \"header_bold\": true,\n          \"word_wrap\": true,\n          \"column_spacing\": 1,\n          \"auto_reduce\": true\n        }\n      }\n    },\n    {\n      \"type\": \"qr\",\n      \"data\": {\n        \"data\": \"https://example.com\",\n        \"align\": \"center\",\n        \"pixel_width\": 150\n      }\n    },\n    {\n      \"type\": \"cut\",\n      \"data\": {\n        \"feed\": 3\n      }\n    }\n  ]\n}\n```\n\n### Library Usage (Go)\n\nYou can also use the packages directly in your Go application:\n\n```go\npackage main\n\nimport (\n\t\"github.com/adcondev/poster/pkg/composer\"\n\t\"github.com/adcondev/poster/pkg/connection\"\n\t\"github.com/adcondev/poster/pkg/profile\"\n\t\"github.com/adcondev/poster/pkg/service\"\n)\n\nfunc main() {\n\t// 1. Configure Profile\n\tprof := profile.CreateProfile80mm()\n\n\t// 2. Connect to Printer\n\tconn, _ := connection.NewWindowsPrintConnector(\"POS-80\")\n\tdefer conn.Close()\n\n\t// 3. Initialize Service\n\tproto := composer.NewEscpos()\n\tprinter, _ := service.NewPrinter(proto, prof, conn)\n\tdefer printer.Close()\n\n\t// 4. Print\n\tprinter.Initialize()\n\tprinter.PrintLine(\"Hello World!\")\n\tprinter.FullFeedAndCut(2)\n}\n```\n\n## 📋 Supported Commands\n\n| Command     | Description                                                         |\n|-------------|---------------------------------------------------------------------|\n| `text`      | Print formatted text with styles (bold, underline, inverse, sizing) |\n| `image`     | Print images with dithering and scaling options                     |\n| `barcode`   | Generate barcodes (CODE128, EAN13, UPC-A, CODE39, etc.)             |\n| `qr`        | Generate QR codes with optional logos and human-readable text       |\n| `table`     | Create formatted tables with column alignment and word wrapping     |\n| `separator` | Print separator lines                                               |\n| `feed`      | Advance paper by specified lines                                    |\n| `cut`       | Perform full or partial paper cut                                   |\n| `raw`       | Send raw ESC/POS bytes directly                                     |\n\nFor complete documentation, see [api/v1/DOCUMENT_V1.md](api/v1/DOCUMENT_V1.md).\n\n## ⚙️ Configuration\n\n### Connection Types\n\n| Type      | Description                                                                          |\n|-----------|--------------------------------------------------------------------------------------|\n| `windows` | Windows Print Spooler (default). Best for USB/Network printers installed in Windows. |\n| `network` | Direct network connection via Raw TCP/9100                                           |\n| `serial`  | Serial/USB direct connection (COM ports)                                             |\n| `file`    | Output to file for debugging or emulator testing                                     |\n\n### Printer Profiles\n\nThe library includes built-in profiles for common hardware:\n\n| Profile               | Description                                  |\n|-----------------------|----------------------------------------------|\n| `CreateProfile80mm()` | Standard ESC/POS 80mm (Epson TM-T88, etc.)   |\n| `CreateProfile58mm()` | Generic 58mm thermal printers                |\n| `CreatePt210()`       | PT-210 portable printer with specific tweaks |\n\n## 🎨 Visual Emulator\n\nThe `pkg/emulator` package provides a visual emulator that renders print jobs as PNG images:\n\n```go\nimport (\n\t\"github.com/adcondev/poster/pkg/emulator\"\n)\n\n// Create emulator with configuration\nemu := emulator.NewEngine(emulator.Config{\n\tPaperWidth: 80,\n\tDPI:        203,\n})\n\n// Render document and save as PNG\nimg := emu.Render(document)\nemu.SaveImage(\"receipt_preview.png\")\n```\n\n## 📊 Code Coverage\n\n\u003cdetails\u003e\n\u003csummary\u003e📈 Coverage Trends\u003c/summary\u003e\n\n[![Coverage Graph](https://codecov.io/github/adcondev/poster/graphs/sunburst.svg?token=X9KVG99DDZ\n)](https://codecov.io/gh/adcondev/poster)\n\u003c/details\u003e\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadcondev%2Fposter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadcondev%2Fposter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadcondev%2Fposter/lists"}