Thermal 🖨️

Thermal printer support for Ruby. Used to print receipts, chits, tickets, labels, etc.

⚠️ WARNING: Gem under active development

All APIs and features should be considered unstable before 1.0.0 release.

✨ Features

🎯 Simple and opinionated API. It just works™
🎨 Generates rich text, image, and QR codes for thermal printers.
🏭 Supports a broad range of makers and models (Epson, Star Micronics, Brother, PBM, Zijiang, etc.)
🌐 Automatic multi-lingual codepage support, including support for CJK extended character sets.
📝 Simple DSL for rich text output formatting.
🦋 Graceful degradation of features based on printer capabilities.

🔌 Optional Features

QR code generation 📱
- Requires rqrcode gem.
Support for Stargraphic (raster-only format) using system-side font rendering. 🖼️
- See requirements below.

📤 Supported Output Formats

Epson ESC/POS
- Industry standard used by most thermal printers
Star Micronics-specific formats
- Star Micronics Extended ESC/POS (UTF-8)
- Starprnt
- Stargraphic

❌ Non-Features & Limitations

HTML-to-text support (planned, not yet released) 🔄
- Requires nokogiri gem.
No support for wire protocols such as USB, Bluetooth, etc. This gem is intended to run on a server; it only generates the instructions/bytes to be sent to the client
(browser, iOS, etc.) which should then send it to the end device.
- PR welcome if someone wants to add USB/Bluetooth support.
Pixel-only printer support (Stargraphic) is rudimentary and slow 🐢, because it uses system-side font rendering (Pango) to generate the image data.
- PR welcome to use a different approach and/or make it faster.
Table formatting support not yet added. PR welcome.
Indian ISCII encoding for Escpos is not yet supported. PR welcome.

🚀 How to Use

📦 Installation

Add this line to your application's Gemfile:

gem 'thermal'

🖨️ Formatting your Output

⌨️ Procedural code

Intended API: (needs to be further extracted)

printer = Thermal::Printer.new(device: :espon_tm_t88v)
printer.text('Contra felicem vix deus vires habet')
printer.align_center
printer.text('Quam vellem nescire litteras!')
printer.flush # todo: #print!?

🧩 DSL

You can also use it as a DSL:

# TODO: Example text should look like an actual receipt
class MyChitPrinter
  include Thermal::Dsl

  def initialize
    @printer = Thermal::Printer.new(device: :espon_tm_t88v)
  end

  def print
    thermal_print do # TODO: does this flush automatically?
      bold do
        text('Contra felicem vix deus vires habet')
        align(:center) do
          text('Quam vellem nescire litteras!')
        end
        # html do
        #
        # end
        # html('<b>foo</b>')
      end
    end
  end
end

📃 HTML Conversion

# TODO: float/tables?
# h1
# h2
# h3
#

🚢 Integrating Thermal into your App

Add details of how to implement a thermal printer config.

🛠️ Advanced Considerations

🧵 Thread-Safety

Thermal's internals are thread-safe in principle.
However, don't use the same Thermal::Printer object from multiple threads. You're gonna have a bad time. 😵

📝 TODOs

✅ Required before 1.0.0 release

[ ] Add render method instead of flush
[ ] Add task to import config from escpos-printer-db
[ ] Rename CjkEncoding to RubyEncoding, rename CharmapEncoding, CharsetEncoding, also add IconvEncoding
[ ] Encoding classes themselves should validate missing char (move from Escpos::Buffer class)
[ ] Iconv config generator rake task.
[ ] Set output format for thermal_print (default, base64, bytes, etc.)
[ ] Params for escpos: :codepages, escpos: charsets
[ ] Copy in Escpos and EscposImage gems (get rid of dependency)
[ ] Param pass-thru to EscposImage
[ ] Configurability of tmp path -- specific to stargraphic (?) -- Should use Tempfile
[ ] Write Readme
[ ] DslMixin should include protocol (?), ipp_uri (?) -- why??
[ ] Specs for all classes, including base.
[ ] StarGraphic needs multiple message buffering. ???
[ ] Add QR to DSL

✨ Nice to haves

[ ] font support. col_width should be dynamic in the printer (currently depends on font 0)
[ ] Copy "Available methods" from https://github.com/escpos/escpos-php
[ ] Add HTML command in addition to text. Should be done as an AST (HtmlAst) like [[:text, 'ddd'], [:underline, 2, [[:text, 'foo']]]]
[ ] Optional HTML image support
[ ] Copy TestReport
[ ] Stargraphic needs much better buffer support, including line break splitting + multiple buffers.
[ ] Allow pass-in of codepage object.
[ ] Allow pass-in of charset object.
[ ] Indian ISCII encoding for Escpos (separate gem?).

🙏 Contributing

To add support for additional Thermal printers.

escpos-printer-db
Add new code in lib/thermal/printer/escpos.rb
Add new code in lib/thermal/printer/starprnt.rb

💖 Acknowledgements

👨‍💻 Maintainers

Thermal is maintained and battle-tested by the team at TableCheck based in Tokyo, Japan. 🗼 We use Thermal to help our restaurant users print chits, receipts, and QR codes to serve their guests' reservations. If you are seeking your next career adventure, we're hiring!

📚 Data Sources

This gem relies on the community-maintained escpos-printer-db to provide a comprehensive list of thermal printers.

🌟 Special Thanks

This gem draws inspiration from the following libraries. Thank you to the authors for their hard work.

The vendor manuals in the doc/vendor directory are the property of their respective owners. They are included here for references purposes only under the fair use doctrine.

📜 License

This gem is released under the MIT License. Please see the LICENSE file for details.