libniimai 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +84 -28
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,11 +1,43 @@
|
|
|
1
1
|
# libniimai
|
|
2
2
|
|
|
3
|
-
Print
|
|
3
|
+
Print from the browser on four families of thermal printers: **NIIMBOT**, **TSPL label printers**, **ESC/POS mini printers** and **cat printers**. One API connects, detects the printer and prints any canvas, over Web Bluetooth or Web Serial. No server, no drivers, no app.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
libniimai powers [niimai](https://niimai.app), the label designer.
|
|
6
|
+
|
|
7
|
+
## Supported printers
|
|
8
|
+
|
|
9
|
+
| Family | Paper | Print width | Connection | Models |
|
|
10
|
+
|---|---|---|---|---|
|
|
11
|
+
| **NIIMBOT** | Labels with gaps, black mark, continuous, transparent | 12 mm and up, by model | Bluetooth, USB | D11, D110, D101, B1, B18, B21, B3S and more |
|
|
12
|
+
| **TSPL label printers** | Labels with gaps, black mark, continuous | Up to 80 mm | Bluetooth | QR380A (sold as CC390) |
|
|
13
|
+
| **ESC/POS mini printers** | 58 mm continuous | 48 mm | Bluetooth | MP583, MPT-II, PT-210, RPP02, ZJ-58 and more |
|
|
14
|
+
| **Cat printers** | 58 mm continuous | 48 mm | Bluetooth | GB01, GB02, GB03, MX05, MX06, MX10 and more |
|
|
15
|
+
|
|
16
|
+
The family is found from the device the user picks: by its Bluetooth name, then checked against the services it offers. Every family gets the same treatment:
|
|
17
|
+
|
|
18
|
+
- **Detection**: the right client and settings, picked for you.
|
|
19
|
+
- **Page handling**: each page is cropped to the head, rotated where the printer needs it, and encoded in the printer's own format.
|
|
20
|
+
- **Paper types**: gaps, black marks and continuous paper, on printers that tell them apart.
|
|
21
|
+
- **Density**: each printer's own darkness range, mapped from one `density` option.
|
|
22
|
+
- **Progress**: pages done, and how much of each page has been sent.
|
|
23
|
+
|
|
24
|
+
### NIIMBOT
|
|
25
|
+
|
|
26
|
+
Label printers in many widths, from 12 mm pocket models up. Protocol by [niimbluelib](https://github.com/MultiMote/niimbluelib), which libniimai loads only when a NIIMBOT connects. libniimai reads the loaded roll from its RFID tag (size, paper type, labels left) and the battery level, and adds fixes verified on hardware, such as the B21 C2B on early firmware. Models niimbluelib does not know yet print with a manual profile from `MANUAL_PROFILES`.
|
|
27
|
+
|
|
28
|
+
### TSPL label printers
|
|
29
|
+
|
|
30
|
+
Desktop label printers up to 80 mm wide that take TSC's TSPL label language. The printer finds each label's edge itself, and confirms each job. When a job goes unconfirmed, libniimai asks the printer why, and an open cover, jam or empty roll comes back as an error. Common 2- to 3-inch label sizes are listed in `profile.sizes`, 3 × 4 inch included. These printers cannot sense the roll, so `status.label.barcode` gives a stable key to remember its size per printer.
|
|
31
|
+
|
|
32
|
+
### ESC/POS mini printers
|
|
33
|
+
|
|
34
|
+
Pocket receipt printers on 58 mm paper with a 384-dot head. Pages print as one raster image at any length, for receipts, lists and long labels.
|
|
35
|
+
|
|
36
|
+
### Cat printers
|
|
37
|
+
|
|
38
|
+
The small "cat" printers sold under many names, on 58 mm paper with a 384-dot head. Five darkness levels, flow control so long prints never overrun the printer, and the newer GB03 and MX-series variants handled per model.
|
|
39
|
+
|
|
40
|
+
Each model is marked by how well it is tested in `TSPL_MODELS`, `ESCPOS_MODELS` and `CAT_MODELS`; see also [thermal-printers.md](https://github.com/theanam/niimai/blob/main/docs/thermal-printers.md).
|
|
9
41
|
|
|
10
42
|
## Install
|
|
11
43
|
|
|
@@ -13,7 +45,9 @@ Print to NIIMBOT label printers and other Bluetooth thermal printers from the br
|
|
|
13
45
|
npm i libniimai
|
|
14
46
|
```
|
|
15
47
|
|
|
16
|
-
|
|
48
|
+
Ships as an ES module with TypeScript types.
|
|
49
|
+
|
|
50
|
+
## Quick start
|
|
17
51
|
|
|
18
52
|
```ts
|
|
19
53
|
import { createPrinter } from 'libniimai';
|
|
@@ -21,26 +55,28 @@ import { createPrinter } from 'libniimai';
|
|
|
21
55
|
const printer = createPrinter();
|
|
22
56
|
printer.subscribe((status) => console.log(status.state, status.deviceName, status.progress));
|
|
23
57
|
|
|
24
|
-
//
|
|
58
|
+
// Connecting must start from a user gesture, such as a click.
|
|
25
59
|
button.onclick = async () => {
|
|
26
60
|
await printer.connect('bluetooth');
|
|
61
|
+
const { dpi } = printer.getStatus().profile!;
|
|
27
62
|
|
|
28
|
-
// A
|
|
63
|
+
// A 50 × 30 mm label at the printer's resolution.
|
|
64
|
+
const dots = (mm: number) => Math.round((mm / 25.4) * dpi);
|
|
29
65
|
const canvas = document.createElement('canvas');
|
|
30
|
-
canvas.width =
|
|
31
|
-
canvas.height =
|
|
66
|
+
canvas.width = dots(50);
|
|
67
|
+
canvas.height = dots(30);
|
|
32
68
|
const ctx = canvas.getContext('2d')!;
|
|
33
69
|
ctx.fillStyle = '#fff';
|
|
34
70
|
ctx.fillRect(0, 0, canvas.width, canvas.height);
|
|
35
71
|
ctx.fillStyle = '#000';
|
|
36
|
-
ctx.font =
|
|
37
|
-
ctx.fillText('Hello',
|
|
72
|
+
ctx.font = `bold ${dots(8)}px sans-serif`;
|
|
73
|
+
ctx.fillText('Hello', dots(4), dots(18));
|
|
38
74
|
|
|
39
75
|
await printer.print(canvas, { density: 3, copies: 1 });
|
|
40
76
|
};
|
|
41
77
|
```
|
|
42
78
|
|
|
43
|
-
Draw black on white
|
|
79
|
+
Draw black on white. Thermal printers print each dot black or white, so dither photos and greys first. The same code prints on all four families; `density` is clamped to the printer's range.
|
|
44
80
|
|
|
45
81
|
## API
|
|
46
82
|
|
|
@@ -50,39 +86,59 @@ Returns a `PrinterService`, which owns one printer connection.
|
|
|
50
86
|
|
|
51
87
|
| Member | What it does |
|
|
52
88
|
| --- | --- |
|
|
53
|
-
| `connect(kind)` | Opens the browser's device picker and connects. `kind` is `'bluetooth'
|
|
89
|
+
| `connect(kind)` | Opens the browser's device picker and connects. `kind` is `'bluetooth'` (every family), `'serial'` (NIIMBOT over USB) or `'demo'` (a printer in memory, for trying things out). |
|
|
54
90
|
| `disconnect()` | Closes the connection. |
|
|
55
|
-
| `print(source, options)` | Prints a canvas, or a `{ count, page(i) }` source for a batch of different labels.
|
|
91
|
+
| `print(source, options)` | Prints a canvas, or a `{ count, page(i) }` source for a batch of different labels. |
|
|
56
92
|
| `getStatus()` | The current `PrinterStatus`. |
|
|
57
93
|
| `subscribe(fn)` | Calls `fn` on every status change. Returns a function that unsubscribes. |
|
|
58
|
-
| `setManualProfile(id)` | Picks a printer type from `MANUAL_PROFILES` for NIIMBOT models niimbluelib does not
|
|
94
|
+
| `setManualProfile(id)` | Picks a printer type from `MANUAL_PROFILES` for NIIMBOT models niimbluelib does not know yet. |
|
|
95
|
+
|
|
96
|
+
**Print options**
|
|
59
97
|
|
|
60
|
-
|
|
98
|
+
| Option | What it does |
|
|
99
|
+
| --- | --- |
|
|
100
|
+
| `density` | Darkness, clamped to `profile.densityMin`–`densityMax`. |
|
|
101
|
+
| `copies` | Copies of each page. |
|
|
102
|
+
| `labelType` | Paper type, from `PAPER_TYPES`: 1 labels with gaps, 2 black mark, 3 continuous. |
|
|
103
|
+
| `offset` | Nudges the print, in mm: `{ x, y }`. |
|
|
104
|
+
|
|
105
|
+
**`PrinterStatus`**
|
|
106
|
+
|
|
107
|
+
| Field | What it holds |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| `state` | `disconnected`, `connecting`, `ready` or `printing`. |
|
|
110
|
+
| `deviceName` | The printer's Bluetooth name. |
|
|
111
|
+
| `profile` | `dpi`, `printheadPixels`, `printDirection`, density range, `kind: 'thermal'` for continuous-paper printers, and `sizes` for printers with a size list. |
|
|
112
|
+
| `label` | The loaded roll, where the printer reports one. |
|
|
113
|
+
| `battery` | Battery level, where the printer reports one. |
|
|
114
|
+
| `progress` | `{ page, total, sending }`; `sending` is 0–100 for the page going over the link. |
|
|
61
115
|
|
|
62
116
|
### Lower level
|
|
63
117
|
|
|
64
|
-
|
|
118
|
+
Every piece is exported, for building your own flow:
|
|
65
119
|
|
|
66
120
|
- `createClient(kind)` returns a raw client for one connection.
|
|
67
|
-
- `TsplPrinterClient`, `EscPosPrinterClient
|
|
121
|
+
- `TsplPrinterClient`, `EscPosPrinterClient` and `CatPrinterClient` take any `ThermalTransport`, so they also work over other links.
|
|
68
122
|
- `tsplJob`, `escposJob` and `catJob` build the bytes for one page.
|
|
69
|
-
- `
|
|
123
|
+
- `tsplModelFor`, `escposModelFor` and `catModelFor` match a Bluetooth name to a known model.
|
|
70
124
|
- `unsupportedReason(kind)` says in a few words why a connection type cannot be used in the current browser.
|
|
71
125
|
|
|
72
|
-
## Printers
|
|
73
|
-
|
|
74
|
-
NIIMBOT printers go through [niimbluelib](https://github.com/MultiMote/niimbluelib), which loads only when one connects. The other families and their models are listed under [Supported printers](https://github.com/theanam/niimai#supported-printers), with how well each model is tested in [thermal-printers.md](https://github.com/theanam/niimai/blob/main/docs/thermal-printers.md).
|
|
75
|
-
|
|
76
126
|
## Browsers
|
|
77
127
|
|
|
78
|
-
Needs Web Bluetooth or Web Serial: Chrome or Edge on desktop, or Chrome on Android.
|
|
128
|
+
Needs Web Bluetooth or Web Serial: Chrome or Edge on desktop, or Chrome on Android. On iPhone and iPad, the Bluefy browser adds Web Bluetooth.
|
|
79
129
|
|
|
80
130
|
## Feedback
|
|
81
131
|
|
|
82
|
-
Found a bug or a printer that should work? [Open an issue](https://github.com/theanam/niimai/issues). For anything else, write to [anam.ahmed.a@gmail.com](mailto:anam.ahmed.a@gmail.com).
|
|
132
|
+
Found a bug, or a printer that should work? [Open an issue](https://github.com/theanam/niimai/issues). For anything else, write to [anam.ahmed.a@gmail.com](mailto:anam.ahmed.a@gmail.com).
|
|
133
|
+
|
|
134
|
+
## Credits
|
|
135
|
+
|
|
136
|
+
- [niimbluelib](https://github.com/MultiMote/niimbluelib) by MultiMote, for the NIIMBOT protocol
|
|
137
|
+
- [rbaron/catprinter](https://github.com/rbaron/catprinter) and [NaitLee/Cat-Printer](https://github.com/NaitLee/Cat-Printer), for the cat printer protocol
|
|
138
|
+
- TSC's TSPL programming manual, for the label printer language
|
|
83
139
|
|
|
84
|
-
libniimai is an independent project and is not affiliated with NIIMBOT.
|
|
140
|
+
libniimai is an independent project and is not affiliated with NIIMBOT or any printer maker.
|
|
85
141
|
|
|
86
142
|
## License
|
|
87
143
|
|
|
88
|
-
[MIT](LICENSE)
|
|
144
|
+
[MIT](https://github.com/theanam/niimai/blob/main/LICENSE)
|