For the card reader solution, you need to add specific metadata to your Android POS app. You also need to present a device management UI for pairing your mobile device and the card reader, connecting to the card reader, viewing card reader details, and updating the card reader firmware.
UI for device management
To use the card reader, store staff needs to:
- Pair the mobile device running the Adyen POS Mobile SDK with the card reader.
- See an overview of card readers. For example, to switch to a different card reader.
- View details of the card reader they are using. For example, to check the battery charge level.
- Update the firmware of the card reader they are using.
The SDK provides a built-in UI for all of those tasks. Here are some example screens.
To handle the device pairing and viewing of device details, you can:
Use the built-in UI
If you have disabled the automatic initialization of the POS Mobile SDK, you need to initialize it manually. If you are unsure of the status of the POS Mobile SDK initialization you can run a status check.
To use the device management screens built into the Adyen POS Mobile SDK for Android, call the following code.
DeviceManagementActivity.start(activity)Build a custom UI
If you have disabled the automatic initialization of the POS Mobile SDK, you need to initialize it manually .
If you intend to build your own UI for device management, use the DeviceManager interface to obtain all the necessary information.
val deviceManager = AdyenCardReaders.getInstance(context).deviceManagerFor details, see DeviceManager functions.
DeviceManager functions
DeviceManager functions let you scan for card readers through Bluetooth device discovery, connect and disconnect a card reader, get information about the currently connected card reader, and manage firmware updates.
You can use the following functions:
-
connectionState: StateFlow<ReaderConnectedState>: returns the connection state of the currently connected card reader. -
activeDeviceInfo: StateFlow<DeviceInfo>: returns the hardware information and battery state of the currently connected card reader. -
startBluetoothDiscovery(): Flow<Result<List<DiscoveredDevice>>>: starts scanning for nearby card readers. Returns an error if scanning failed. -
stopBluetoothDiscovery(): stops scanning for nearby card readers. -
getKnownDevices(): List<CardReaderDevice>: returns a list of paired card readers. -
connect(cardReaderDevice: CardReaderDevice): connects to a card reader. -
disconnect(): disconnects from the currently connected card reader. -
firmwareUpdateSummary(): Result<AvailableFirmwareUpdate>: returns information about available firmware updates for the card reader that is currently connected to the mobile device. The result includes:requiresBluetoothConnection: indicates if a Bluetooth connection is required to update the card reader.requiredDate: null, or the date by which transactions will be refused if the card reader is not updated to this firmware version.
-
startFirmwareUpdate(): implements the available card reader firmware update. Shows an error if the update failed because the card reader was connected through USB and the update required a Bluetooth connection.
Manage card reader firmware
The firmware of the card reader must be updated from time to time, to keep the reader secure. Firmware updates have a due date, at which time they become mandatory. This means the card reader cannot process transactions anymore until it is updated to the mandatory firmware version.
You must check for new firmware updates regularly, and update your card readers to the latest version.
Our built-in UI shows a red indicator when a new firmware version is available for the connected card reader, and has an Update button to start the firmware update. In case a firmware update failed because the card reader didn't have an active Bluetooth connection when the update required it, the built-in UI shows instructions on how to reset the reader before retrying the update.
Custom UI
You must check for new firmware updates regularly, and provide a way to update the card reader to the latest version.
If you use your own custom UI, it is required that you build logic into your POS app to:
- Check for new card reader firmware updates often. For example, when the app is launched.
- Handle the firmware update flow correctly within your POS app.
In this way, you are informed in time, and can prevent card readers becoming blocked because a mandatory update was not installed.
You can manage the card reader firmware using the following DeviceManager functions:
firmwareUpdateSummary(): Result<AvailableFirmwareUpdate>startFirmwareUpdate()
In case a firmware update failed because it required a Bluetooth connection and the error UpdateRequiresBluetooth is thrown, ensure you provide instructions on how to reset the card reader before retrying the update. The instructions you need to provide, are as follows:
- Power off the reader.
- Press and hold the power button until a single loud beep sounds.
- Wait for the reader to reset and reboot.
- In the Bluetooth settings of the mobile device, select "Forget This Device".
- Re-pair the reader and retry installing the update.