Thermaltastic

Control a Adafruit thermal printer over different adapters. This library is very WIP.

· Report Bug · Request Feature ·

About The Project

I wanted to talk to a thermal printer over an api. I experimented with a esp32 and quickly came to its limits.

After investigating the Adafruit library and many many failed other attempts, I concluded that I can extract the heavy lifting to TypeScript and only run a light mqtt to serial implementation on the esp32.

To allow different 'streams' like mqtt I came up with the adapter concept.

So now you can utilize the versatile package landscape of NPM to generate bitmaps, wrap it in REST APIs and and and.

Installation

npm i @beuluis/thermaltastic

Unstable installation

The next dist-tag is kept in sync with the latest commit on main. So this contains always the latest changes but is highly unstable.

npm i @beuluis/thermaltastic@next

Usage

const printer = new Thermaltastic(adapter);

await printer.begin();

await printer.println('Hello World!');

Adapters

The original library used a serial stream to send the bytes to the printer. In this implementation we use adapters to achieve this.

A adapter defines how the printer receives the bytes.

MqttasticAdapter

Send the to print bytes over mqtt.

⚠️ You need the corresponding arduino MQTT client also listening: See ThermalMqttasticPrinter for more details.

You also need a MQTT broker. An example would be eclipse-mosquitto.

const adapter = new MqttasticAdapter({
    mqttUrl: 'mqtt://localhost:1883',
    mqttOptions: {
        password: '12345678',
    },
});

new Thermaltastic(adapter);

MQTT connection

mqttOptions is the option interface of the MQTT package. Please refer to this documentation on how to establish the connection.

Implement your own adapter

For your own adapter you just need to implement the Adapter interface.

export class MyAdapter implements Adapter {
    public async begin() {}

    public async write(...bytes: [number, number?, number?, number?]) {}

    public async writeBytes(...bytes: [number, number?, number?, number?]) {}
}

Functions

Parameters get validated using zod. Please refer to this documentation on how the parameters get validated.

setTimes(dotPrintTime: number, dotFeedTime: number)

This method sets the times (in microseconds) for the paper to advance one vertical 'dot' when printing and when feeding.

Parameter constrains:

• z.number().int().nonnegative().parse(dotPrintTime);
• z.number().int().nonnegative().parse(dotFeedTime);

Example

printer.setTimes(10, 15);

print(message: string)

Prints the message.

Example

await printer.print('Hello World!');

println(message: string)

Prints the message with a line break at the end.

Example

await printer.println('Hello World!');

begin(firmware = 268)

Initializes the printer and set default values. Needs to be called before performing any operations!

Parameter constrains:

• z.number().int().nonnegative().parse(firmware);

Example

await printer.begin();

reset()

Resets the printer!

Example

await printer.begin();

setDefaults()

Resets all text formatting back to the defaults.

Example

await printer.setDefaults();

test()

Prints a test.

Example

await printer.test();

testPage()

Prints a test page.

Example

await printer.testPage();

setBarcodeHeight(barcodeHeight = 50)

Sets the printing height of the barcode.

Parameter constrains:

• z.number().int().nonnegative().parse(barcodeHeight);

Example

await printer.setBarcodeHeight(60);

printBarcode(text: string, type: Barcode)

Prints a barcode.

Parameter constrains:

• z.string().max(255).parse(text);

Example

await printer.printBarcode('ADAFRUT', Barcode.CODE39);

normal()

Sets print mode to normal.

Example

await printer.normal();

inverseOn()

Turn on inverse print mode.

Example

await printer.inverseOn();

inverseOff()

Turn off inverse print mode.

Example

await printer.inverseOff();

upsideDownOn()

Turn on upside down print mode.

Example

await printer.upsideDownOn();

upsideDownOff()

Turn off upside down print mode.

Example

await printer.upsideDownOff();

doubleHeightOn()

Turn on double height print mode.

Example

await printer.doubleHeightOn();

doubleHeightOff()

Turn off double height print mode.

Example

await printer.doubleHeightOff();

doubleWidthOn()

Turn on double width print mode.

Example

await printer.doubleWidthOn();

doubleWidthOff()

Turn off double width print mode.

Example

await printer.doubleWidthOff();

strikeOn()

Turn on strike print mode.

Example

await printer.strikeOn();

strikeOff()

Turn off strike print mode.

Example

await printer.strikeOff();

boldOn()

Turn on bold print mode.

Example

await printer.boldOn();

boldOff()

Turn off bold print mode.

Example

await printer.boldOff();

justify(value: 'C' | 'L' | 'R' = 'L')

Justifies the content.

Example

await printer.justify('C');

feed(lines = 1)

Feeds lines of paper.

Parameter constrains:

• z.number().int().min(1).parse(lines);

Example

await printer.feed(2);

feedRows(rows = 1)

Feeds rows of paper.

Parameter constrains:

• z.number().int().min(1).parse(rows);

Example

await printer.feedRows(2);

flush()

Flush the printer.

Example

await printer.flush(2);

setSize(value: 'L' | 'M' | 'S' = 'S')

Set the text size.

Example

await printer.setSize('L');

setPrintDensity(density = 10, breakTime = 2)

Sets the printer density.

Parameter constrains:

• z.number().int().nonnegative().max(31).parse(density);
• z.number().int().nonnegative().max(7).parse(breakTime);

Example

await printer.setPrintDensity(11, 3);

underlineOn()

Turn on underline.

Example

await printer.underlineOn();

underlineOff()

Turn off underline.

Example

await printer.underlineOff();

printBitmap(width: number, height: number, bitmap: Uint8Array)

⚠️ WIP

Prints a bitmap.

Parameter constrains:

• z.number().int().nonnegative().max(384).parse(width);
• z.number().int().min(1).parse(height);

Example

await printer.printBitmap(2, 2, new Uint8Array([0, 255, 255, 0]));

offline()

Take the printer offline. Print commands sent after this will be ignored until online is called.

Example

await printer.offline();

online()

Take the printer online.

Example

await printer.online();

sleep()

Put the printer into a low-energy state immediately.

Example

await printer.sleep();

sleepAfter(seconds: number)

Put the printer into a low-energy state after the given number of seconds.

Parameter constrains:

• z.number().int().min(1).parse(seconds);

Example

await printer.sleepAfter(1);

wake()

Wake the printer from a low-energy state.

Example

await printer.wake();

setMaxChunkHeight(value = 256)

Set maximum chunk height for bitmap printing.

Parameter constrains:

• z.number().int().min(1).parse(value);

Example

printer.setMaxChunkHeight(200);

setCharset(value = 0)

Set maximum chunk height for bitmap printing. May only work in recent firmware.

Parameter constrains:

• z.number().int().nonnegative().max(15).parse(value);

Example

printer.setCharset(10);

setCodePage(value = 0)

Select alternate characters for upper ASCII. May only work in recent firmware.

Parameter constrains:

• z.number().int().nonnegative().max(47).parse(value);

Example

await printer.setCodePage(12);

tab()

Print a tab. May only work in recent firmware.

Example

await printer.tab();

setFont(font: 'A' | 'B' = 'A')

Sets font type. May only work in recent firmware.

Example

await printer.setFont('B');

setCharSpacing(spacing = 0)

Set character spacing. May only work in recent firmware.

Parameter constrains:

• z.number().int().nonnegative().parse(spacing);

Example

await printer.setCharSpacing(10);

Debugging

You can enable the debugging logger when you provide a logger to the constructor.

const printer = new Thermaltastic(adapter, {
    logger: console,
});