Sunmi Device SDK

A modern JavaScript/TypeScript SDK for Sunmi card readers and thermal printers. Works with Expo, React Native, Cordova, and Capacitor.

Features

• 🃏 Card Reader Support: Read/write Mifare cards, IC cards, and magnetic cards
• 🖨️ Thermal Printer: Full control over Sunmi thermal printers
• 📘 TypeScript: Full type definitions included
• 🔌 Multi-Platform: Works with Expo, React Native, Cordova, and Capacitor
• 🎯 Promise-based: Modern async/await API
• ⚡ No Cordova Required: Pure npm package for modern apps

Installation

npm install @sunmi/device-sdk

Quick Start

Card Reader

import { SunmiCardReader, CardType } from '@sunmi/device-sdk';

// Start reading a card
const result = await SunmiCardReader.startReadCard(['mifare', 'ic']);
console.log('Card detected:', result);

// Authenticate and read Mifare card
await SunmiCardReader.authMifare('FFFFFFFFFFFF', 'A', 4);
const data = await SunmiCardReader.readBlockMifare(4);
console.log('Block data:', data);

Thermal Printer

import { SunmiPrinter, PrintAlignment } from '@sunmi/device-sdk';

// Initialize printer
await SunmiPrinter.init();

// Print some text
await SunmiPrinter.setAlignment(PrintAlignment.CENTER);
await SunmiPrinter.setFontSize(24);
await SunmiPrinter.printText('Hello, Sunmi!');

// Print QR code
await SunmiPrinter.printQRCode('https://example.com', 8, 1);

// Feed paper and finish
await SunmiPrinter.feedPaper(3);

API Documentation

Card Reader

startReadCard(cardTypes: string[]): Promise<CardReadResult>

Start reading a card. Supports multiple card types: 'mifare', 'ic', 'magnetic', 'psam'.

authMifare(blockKey: string, keyType: 'A' | 'B', blockToRead: number): Promise<void>

Authenticate a Mifare card block before reading/writing.

readBlockMifare(blockToRead: number): Promise<string>

Read data from an authenticated Mifare block. Returns hex string.

writeBlockMifare(blockToWrite: number, data: string): Promise<void>

Write data to a Mifare block. Data must be a 16-byte hex string.

cancelCheckCard(): Promise<void>

Cancel an ongoing card reading operation.

Printer

init(): Promise<void>

Initialize the printer. Call this before any other printer operations.

printText(text: string): Promise<void>

Print text with current settings.

printTextWithFont(text: string, typeface: string, fontSize: number): Promise<void>

Print text with specific font settings.

setAlignment(alignment: PrintAlignment): Promise<void>

Set text alignment. Options: LEFT, CENTER, RIGHT.

setFontSize(fontSize: number): Promise<void>

Set font size in points.

printQRCode(data: string, moduleSize: number, errorLevel: number): Promise<void>

Print a QR code.

• moduleSize: 1-16 (size of each QR module)
• errorLevel: 0-3 (error correction level)

printBarcode(data: string, symbology: string, width: number, height: number, textPosition: BarcodeTextPosition): Promise<void>

Print a barcode. Supports various symbologies like 'CODE128', 'EAN13', etc.

printBitmap(base64Data: string, width: number, height: number): Promise<void>

Print a bitmap image from base64-encoded data.

printColumns(columns: string[], widths: number[], alignments: PrintAlignment[]): Promise<void>

Print text in columns (useful for receipts).

feedPaper(lines: number): Promise<void>

Feed paper by specified number of lines.

getSerialNumber(): Promise<string>

Get printer serial number.

getVersion(): Promise<string>

Get printer firmware version.

hasPrinter(): Promise<boolean>

Check if printer is available on the device.

Platform Setup

Expo 🚀 (Easiest!)

Perfect for Expo users! Uses Expo's prebuild workflow:

1. Install:

   npm install @sunmi/device-sdk

2. Prebuild:

   npx expo prebuild

3. Copy native files and register packages (one-time setup)

4. Use it:

   import { SunmiPrinter } from '@sunmi/device-sdk';
   await SunmiPrinter.printText('Hello from Expo!');

See EXPO_SETUP.md for complete step-by-step instructions and check out the expo-example/ folder for a working app!

React Native ⚡

No Cordova needed! Follow these steps:

1. Install the package:

   npm install @sunmi/device-sdk

2. Add native modules: Copy the bridge files from react-native/ directory to your Android project:

   • SunmiPrinterModule.java
   • SunmiPrinterPackage.java
   • SunmiCardReaderModule.java
   • SunmiCardReaderPackage.java

3. Copy native Android code:

   cp -r src/android/com your-rn-project/android/app/src/main/java/
   cp -r src/android/woyou your-rn-project/android/app/src/main/aidl/
   cp libs/rel.aar your-rn-project/android/app/libs/

4. Register in MainApplication.java:

   import com.sunmi.SunmiCardReaderPackage;
   import com.sunmi.SunmiPrinterPackage;
      
   @Override
   protected List<ReactPackage> getPackages() {
     return Arrays.asList(
       new MainReactPackage(),
       new SunmiCardReaderPackage(),
       new SunmiPrinterPackage()
     );
   }

5. Use in your app:

   import { SunmiPrinter } from '@sunmi/device-sdk';
   await SunmiPrinter.printText('Hello from React Native!');

See react-native/README.md for complete setup instructions.

Cordova

The package maintains Cordova compatibility. The existing plugin.xml works as-is.

Capacitor

Similar setup to React Native. Create Capacitor plugins using the native Android code.

Examples

Print a Receipt

import { SunmiPrinter, PrintAlignment } from '@sunmi/device-sdk';

async function printReceipt() {
  await SunmiPrinter.init();
  
  // Header
  await SunmiPrinter.setAlignment(PrintAlignment.CENTER);
  await SunmiPrinter.setFontSize(28);
  await SunmiPrinter.printText('My Store Name');
  await SunmiPrinter.feedPaper(1);
  
  // Items
  await SunmiPrinter.setAlignment(PrintAlignment.LEFT);
  await SunmiPrinter.setFontSize(20);
  await SunmiPrinter.printColumns(
    ['Item 1', '10.00'],
    [20, 10],
    [PrintAlignment.LEFT, PrintAlignment.RIGHT]
  );
  
  await SunmiPrinter.printColumns(
    ['Item 2', '15.00'],
    [20, 10],
    [PrintAlignment.LEFT, PrintAlignment.RIGHT]
  );
  
  // Total
  await SunmiPrinter.feedPaper(1);
  await SunmiPrinter.printColumns(
    ['TOTAL', '25.00'],
    [20, 10],
    [PrintAlignment.LEFT, PrintAlignment.RIGHT]
  );
  
  await SunmiPrinter.feedPaper(3);
}

Read Mifare Card

import { SunmiCardReader } from '@sunmi/device-sdk';

async function readCard() {
  // Start reading
  const card = await SunmiCardReader.startReadCard(['mifare']);
  console.log('Card UID:', card.uid);
  
  // Authenticate with default key
  const block = 4;
  await SunmiCardReader.authMifare('FFFFFFFFFFFF', 'A', block);
  
  // Read data
  const data = await SunmiCardReader.readBlockMifare(block);
  console.log('Block data:', data);
}

Error Handling

All methods return promises that reject on error:

try {
  await SunmiPrinter.printText('Hello');
} catch (error) {
  console.error('Print failed:', error);
}

License

MIT

Contributing

Contributions welcome! Please open an issue or PR on GitHub.