Getnet DocsGetnet Docs

Get Smart PeripheralsLib Overview

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

PeripheralsLib is an Android library designed to facilitate interaction between Android applications and Point-of-Sale (POS) hardware. It provides a unified interface for controlling specific peripherals on TPV-Android devices, such as thermal printers, magnetic stripe readers, and professional barcode scanners.

This guide introduces the core concepts, architecture, and capabilities of PeripheralsLib to help you understand how it integrates into your payment or retail solutions.

Purpose and Scope

The primary goal of PeripheralsLib is to abstract the complexities of low-level hardware communication. Instead of writing raw commands to device drivers, you interact with high-level Java objects and methods.

This library is specifically tailored for:

  • Printing: Sending bitmap images to the device’s thermal printer.
  • Data Capture: Reading health cards (magnetic stripe) and scanning barcodes using professional hardware scanners.
  • Device Management: Configuring kiosk modes, such as locking navigation bars or setting default launchers.

Core Architecture

PeripheralsLib operates on a Manager-Callback pattern. This ensures that your application remains responsive while hardware operations—which can be time-consuming—execute asynchronously.

The PeripheralsManager

The PeripheralsManager class is the central entry point for all library operations. It acts as a singleton-like bridge between your application context and the device hardware.

  • Initialization: You instantiate the manager once, passing the application Context. This automatically establishes the connection to the underlying terminal hardware.
  • Scope: All hardware requests (printing, scanning, configuring) are routed through this single instance.

Asynchronous Callbacks

Most hardware operations in PeripheralsLib are asynchronous. When you request an action, such as printing a receipt or waiting for a barcode scan, you must provide a Callback implementation.

The library uses specific callback interfaces for different operations:

  • PrintBmpCallback: Handles success or error states for print jobs.
  • MagReadCallback: Returns magnetic stripe data (Tracks 1 and 2) or errors.
  • BarcodeCallback: Returns scanned barcode data or errors.
  • ConfigCallback: Confirms the success or failure of system configuration changes.

This pattern ensures that your UI thread is not blocked while the device initializes the printer or waits for a user to swipe a card.

Key Features

1. Thermal Printing

The library supports printing images in Bitmap format. To ensure consistent output across different terminal models, the library relies on specific image standards (e.g., maximum width of 390px, black and white color scheme, JPEG compression).

2. Health Card Reading

PeripheralsLib includes specialized logic for Health Cards. Unlike generic magnetic stripe readers, the magStripeRead function parses specific tracks (Track 1 and Track 2) to identify if the swiped card is a valid health card.

3. Professional Barcode Scanning

For devices equipped with a dedicated professional laser scanner (hardware-based), the library provides a direct interface to trigger the scanner and retrieve data.

This feature targets devices with integrated professional scanners. It does not control the device’s standard camera.

4. Terminal Kiosk Configuration

For dedicated business environments, PeripheralsLib allows you to programmatically lock down the Android interface. This includes:

  • Status Bar & Navigation Bar: Hiding or disabling system bars to prevent users from exiting the app or changing settings.
  • Launcher Configuration: Setting a specific application package and activity as the default home screen (Launcher).

System Requirements

PeripheralsLib is compatible with Android Studio projects.

Android 12 Support

As of version 1.0.6, the library includes specific support for Android 12 and higher. Due to security changes in newer Android versions, specific permissions (android.permission.QUERY_ALL_PACKAGES) must be declared in your application’s manifest to allow the library to interact with system services correctly.