Epson.EposPrint 1.1.1

Epson.EposPrint

A .NET library for generating EPSON ePOS-Print XML documents with a fluent API.

Open-sourced by Jamatu AG

About

This library provides a type-safe, fluent API for building EPSON ePOS-Print XML documents to control EPSON POS printers. It supports all standard ePOS-Print XML elements including text formatting, barcodes, QR codes, images, and printer control commands.

Features

• ✅ Fluent API for building ePOS-Print XML documents
• ✅ Type-safe element and attribute configuration
• ✅ Support for all ePOS-Print XML elements
• ✅ Text formatting (alignment, size, fonts, bold, underline, reverse)
• ✅ Barcodes (UPC, EAN, Code39, Code128, GS1, etc.)
• ✅ 2D Symbols (QR codes, PDF417, DataMatrix, Aztec, etc.)
• ✅ Images and NV logos
• ✅ Lines, rectangles, and page mode layout
• ✅ Printer control (cut, drawer kick, buzzer)
• ✅ Multi-language support
• ✅ Comprehensive documentation
• ✅ .NET 6 and .NET 8 support

Installation

dotnet add package Epson.EposPrint

Or via Package Manager Console:

Install-Package Epson.EposPrint

Release Notes

Version 1.1.0 (Latest)

New Features:

• ✨ Paper Width Configuration - Configure paper width (58mm/80mm) with WithPaperWidth() and add full-width lines with AddFullWidthLine()
• ✨ Fluent Helper Methods - Semantic shortcuts like AddHeader(), AddBoldText(), AddCenteredText(), AddLargeText(), and AddRightAlignedText()
• ✨ Spacing Helpers - Convenient methods including AddLineBreaks(), AddGap(), AddLargeGap(), AddSpacing(), AddSeparator(), and AddDivider()
• ✨ Style Isolation - Automatic style reset between AddText() calls - no more manual resets needed!

Improvements:

• 🔧 Text styles (bold, underline, reverse, size, alignment, color) now automatically reset to defaults after each AddText() call
• 🔧 More intuitive API - styles don't "bleed through" to subsequent text elements
• 📚 Enhanced examples demonstrating new helper methods and paper width configuration

Breaking Changes:

• ⚠️ Text element behavior changed: unstated style attributes now automatically reset to defaults instead of persisting. If you rely on style persistence across multiple AddText() calls, you'll need to explicitly set styles on each call.

Version 1.0.0

• 🎉 Initial release - open-sourced by Jamatu AG
• Full support for ePOS-Print XML specification
• Fluent API for building receipts
• Support for text, barcodes, QR codes, images, and printer control

Quick Start

using Epson.EposPrint;

// Create a receipt
var receipt = new EposPrintDocument()
    .AddLogo(1, 0, Align.Center)
    .AddText("ACME STORE", align: Align.Center, doubleWidth: true, doubleHeight: true, emphasized: true)
    .AddFeed()
    .AddText("123 Main Street")
    .AddText("Anytown, USA 12345")
    .AddFeed(2)
    .AddText("Receipt #: 12345")
    .AddHorizontalLine()
    .AddText("Item 1           $10.00")
    .AddText("Item 2           $15.50")
    .AddHorizontalLine()
    .AddText("TOTAL:          $25.50", doubleWidth: true, doubleHeight: true, emphasized: true)
    .AddFeed()
    .AddQRCode("https://example.com/receipt/12345", align: Align.Center)
    .AddFeed()
    .AddText("Thank you!", align: Align.Center)
    .Cut()
    .ToXml();

// Send to printer via HTTP/SOAP
await SendToPrinter(receipt);

Paper Width Configuration

The library supports standard EPSON paper widths with a fluent API:

// Configure for 80mm paper (576 dots - default)
var receipt = new EposPrintDocument()
    .WithPaperWidth(PaperWidth.Width80mm)
    .AddFullWidthLine()  // Automatically uses 576 dots
    .ToXml();

// Configure for 58mm paper (420 dots)
var receipt = new EposPrintDocument()
    .WithPaperWidth(PaperWidth.Width58mm)
    .AddFullWidthLine()  // Automatically uses 420 dots
    .ToXml();

// Custom paper width (e.g., 70mm ≈ 504 dots at 203 DPI)
var receipt = new EposPrintDocument()
    .WithCustomPaperWidth(504)
    .AddFullWidthLine()
    .ToXml();

// Full-width line with custom thickness
.AddFullWidthLine(thickness: 2)

Available Paper Widths:

• PaperWidth.Width80mm - 576 dots (standard receipt paper)
• PaperWidth.Width58mm - 420 dots (compact receipt paper)
• WithCustomPaperWidth(dots) - Custom width in dots at 203 DPI

Helper Methods:

• AddFullWidthLine(thickness) - Adds a horizontal line spanning the full configured paper width

Fluent Helper Methods

The library includes semantic helper methods that make common patterns more intuitive and readable:

Spacing Helpers

// Line breaks (blank lines)
.AddLineBreaks(2)         // Add 2 blank lines

// Precise spacing in dots
.AddSpacing(24)           // Add 24 dots spacing

// Quick gaps
.AddGap()                 // Small gap (12 dots)
.AddLargeGap()            // Large gap (48 dots)

Visual Separators

// Full-width line with spacing
.AddSeparator()           // Line with spacing above/below
.AddDivider()             // Alias for AddSeparator
.AddDivider(thickness: 2) // Thick separator line

Text Shortcuts

// Semantic text methods
.AddHeader("STORE NAME")              // Large, bold, centered
.AddBoldText("Important")             // Emphasized text
.AddCenteredText("Welcome")           // Centered alignment
.AddLargeText("SALE!")                // Double width/height
.AddRightAlignedText("$25.00")        // Right-aligned

// Combine with optional parameters
.AddCenteredText("Bold Center", emphasized: true)
.AddLargeText("BIG SALE", align: Alignment.Center, emphasized: true)
.AddBoldText("TOTAL", align: Alignment.Right)

Complete Example

var receipt = new EposPrintDocument()
    .WithPaperWidth(PaperWidth.Width80mm)

    // Header
    .AddHeader("MODERN CAFE")
    .AddLineBreaks(2)

    // Address
    .AddCenteredText("123 Coffee Street")
    .AddCenteredText("Downtown, CA 12345")
    .AddLargeGap()

    // Divider
    .AddDivider()

    // Content
    .AddBoldText("Items:")
    .AddText("Cappuccino           $4.50")
    .AddText("Croissant            $3.00")
    .AddGap()

    // Total
    .AddSeparator()
    .AddLargeText("TOTAL: $7.50", emphasized: true)
    .AddSeparator(thickness: 2)

    // Footer
    .AddLineBreaks(2)
    .AddCenteredText("Thank you!")

    .Cut()
    .ToXml();

Benefits

• ✅ More readable - Intent is clear from method names
• ✅ Less verbose - No need to remember parameter names
• ✅ Semantic - Methods describe what, not how
• ✅ Discoverable - IntelliSense shows purpose
• ✅ Chainable - All methods support fluent chaining

Note: All helper methods are shortcuts for common patterns. You can still use the full AddText() method with all parameters for complete control.

Text Formatting

The library supports comprehensive text styling options with automatic style isolation - each AddText() call is independent and doesn't affect subsequent text.

// Bold text
.AddText("Important Notice", emphasized: true)

// Next text automatically returns to normal (no manual reset needed!)
.AddText("Regular text")  // Not bold

// Combined formatting
.AddText("STORE HEADER",
    align: Alignment.Center,
    doubleWidth: true,
    doubleHeight: true,
    emphasized: true)  // Bold + large + centered

// Automatically resets to: left-aligned, normal size, not bold
.AddText("Back to normal")

// Other text styles
.AddText("Underlined", underline: true)
.AddText("Not underlined anymore")  // Auto-reset!

.AddText("Reversed", reverse: true)  // White text on black background
.AddText("Normal colors")  // Auto-reset!

// Font selection
.AddText("Different Font", font: Font.FontB, emphasized: true)
.AddText("Back to default font")  // Auto-reset!

Style Isolation

Important: Unlike EPSON printers which maintain state across text elements, this library automatically resets unstated styling attributes to their defaults after each AddText() call. This prevents style "bleed-through" and makes the API more intuitive.

// Old way (without style isolation) - would require manual resets:
.AddText("Bold", emphasized: true)
.AddText("Normal", emphasized: false)  // ❌ Manual reset required

// New way (with style isolation) - automatic resets:
.AddText("Bold", emphasized: true)
.AddText("Normal")  // ✅ Automatically not bold!

Available text formatting options:

• emphasized - Bold/thick text (maps to ePOS-Print em attribute)
• underline - Underlined text
• reverse - White-on-black text
• doubleWidth / doubleHeight - Size multipliers
• align - Text alignment (Left, Center, Right)
• font - Font selection (FontA through FontE, SpecialA, SpecialB)
• color - Print color (Color1 through Color4)

Documentation

Full documentation is available in the Wiki.

See the EPSON ePOS-Print XML Specification for details on the XML format.

Examples

See the Examples project for more usage examples.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - See LICENSE for details.

Copyright © 2025 Jamatu AG

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

Developed by Jamatu AG

Special thanks to:

• EPSON for the ePOS-Print XML specification
• All our contributors

Made by Jamatu AG