Crate escpos_rs

Library for controlling esc/pos printers with rust

Not ready for production (yet, but soon!).

use escpos_rs::{Printer, PrinterProfile};

// We create a usb contest for the printer
let printer_profile = PrinterProfile::usb_builder(0x0001, 0x0001).build();
// We pass it to the printer
let printer = match Printer::new(printer_profile) {
    Ok(maybe_printer) => match maybe_printer {
        Some(printer) => printer,
        None => panic!("No printer was found :(")
    },
    Err(e) => panic!("Error: {}", e)
};
// We print simple text
match printer.println("Hello, world!") {
    Ok(_) => (),
    Err(e) => println!("Error: {}", e)
}

See the Printer structure to see the rest of the implemented functions for interacting with the thermal printer (raw printing, images, etc.).

Printer Profile

In order to print, some data about the printer must be known. The PrinterProfile structure fulfills this purpose.

The strict minimum information needed to print, are the vendor id, the product id. Both vendor and product id should be found in the maker’s website, or sometimes they get printed in test prints (which usually occur if you hold the feed button on the printer).

If you are running linux, then one way to get these values is by executing the lsusb command.

Instructions

Because of the usual applications for thermal printers, the Instruction structure has been implemented, which allows you to define a sort of template, that you can use to print multiple documents with certain data customized for each print.

use escpos_rs::{
    Printer, PrintData, PrinterProfile,
    Instruction, Justification, command::Font
};
 
// Printer details...
let printer_profile = PrinterProfile::usb_builder(0x0001, 0x0001)
    .with_font_width(Font::FontA, 32)
    .build();
// We pass it to the printer
let printer = match Printer::new(printer_profile) {
    Ok(maybe_printer) => match maybe_printer {
        Some(printer) => printer,
        None => panic!("No printer was found :(")
    },
    Err(e) => panic!("Error: {}", e)
};
// We create a simple instruction with a single substitution
let instruction = Instruction::text(
    "Hello, %name%!",
    Font::FontA,
    Justification::Center,
    // Words that will be replaced in this specific instruction
    Some(vec!["%name%".into()].into_iter().collect())
);
// We create custom information for the instruction
let print_data_1 = PrintData::builder()
    .replacement("%name%", "Carlos")
    .build();
// And a second set...
let print_data_2 = PrintData::builder()
    .replacement("%name%", "John")
    .build();
// We send the instruction to the printer, along with the custom data
// for this particular print
match printer.instruction(&instruction, Some(&print_data_1)) {
    Ok(_) => (), // "Hello, Carlos!" should've been printed.
    Err(e) => println!("Error: {}", e)
}
// Now we print the second data
match printer.instruction(&instruction, Some(&print_data_2)) {
    Ok(_) => (), // "Hello, John!" should've been printed.
    Err(e) => println!("Error: {}", e)
}

This structure implements both Serialize, and Deserialize from serde, so it is possible to store these instructions to recover them from memory. You can serialize to a json, as pictures are encoded to base64 first to be utf-8 compatible.

Modules

command

Contains raw esc/pos commands

Structs

EscposImage

Image adapted to the printer.

Formatter

Helper structure to format text

PrintData

Contains custom information for each print

PrintDataBuilder

Helps build a valid PrintData

Printer

Main escpos-rs structure

PrinterProfile

Details required to connect and print

PrinterProfileBuilder

Helper structure to create a PrinterProfile

TableOptions

Options to print tables

Enums

Error

Errors that this crate throws.

Instruction

Templates for recurrent prints

Justification

Alignment for text printing

PrinterConnectionData

Available connections with the printer

PrinterModel

Printers known to this library