receiptline

ReceiptLine

Markdown for receipts. Printable digital receipts. 🧾
Generate receipt printer commands and images.

"ReceiptLine" is a coined word from "Receipt" and "Streamline".
Make it more efficient by making it simpler!

Features

ReceiptLine is the receipt description language that expresses the output image of small roll paper.
It supports printing paper receipts using a receipt printer and displaying electronic receipts on a POS system or smartphone.
It can be described simply with receipt markdown text data that does not depend on the paper width.

This implementation also provides the development tool "ReceiptLine Designer" for editing, previewing, hex dumps with a virtual printer, and test printing on receipt printers.

Receipt Printers

• Epson TM series
• Seiko Instruments RP series
• Star MC series
• Citizen CT series
• Fujitsu FP series

Epson TM series (South Asia model) and Star MC series (StarPRNT model) can print with device font of Thai characters.

Installation

$ npm install receiptline

Usage

receiptline.transform() method transforms ReceiptLine document to printer commands or SVG images.

const receiptline = require('receiptline');

const doc = '{code:2012345678903;option:ean,hri}';

// printer example
const printer = {
    cpl: 42,
    encoding: 'multilingual',
    upsideDown: false,
    gamma: 1.8,
    command: 'escpos'
};
const command = receiptline.transform(doc, printer);

// display example
const display = {
    cpl: 42,
    encoding: 'multilingual'
};
const svg = receiptline.transform(doc, display);

Method

receiptline.transform(doc[, printer])

Parameters

• doc
  • a string of ReceiptLine document
• printer
  • an object of printer configuration

Return value

• printer commands or SVG images

Printer configuration

• cpl
  • characters per line (default: 48)
• encoding
  • multilingual: Multilingual (including cp437, cp852, cp858, cp866, cp1252)
  • cp437: United States (default)
  • cp852: Central European
  • cp858: Western European
  • cp860: Portuguese
  • cp863: French Canadian
  • cp865: Nordic
  • cp866: Cyrillic
  • cp1252: Western European
  • cp932: Japanese
  • shiftjis: Japanese
  • cp936: Simplified Chinese
  • gb18030: Simplified Chinese
  • cp949: Korean
  • ksc5601: Korean
  • cp950: Traditional Chinese
  • big5: Traditional Chinese
  • tis620: Thai
• gradient (for printer)
  • false: image processing for text, barcodes, and 2D codes
  • true: image processing for photos (default)
• gamma (for printer)
  • image gamma correction (range: 0.1 - 10.0, default: 1.8)
• threshold (for printer)
  • image thresholding (range: 0 - 255, default: 128)
• upsideDown (for printer)
  • false: normal (default)
  • true: upside down
• spacing
  • false: no line spacing (default)
  • true: line spacing
• cutting (for printer)
  • false: no paper cutting
  • true: paper cutting (default)
• margin (for printer)
  • print margin (left) (range: 0 - 24, default: 0)
• marginRight (for printer)
  • print margin (right) (range: 0 - 24, default: 0)
• command
  • svg: SVG (default)
  • text: plain text
  • escpos: ESC/POS
  • epson: ESC/POS (Epson)
  • sii: ESC/POS (Seiko Instruments)
  • citizen: ESC/POS (Citizen)
  • fit: ESC/POS (Fujitsu)
  • impact: ESC/POS (TM-U220)
  • impactb: ESC/POS (TM-U220 Font B)
  • generic: ESC/POS (Generic) Experimental
  • starsbcs: StarPRNT (SBCS, Thai)
  • starmbcs: StarPRNT (Japanese)
  • starmbcs2: StarPRNT (Chinese, Korean)
  • starlinesbcs: Star Line Mode (SBCS)
  • starlinembcs: Star Line Mode (Japanese)
  • starlinembcs2: Star Line Mode (Chinese, Korean)
  • emustarlinesbcs: Command Emulator Star Line Mode (SBCS)
  • emustarlinembcs: Command Emulator Star Line Mode (Japanese)
  • emustarlinembcs2: Command Emulator Star Line Mode (Chinese, Korean)
  • stargraphic: Star Graphic Mode (TSP100LAN)
  • starimpact: Star Mode on dot impact printers Experimental
  • starimpact2: Star Mode on dot impact printers (Font 5x9 2P-1) Experimental
  • starimpact3: Star Mode on dot impact printers (Font 5x9 3P-1) Experimental

Generate barcodes and QR Codes

receiptline.barcode.generate() method generates a barcode.
receiptline.qrcode.generate() method generates a QR Code.

const bar = { data: '1234', type: 'code39', width: 2, quietZone: true };
const barform = receiptline.barcode.generate(bar);

const qr = { data: 'abcdefgh', level: 'm', quietZone: true };
const qrform = receiptline.qrcode.generate(qr);

Method

receiptline.barcode.generate(symbol)

Parameters

• symbol <object>: barcode data
  • data <string>: data to encode
  • type <string>: barcode type
    • upc: UPC-A, UPC-E (check digit can be omitted)
    • ean, jan: EAN-13, EAN-8 (check digit can be omitted)
    • code39: CODE39
    • itf: Interleaved 2 of 5
    • codabar, nw7: Codabar (NW-7)
    • code93: CODE93
    • code128: CODE128
    • default: code128
  • width <number>: module width
    • range: 2-4
    • default: 2
  • height <number>: module height
    • range: 24-240
    • default: 72
  • hri <boolean>: human readable interpretation
    • default: false
  • quietZone <boolean>: quiet zone
    • default: false

Return value

• <object>: barcode form
  • length <number>: barcode width (sum of widths)
  • height <number>: barcode height
  • widths <number[]>: bar / space width (quiet zone, bar, space, ... , bar, quiet zone)
  • hri <boolean>: human readable interpretation
  • text <string>: human readable interpretation text

Method

receiptline.qrcode.generate(symbol)

Parameters

• symbol <object>: QR Code data
  • data <string>: data to encode
  • level <string>: error correction level
    • l: Low
    • m: Middle
    • q: Quartile
    • h: High
    • default: l
  • quietZone <boolean>: quiet zone
    • default: false

Return value

• <Uint8Array[]>: QR Code form (matrix of dark and light modules)
  • 0: light
  • 1: dark

QR Code is a registered trademark of DENSO WAVE INCORPORATED.

Transform stream API

receiptline.createTransform() method is the stream version of the receiptline.transform().

const fs = require('fs');
const receiptline = require('receiptline');

const source = fs.createReadStream('example.receipt');
const transform = receiptline.createTransform({ command: 'svg' });
const destination = fs.createWriteStream('example.svg');

source.pipe(transform).pipe(destination);

Method

receiptline.createTransform([printer])

Parameters

• printer
  • an object of printer configuration

Return value

• Transform stream <stream.Transform>

Examples

example/receipt/*

Display digital receipts in the web browser and print paper receipts on the printer as needed.

example/cloud/*

Print order slips from cloud server using Epson Server Direct Print or Star CloudPRNT.

example/nodejs/*

Enter receipt markdown text from the web form, transform it to printer commands on the server, and print it out.

example/js/*

Enter receipt markdown text from the web form, transform it to SVG images on the web browser, and display it.

example/data/*

The documents (receipt markdown text) are the same as the examples in the OFSC ReceiptLine Specification.

example/command/*

Customize the command object to output your own commands.

Libraries

lib/receiptline.js

It works on both web browser and Node.js.
To output printer commands on a web browser, use Receipt.js or Browserify.

$ browserify -o receiptline-full.js receiptline.js

ReceiptLine Designer

Online version is available.
https://receiptline.github.io/designer/

The ReceiptLine Designer provides more features.

• Edit and preview
• Data transmission via TCP socket
• Hex dump view by listening TCP 19100 port

Setup

1. Copy the following files to your working directory

   • designer/*
   • designer.js
   • printers.json
   • servers.json

2. Start the server

   bash复制

   $ node designer.js

3. Open http://localhost:8080

   Use a modern browser.

4. Configure printers.json

   json复制

   "printer_id": {
       "host": "127.0.0.1",
       "port": 19100,
       "asImage": false,
       "cpl": 48,
       "encoding": "shiftjis",
       "gradient": true,
       "gamma": 1.8,
       "threshold": 128,
       "upsideDown": false,
       "spacing": true,
       "cutting": true,
       "command": "escpos"
   }

   • printer_id
     • printer identifier (alphanumeric or underscore characters)
   • host
     • printer address
   • port
     • printer port (will be 9100)
   • asImage
     • false: print with device font (default)
     • true: print as image (Requires puppeteer or sharp)
   • landscape
     • false: normal (default)
     • true: landscape orientation (for escpos, epson, sii, citizen, starsbcs, starmbcs, starmbcs2)
   • resolution
     • print resolution for landscape (values: 180, 203, default: 203)
   • cpl
   • encoding
   • gradient
   • gamma
   • threshold
   • upsideDown
   • spacing
   • cutting
   • margin
   • marginRight
     • see the printer configuration above
   • command
     • see the printer configuration above
     • png: PNG (Requires puppeteer or sharp)

URL query string

The designer can set initial values in the URL query string.

Parameters

• z: zoom (range: -5-5, default: 0)
• l: language (en, ja, ko, zh-hans, zh-hant, th, ...)
• c: characters per line (range: 24-96, default: 48)
• v: landscape (values: 0, 1, default: 0)
• s: line spacing (values: 0, 1, default: 0)
• p: printer identifier (alphanumeric or underscore characters)
• d: ReceiptLine document

Examples

• http://localhost:8080/index.html?c=42&p=tm_series1
• https://receiptline.github.io/designer/index.html?d={code%3A2012345678903%3Boption%3Aean%2Chri}

Serial-LAN Converter

The serial-LAN converter enables test printing to USB / Bluetooth printers that support virtual serial ports.

Setup

1. Install the virtual serial port driver for the printer and Node Serialport

   bash复制

   $ npm install serialport

2. Configure servers.json

   json复制

   "serial": {
       "host": "127.0