EscPosKit 1.0.1

EscPosKit

ESC/POS command generation for Epson-compatible thermal receipt printers, plus optional printer transports. Runs on .NET 10.

EscPosKit continues lukevp/ESC-POS-.NET (NuGet ESCPOS_NET 3.0.0), which stopped receiving updates in 2024. The namespaces are still ESCPOS_NET.*, so switching is a package swap plus the few changes listed under Migrating from ESCPOS_NET.

Packages

You only need EscPosKit if you already have a way to get bytes to the printer (a raw print queue, IPP, your own socket).

dotnet add package EscPosKit
dotnet add package EscPosKit.Printers

Quick start

using ESCPOS_NET;
using ESCPOS_NET.Emitters;
using ESCPOS_NET.Utilities;

var e = new EPSON();
var receipt = ByteSplicer.Combine(
    e.Initialize(),
    e.CenterAlign(),
    e.PrintImage(File.ReadAllBytes("logo.png"), isHiDPI: true, maxWidth: 384),
    e.SetStyles(PrintStyle.Bold | PrintStyle.DoubleHeight),
    e.PrintLine("EXAMPLE STORE"),
    e.SetStyles(PrintStyle.None),
    e.PrintLine("123 Main Street"),
    e.LeftAlign(),
    e.PrintLine(""),
    e.SetStyles(PrintStyle.FontB),
    e.PrintLine("1 x Coffee                    3.50"),
    e.PrintLine("1 x Bagel                     2.20"),
    e.SetStyles(PrintStyle.Bold),
    e.PrintLine("TOTAL                         5.70"),
    e.SetStyles(PrintStyle.None),
    e.PrintLine(""),
    e.PrintQRCode("https://example.com/receipt/123"),
    e.PartialCutAfterFeed(4)
);

// EscPosKit.Printers: network printer, one-shot write
var printer = new ImmediateNetworkPrinter(
    new ImmediateNetworkPrinterSettings { ConnectionString = "192.168.1.50:9100", PrinterName = "Front desk" }
);
await printer.WriteAsync(receipt);

ICommandEmitter methods return byte[]; ByteSplicer.Combine concatenates them. Everything the emitter produces is plain ESC/POS, so any transport works.

Images

PrintImage(byte[] image, ...) accepts PNG, JPEG, BMP, GIF, TGA or PSD bytes. The image is fitted into maxWidth (keeping the aspect ratio), composited over white, converted to BT.709 luminance and dithered with Stucki error diffusion before it is sent as a raster image. isHiDPI selects the printer's high density mode; isLegacy: true uses GS v 0 for printers without GS ( L support.

If you already have pixels, skip the decoder:

using ESCPOS_NET.Imaging;

MonochromeBitmap bitmap = ImageRasterizer.FromRgba(rgbaBytes, width, height, maxWidth: 384);
var bytes = e.PrintImage(bitmap, isHiDPI: true);

MonochromeBitmap is 1 bit per pixel, MSB first, rows padded to whole bytes, set bit = black dot. You can also build one yourself and hand it to PrintImage, BufferImage or DefineStoredImage.

Stored images

Logos can live in the printer's non-volatile memory and be printed by key code, which saves transfer time on every receipt:

// once, during setup
await printer.WriteAsync(e.DefineStoredImage(File.ReadAllBytes("logo.png"), "LG", isHiDPI: true, maxWidth: 384));

// on every receipt
await printer.WriteAsync(e.PrintStoredImage("LG"));

// housekeeping
await printer.WriteAsync(e.DeleteStoredImage("LG"));
await printer.WriteAsync(e.DeleteAllStoredImages());

Key codes are two printable ASCII characters. PrintStoredImage takes an ImageScale per axis (Normal or Double).

Text and encodings

Strings are encoded with the emitter's Encoding property. Thermal printers do not understand Unicode by default: either select a code page that contains your characters and set Encoding to match, or switch UTF-8 capable models (TM-T88VI, TM-m30 and newer) to UTF-8 mode:

using System.Text;

// Code page mode
await printer.WriteAsync(e.CodePage(CodePage.PC858_EURO));
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance); // once at startup
e.Encoding = Encoding.GetEncoding(858);

// UTF-8 mode
await printer.WriteAsync(e.SelectCharacterEncoding(CharacterEncoding.Utf8));
e.Encoding = Encoding.UTF8;

SetStyles sends underline through ESC - instead of bit 7 of ESC !, so underline works in UTF-8 mode too. UnderlineMode(bool) toggles it on its own, like ReverseMode and UpsideDownMode.

Implemented commands

Every method of ICommandEmitter and the ESC/POS command it emits. Commands not listed here are not implemented; see Epson's ESC/POS command reference for the full protocol.

Transports (EscPosKit.Printers)

The transports are carried over from the original project. Network, serial and Samba transports are verified by compilation and unit tests here, not on hardware; the command emitter is verified on Epson TM-T88 and TM-m30 printers.

NetworkPrinter keeps the connection open and raises StatusChanged once automatic status back is enabled:

var printer = new NetworkPrinter(new NetworkPrinterSettings { ConnectionString = "192.168.1.50:9100" });
printer.StatusChanged += (sender, args) =>
{
    var status = (PrinterStatusEventArgs)args;
    Console.WriteLine($"Online: {status.IsPrinterOnline}, paper out: {status.IsPaperOut}, cover open: {status.IsCoverOpen}");
};
printer.Write(ByteSplicer.Combine(e.Initialize(), e.Enable(), e.EnableAutomaticStatusBack()));

USB printers are used through a virtual COM port. On Linux and macOS the OS exposes them as a serial device; on Windows install the vendor's virtual COM port driver or use a USB-to-serial cable. The .NET serial port implementation only supports COM ports 1 to 8 on Windows.

Migrating from ESCPOS_NET 3.0.0

• Replace the ESCPOS_NET package with EscPosKit; add EscPosKit.Printers if you used the printer classes. Namespaces are unchanged.
• Target framework is net10.0 only.
• SixLabors.ImageSharp is no longer referenced. The ToSingleBitPixelByteArray extension in the SixLabors.ImageSharp namespace is gone; use ImageRasterizer.
• SetStyles(PrintStyle.Underline) now emits ESC ! n without bit 7 followed by ESC - 1. The printed result is the same.
• Logging and BaseLogger moved to EscPosKit.Printers; the emitter package does not log.
• TCPConnection.Connected and Disconnected use SuperSimpleTcp.ConnectionEventArgs (SuperSimpleTcp 3).
• New: SelectCharacterEncoding, UnderlineMode, ExecuteTestPrint, DefineStoredImage, PrintStoredImage, DeleteStoredImage, DeleteAllStoredImages, and MonochromeBitmap overloads of BufferImage and PrintImage.

Building

Requires the .NET SDK pinned in global.json. dotnet build EscPosKit.slnx, dotnet test EscPosKit.slnx. Formatting is enforced by CSharpier and dotnet format whitespace (dotnet tool restore first). The console sample in samples/ConsoleTest prints test pages to a real printer.

Releases are cut by pushing a tag vX.Y.Z (or vX.Y.Z-rc.N for a prerelease); the version comes from the tag through MinVer and the workflow publishes both packages to nuget.org.

Credits and license

Originally written by Luke Paireepinart and the contributors of ESC-POS-.NET. MIT License, see LICENSE.