pos_barcodes

A pure Dart library for generating and printing barcodes on POS thermal printers. No Flutter dependency — works in any Dart project.

Features

• Configurable symbologies — EAN-13, Code 128, QR Code
• Full layout control — margins, DPI, quiet zones, rotation, text position
• TSPL printer backend — direct integration with TSC-compatible thermal printers
• Pure Dart — no Flutter dependency, works in CLI, backend, or Flutter apps
• Type-safe configuration — immutable config with sensible defaults

Quick Start

import 'package:pos_barcodes/pos_barcodes.dart';

// 1. Configure
final config = BarcodeConfig(
  symbology: BarcodeSymbology.code128,
  paperSize: PaperSize.receipt80,
  barcodeWidth: 50,    // mm
  barcodeHeight: 25,   // mm
  quietZone: 2,        // mm
  margins: Margins.all(5),
  dpi: 203,
  printSpeed: 4,       // inches per second
  printDensity: PrintDensity.defaultDensity,
);

// 2. Generate payload (PLU only — no price)
final generator = Code128Generator();
final payload = generator.generate('00142');

// 3. Print
final printer = TsplPrinter(host: '192.168.1.100');
final result = await printer.print(config, payload);

if (result.success) {
  print('Printed ${result.bytesSent} bytes');
} else {
  print('Error: ${result.message}');
}

Installation

Add to your pubspec.yaml:

dependencies:
  pos_barcodes:
    path: ../pos_barcodes  # local package

Or publish to pub.dev and use:

dependencies:
  pos_barcodes: ^0.1.0

Configuration

BarcodeConfig

The main configuration class controls all aspects of barcode printing:

const config = BarcodeConfig(
  // Barcode settings
  symbology: BarcodeSymbology.code128,  // EAN-13, Code 128, QR Code
  barcodeWidth: 50,                      // mm
  barcodeHeight: 25,                     // mm
  quietZone: 2,                         // mm (ISO requirement)
  rotation: BarcodeRotation.zero,       // 0°, 90°, 180°, 270°
  humanReadable: TextPosition.bottom,   // none, bottom, top

  // Paper settings
  paperSize: PaperSize.receipt80,       // or PaperSize.mm(width, height)
  gap: 2,                               // mm between labels

  // Print settings
  dpi: 203,                             // 203, 300, or 600
  printSpeed: 4,                        // inches per second
  printDensity: PrintDensity.defaultDensity,  // 0-15

  // Layout
  margins: Margins(                     // or Margins.all(value)
    top: 5,
    bottom: 5,
    left: 5,
    right: 5,
  ),
);

Paper Sizes

Built-in presets:

Preset	Dimensions
PaperSize.receipt58	58 × 200 mm
PaperSize.receipt80	80 × 200 mm
PaperSize.label4x6	101.6 × 152.4 mm
PaperSize.label3x2	76.2 × 50.8 mm
PaperSize.a4	210 × 297 mm
PaperSize.a5	148 × 210 mm

Custom sizes:

const customSize = PaperSize(100, 150);  // 100mm × 150mm

Print Density

Controls darkness (0 = lightest, 15 = darkest):

PrintDensity.lightest    // 0
PrintDensity.light       // 2
PrintDensity.medium      // 6
PrintDensity.defaultDensity  // 8 (default)
PrintDensity.dark        // 12
PrintDensity.darkest     // 15

DPI Conversion

The library converts mm to dots automatically:

const config = BarcodeConfig(dpi: 300);
config.mmToDots(25.4);  // 300 dots (1 inch at 300 DPI)
config.mmToDots(1);     // 12 dots (1mm at 300 DPI)

Barcode Symbologies

EAN-13

13-digit retail barcode. Input is zero-padded to 12 digits, check digit is calculated automatically.

final gen = Ean13Generator();
gen.generate('142');      // '0000000001425' (13 digits)
gen.generate('12345678'); // '0000123456785'

Validation:

• Must be 1-12 numeric digits
• Throws ArgumentError on invalid input

Code 128

High-density alphanumeric barcode. Variable length, supports full ASCII.

final gen = Code128Generator();
gen.generate('00142');     // '00142'
gen.generate('ABC-123');   // 'ABC-123'

Validation:

• Must be 1-80 printable ASCII characters
• Throws ArgumentError on invalid input

QR Code

2D matrix barcode. Supports structured format for POS parsing.

// Simple passthrough
final gen = QrCodeGenerator();
gen.generate('00142');  // '00142'

// Structured format
final structured = QrCodeGenerator(structured: true);
structured.generate('00142');  // 'PLU:00142'

Validation:

• Must be 1-2000 characters
• Throws ArgumentError on invalid input

TSPL Printer

Connecting

final printer = TsplPrinter(
  host: '192.168.1.100',  // IP address or hostname
  port: 9100,              // default TSPL port
  timeout: 5,              // connection timeout in seconds
);

Printing

final result = await printer.print(config, payload);

if (result.success) {
  print('Sent ${result.bytesSent} bytes');
} else {
  print('Failed: ${result.message}');
}

Raw Commands

Send arbitrary TSPL commands:

await printer.sendRaw('CLS\n');
await printer.sendRaw('PRINT 1,1\n');

Generated TSPL Output

The library generates complete TSPL label programs:

SIZE 80.0 mm,200.0 mm
GAP 2.0 mm,0
SPEED 4
DENSITY 8
DIRECTION 0
REFERENCE 0,0
CLS
BARCODE 16,16,"128",197,2,0,8,16,"00142"
PRINT 1,1

Helper Commands

// Text
printer.textCommand(100, 50, '3', 0, 'Product Label');

// Box
printer.boxCommand(10, 10, 300, 200, thickness: 2);

// QR Code
printer.qrCodeCommand(config, 100, 100, 'https://example.com');

Custom Printer Backend

Implement the BarcodePrinter interface for other printer languages:

class ZplPrinter implements BarcodePrinter {
  @override
  Future<PrintResult> print(BarcodeConfig config, String payload) async {
    final zpl = _buildZpl(config, payload);
    // Send to printer...
    return PrintResult.success(bytesSent: zpl.length);
  }

  @override
  Future<void> sendRaw(String commands) async { /* ... */ }

  @override
  Future<bool> testConnection() async { /* ... */ }

  @override
  Future<void> close() async { /* ... */ }
}

API Reference

Enums

Enum	Values
BarcodeSymbology	ean13, code128, qrCode
BarcodeRotation	zero, ninety, oneEighty, twoSeventy
TextPosition	none, bottom, top
PrintDensity	lightest (0) ... darkest (15)

Classes

Class	Description
BarcodeConfig	Immutable print configuration
PaperSize	Paper dimensions in mm
Margins	Label margins
BarcodeGenerator	Abstract generator interface
Ean13Generator	EAN-13 payload generator
Code128Generator	Code 128 payload generator
QrCodeGenerator	QR Code payload generator
BarcodePrinter	Abstract printer interface
TsplPrinter	TSPL printer implementation
PrintResult	Print operation result

Testing

cd pos_barcodes
dart test

30 tests covering config, generators, and enums.

License

MIT