README

NativeScript Star Printer

That's the demo app in action, printing on a Star Micronics TSP650II

Installation

For NativeScript 7+, please use plugin version 4+

tns plugin add nativescript-star-printer

API

requiring / importing the plugin

All examples below assume you're using TypeScript, but here's how to require the plugin with plain old JS as well:

JavaScript

var StarPrinterPlugin = require("nativescript-star-printer");
var starPrinter = new StarPrinterPlugin.StarPrinter();

TypeScript

import { StarPrinter, SPPrinter, SPCommands } from "nativescript-star-printer";

export Class MyPrintingClass {
  private starPrinter: StarPrinter;
  
  constructor() {
    this.starPrinter = new StarPrinter();
  }
}

`searchPrinters`

If you're searching for a Bluetooth printer, enable Bluetooth in the device settings and pair/connect the printer. Then do:

this.starPrinter.searchPrinters().then(
    (printers: Array<SPPrinter>) => {
      console.log(`Found ${printers.length} printers`);
    }, (err: string) => {
      console.log(`Search printers error: ${err}`);
    });

The most useful property on the SPPrinter class is the portName which you will need in other API methods.

The only other property is modelName.

`connect`

Once you know the printer port name, you can connect to it.

Note that there's no need to connect if you want to print as the print function does this automatically.

this.starPrinter.connect({
  portName: thePortName
}).then((result: SPPrinterStatusResult) => console.log("Connected: " + result.connected));

`getPrinterStatus`

After connecting to a printer, you can use this method to poll for the 'online' and 'paper' statuses.

this.starPrinter.getPrinterStatus({
  portName: this.lastConnectedPrinterPort
}).then(result => {
  const online: boolean = result.online;
  const onlineStatus: PrinterOnlineStatus = result.onlineStatus;
  const paperStatus: PrinterPaperStatus = result.paperStatus;
});

`print`

Once you've got the port of the printer you want to print to, just do:

this.starPrinter.print({
  portName: this.selectedPrinterPort,
  commands: commands
});

So what are those commands? Let's recreate the fake receipt below to answer that (see the TypeScript definition for all options):

const image = ImageSource.fromFile("~/res/mww-logo.png");

// Note that a standard 3 inch roll is 48 characters wide - we use that knowledge for our "columns"
let commands = new SPCommands()
    .image(
        image,
        true, // diffuse
        true // align center (set to 'false' to align left)
     )
    // alternatively, you can use imagePositioned for a bit more control (on Android this behaves the same as 'image' though)
    .imagePositioned(
        image,
        80, // width
        20, // position
        true, // both scale
        true, // diffuse
        true // align center (set to 'false' to align left)
     )
    .alignCenter()
    .text("My Awesome Boutique").newLine()
    .text("In a shop near you").newLine()
    .setFont("smaller")
    .text("Planet Earth").newLine()
    .setFont("default")
    .newLine()
    .text("Date: 11/11/2017                   Time: 3:15 PM")
    .horizontalLine() // you can pass in the character and the nr of characters (use 48 for a 3" roll, 42 for a smaller one)
    .newLine()
    .textBold("SKU           Description                  Total").newLine()
    .text("300678566     Plain White Tee             €10.99").newLine()
    .text("300692003     Black Dénim                 €29.99").newLine()
    .text("300651148     Blue Denim                  €29.99").newLine()
    .newLine()
    .newLine()
    .barcode({
      type: "Code128",
      value: "12345678",
      width: "large",
      height: 60,
      appendEncodedValue: false
    })
    .newLine()
    .cutPaper();

this.starPrinter.print({
  portName: this.selectedPrinterPort,
  commands: commands
});

`openCashDrawer`

In case a cash drawer is connected via the UTP (network) connector of the Star printer, you can open the drawer from your code!

this.starPrinter.openCashDrawer({
  portName: this.selectedPrinterPort
});

iOS runtime permission reason

iOS 10+ requires a permission popup when connecting (the first) time to a Bluetooth peripheral explaining why it needs to connect.

You can provide your own reason by adding something like this to app/App_Resources/ios/Info.plist:

  <key>NSBluetoothPeripheralUsageDescription</key>
  <string>My reason justifying fooling around with your Bluetooth</string>

To not crash your app in case you forgot to provide the reason this plugin adds an empty reason to the .plist during build. This value gets overridden by anything you specified yourself. You're welcome.

Known limitations

On iOS you want to run this on a real device.

Future work

Possibly add more print formatting options.

Usage no npm install needed!