Release Documentation

Introduction

Overview

RTNBrotherPrintSDK is a React Native Turbo Module that bridges the gap between the native Brother Print SDK and React Native. It acts as a wrapper around our native SDK for iOS and Android, providing a single interface.

Compatibility

The React Native SDK is built using version 4.12.0 of the native Brother Print SDKs.

License

Use of this software is governed by an End-User License Agreement (EULA), found in LICENSE-EULA in the root directory. In addition, use of the Brother Print SDK is governed by its own EULA, found in EULA-SDK.pdf in the root directory.

Features

• Printer Communication
  • Search and connect to printers using channels.
  • Request printer information.
  • Send commands and data directly to the printer.
• Printing Functions
  • Print images and PDFs.
  • Batch printing.
• Print Settings
  • Create and update PrintSettings for different families of printers.
  • Copy print settings across printer families or models.
• Update Firmware
  • Update firmware of any printer using the SDK.
• Native SDK Integration
  • 1:1 mapping of most native functions.^1
• Error handling and validation
  • Comprehensive list of errors and validations are handled by the React Native SDK.
• Platform-Specific Operations
  • Maintained integrity of platform specific functions.

How to use the module

Installing the module

1. Copy the rtn-brotherprintsdk-1.0.0.tgz file to location of your choice. Preferably your project folder run following command

yarn add location_of_tgz_file/rtn-brotherprintsdk-1.0.0.tgz

This will add the library as dependency for your react project.

Android

no further steps is needed. You should be able to run your project.

iOS

run following command from your iOS folder

RCT_NEW_ARCH_ENABLED=1 bundle install && bundle exec pod install

This will install the required pod dependency in your ios project.

Basic Operations

The SDK provides 4 ways to search for your compatible printers.

1. Bluetooth Classic
2. Bluetooth Low Energy
3. Network
4. USB

Search

Bluetooth

You can search for Bluetooth Printers using the startBluetoothSearch() function. This function returns a list of Bluetooth classic printers that are connected to your handset. Only printers that are connected to your handset are returned by this function; it does not perform a Bluetooth search. Connect the printer to your handset using the Bluetooth settings first, then start search for Bluetooth printers.

BLE

You can search for Bluetooth Low Energy printers using the startBLESearch(SearchOptions) function. This function can accept SearchOptions as an argument. Specifying searchDuration in the SearchOptions will search for the mentioned duration. BLE search ONLY uses the searchDuration from SearchOptions. All other fields are ignored.

Network

You can search for Network printers by using the startNetworkSearch(SearchOptions) function. This function can accept SearchOptions as an argument. You can specify the duration of search using this object. If you are searching in iOS, you can specify which printer model you are searching for by using the printerList property. This is only available in iOS. If you are searching for network printers in Android, you can search for tethered network printers by using the isTethering variable. This is only available in Android.

USB

You can search for printers connected to your handset with the startUSBSearch() function. This function is only available in Android. You cannot search for printers connected to Apple devices.

Alternative to Search

If you know the information needed to identify a particular printer, you can use it to create a Channel directly, rather than waiting for a printer search. The React Native Module provides five functions for this purpose. Each returns a Channel that can be used the same way as a Channel returned by a search.

Bluetooth

For iOS only, use newBluetoothChannelWithSerialNumber(serialNumber: string).
For Android only, use newBluetoothChannelWithMacAddress(macAddress: string).
Both return a Channel with the serial number or MAC address you specify.

BLE

The function newBluetoothLowEnergyChannel(localName: string) returns a Channel with the local name you specify.

Network

The function newWifiChannel(ipAddress: string) returns a Channel with the IP address you specify.

USB

The function newUsbChannel() returns a Channel of the right type for a USB connection. You can't specify a particular printer. When you use this Channel in an openChannel call, the SDK will attempt to connect to the first Brother printer it finds on USB.

Open Channel

A search returns a list of Channels. A Channel has the information the SDK needs to connect to a printer. It holds the connection type ("Wifi", "Bluetooth", "BluetoothLowEnergy", or "USB") and information such as an IP address or MAC address that identifies the printer to connect to. See Channel (Android) or BRLMChannel (iOS) in the SDK Manual for form information. You use the openChannel(Channel) function to tell the SDK to use the Channel information to connect to the specified printer.

Print Image

The React Native Module provides three functions for printing an image.

Setup

Before printing with these functions, you must:

1. Connect to a printer with the openChannel() function
2. Configure the print job with the newPrintSettings() and updatePrintSettings() functions. You may send as many print jobs or information requests as you like. When done, call closeChannel.

Printing

You can print one image that is in a file using the printImageFile(string) function. The string parameter is the full path to a file stored on your handset. Most standard image formats (jpg, bmp, png, etc.), are accepted. You can print multiple images, each in a file, using the printImageFiles(string[]) function. The parameter is an array of paths to files stored on your handset. Most standard image formats (jpeg, bmp, png, etc.), are accepted. You can print an image from a bitmap using the printImageBitmap(string) function. The parameter is a Base64-encoded string created from an array of bytes that contain the image data. The original data is the same as what would be found in a standard image file.

Print PDF

The React Native Module provides three functions for printing a PDF.

Setup

Before printing with these functions, you must:

1. Connect to a printer with the openChannel() function
2. Configure the print job with the newPrintSettings() and updatePrintSettings() functions. You may send as many print jobs or information requests as you like. When done, call closeChannel.

Printing

You can print one PDF file using the printPDFFile(string) function. The string parameter is the full path to a file stored on your handset. This function prints all pages of the PDF. You can print multiple PDF files using the printPDFFiles(string[]) function. The parameter is an array of paths to files stored on your handset. This function prints all pages of all of the PDF files. You can print selected pages of a single PDF file using the printPDFPages(string, number[]) function. The string parameter is the full path to a file stored on your handset. The number[] parameter is an array of page numbers. The function prints only the pages of the PDF that are listed in the array.

Request Printer Info

The RTN module provides one to one relation for all functions that request data from the printer. You can request information like printer status, media version, battery info and many more.

Setup

Before using these functions to request information from a printer, you must connect to the printer with the openChannel() function. No other setup is required. You may send as many print jobs or information requests as you like. When done, call closeChannel.

Printer Status

You can use the getPrinterStatus() function to return printer status. If successful, this function returns an instance of PrinterStatus. The raw data is contained in the rawData property, which is array of bytes returned by the SDK. Other properties provide human-readable values of some parts of the rawData.

Media Version

You can use the getMediaVersion() function to get the media version that is currently used by the printer. If the request is successful, a promise resolve is returned by the RTN module. Some printer families do not support this function.

Serial Number, Firmware Version

You can use the getSerialNumber() and getMainFirmVersion() functions to get the serial number and firmware version of the printer. If the request is successful, a promise resolve with a string value of each field is returned.

System Report

The getSystemReport() function returns a string that contains information about the printer's configuration and status. The content and format vary across printer families.

Printer Communication

This section describes sending raw data or commands to the printer. Most of the SDK printing functions take formatted data, such as a jpeg image or a PDF, and process it to a format the printer can accept. The processed data goes to the printer along with commands that may change the printer's configuration. The React Native Module also provides three functions that tell the SDK to send data to the printer without processing. These functions provide only printer communication. You must provide commands and data that are meaningful to the printer. The Command References for each printer family are available on the Brother Support site. You may send commands and data to the printer as a raw binary stream, or you may put them in a binary file. The file name must have an extension of ".prn" or ".bin".

Setup

Before using these functions to communicate with a printer, you must connect to the printer with the openChannel() function. No configuration is required, other than what is in the raw data you send. When done with print functions, info request functions, and raw data/command functions, call closeChannel().

Sending data/commands

You can send one binary file using the sendPRNFile(string) function. The string parameter is the full path to a file stored on your handset. The extension must be ".prn" or ".bin". You send multiple binary files together using the printPRNFiles(string[]) function. The parameter is an array of paths to files stored on your handset. The printer will see the file contents as a single stream with no boundaries between files. You can send raw binary data to the printer using the sendRawData(string) function. The string parameter is a Base64-encoded string created from an array of bytes that contain the raw data.

Single-operation Convenience Functions ("WithChannel" functions)

Any number of the individual functions above for printing or otherwise communicating with printer may be sent between an openChannel() and a closeChannel(). One common use case is to do only one printer operation between open and close. The React Native Module provides a set of functions for this use case. Most of the functions described above have a "WithChannel" variant, where the function name has WithChannel appended, and the function takes an addition argument that is a Channel. Each of these functions performs the following sequence:

1. Open a channel (equivalent to your code calling openChannel(Channel)).
2. If the open was successful, perform one printer operation.
3. Close the channel (equivalent to closeChannel()). The "WithChannel" variants are:

printImageFileWithChannel(channel: Channel, path: string): Promise<PrintError>;
printImageFilesWithChannel(channel: Channel, paths: string[]): Promise<PrintError>;
printImageBitmapWithChannel(channel: Channel, bitmap: string): Promise<PrintError>;
printPDFFileWithChannel(channel: Channel, path: string): Promise<PrintError>;
printPDFFilesWithChannel(channel: Channel, paths: string[]): Promise<PrintError>;
printPDFPagesWithChannel(channel: Channel, path: string, pages: number[]): Promise<PrintError>;
sendPRNFileWithChannel(channel: Channel, path: string): Promise<PrintError>;
sendPRNFilesWithChannel(channel: Channel, paths: string[]): Promise<PrintError>;
sendRawDataWithChannel(channel: Channel, data: string): Promise<PrintError>;
requestMainFirmVersionWithChannel(channel: Channel): Promise<string>;
requestSerialNumberWithChannel(channel: Channel): Promise<string>;
requestSystemReportWithChannel(channel: Channel): Promise<string>;
requestBatteryInfoWithChannel(channel: Channel): Promise<BatteryInfo>;
requestMediaVersionWithChannel(channel: Channel): Promise<string>;
getPrinterStatusWithChannel(channel: Channel): Promise<GetStatusResult>;

Errors

All functions that interact with the SDK returns a promise. If the operation was successful, the promise will be resolved and the returned object will be included in the resolve. If there is any type of error, then the promise will be rejected and the error will be included in the userInfo section of the reject. In most cases, the reject will have an EnumMap containing the error. However, if you get an error trying to print or to request printer information, the error object will no longer be just an EnumMap. It will have the full PrintError, including logs and any other relevant information sent by the printer. The React Native Module sends all the errors that the native SDK returns in the reject of the promise. All enum values are wrapped with an EnumMap. The React Native Module itself may return an error, also wrapped in an EnumMap, if the module decides that there isn't enough information to be sent to the printer, or the information sent is invalid. These errors that are returned by the Module have been standardized for both iOS and Android. All errors returned by the Module will have 4 properties.

• Code
• Message
• Throwable (Not used at the moment. All relevant information is returned in the UserInfo)
• UserInfo

Code

Code will represent the type of error that occurred in the SDK. There could be three types of error

1. SDK Error: This type of error is returned by the SDK.
2. Invalid Argument Error: This type of error is returned by the module if it detects the request is invalid.
3. Unknown Error: This type of error is a catch all error. This error should never happen. If it does, please report the error back to us so that we can fix the issue.

Custom Error Codes sent by RTN module.

RTN module will use integers 60xxx to represent errors in different part of the app. An example of how the error is structured is given below. Let's assume that we are trying to update print settings, but the printer family/series the user provided doesn't exist or is invalid. In this case, CODE: in the promise reject will be E_INVALID_ARGUMENT. Message: will be "Invalid argument sent. Check your request object" throwable: will be null userInfo: Will have only property error which will contain the information about the error. In most cases, this error will be of type EnumMap containing information about the error. During print operation, or request information about the printer, the error object will contain an object of type PrintError.

EnumMap {
   type: PrintSettingsResult,
   label: UnsupportedPrinterSeries,
   code: 60302
}

The final reject will look like following;

reject {
   code: E_INVALID_ARGUMENT
   message: Invalid Argument sent. Check your request object
   throwable: null
   userInfo: {
      "error": {
         "type": "PrintSettingsResult",
         "label": "UnsupportedPrinterSeries",
         "code": 60302
      }
   }
}

List of error definitions

| Code | Type | Description | |---|---|---| | 600xx | RTNModuleError - This shouldn't occur. | Anything above 60000 are errors generated by the RTNModule. This will be used to send errors related to reading data or printer status from the printer. | | 601xx | RTNSearchError | This will be used to send errors related to Search Operation. | | 602xx | RTNOpenChannelError | This will be used to send errors related to Opening a Channel. | | 603xx | RTNPrintSettingsError | This will be used to send errors related to PrintSettings. | | 604xx | RTNPrintError | This will be used to send errors related to PrintError. | | 605xx | RTNRequestPrinterInfoError | This will be used to send errors related to RequestPrinterInfoError. | | 609xx | RTNUpdateFirmwareError | This will be used to send errors related to Updating Firmware. |

60000 RTNModuleError

This set of error codes will be thrown by the RTN Module to catch general errors. | Code | Label | Description | Possible Fix | |---|---|---|---| | 60001 | NoPrinterConnected | User tried to use a printer but the RTM module doesn't have any connected printer. | Start by searching for printer and opening a channel. | | 60002 | PrinterAlreadyConnected | User tried to open a new channel with the module when it already has a connected printer. | Close channel first, then try to open a new channel. | | 60003 | FunctionUnavailable | This function is only available in iOS or Android|Use functions respective to your platform. | Use functions respective to your platform. |

6010x RTNSearch Error

This set of integers will be used to send errors related to Search Operation.

6020x RTNOpenChannelError

| Code | Label | Description | Possible Fix | |---|---|---|---| | 60201 | UnknownPrinterModel | User supplied a printerModel parameter this is not recognized. | Verify the requested printer model is valid. | | 60202 | InvalidDataProvidedForOpenChannel | User supplied invalid data while trying to open channel. This could be because one of the following;1. Invalid or wrong IP address 2. Invalid or wrong Bluetooth Serial Number 3. Invalid or wrong BLE local name. | | | 60203 | InvalidChannelType | User supplied a Channel instance with an invalid channelType property | Verify the Channel properties are valid. |

6030x RTNPrintSettingsError

| Code | Label | Description | Possible Fix | |---|---|---|---| | 60300 | NoError | | | | 60301 | NoSettings | User tried to get, update, copy, or validate current PrintSettings but the RTN module has no PrintSettings. | Use newPrintSettings to create a PrintSettings and modify as needed with updatePrintSettings. | | 60302 | UnsupportedPrinterSeries | User tried to update current PrintSettings with a printer model of an unsupported type. | Verify the requested printer model is valid and is in a supported series (PJ/RJ/TD). | | 60303 | UnknownPrinterModel | User supplied a printerModel parameter this is not recognized. | Verify the requested printer model is valid. | | 60304 | UnknownProperty | User tried to create/update current PrintSettings with an invalid property name or value. | Verify the parameters are correct. | | 60305 | WrongPrinterModel | User specified a printer model that doesn't work with current PrintSettings | Verify the printer model is appropriate for the current PrintSettings |

6040x RTNPrintError

| Code | Label | Description | Possible Fix | |---|---|---|---| | 60401 | NoDriver | User tried to print without first connecting to a printer | Start by searching for a printer and opening a channel. | | 60402 | NoSettings | Requested print operation requires a PrintSettings. | Use newPrintSettings to create a PrintSettings and modify as needed with updatePrintSettings. | | 60403 | InvalidBitmap | User data is not a valid bitmap | Create a valid bitmap as a byte array before Base64 encoding. | | 60404 | InvalidBase64Data | Error decoding Base64-encoded data | Verify that Base64 data is encoded correctly. |

6050x RTNRequestPrinterInfoError

6090x RTNUpdateFirmwareError

Code Documentation

TypeScript Generated documentation

FAQ

• I provided list of printer models in the startNetworkSearch() function, but all printers are being returned.
  • Make sure that you are running the search in iOS device. Searching for printer model doesn't work in Android.
• I sent ZPL or ESC/P command to print some raw data, but it isn't printing.
  • Make sure that the printer is in the right mode to receive the command. If it is not in the right mode, printer will receive the command but never do anything with it.
• When searching for network printers, I get an javascript error saying "Possible unhandled promise rejection."
  • There could be many reason for you to see this error. One of the reason could be, that you are not sending all 3 arguments in the startNetworkSearch function. If you are only using searchDuration, you still need to send the other 2 parameters as undefined. ^1 Template not included.