NiimPrintX

NiimPrintX is a Python library designed to seamlessly interface with NiimBot label printers via Bluetooth. It provides both a Command-Line Interface (CLI) and a Graphical User Interface (GUI) for users to design and print labels efficiently.

Fork Notice

This is a community-maintained fork of the original labbots/NiimPrintX. The upstream project was last updated in May 2024 and is no longer actively maintained. We picked up where it left off to keep NiimPrintX alive and moving forward.

Since forking, we have:

• Merged outstanding upstream pull requests from the community
• Conducted 26 rounds of deep code review (143 findings fixed), hardening the codebase throughout
• Added a comprehensive test suite (354 pytest tests, 90%+ coverage) and CI/CD pipeline
• Replaced the pickle-based .niim file format with a secure JSON-based format
• Introduced user-configurable custom label sizes, per-device rotation, and BLE resilience improvements

Current version: v0.9.0

A huge thank you to labbots for creating NiimPrintX and building the foundation this project stands on.

Key Features

• Cross-Platform Compatibility: Works on Windows, macOS, and Linux.
• Bluetooth Connectivity: Effortlessly connect to NiimBot label printers via BLE, with auto-reconnect and lock-based concurrency for resilient connections.
• Comprehensive Model Support: Compatible with multiple NiimBot printer models (D11, D11_H, D101, D110, D110_M, B1, B18, B21).
• Dual Interface Options: Provides both a Command-Line Interface (CLI) and a Graphical User Interface (GUI).
• Custom Label Design: The GUI enables users to design labels tailored to specific devices and label sizes.
• Advanced Print Settings: Customize print density, quantity, and image rotation for precise label printing.
• JSON-Based .niim Format: Label designs are saved in a secure JSON format, replacing the original pickle-based approach to eliminate deserialization risks.
• User-Configurable Label Sizes: Define custom label dimensions and device profiles via a simple TOML config file.
• Per-Device Rotation Settings: Configure default rotation on a per-device basis through the config file.
• Decompression Bomb Protection: Image loading includes safeguards against decompression bomb attacks.
• Comprehensive Test Suite: 380 pytest tests (90%+ coverage) covering packets, Bluetooth communication, image encoding, configuration, CLI, and print integration.
• CI/CD Pipeline: Automated ruff linting, pytest runs on every push, and PyInstaller builds for Linux, macOS, and Windows on tagged releases.

Requirements

To run NiimPrintX, you need to have the following installed:

• Python 3.12 or later -- bleak's winrt backend requires Python 3.12+, and the TOML config parser (tomllib) requires Python 3.11+
• ImageMagick library (GUI only -- not required for CLI usage)
• Poetry for dependency management

Supported Printer Models

D11, D11_H, D101, D110, D110_M, B1, B18, B21

Installation

If you plan to use the GUI, ensure that ImageMagick is installed and properly configured on your system. You can download it from here. The CLI does not require ImageMagick.

Clone the repository:

git clone https://github.com/avicennasis/NiimPrintX.git
cd NiimPrintX

Install the necessary dependencies using Poetry (Poetry manages its own virtual environment automatically):

poetry install

To include the optional GUI dependencies (Tkinter theme):

poetry install --extras gui

After installation, two console entry points are available:

niimprintx --help    # CLI interface
niimprintx-ui        # GUI application

These are the recommended way to run NiimPrintX. The python -m invocations shown in the Usage section below also work.

Note:

ImageMagick is only required for the GUI (--extras gui). The CLI works without it.

macOS specific setup for local development:

brew install libffi
brew install glib gobject-introspection cairo pkg-config

export PKG_CONFIG_PATH="$(brew --prefix libffi)/lib/pkgconfig"
export LDFLAGS="-L$(brew --prefix libffi)/lib"
export CFLAGS="-I$(brew --prefix libffi)/include"

User Configuration

NiimPrintX supports an optional TOML configuration file for customizing device settings and adding custom label sizes. The config file is located at:

• Linux/macOS: ~/.config/NiimPrintX/config.toml
• Windows: %LOCALAPPDATA%\NiimPrintX\config.toml

(The exact path is determined by platformdirs.)

Example config.toml

# Add custom label sizes to an existing built-in device
[devices.d110.size]
"30mm x 15mm" = [30, 15]
"custom" = [60, 20]

# Define an entirely new device (must include at least one valid size)
[devices.myprinter]
density = 3
print_dpi = 203
rotation = 270

[devices.myprinter.size]
"50mm x 25mm" = [50, 25]

How merging works

• Existing devices: User-defined sizes are merged into the built-in size list. You can add new label sizes without losing the defaults.
• New devices: You can define entirely new device entries. A new device must include at least one valid size (a [width, height] pair). Optional settings (density, print_dpi, rotation) default to 3, 203, and 270 respectively if omitted.

Usage

NiimPrintX provides both CLI and GUI applications to use the printer.

Command-Line Interface (CLI)

The CLI allows you to print images and get information about the printer models.

General CLI Usage

Usage: python -m NiimPrintX.cli [OPTIONS] COMMAND [ARGS]...

Options:
  -v, --verbose  Enable verbose logging
  -h, --help     Show this message and exit.

Commands:
  info
  print

Print Command

Usage: python -m NiimPrintX.cli print [OPTIONS]

Options:
  -m, --model [b1|b18|b21|d11|d11_h|d110|d101|d110_m]
                                  Niimbot printer model  [default: d110]
  -d, --density INTEGER RANGE     Print density  [default: 3; 1<=x<=5]
  -n, --quantity INTEGER RANGE    Print quantity  [default: 1; 1<=x<=65535]
  -r, --rotate [0|90|180|270]     Image rotation (clockwise)  [default: 0]
  --vo INTEGER                    Vertical offset in pixels  [default: 0]
  --ho INTEGER                    Horizontal offset in pixels  [default: 0]
  -i, --image PATH                Image path  [required]
  -h, --help                      Show this message and exit.

Example:

python -m NiimPrintX.cli print -m d110 -d 3 -n 1 -r 90 -i path/to/image.png

Info Command

Usage: python -m NiimPrintX.cli info [OPTIONS]

Options:
  -m, --model [b1|b18|b21|d11|d11_h|d110|d101|d110_m]
                                  Niimbot printer model  [default: d110]
  -h, --help                      Show this message and exit.

Example:

python -m NiimPrintX.cli info -m d110

Graphical User Interface (GUI)

The GUI application allows users to design labels based on the label device and label size. Simply run the GUI application:

python -m NiimPrintX.ui

Development

Contributions are welcome! Please fork the repository and submit a pull request with your improvements.

Running Tests

poetry run pytest -v

Running Lint

poetry run ruff check NiimPrintX/ tests/

Formatting

poetry run ruff format NiimPrintX/ tests/

Type Checking

poetry run mypy NiimPrintX/nimmy/ NiimPrintX/cli/

Building

Automated builds for Linux, macOS (Intel and Apple Silicon), and Windows are handled by GitHub Actions workflows. Tagged releases trigger PyInstaller builds and publish artifacts to GitHub Releases.

Credits

• Special thanks to labbots for creating the original NiimPrintX project. The vision, architecture, and initial implementation are all theirs -- this fork simply carries the torch forward.

Community Contributors

This fork incorporates pull requests and addresses issues submitted by the original project's community. Thank you to everyone who contributed code, bug reports, and feature requests:

Merged Pull Requests:

• @LorisPolenz — B1 printer support via V2 protocol (#6)
• @hadess — Linux desktop and metainfo files for Flatpak (#16)
• @kwon0408 — Encoding crash fix for non-ASCII font names (#28)
• @uab2411 — Device selection propagation fix (#30)
• @teambob — D110 BLE connection discovery fix (#33)
• @corpix — D11_H (300 DPI) support (#36)
• @CMGeorge — Multi-line text label support (#39)
• @atanarro — Python 3.13 dependency updates (#41)

Issues that informed our work:

• @cropse — D101 support request (#2)

• @raenye — Per-device DPI for 2024 models (#4)

• @parisneto — B1 label size correction (#5)

• @Cvaniak — Config file for custom label sizes (#7)

• @Adrian-Grimm — D11_H print bug report (#8)

• @x1klim — macOS Bluetooth plist crash report (#9)

• @hadess — Linux theme, Flatpak, CLI file open, multi-line labels (#14, #15, #17, #21)

• @quistuipater — B21 GUI visibility (#19)

• @krp-ulag — D11 rotation orientation fix (#24)

• @kwon0408 — Korean Windows encoding crash (#26)

• @verglor — Rotation feature request (#38)

• Icons made by Dave Gandy from www.flaticon.com

• Icons made by Pixel perfect from www.flaticon.com

• Icons made by Freepik from www.flaticon.com

• Icons made by rddrt from www.flaticon.com

• Icons made by Icongeek26 from www.flaticon.com

• Icons made by SyafriStudio from www.flaticon.com

• Icons made by Wahyu Adam from www.flaticon.com

• Icons made by meaicon from www.flaticon.com

• Icons made by IconKanan from www.flaticon.com

• Icons made by kornkun from www.flaticon.com

• Icons made by Rifaldi Ridha Aisy from www.flaticon.com

License

NiimPrintX is licensed under the GNU General Public License v3.0. See the LICENSE file for details.