react-native-niimblue-lib

v1.2.1

Published

15 days ago

React Native library for BLE printing with NIIMBOT devices

Downloads

324

0High
0Medium
0Low

kidwar

react-native bluetooth ble printing niimbot thermal-printer

React Native NiimBlue Library

A React Native library for Bluetooth LE printing with NIIMBOT thermal printers. Features automatic printer model detection, rich content rendering (text, QR codes, barcodes, images), and comprehensive print control.

✨ Features

🔍 Auto-detect printer models - Automatically selects the correct print task based on connected printer
📱 BLE Communication - Direct Bluetooth Low Energy connection to NIIMBOT printers
🎨 Rich Content Support:
- Text rendering with Skia (custom fonts, alignment, scaling)
- QR codes with error correction levels
- Barcodes (EAN13, CODE128)
- Images from buffers or URIs (PNG, JPG, BMP)
- Lines and custom pixel data
🖼️ Print Preview - Generate base64 PNG previews before printing
📏 Flexible Layout - Pixel-perfect positioning with alignment options
🔄 Multiple Printer Support - B1, B21, D110, D11 and more

📦 Installation

npm install react-native-niimblue-lib

Install Required Peer Dependencies

Always required for Bluetooth connectivity:

npm install react-native-ble-plx

Optional - only needed if you use PrintPage.addText() for text rendering:

npm install @shopify/react-native-skia

Note: If you only print QR codes, barcodes, or images without text, you don't need Skia.
Alternative: Instead of using Skia, you can render text to image/pixel data using any method (Canvas, SVG, native views, etc.) and add it via addPixelData() or addImageFromBuffer().
Important: These dependencies have native code and require proper linking/building. They cannot work as transitive dependencies.

Expo Setup

If using Expo, add the BLE plugin to your app.json:

{
  "expo": {
    "plugins": [
      [
        "react-native-ble-plx",
        {
          "isBackgroundEnabled": true,
          "modes": ["peripheral", "central"],
          "bluetoothAlwaysPermission": "App needs Bluetooth to connect to NIIMBOT printers"
        }
      ]
    ]
  }
}

Then create a development build:

npx expo prebuild
npx expo run:ios
# or
npx expo run:android

Note: If you use PrintPage.addText(), Skia requires a development build and does NOT work in Expo Go. However, QR codes, barcodes, and images work fine without Skia.

iOS Setup

Install CocoaPods dependencies:

cd ios && pod install

Add to Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>App needs Bluetooth to connect to NIIMBOT printers</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Required for Bluetooth device scanning</string>

Note: If you installed @shopify/react-native-skia for text rendering, run pod install again after installation.

Android Setup

Add permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" 
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.INTERNET" />

🚀 Quick Start

Basic Printing

import { NiimbotBluetoothClient, PrintPage } from 'react-native-niimblue-lib';

// 1. Connect to printer
const client = new NiimbotBluetoothClient();
await client.connect(); // Auto-scans and connects to first NIIMBOT device

// 2. Create print task (auto-detects printer model)
client.stopHeartbeat();
client.setPacketInterval(0); // Fast printing
const task = client.createPrintTask({
  totalPages: 1,
  density: 3,
  labelType: 1,
});

if (!task) {
  throw new Error('Printer model not detected');
}

// 3. Build page content
const page = new PrintPage(400, 240); // width x height in pixels

page.addText('Hello NIIMBOT!', {
  x: 192,
  y: 100,
  fontSize: 24,
  align: 'center',
  vAlign: 'middle',
});

// 4. Print
await task.printInit();
await task.printPage(page.toEncodedImage(), 1);
await task.waitForFinished();
client.startHeartbeat();

📖 Usage Examples

Page Orientation

Use orientation parameter to automatically rotate all content for landscape printing:

// Portrait mode (default) - for vertical labels
const portraitPage = new PrintPage(400, 240, 'portrait');
portraitPage.addText('Product Name', { x: 200, y: 120 });

// Landscape mode - for horizontal labels on vertical paper
// Dimensions are AUTO-SWAPPED: 240x400 becomes 400x240 canvas + 90° rotation
const landscapePage = new PrintPage(240, 400, 'landscape');
landscapePage.addText('Product Name', { 
  x: 200, // Same coordinates work!
  y: 120, // Canvas is 400x240 (swapped) + rotated 90°
});

How it works:

Physical paper: 240px width × 400px height (vertical)
new PrintPage(240, 400, 'landscape'):
- ✅ Canvas dimensions: 400×240 (auto-swapped)
- ✅ Content rotated: 90° clockwise
- ✅ Result: Horizontal content on vertical paper
- ✅ Same coordinates as new PrintPage(400, 240, 'portrait')

Text Rendering

Option 1: Using Skia (requires @shopify/react-native-skia)

const page = new PrintPage(400, 240);

// Simple text with default font
page.addText('NIIMBOT PRINTER', {
  x: 192,
  y: 50,
  fontSize: 24,
  align: 'center',
  vAlign: 'middle',
});

// Bold text with manual rotation
import { Skia, FontStyle } from '@shopify/react-native-skia';
page.addText('Rotated Text', {
  x: 192,
  y: 100,
  fontSize: 20,
  fontStyle: FontStyle.Bold,
  align: 'center',
  vAlign: 'middle',
  rotate: 45, // Additional rotation (on top of page orientation)
});

// Custom font style
page.addText('Heavy Text', {
  x: 192,
  y: 140,
  fontSize: 18,
  fontStyle: Skia.FontStyle({ weight: 800 }), // Custom weight
  align: 'center',
  vAlign: 'middle',
  rotate: -15, // Rotate 15 degrees counter-clockwise
});

// Custom font (user loads Typeface separately)
const fontData = await Skia.Data.fromURI('file://path/to/font.ttf');
const customTypeface = Skia.Typeface.MakeFreeTypeFaceFromData(fontData);

page.addText('Custom Font Text', {
  x: 100,
  y: 180,
  fontSize: 16,
  typeface: customTypeface, // Optional
  align: 'left',
});

Option 2: Without Skia - Convert text to image first

// Example: Using react-native-view-shot to capture text as image
import { captureRef } from 'react-native-view-shot';

// 1. Render text in a hidden View with ref
const textRef = useRef();

// 2. Capture as base64
const uri = await captureRef(textRef, {
  format: 'png',
  quality: 1,
});

// 3. Convert to buffer and add to page
const response = await fetch(uri);
const arrayBuffer = await response.arrayBuffer();
const buffer = new Uint8Array(arrayBuffer);

page.addImageFromBuffer({
  buffer,
  x: 192,
  y: 100,
  align: 'center',
  vAlign: 'middle',
});

// Or use any other method: Canvas, SVG to PNG, native rendering, etc.

QR Code

page.addQR('https://github.com', {
  x: 192,
  y: 100,
  width: 150,
  height: 150,
  align: 'center',
  vAlign: 'middle',
  ecl: 'M', // Error correction: L, M, Q, H
  rotate: 90, // Optional: rotate 90 degrees
});

Barcode

page.addBarcode('123456789012', {
  encoding: 'EAN13', // or 'CODE128'
  x: 192,
  y: 150,
  width: 200,
  height: 60,
  align: 'center',
  vAlign: 'middle',
  rotate: 180, // Optional: rotate 180 degrees
});

Image from Buffer (PNG/JPG/BMP)

const imageBuffer = await fetch('https://example.com/image.jpg')
  .then(res => res.arrayBuffer())
  .then(buf => new Uint8Array(buf));

page.addImageFromBuffer({
  buffer: imageBuffer,
  x: 192,
  y: 100,
  width: 200,
  height: 150,
  align: 'center',
  vAlign: 'middle',
  threshold: 128, // Grayscale to binary threshold
  rotate: 270, // Optional: rotate 270 degrees
});

Image from URI

await page.addImageFromUri('https://example.com/logo.png', {
  x: 192,
  y: 100,
  width: 150,
  height: 150,
  align: 'center',
  vAlign: 'middle',
  threshold: 128,
});

Custom Pixel Data

const heartPixels = [
  0,0,0,0,1,1,0,0,0,0,1,1,0,0,0,0,
  0,0,1,1,1,1,1,0,0,1,1,1,1,0,0,0,
  0,1,1,1,1,1,1,1,1,1,1,1,1,1,0,0,
  // ... (1 = black, 0 = white)
];

page.addPixelData({
  data: heartPixels,
  imageWidth: 16,
  imageHeight: 11,
  x: 192,
  y: 100,
  width: 128, // Scaled width
  height: 88,
  align: 'center',
  vAlign: 'middle',
  rotate: 45, // Optional: rotate 45 degrees
});

Line Drawing

page.addLine({
  x: 10,
  y: 100,
  endX: 374,
  endY: 100,
  thickness: 2,
});

Print Preview

const page = new PrintPage(400, 240);
page.addQR('Preview Test', { x: 192, y: 100, align: 'center', vAlign: 'middle' });

// Generate base64 PNG
const base64Uri = await page.toPreviewImage();
// Display in <Image source={{ uri: base64Uri }} />

🔧 API Reference

NiimbotBluetoothClient

Methods

connect(device?: Device): Connect to printer (auto-scan or specific device)
disconnect(): Disconnect from printer
listDevices(scanDurationMs: number): Scan for available printers
listConnectedDevices(): List already connected devices
createPrintTask(options: PrintOptions): Create print task with auto-detection
setPacketInterval(ms: number): Set delay between packets (0 = fastest)
startHeartbeat() / stopHeartbeat(): Control heartbeat

PrintPage

Constructor

new PrintPage(width: number, height: number, orientation?: PageOrientation)

width: number - Page width in pixels
height: number - Page height in pixels
orientation?: 'portrait' | 'landscape' - Page orientation (default: 'portrait')
- 'portrait': Normal orientation, canvas dimensions = (width, height)
- 'landscape': Auto-swaps dimensions → canvas becomes (height, width) + rotates all content 90° clockwise
  - Perfect for printing horizontal content on vertical paper
  - Example: new PrintPage(240, 400, 'landscape') → 400×240 canvas with 90° rotation
  - Use same coordinates as new PrintPage(400, 240, 'portrait')

Methods

addText(text: string, options: TextOptions): void
addQR(text: string, options: QROptions): void
addBarcode(text: string, options: BarcodeOptions): void
addPixelData(options: ImageOptions): void
addImageFromBuffer(options: ImageFromBufferOptions): void
addImageFromUri(uri: string, options: ImageFromBufferOptions): Promise<void>
addLine(options: LineOptions): void
toEncodedImage(): EncodedImage - Convert to printer format
toPreviewImage(): Promise<string> - Generate base64 PNG preview

Type Definitions

PageOrientation

type PageOrientation = 'portrait' | 'landscape';

PrintOptions

totalPages?: number - Number of pages to print
density?: number - Print density (1-5, default: 3, higher = darker)
labelType?: number - Label type identifier (printer-specific)
statusPollIntervalMs?: number - Status polling interval in ms (default: 100)
statusTimeoutMs?: number - Status check timeout in ms (default: 8000)
pageTimeoutMs?: number - Timeout for printing each page in ms