Barcode Scanner App Codelab

**Estimated time:** 14 minutes

Introduction

Welcome to the Barcode Scanner App codelab! In this tutorial, you will learn how to:

• Install the app via terminal
• Verify the service is running
• Simulate external connections using Postman
• Send commands and check responses
• Explore three use cases: successful scan, aborted scan, and unsupported device

Prerequisites

The following requirements must be met before starting this codelab:

• Castles S1U2 device is required for this codelab
• Device must be connected to a network (via WiFi)
• Barcode Scanner app (only available from the SmartPOS Store)
• Postman installed on your computer

Step 1: Install the Application

1

Open SmartPOS Store

Open the SmartPOS Store client app on your device (usually found in the terminal menu)

2

Search for App

Search for "Barcode Scanner" in the SmartPOS Store

3

Install

Install the application directly from the SmartPOS Store

4

Confirm

Confirm installation on your device

The Barcode Scanner app is only available as an official release through the SmartPOS Store.

Step 2: Verify Service Startup

1

Check Status Bar

After installation, check the status bar for the Barcode Scanner app service icon

2

Open from Launcher

If the icon is not visible, open the app from the launcher menu

3

View Connection Info

The main activity will display the service status and WebSocket connection info

4

Verify Camera Icon

Verify that the service icon (camera icon) is present in the status bar

5

Check Notifications

If an external connection has been established, the notification center will display the connection status

The WebSocket server must be running for external connections to work.

Step 3: Simulate External Connection Using Postman

1

Open Postman

Open Postman on your computer

2

Create Collection

Create a new collection

3

Create WebSocket Request

Create a new WebSocket request

4

Enter URL

Enter the WebSocket URL with the device IP and port (found in the app's main activity screen)

5

Connect

Click Connect to establish the WebSocket connection

6

Verify Connection

You should see a successful connection message

Ensure your computer and device are on the same network.

Step 4: Use Case 1 - Successful readScannerData

1

Send Command

In Postman, send the following command as a simple string (not JSON): readScannerData

2

Confirm Sent

Confirm the command has been sent successfully in Postman

3

Present Barcode

The app will initiate a scan. Present a barcode or QR code at the bottom of the device so the reader can scan it

4

Receive Response

You should receive a response in Postman with the scanned data

Success Response

{
  "status": "success",
  "data": "<scanned-barcode-data>"
}

Step 5: Use Case 2 - Aborted Scan

This use case demonstrates how to abort a scan operation using cancelRead.

1

Send Read Command

Send the readScannerData command: readScannerData

2

Send Cancel Command

Before scanning a barcode, send the cancelRead command: cancelRead

3

Check Cancel Response

You should receive the cancel confirmation: json { "status": "success", "data": "Read operation canceled" }

4

Check Read Response

You should also receive a response to the initial read command: json { "status": "error", "data": "No data read from scanner" }

This demonstrates how to abort a scan operation from an external client.

Step 6: Use Case 3 - Unsupported Device

This use case demonstrates what happens when you attempt to use the scanner on a device that does not support barcode scanning hardware.

1

Send Command on Unsupported Device

Send the readScannerData command on a device without scanner hardware

2

Receive Fatal Response

You will receive a response indicating a fatal error: json { "status": "fatal", "data": "Scanner not supported" }

This response is only returned on devices that do not support the scanner hardware. On supported devices, you will receive either a success or a recoverable error.

Command Reference

Command	Description	Response
readScannerData	Initiates a barcode scan	Success with data or error
cancelRead	Cancels an ongoing scan	Success confirmation

Response Status Types

Status	Description
success	Operation completed successfully
error	Recoverable error occurred
fatal	Unrecoverable error (e.g., unsupported hardware)

Summary

You have learned how to:

• Install and verify the Barcode Scanner app
• Connect and interact with the app using Postman
• Send commands and handle responses for successful, aborted, and unsupported scan operations

Next Steps

Value Added Services

Explore more VAS options

SmartPOS API

Learn about SmartPOS API features