README for public release; blank default printer address
Download table for release builds, supported-printer table, fork notes, credits for bundled fonts/libraries. DEFAULT_ADDR is now empty and the screenshots use a placeholder MAC.
This commit is contained in:
Gracious
@@ -1,27 +1,41 @@
|
||||
# `niimprint` — Niimbot Printer Client + Label Designer
|
||||
# Niimbot Label Designer — `niimprint`
|
||||
|
||||
Print to Niimbot label printers (B1, B18, B21, D11, D101, D110) over Bluetooth or USB, from a CLI or a desktop label designer with full emoji support.
|
||||
Design and print labels on Niimbot thermal label printers (B1, B18, B21, D11, D101, D110) over Bluetooth or USB. Includes a desktop **label designer** with drag-and-drop text and ~1,900 emoji, and the `niimprint` command-line client / Python library it is built on.
|
||||
|
||||
|
||||
|
||||
Fork of [AndBondStyle/niimprint](https://github.com/AndBondStyle/niimprint). Changes in this fork:
|
||||
## Download
|
||||
|
||||
- **Label designer app** (`label_app.py`): drag-and-drop text and emoji, rotation, live 1-bit preview, light/dark themes
|
||||
Standalone builds, no Python needed — grab the latest from the [releases page](https://git.gracious.one/gracious_admin/NIIMBOT-D101/releases):
|
||||
|
||||
| File | Platform |
|
||||
|---|---|
|
||||
| `NiimbotLabel.exe` | Windows 10/11 x64 |
|
||||
| `NiimbotLabel` | Linux x64 (needs a system Tcl/Tk) |
|
||||
|
||||
Pair the printer over Bluetooth in your OS first, then enter its MAC address in the app's *Printer* box (see [Bluetooth connection](#bluetooth-connection) for which address to use). For USB, leave the address blank to auto-detect, or enter the port (`/dev/ttyACM0`, `COM3`).
|
||||
|
||||
## Supported printers
|
||||
|
||||
| Model | Max print width | Density | Notes |
|
||||
|---|---|---|---|
|
||||
| B1, B21 | 384 px (50 mm tape) | 1–5 | |
|
||||
| B18 | 384 px | 1–3 | |
|
||||
| D11, D110 | 96 px (12 mm tape) | 1–3 | |
|
||||
| D101 | 192 px (25 mm tape) | 1–3 | tested on 12 mm tape, firmware 20.51 |
|
||||
|
||||
Printers print at 8 px/mm (~203 dpi). Add a model in `niimprint/models.py` if yours is missing.
|
||||
|
||||
## About this fork
|
||||
|
||||
Fork of [AndBondStyle/niimprint](https://github.com/AndBondStyle/niimprint) (itself a fork of [kjy00302/niimprint](https://github.com/kjy00302/niimprint)). Changes here:
|
||||
|
||||
- **Label designer app** (`label_app.py`): free placement, rotation, live 1-bit preview, full emoji set, light/dark themes, standalone builds
|
||||
- Printer model table (`niimprint/models.py`) with per-model width / density / protocol quirks; adds **D101**
|
||||
- Ported upstream PRs [#28](https://github.com/AndBondStyle/niimprint/pull/28) and [#12](https://github.com/AndBondStyle/niimprint/pull/12): D-series `ALLOW_PRINT_CLEAR`/`SET_QUANTITY` (fixes tall labels), print-status polling instead of a fixed sleep
|
||||
- Ported upstream PRs [#28](https://github.com/AndBondStyle/niimprint/pull/28) and [#12](https://github.com/AndBondStyle/niimprint/pull/12): D-series `ALLOW_PRINT_CLEAR` / `SET_QUANTITY` (fixes labels taller than ~210 px), print-status polling instead of a fixed sleep
|
||||
- `PrinterError` raised on timeouts / rejected commands instead of returning `None`
|
||||
- Tested on a D101 (firmware 20.51) over Bluetooth
|
||||
|
||||
Upstream's own changelog vs. the original project:
|
||||
|
||||
- Tested on Niimbot B1, B18, B21, D11, D110 and Python 3.11
|
||||
- Added transport abstraction: switch between bluetooth and USB (serial)
|
||||
- Disabled checksum calculation for image encoding (works fine without it so far)
|
||||
- Switched to [click](https://click.palletsprojects.com/) CLI library instead of argparse
|
||||
- Integrated [pyproject.toml](https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/) and [poetry](https://python-poetry.org)
|
||||
- Integrated [pre-commit](https://pre-commit.com/) and [ruff](https://docs.astral.sh/ruff/), re-formatted all files
|
||||
|
||||
## Installation
|
||||
## Running from source
|
||||
|
||||
```
|
||||
git clone https://git.gracious.one/gracious_admin/NIIMBOT-D101.git
|
||||
@@ -30,7 +44,9 @@ python -m venv --system-site-packages .venv # system Python gives you tkinter
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Or with [poetry](https://python-poetry.org): `poetry install`. Python 3.10+ (uses `match`); tested on 3.13.
|
||||
Or with [poetry](https://python-poetry.org): `poetry install`. Python 3.10+; tested on 3.13.
|
||||
|
||||
Then `python label_app.py` for the designer, or `python -m niimprint --help` for the CLI.
|
||||
|
||||
The label designer needs two fonts, both standard on most distros:
|
||||
|
||||
@@ -39,10 +55,10 @@ The label designer needs two fonts, both standard on most distros:
|
||||
|
||||
Edit `TEXT_FONTS` / `EMOJI_FONT` at the top of `label_app.py` if yours live elsewhere.
|
||||
|
||||
## Usage
|
||||
## Command-line client
|
||||
|
||||
```
|
||||
$ python niimprint --help
|
||||
$ python -m niimprint --help
|
||||
|
||||
Usage: niimprint [OPTIONS]
|
||||
|
||||
@@ -57,7 +73,7 @@ Options:
|
||||
--help Show this message and exit.
|
||||
```
|
||||
|
||||
### Image orientation:
|
||||
### Image orientation
|
||||
|
||||
Generally, the image comes out of the printer with the same orientation you see it on your screen. You can have your input image rotated as you like, but adjust its orientation by passing `-r <...>` flag. See the image below for clarification.
|
||||
|
||||
@@ -65,7 +81,7 @@ Generally, the image comes out of the printer with the same orientation you see
|
||||
|
||||
<!-- Excalidraw link: https://excalidraw.com/#json=vYHMBohMn5GeB-5M6SNch,TsxRmh_WKUfzYjL183FGfg -->
|
||||
|
||||
### Image resolution:
|
||||
### Image resolution
|
||||
|
||||
As far as we've tested, Niimbot printers have **8 pixels per mm** (~203 dpi) resolution. The CLI prints the image you provided as-is, without any checks of the actual label size, so be careful. However the script will check if the image width is too big for selected printer. The maximum width in pixels is usually slightly less than specified maximum width in mm:
|
||||
|
||||
@@ -73,17 +89,17 @@ As far as we've tested, Niimbot printers have **8 pixels per mm** (~203 dpi) res
|
||||
- **D11, D110**: max 96 pixels (almost equal to 15 mm * 8 px/mm = 120)
|
||||
- **D101**: max 192 pixels (25 mm tape); tested on 12 mm tape
|
||||
|
||||
### USB connection:
|
||||
### USB connection
|
||||
|
||||
For USB connection, you can omit the `--addr` argument and let the script auto-detect the serial port. However, it will fail if there're multiple available ports. On linux, serial ports can be found at `/dev/ttyUSB*`, `/dev/ttyACM*` or `/dev/serial/*`. On windows, they will be named like `COM1`, `COM2` etc. Check the device manager to choose the correct one.
|
||||
|
||||
### Bluetooth connection:
|
||||
### Bluetooth connection
|
||||
|
||||
It seems like B21 and B1 (and maybe other models?) have two bluetooth adresses. They have the same last 3 bytes, but the first 3 are rotated (for example `AA:BB:CC:DD:EE:FF` and `CC:AA:BB:DD:EE:FF`). Connection works only if you disconnect from one and connect to the other. After connecting via bluetoothctl you may get `org.bluez.Error.NotAvailable br-connection-profile-unavailable` error, but printing works fine regardless.
|
||||
|
||||
To identify which address is the correct one, run `bluetoothctl info` on the address you want to check. The incorrect one might list `UUID: Generic Access Profile` and `UUID: Generic Attribute Profile`, while the correct one will list `UUID: Serial Port`.
|
||||
|
||||
The D101 does the same: it advertises as `D101-<serial>` on two addresses (e.g. `94:11:02:…` and `11:02:94:…`); use the one whose `bluetoothctl info` lists `UUID: Serial Port`, then `pair` and `trust` it once.
|
||||
The D101 does the same: it advertises as `D101-<serial>` on two addresses (e.g. `AA:BB:CC:…` and `BB:CC:AA:…`); use the one whose `bluetoothctl info` lists `UUID: Serial Port`, then `pair` and `trust` it once.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -143,7 +159,7 @@ from niimprint import BluetoothTransport, PrinterClient, prepare_print
|
||||
|
||||
image = Image.open("label.png") # landscape, 8 px/mm
|
||||
image, density = prepare_print("d101", image, 3, rotate=90)
|
||||
printer = PrinterClient(BluetoothTransport("94:11:02:66:16:4D"))
|
||||
printer = PrinterClient(BluetoothTransport("AA:BB:CC:DD:EE:FF"))
|
||||
printer.print_image(image, density=density, model="d101")
|
||||
```
|
||||
|
||||
@@ -172,4 +188,6 @@ produces `dist\NiimbotLabel.exe` (~30 MB, no installation needed). Bluetooth use
|
||||
|
||||
## Licence
|
||||
|
||||
[MIT](https://choosealicense.com/licenses/mit/). Originally developed by [kjy00302](https://github.com/kjy00302), forked & enhanced by [AndBondStyle](https://github.com/AndBondStyle)
|
||||
[MIT](https://choosealicense.com/licenses/mit/). Originally developed by [kjy00302](https://github.com/kjy00302), extended by [AndBondStyle](https://github.com/AndBondStyle); label designer and D101 support added in this fork.
|
||||
|
||||
Bundled third-party assets: [DejaVu fonts](https://dejavu-fonts.github.io/) (Bitstream Vera licence), [Noto Color Emoji](https://github.com/googlefonts/noto-emoji) (SIL OFL 1.1), [FriBidi](https://github.com/fribidi/fribidi) (LGPL 2.1, Windows build only) — see `assets/`. Emoji metadata from [emoji-data-python](https://github.com/alexmick/emoji-data-python); UI theme by [ttkbootstrap](https://ttkbootstrap.readthedocs.io).
|
||||
|
||||
Reference in New Issue
Block a user