receiptline

Printable digital receipts 🧾

Transform markdown-like text to receipt printer commands or SVG images.

Features

The reference implementation of the OFSC ReceiptLine Specification.
http://www.ofsc.or.jp/receiptline/en/

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 markdown-like text data that does not depend on the paper width.

This reference 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
SII RP series
Star MC series
Citizen CT series
Fujitsu FP series

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: 'cp437',
    upsideDown: false,
    gamma: 1.8,
    command: 'escpos'
};
const command = receiptline.transform(doc, printer);

// display example
const display = {
    cpl: 42,
    encoding: 'cp437'
};
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
- cp437: United States (default)
- cp852: Central European
- cp858: Western European
- cp860: Portuguese
- cp863: French Canadian
- cp865: Nordic
- cp866: Cyrillic
- cp932: Japanese
- cp1252: Western European
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)
gamma (for printer)
- image gamma correction (default: 1.8)
command
- svg: SVG (default)
- escpos: Epson, Citizen
- sii: SII
- starmbcs: Star MBCS
- starsbcs: Star SBCS
- fit: Fujitsu

Examples

example/receipt/*

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

example/nodejs/*

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

example/js/*

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

example/data/*

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

Libraries

lib/receiptline.js

JavaScript ES2015(ES6) version. It works on both web browser and Node.js.
To output printer commands on a web browser, use Browserify.

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

lib/qrcode-generator/qrcode.js

Generate the QR Code for display. Optional.

ReceiptLine Designer

The ReceiptLine Designer provides more features.

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

Setup

Start the server

$ cd node_modules/receiptline
$ npm start

Open http://localhost:10080

Use a modern browser.
Configure printers.json
```
"printer_id": {
    "host": "127.0.0.1",
    "port": 19100,
    "cpl": 48,
    "encoding": "cp437",
    "upsideDown": false,
    "spacing": false,
    "cutting": true,
    "gamma": 1.8,
    "command": "svg"
}
```
- printer_id
  - printer identifier (alphanumeric or underscore characters)
- host
  - printer address
- port
  - printer port (will be 9100)
- cpl, encoding, upsideDown, spacing, cutting, gamma, command
  - see the printer configuration above
Please back up this json file as it will be initialized by updating the package.

Serial-LAN Converter

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

Setup

Install the virtual serial port driver for the printer and Node Serialport
```
$ npm install serialport
$ cd node_modules/receiptline
```
Configure servers.json
```
"serial": {
    "host": "127.0.0.1",
    "port": 9100,
    "device": "COM9"
}
```
- serial
  - to enable it, change from _serial
- host
  - local address
- port
  - local port
- device
  - the system path of the serial port
Please back up this json file as it will be initialized by updating the package.
Restart the server
```
$ npm start
```

Syntax

Railroad diagram

document

line

columns

column

text

char

escape

ws (whitespace)

property

member

key

value

Grammar

Structure

The receipt is made of a table, which separates each column with a pipe |.

Line	Content	Description
column `\|` column `\|` `\|` column column `\|`	Text Property	Single column
column `\|` column `\|` column `\|` column `\|` `\|` column `\|` column column `\|` column `\|`	Text	Double column
column `\|` ... `\|` column `\|` column `\|` ... `\|` column `\|` `\|` column `\|` ... `\|` column column `\|` ... `\|` column `\|`	Text	Multiple columns

Alignment

The column is attracted to the pipe | like a magnet.
␣ means one or more whitespaces.

Column	Description
column `\|`column`\|` `\|␣`column`␣\|`	Center
`\|`column `\|`column`␣\|` column`␣\|`	Left
column`\|` `\|␣`column`\|` `\|␣`column	Right

Text

The text is valid for any column.

Asparagus | 0.99
Broccoli | 1.99
Carrot | 2.99
---
^TOTAL | ^5.97

Characters are printed in a monospace font (12 x 24 px).
Wide characters are twice as wide as Latin characters (24 x 24 px).
Control characters are ignored.

Special characters in text

Special characters are assigned to characters that are rarely used in the receipt.

Special character	Description
`\`	Character escape
`\|`	Column delimiter
`{`	Property delimiter (Start)
`}`	Property delimiter (End)
`-` (1 or more, exclusive)	Horizontal rule
`=` (1 or more, exclusive)	Paper cut
`~`	Space
`_`	Underline
`"`	Emphasis
`	Invert
`^`	Double width
`^^`	Double height
`^^^`	2x size
`^^^^`	3x size
`^^^^^`	4x size
`^^^^^^`	5x size
`^^^^^^^` (7 or more)	6x size

Escape sequences in text

Escape special characters.

Escape sequence	Description
`\\`	\
`\\|`	\|
`\{`	{
`\}`	}
`\-`	- (Cancel horizontal rule)
`\=`	= (Cancel paper cut)
`\~`	~
`\_`	_
`\"`	_
\`	`
`\^`	^
`\n`	Wrap text manually
`\x`nn	Hexadecimal character code
`\`char (Others)	Ignore

Properties

The property is valid for lines with a single column.

{ width: * 10; comment: the column width is specified in characters }

Key	Abbreviation	Value	Case-sensitive	Default	Saved	Description
`image`	`i`	base64 png format	✓	-	-	Image (Recommended: monochrome, critical chunks only)
`code`	`c`	textdata	✓	-	-	Barcode / 2D code
`option`	`o`	see below	-	`code128 2 72 nohri 3 l`	✓	Barcode / 2D code options (Options are separated by commas or one or more whitespaces)
`align`	`a`	`left` `center` `right`	-	`center`	✓	Line alignment (Valid when line width < CPL)
`width`	`w`	`auto` `*` `0` -	-	`auto` (`*` for all columns)	✓	Column widths (chars) (Widths are separated by commas or one or more whitespaces)
`border`	`b`	`line` `space` `none` `0` - `2`	-	`space`	✓	Column border (chars) (Border width: line=1, space=1, none=0)
`text`	`t`	`wrap` `nowrap`	-	`wrap`	✓	Text wrapping
`command`	`x`	textdata	✓	-	-	Device-specific commands
`comment`	`_`	textdata	✓	-	-	Comment

Barcode options

Barcode options are separated by commas or one or more whitespaces.

Barcode option	Description
`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
`2` - `4`	Barcode module width (px)
`24` - `240`	Barcode module height (px)
`hri`	With human readable interpretation
`nohri`	Without human readable interpretation

2D code options

2D code options are separated by commas or one or more whitespaces.

2D code option	Description
`qrcode`	QR Code
`3` - `8`	Cell size (px)
`l` `m` `q` `h`	Error correction level

Special characters in property values

Special characters in property values are different from special characters in text.

Special character	Description
`\`	Character escape
`\|`	Column delimiter
`{`	Property delimiter (Start)
`}`	Property delimiter (End)
`:`	Key-value separator
`;`	Key-value delimiter

Escape sequences in property values

Escape special characters.

Escape sequence	Description
`\\`	\
`\\|`	\|
`\{`	{
`\}`	}
`\;`	;
`\n`	New line
`\x`nn	Hexadecimal character code
`\`char (Others)	Ignore

Restrictions

Communication with the printer, status event processing, and error handling are out of scope.
SVG images depend on the font family installed on the computer and may not display properly.
The QR code for display is encoded in UTF-8, while the QR code for printing is encoded in ASCII or Shift_JIS.

Author

Open Foodservice System Consortium
http://www.ofsc.or.jp/

License

receiptline
- Apache License, Version 2.0
QR Code Generator for JavaScript with UTF8 Support
- MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
designer		designer
example		example
lib		lib
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
designer.js		designer.js
package-lock.json		package-lock.json
package.json		package.json
printers.json		printers.json
readme_designer.png		readme_designer.png
readme_printer.jpg		readme_printer.jpg
screenshot_de.png		screenshot_de.png
screenshot_en.png		screenshot_en.png
screenshot_ja.png		screenshot_ja.png
servers.json		servers.json

Folders and files

Latest commit

History

Repository files navigation

receiptline

Features

Receipt Printers

Installation

Usage

Method

Parameters

Return value

Printer configuration

Examples

example/receipt/*

example/nodejs/*

example/js/*

example/data/*

Libraries

lib/receiptline.js

lib/qrcode-generator/qrcode.js

ReceiptLine Designer

Setup

Serial-LAN Converter

Setup

Syntax

Railroad diagram

Grammar

Structure

Alignment

Text

Special characters in text

Escape sequences in text

Properties

Barcode options

2D code options

Special characters in property values

Escape sequences in property values

Restrictions

Author

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages