Skip to content

escpos/escpos

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Build Status

Escpos

A ruby implementation of ESC/POS (thermal) printer command specification.

Installation

Add this line to your application's Gemfile:

gem 'escpos'

# see https://github.com/escpos/escpos-image
gem 'escpos-image' # add this if you want to print images

And then execute:

$ bundle

Or install it yourself as:

$ gem install escpos

Image support

To keep this gem lightweight and modular image support was implemented in another gem:

https://github.com/escpos/escpos-image

# Add this line to your application's Gemfile if you want to print images
gem 'escpos-image'
# And depending on your image processor of choice
gem 'mini_magick'
# or
gem 'chunky_png'

Or install it yourself as:

gem install escpos-image
# and then depending on your image processor of choice
gem install mini_magick
# or
gem install chunky_png

For more information about image processors, their options and supported formats please see https://github.com/escpos/escpos-image readme file.

Examples

Basic usage

@printer = Escpos::Printer.new
@printer << "Some text"
@printer << Escpos::Helpers.big "Big text"

@printer.to_escpos # returns ESC/POS data ready to be sent to printer
# on linux this can be piped directly to /dev/usb/lp0
# with network printer sent directly to printer socket (see example below)
# with serial port printer it can be sent directly to the serial port

@printer.to_base64 # returns base64 encoded ESC/POS data

Report class usage

# my_report.rb:

class MyReport < Escpos::Report
  def item(text)
    @count ||= 0
    @count += 1
    bold "#{@count}. #{text}"
  end

  def order
    options[:order]
  end
end
<% # my_report.erb: %>

<%= big "Order number #{order[:number]}" %>
<%= item "First item" %>
<%= item "Second item" %>
<%= item "Third item" %>
report = MyReport.new 'path/to/my_report.erb', {
  order: { number: 123 }
}
@printer << report.render
@printer.cut!

@printer.to_escpos # returns ESC/POS data ready to be sent to printer
# - on linux this can be piped directly to /dev/usb/lp0
# - with network printer sent directly to printer socket
# - with serial port printer it can be sent directly to the serial port
# see example below

@printer.to_base64 # returns base64 encoded ESC/POS data

Printing to Linux/UNIX/BSD block device (USB/Serial/LPT)

printer = Escpos::Printer.new
printer << "Some text"

# change /dev/usb/lp0 to match the printer device
# e.g. on Linux this may be /dev/ttyS0 for serial port
File.open("/dev/usb/lp0", "w") { |f| f.write printer.to_escpos }

Network printing

require "socket"

printer = Escpos::Printer.new
printer << "Some text"

# change 192.168.2.7 and 9100 to match the IP or host and port of the printer
socket = TCPSocket.new "192.168.2.7", 9100

socket.write printer.to_escpos
socket.close

Available helper methods

Method name Description
text Normal text formatting
encoding, set_encoding, set_printer_encoding Set printer encoding (see example below)
encode Encode text for the printer (see example below)
double_height Double height text
quad_text, big, title, header, double_width_double_height, double_height_double_width Double width & Double height text
double_width Double width text
underline, u Underlined text
underline2, u2 Stronger underlined text
bold, b Bold text
left Align to left
right Align to right
center Align to center
invert, inverted Color inverted text
black, default_color, color_black, black_color Default Color (Usually black)
red, alt_color, alternative_color, color_red, red_color Alternative Color (Usually Red)
barcode Print barcode (see example below)
partial_cut Partially cut the paper (may not be available on all devices)
cut Fully cut the paper (may not be available on all devices)

Encoding & diacritics

To print diacritics (accented characters) with ESC/POS two things have to be done. First the desired code page must be set on the printer (can be done using an ESC/POS command) and the desired text has to be encoded to the code page set on the printer.

printer = Escpos::Printer.new
printer << Escpos::Helpers.set_printer_encoding(Escpos::CP_ISO8859_2)
printer << Escpos::Helpers.encode("This is UTF-8 to ISO-8859-2 text: ěščřžýáíéúů", encoding: "ISO-8859-2")

Some printers (e.g. Epson TM line) allow setting a default code page in printer setup, then the set_printer_encoding call can be omitted.

Printing barcodes

The barcode helper accepts barcode data as first argument and an options hash as second.

Possible options:

Option Possible values Description
format Escpos::BARCODE_UPC_A: Barcode type UPC-A
Escpos::BARCODE_UPC_E: Barcode type UPC-E
Escpos::BARCODE_EAN13: Barcode type EAN13
Escpos::BARCODE_EAN8: Barcode type EAN8
Escpos::BARCODE_CODE39: Barcode type CODE39
Escpos::BARCODE_ITF: Barcode type ITF
Escpos::BARCODE_NW7: Barcode type NW7
Type of barcode
text_position Escpos::BARCODE_TXT_OFF: no text, only barcode
Escpos::BARCODE_TXT_ABV: text positioned above the barcode
Escpos::BARCODE_TXT_BLW: text positioned below the barcode
Escpos::BARCODE_TXT_BTH: text positioned both above and below the barcode
Text position
height 1 to 255 Barcode height
width 2 to 6 Barcode width
barcode_data = Escpos::Helpers.barcode("12345678", {
  format: Escpos::BARCODE_CODE39,
  text_position: Escpos::BARCODE_TXT_BLW,
  height: 50,
  width: 3
})

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/escpos/escpos.

  1. Fork it ( https://github.com/escpos/escpos/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

About

A ruby implementation of ESC/POS (thermal) printer command specification.

Resources

Stars

Watchers

Forks

Packages

No packages published