Developer hub / public basics / Technical article

Android printer integration

Implement a receipt or label print path around SUNMI printing services, then verify the exact printer mode, service version, paper setup and failure behavior.

Discuss your project

Implement a receipt or label print path around SUNMI printing services, then verify the exact printer mode, service version, paper setup and failure behavior.

v1.0.0 / Technical articleSources checked: 2026-08-30

Model scope: Built-in printer or named external printer on a selected SUNMI model. The official examples cover different device and printer configurations; do not generalize across the catalog.
Android version: Vendor matrix examples used for this note: V2s and V2s PLUS Android 11. Confirm the target model and batch in the current SUNMI matrix.
Firmware: Not fixed by the public note. Record the exact SUNMI OS or firmware image because printer service behavior and available modes can vary.
SDK / interface: SUNMI printing service: LineApi, CommandApi and QueryApi; service package and current printer library version are target-device inputs.
Application build: Record the exact project build and hardware environment before deployment.

What the vendor documentation covers

SUNMI documents built-in printing services and external LAN, Bluetooth and USB printer paths.
Built-in printers use an InnerPrinter virtual Bluetooth path in the documented service model; external printer support and transport are configuration-specific.
ESC/POS is the default instruction set in the documentation; some devices support TSPL and require label-mode configuration.

API surface

woyou.aidlservice.jiuiv5 / IWoyouService
LineApi: initLine, addText, printText, printTexts, printBarCode, printQrCode, printBitmap
CommandApi: sendEscCommand(byte[]), sendTsplCommand(byte[])
QueryApi: getStatus() and getInfo(PrinterInfo)
Printer status actions: OUT_OF_PAPER_ACTION, COVER_OPEN_ACTION and ERROR_ACTION

Scope and prerequisites

Named SUNMI model and printer variant.
Paper, language, receipt or label mode and connection transport.
Target Android, SUNMI OS or firmware, application build and network assumptions.
A representative print fixture and an owner for reprint and failure behavior.

Permissions and ownership

Use only the permissions required by the selected Android version and printer transport; external Bluetooth, USB and LAN paths can have different policy requirements.
Package visibility declarations are configuration inputs on Android 11 and later when the app queries a vendor service.
Obtain vendor libraries through the authorized distribution path. This site does not package the library, native binaries or AIDL files.

Error handling

Handle service binding failure, printer discovery, timeout, paper-out, cover-open, overheat, cutter, communication and reconnect states as separate operator-visible outcomes. Queueing and reprint policy belongs to the application workflow.

Known limitations

The official documentation does not make every printer API or mode universal across SUNMI models.
Column APIs and custom barcode or QR dimensions have documented printer-service version requirements.
LAN support in the printing overview is currently described for SUNMI cloud printer; do not promise arbitrary network printers from this page.
This guide is an implementation baseline; a compatibility conclusion belongs to a named project record.

Implementation path

01
Name the target model, built-in or external printer, connection transport, paper width, print language and label or receipt mode before choosing an API path.
02
Follow the current SUNMI printer-library distribution for that device. The checked English and Chinese vendor pages showed different library version text, so this public note intentionally does not prescribe one universal dependency version.
03
When the application targets Android 11 or later and discovers the documented printer service, add the required package-visibility declaration for the target service package and verify the lookup on the target image.
04
Use LineApi for ordinary text, columns, barcodes, QR codes and bitmaps. Use CommandApi only when the selected printer and mode support the required ESC/POS or TSPL instruction set.
05
Treat print calls and status queries as asynchronous device work. Keep slow status queries off the main thread and do not poll getStatus() aggressively.
06
Model the operator path for paper, cover, overheat, cutter, communication and timeout errors. A successful API call is not by itself proof that the document reached the printer.
07
Create a repeatable print fixture with representative text, non-ASCII text, QR code, barcode, bitmap, long receipt and reprint behavior before requesting a compatibility result.

Verification checklist

Record model, printer service version, firmware, paper width, print mode and application build.
Print text, columns, QR code, barcode, bitmap and a long receipt or label representative of the workflow.
Remove paper, open the cover and induce a communication or disconnect condition; record the visible and recoverable result.
Check that status and error broadcasts do not create duplicate jobs or block the UI.
Repeat after reboot, application restart, sleep or wake and printer reconnect.
Record whether the result is manufacturer-supported documentation, tested by UnitWeave, customer-validated or unsupported for the exact environment.

Publication gate

A published note must link a public source, keep claims within that source, show a named acceptance result and exclude private or customer material.

At least one public source is linked and its retrieval date is recorded.
Implementation claims stay within the named model, API and vendor-documentation scope.
UnitWeave test status is shown separately from manufacturer documentation status.
No private SDK, credential, customer binary, serial number or production data is included.
A project-specific compatibility or acceptance conclusion still requires a named test record.

License and provenance

Original UnitWeave editorial synthesis with source provenance. No vendor AAR, SO, APK, private SDK, customer binary or production data is redistributed.

Sample reference

SunmiPrinterXSample is linked as an external reference. The checked repository did not expose a root LICENSE file, so its code is not copied or redistributed here.

Source basis

Source provenance

Sources checked: 2026-08-30

The implementation content is maintained here in UnitWeave structure and wording. Source URLs remain in the provenance record for attribution and version checking; they are not a substitute for the guide.

SUNMI Integration GuideSUNMI / General integration entry point and vendor documentation navigation. / Sources checked: 2026-08-30
External SUNMI documentation. Link to the current vendor page; do not redistribute vendor SDK binaries or assume every model shares the same implementation.
Open reference
Introduction to SUNMI Printing ServicesSUNMI / Built-in and external printer paths, connection types, modes and device configuration. / Sources checked: 2026-08-30
External SUNMI documentation. Link to the current vendor page; do not redistribute vendor SDK binaries or assume every model shares the same implementation.
Open reference
APIs for Printing Thermal ReceiptsSUNMI / LineApi operations for text, barcodes, QR codes, bitmaps, columns and print transactions. / Sources checked: 2026-08-30
External SUNMI documentation. Link to the current vendor page; do not redistribute vendor SDK binaries or assume every model shares the same implementation.
Open reference
APIs for Printing Instruction SetsSUNMI / ESC/POS and TSPL command paths and label-mode considerations. / Sources checked: 2026-08-30
External SUNMI documentation. Link to the current vendor page; do not redistribute vendor SDK binaries or assume every model shares the same implementation.
Open reference
APIs for Querying PrinterSUNMI / Printer status, information queries and documented error broadcasts. / Sources checked: 2026-08-30
External SUNMI documentation. Link to the current vendor page; do not redistribute vendor SDK binaries or assume every model shares the same implementation.
Open reference
SDK Versions of Devices With Built-in PrintersSUNMI / Target-device SDK and Android package-visibility considerations for built-in printers. / Sources checked: 2026-08-30
External SUNMI documentation. The English and Chinese pages showed different printer library version text when checked; use the current page or Partner Portal entry for the target device rather than hard-coding one version here.
Open reference
SUNMI Device's Android VersionSUNMI / Model-specific Android version information; some models have multiple versions or configurations. / Sources checked: 2026-08-30
External SUNMI documentation. Link to the current vendor page; do not redistribute vendor SDK binaries or assume every model shares the same implementation.
Open reference
SunmiPrinterXSampleSUNMI / Public GitHub printer sample repository used as an external reference. / Sources checked: 2026-08-30 / b3df54b59f56f6a670429bdfca9383b95319dcd8
External reference only. The checked revision did not expose a root LICENSE file; do not copy or redistribute its code without permission.
Open reference
Android package visibilityAndroid Developers / Package visibility and manifest queries for Android 11 and later. / Sources checked: 2026-08-30
External Android documentation. Apply the guidance to the target Android API level and device policy.
Open reference