tmt88v

tm-t88v

Go library and CLI for the Epson TM-T88V (M244A) thermal receipt printer. It provides:

• A low-level ESC/POS command builder (escpos package)
• A high-level Printer API and receipt builder (tmt88v package)
• USB and file-based transports
• A CLI tool for quick printing and status checks

Requirements

• Go 1.24+
• Linux access to the printer device (usually /dev/usb/lp0)
• Optional: libusb-1.0 when using the USB transport (-tags libusb)

Installation

go get github.com/AkatukiSora/tm-t88v

Quick Start

File transport (default)

package main

import (
    "log"

    "github.com/AkatukiSora/tm-t88v"
)

func main() {
    p, err := tmt88v.Open("/dev/usb/lp0")
    if err != nil {
        log.Fatal(err)
    }
    defer p.Close()

    if err := p.Init(); err != nil {
        log.Fatal(err)
    }

    if err := p.PrintText("Hello TM-T88V\n"); err != nil {
        log.Fatal(err)
    }

    if err := p.FeedAndCut(); err != nil {
        log.Fatal(err)
    }
}

USB transport (libusb)

transport, err := tmt88v.OpenUSB()
if err != nil {
    // Build with: go build -tags libusb ./...
    log.Fatal(err)
}
defer transport.Close()

p, err := tmt88v.New(transport)
if err != nil {
    log.Fatal(err)
}
defer p.Close()

Receipt Builder

if err := p.Receipt().
    Header("My Shop").
    Text("Item 1").
    LineItem("Coffee", "$3.50").
    QRCode("https://example.com").
    Cut().
    Print(); err != nil {
    log.Fatal(err)
}

Image Printing

// Uses paper width and dithering options when converting to raster.
printer, _ := tmt88v.New(transport, tmt88v.WithPaperWidth(576), tmt88v.WithDithering(true))
_ = printer.PrintImage(img)

Status Monitoring

monitor := tmt88v.NewStatusMonitor(transport, func(s tmt88v.Status) {
    log.Printf("status: %+v", s)
})

if err := monitor.Start(context.Background()); err != nil {
    log.Fatal(err)
}
defer monitor.Stop()

CLI

Build the CLI:

go build ./cmd/tmt88v/

Examples:

./tmt88v status
./tmt88v test-print
./tmt88v print-text "Hello"
./tmt88v print-image ./examples/image/sample.png
./tmt88v print-barcode code128 "12345"
./tmt88v print-qr "https://example.com"
./tmt88v cut
./tmt88v drawer

# Use USB transport instead of /dev/usb/lp0
./tmt88v -u status

Run ./tmt88v help <subcommand> for full command usage.

Libusb-First Strict Verification

When using the USB transport (-u flag or OpenUSB()), the library enforces a strict success definition: a print operation is only considered successful when:

1. The print data was written and flushed to the printer.
2. A DLE EOT status query was sent and a response was received.
3. The response indicates no fault conditions (online, no cover open, no paper end, no errors).

Strict Success Checklist

# 1. Build with libusb support
go build -tags libusb ./cmd/tmt88v/

# 2. Check USB readiness (optional pre-flight)
./tmt88v -u status

# 3. Print with strict post-print verification
./tmt88v -u print-text "Hello"
# Exit 0 = print completed AND status verified OK
# Exit 1 = print failed OR status fault detected (reason code in stderr)

Status Command

The status command requires the USB transport (-u) when the device path is a usblp path (/dev/usb/lp*). The usblp kernel driver does not support bidirectional reads, so DLE EOT status queries cannot be used over it.

# Correct: use USB transport for status
./tmt88v -u status

# Wrong: will fail with guidance
./tmt88v -d /dev/usb/lp0 status
# Error: status requires USB transport: device "/dev/usb/lp0" is a usblp path; re-run with -u flag and a libusb build

Failure Codes and Troubleshooting

When a USB open fails, the CLI emits a canonical failure code:

Error: open USB transport code=<code>: <detail>

Post-Print Status Fault Codes

When a print operation completes but the strict status check fails, the error contains a machine-readable reason code:

Note: paper_near_end is a warning only and does not cause a fault.

Examples

go run ./examples/basic
go run ./examples/receipt
go run ./examples/barcode
go run ./examples/image
go run ./examples/status

Tests

go test ./...

Integration tests (requires printer access):

TMT88V_DEVICE=/dev/usb/lp0 go test -tags integration ./... -v

Libusb integration tests (requires printer + libusb build):

go test -tags integration,libusb ./... -v

Non-cgo libusb build verification:

CGO_ENABLED=0 go test -tags libusb ./...

Notes

• Default device is /dev/usb/lp0 (usblp driver). Ensure your user has access.
• USB transport requires libusb-1.0 and build tag libusb.
• Status queries require the USB transport (-u); usblp does not support bidirectional reads.
• The USB transport enforces strict post-print status verification when used via the CLI.

License

MIT