niimgo

A Go client for Niimbot label printers (D110, D11, K3, and compatible models)

A pure Go implementation for controlling Niimbot label printers via USB serial communication. Ported from the Python library niimprint.

• ✅ USB serial communication (CDC ACM) for D110, D11
• ✅ USB printer interface (/dev/usb/lp*) for K3 and similar models
• ✅ Automatic transport and port detection
• ✅ Support for Niimbot D110 (40x12mm labels), D11 (15x30mm labels), and K3
• ✅ Automatic image processing (scaling, conversion to black & white)
• ✅ Adjustable print density (1-5)
• ✅ Device information retrieval
• ✅ No external dependencies except Go standard library and serial port library

Download the latest release for your platform from the Releases page:

• Linux: niimgo-vX.X.X-linux-amd64.tar.gz (Intel/AMD 64-bit)
• Linux ARM: niimgo-vX.X.X-linux-arm64.tar.gz (ARM 64-bit, e.g., Raspberry Pi 4)
• Linux ARM: niimgo-vX.X.X-linux-arm.tar.gz (ARM 32-bit, e.g., older Raspberry Pi)
• macOS: niimgo-vX.X.X-darwin-amd64.tar.gz (Intel Mac)
• macOS: niimgo-vX.X.X-darwin-arm64.tar.gz (Apple Silicon M1/M2/M3)
• Windows: niimgo-vX.X.X-windows-amd64.zip (Intel/AMD 64-bit)

Extract and run:

# Linux/macOS
tar xzf niimgo-*.tar.gz
sudo ./niimgo-* -port /dev/ttyACM0 image.png

# Windows
# Extract the zip and run niimgo-windows-amd64.exe

git clone https://github.com/MarkusOderSo/niimgo.git
cd niimgo
go build -o niimgo .

go install github.com/MarkusOderSo/niimgo@latest

• Go 1.21 or higher
• USB connection to Niimbot printer
• Linux/macOS (Windows support via Niimbot Windows driver)

The D110 prints on 40x12mm labels:

• Print head width: 12mm = 96 pixels (across the label)
• Label length: up to 40mm = 320 pixels (print direction)

Your image should be 96 pixels wide and up to 320 pixels tall.

┌─────────────────────────────────┐  ↑
│                                 │  │ 12mm (96 pixels wide)
│  Your image: 96 x ??? pixels   │  │
│                                 │  ↓
└─────────────────────────────────┘
←────────── 40mm (320 pixels) ──────→
        (Print direction →)

sudo ./niimgo -port /dev/ttyACM0 examples/test_label_40x12mm_96x320.png

sudo ./niimgo -port /dev/usb/lp0 examples/test_label_40x12mm_96x320.png

The tool auto-detects the transport: USB printer devices (/dev/usb/lp*) are preferred (for K3), falling back to serial/ACM devices (for D110/D11) when no USB printer is found.

# Higher print density (1-5)
sudo ./niimgo -port /dev/ttyACM0 -density 5 examples/test_label_40x12mm_96x320.png

# K3 via USB printer interface
sudo ./niimgo -port /dev/usb/lp0 -density 5 examples/test_label_40x12mm_96x320.png

# Specify port explicitly
sudo ./niimgo -port /dev/ttyACM0 examples/test_label_40x12mm_96x320.png

# Debug mode
sudo ./niimgo -port /dev/ttyACM0 -debug examples/test_label_40x12mm_96x320.png

# Show device information only (auto-detect)
sudo ./niimgo -info

# Show device information for K3
sudo ./niimgo -port /dev/usb/lp0 -info

For best results:

1. Image width: Create your image with 96 pixels width
2. Height: Up to 320 pixels (= 40mm label length)
3. Example: A 96x200 pixel image = 12mm wide × 25mm long

# Example: Perfectly sized image
sudo ./niimgo my_label_96x200.png

# The program automatically scales to 96 pixels width
sudo ./niimgo any_image.png

• Image preparation: Use images with 96 pixels width for optimal quality
• Auto-scaling: The program automatically scales to 96 pixels width
• Length: Your image can be up to 320 pixels long (= 40mm)
• Print density: Higher values (4-5) for darker prints

This implementation:

• Uses USB serial communication via /dev/ttyACM* (CDC ACM) for D110/D11
• Uses USB printer interface via /dev/usb/lp* for K3 and similar models
• Auto-detects the transport type: USB printer devices are tried first, then serial
• Follows the same protocol as the Python version
• Baud rate: 115200
• Packet format: 0x55 0x55 [TYPE] [LEN] [DATA...] [CHECKSUM] 0xAA 0xAA
• Image format: Black/white with 1-bit per pixel (MSB = left)
• D110: Print head 12mm (96 pixels wide), labels up to 40mm long (320 pixels)

# Check if device is recognized
lsusb | grep 3513

# Check available ports
ls -la /dev/ttyACM*

# Specify port explicitly
sudo ./niimgo -port /dev/ttyACM0 test_label_40x12mm_96x320.png

The K3 printer exposes both a CDC-ACM serial interface (/dev/ttyACM*) and a USB printer interface (/dev/usb/lp*). The Niimbot protocol only works over the USB printer interface. Use -port /dev/usb/lp0 (or the appropriate number) instead:

# Check the USB printer device
ls -la /dev/usb/lp*

# Connect to K3 via USB printer interface
sudo ./niimgo -port /dev/usb/lp0 -info

# If CUPS is managing the device, you may need to disable/remove the CUPS queue
# or stop the CUPS service temporarily:
sudo systemctl stop cups
sudo ./niimgo -port /dev/usb/lp0 test.png
sudo systemctl start cups

# Run with sudo
sudo ./niimgo test_label_40x12mm_96x320.png

# OR: Add user to dialout group
sudo usermod -a -G dialout $USER
# Then log out and back in

• This is normal - the printer prints in the lengthwise direction
• The image appears at the end of the label as it passes through

• Make sure your image is 96 pixels wide
• The program scales automatically, but prepared images look better
• Increase print density with -density 5

Based on the Python implementation by kjy00302.

Contributions are welcome! Please feel free to submit a Pull Request.