# AB Circle Bluetooth iOS Demo

The AB Circle Bluetooth iOS Demo Application is a Swift application demonstrating the use of the "ABCSmartCardIO" framework.  

The "ABCSmartCardIO" framework is a Swift framework used for iOS applications to communicate with ABC Bluetooth Smart Card Readers 
through a derived version of the Java Smart Card I/O API as defined by [JSR 268](https://jcp.org/en/jsr/detail?id=268). 
To do so, the framework implements a custom "TerminalFactory" interface written in Swift which is referenced by this demo application.

## Supported Readers

- CIR415
- CIR515

## OS Support

- This demo application supports iOS 13.0 or above.

## Prerequisites

1. A Mac computer
2. An Apple Developer Account: https://developer.apple.com/programs/register/
2. Xcode IDE - Xcode 11 or higher
2. An iOS device  - iPhone or iPad

## Getting Started

1. Open the project in Xcode 11 or higher
2. Connect the iPhone or iPad to the Mac
3. Select the iPhone or iPad as Target and press "Run" to start the demo on the device

Note: it is also possible to run the demo in a simulator also, but simulators do not have bluetooth support available.

## Demo Details
  
### Main Screen

The Demo application consists of a main view holding controls to:
1. Discover Bluetooth Devices
2. Select a Card Terminal
3. Connect to a Card on the Terminal
4. Send APDU or Escape Commands to the connected Terminal
5. Monitor the status of Card Terminals by use of a monitor class.

Notes:
- Details and results are shown in a logger text view.  
- Options can be changed in an options screen: 
    - A custom encryption key; in case a custom key is set in the bluetooth reader used.
    - Filters on terminal name and RSSI value
    - Card Terminal monitor refresh rate and battery threshold values
    - Enabling or disabling of the ACK Protocol (supported on readers with fw 109.00 or above).
      The ACK protocol uses ACK and NACK packets to try to further stabilise communication and 
      enables the possibility to recover communication errors in most cases.
- Press the 'Disconnect' button to disconnect (and unpair) a selected terminal completely.
- Press the 'Battery' button to get the battery level of the selected terminal.
- Press the 'Version' button to get the firmware version of the selected terminal.
- Enable or disable the Card Terminal monitor by pressing the 'Monitor' switch.
<br>

### Usage

1. Start the application, the main screen will open (with no terminals selected)
2. Turn on a CIR415/CIR515 Bluetooth reader and press the 'Refresh' button on the main screen
3. If a CIR415/CIR515 reader has been found, the selected terminal field will show its name
4. Press the selected terminal field to open a terminal selection view in order to select another terminal if needed
5. Choose the connection method (exclusive or direct) and the connection protocol (T=0, T=1 or both)
6. Place a card on the CIR415 reader (or insert a card in the CIR515 reader) and press'Connect' to connect to the card using above-mentioned settings
7. Press 'Send' to send the default APDU or tap the APDU field to enter another APDU first
8. Alternatively, press 'Send' to send the default escape command or tap the Escape Command field to enter another command first

Notes:
- Bluetooth devices can be discovered using the 'Discover' button. This will initiate a scan without connecting to a terminal.
- Apdu / Escape command fields will only enabled after connecting to a terminal / card.
- For testing card detection, disconnect from a terminal and press 'Wait Card Change' to wait for a card change and tap / remove a card from the CIR415/CIR515 reader.
- When a CIR415/CIR515 is using a custom encryption key, press the pencil icon in the top bar to open the Options window and input the custom key there.
- A Card Terminal monitor has been added which monitors Card Terminals for disconnection and a battery threshold value.
<br>

### Demo Contents

The following files are shown in the demo project:
- Main.storyboard : Holds the main views used in the demo
- ViewController.Swift: Main class controlling the main view and using the ABCSmartCardIO framework functionality
- TextInputViewController.Swift: Class controlling the APDU / Escape command input view
- OptionsController.Swift: Class controlling the Custom Key input view, terminal name / RSSI filters and Card Terminal monitor options
- Options.Swift: Class holding the various options used in the demo application
- NoCaretUITextField.Swift: Custom read only UITextField control (used for APDU / Escape Command input fields)
- NoCaretUITextView.Swift: Custom read only UITextView control (used for the log view)
- HexEditUITextView.Swift: Custom UITextView control enabling hexadecimal input (used for APDU / Escape Command input)
- ToolbarUIPickerView.Swift: Custom UIPickerView with toolbar (used for terminal selection)
- Helper.Swift: Class holding some helper functions  
- ABCCardTerminalMonitor.Swift: Card Terminal monitor to help monitor the disconnecting of Card Terminals or their battery level
- CardTerminalToMonitor.Swift: Class holding information on a monitored Card Terminal
- Info.plist: application information property list (see also the paragraph below for bluetooth access)
- Assets.sxassets: defines the icons used in this demo
  
Notes:
- For details on above classes, see also the documentation in the Documentation folder.
- Other files are auto-generated files when the project was created and should not be modified
<br>

### Bluetooth Access Rights for applications

In order for applications to use bluetooth, access needs to be enabled by adding a usage description key to the info.plist file.
On apps linked on or after iOS 13, include the "NSBluetoothAlwaysUsageDescription" key. In iOS 12 and earlier, include "NSBluetoothPeripheralUsageDescription" to access Bluetooth peripheral data.

See also:  https://developer.apple.com/documentation/corebluetooth
<br>
  
## History

v1.5.8                23 Apr 2024
* Uses AB Circle SmartCardIO framework v1.5.8
* fixed Xcode backward compatibility issue

v1.5.7                16 Apr 2024
* Uses AB Circle SmartCardIO framework v1.5.7

v1.5.6                04 Feb 2024
* Uses AB Circle SmartCardIO framework v1.5.6
* Added reader discovery

v1.5.5                29 Aug 2023
* Uses AB Circle SmartCardIO framework v1.5.5

v1.5.4                16 May 2023
* Uses AB Circle SmartCardIO framework v1.5.4

v1.5.3                28 February 2022
* Uses AB Circle SmartCardIO framework v1.5.3
* Added option for setting ACK Protocol (supported by readers using fw 109.00 or higher)

v1.4.5                08 February 2022
* Uses AB Circle SmartCardIO framework v1.4.5

v1.4.4                04 February 2022
* Uses AB Circle SmartCardIO framework v1.4.4

v1.4.3                31 January 2022
* Uses AB Circle SmartCardIO framework v1.4.3

v1.4.2                02 September 2021
* Uses AB Circle SmartCardIO framework v1.4.2

v1.4.1                26 May 2021
* Uses AB Circle SmartCardIO framework v1.4.1

v1.4.0                03 May 2021
* Uses AB Circle SmartCardIO framework v1.4.0
* Added support for the CIR515 reader
* Added Card Terminal monitor

v1.3.0                12 April 2021
* Uses AB Circle SmartCardIO framework v1.3.0
* Added Battery button to get the battery level of a selected terminal
* Added Version button to get the firmware version of a selected terminal

v1.2.1                25 March 2021
* Uses AB Circle SmartCardIO framework v1.2.1

v1.1.0                18 February 2021
* Uses AB Circle SmartCardIO framework v1.2.0
* Added terminal name and RSSI filters in the Options screen
* Added disconnect button for disconnecting a terminal
  
v1.0.0                21 December 2020
* Initial release

## Authors

* **ABC Software Team** (engineering@abcircle.com)

## License
```
Copyright (c) 2018-2024, AB Circle Ltd. All rights reserved.
```
