Elatec TWN4 MultiTech 2 HF User manual

TWN4
BLE User Guide
DocRev2, June 17, 2020
Elatec GmbH

Contents
Contents
1 Introduction .............................................. 3
2 Mobile Badge 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 TWN4 Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.1 Created with AppBlaster.exe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.2 Reader with Simple Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.3 Third Party Reader App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Phone Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.1 Mobile Bagde 2.0 Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2 Mobile Bagde 2.0 iPhone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3 Third Party Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3.1 Advertise-String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3.2 GATT Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3.3 AES128 MasterKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3.4 The Authentication Process . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Cable Replacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1 Datatransfer = BLOCKWISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1.1 Simple Protocol Reader with Third Party Reader Apps . . . . . . . . . . . . . . . . 10
3.1.1.1 Reader A as Advertiser, GATT Server and Simple Command Executer . . 10
3.1.1.2 Reader B as Scanner, GATT Client and Connected to Director.exe . . . . . 12
3.1.2 Transparent Data Transfer with 2 Readers . . . . . . . . . . . . . . . . . . . . . . . 14
3.1.2.1 Reader A as Advertiser, GATT Server with Transparent Data Transfer . . . 14
3.1.2.2 Reader B as Scanner, GATT Client with Transparent Data Transfer . . . . 14
3.2 Datatransfer = BYTEWISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.1 Transparent Data Transfer with 2 Readers . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.1.1 Reader A as Advertiser, GATT Server with Transparent Data Transfer . . . 15
3.2.1.2 Reader B as Scanner, GATT Client with Transparent Data Transfer . . . . 15
3.2.2 Data Transfer with Two Readers programmed with Simple Protocol . . . . . . . . . 15
3.2.2.1 Reader A as Advertiser, GATT Server . . . . . . . . . . . . . . . . . . . . 15
3.2.2.2 Reader B as Scanner, GATT Client . . . . . . . . . . . . . . . . . . . . . . 16
4 Disclaimer............................................... 18
Page 2 of 18

1 Introduction
1 Introduction
In general, BLE integration into the TWN4 BLE reader family is performed via the API interface. The
individual API functions control the BLE controller. The following graphic shows the TWN4 BLE Open
System Interconnection model as an overview.
Page 3 of 18

2 Mobile Badge 2.0
2 Mobile Badge 2.0
2.1 TWN4 Firmware
"Mobile Badge 2.0" is a virtually programmed card which runs as an application on a phone. The app
connects to the TWN4 reader and presents the reader with a GATT server for reading and writing. The
authentication process is an AES128 process with two ways to securely authenticate the device.
2.1.1 Created with AppBlaster.exe
The AppBlaster.exe program is a simple tool for configuring the reader to read and write various cards (LF,
HF and BLE).
For the special Bluetooth card "Mobile Badge 2.0" configure the project to search for Transponder type
"BLE (Bluetooth Low Energy)" -> "Mobile Badge BLE 2.0".
Start the program AppBlaster.exe, select "Configurable project" and configure all required transponders.
For more detailed operation of AppBlaster.exe, refer to the user manual of this software.
Page 4 of 18

2 Mobile Badge 2.0
Next, select "Create Image" and "Program Image" to program the connected TWN4 reader. The reader
now reads your selected transponder and the transponder "Mobile Badge 2.0" (e.g. the phone app on
Android or iPhone).
2.1.2 Reader with Simple Protocol
The TWN4 Reader’s Simple Protocol is a very flexible way to control the TWN4 Reader over a serial
connection.
Setup your reader with Simple Protocol for reading cards:
Flash the simple protocol firmware "TWN4_NCx321_PRS104_Nano_CDC_Simple_Protocol.bix" (or newer
versions) with the software AppBlaster.exe to your TWN4 BLE reader (the reader needs to have B op-
tion).
Start the Director.exe application and press "Connect" to connect to your TWN4 reader. Select the section
"Function Test" and then API -> "BLE", Function -> "BLEInit" and Mode -> "BLE_MODE_MOBILE_BADGE_2_0".
Press "Send" to execute the function BLEInit(BLE_MODE_MOBILE_BADGE_2_0). Now the reader is con-
figured to interact with "Mobile Badge 2.0" applications (for example, an app on the phone).
Go to the "Simple Test" section. Under "Select Tag Types", in addition to the other transponders, activate
the type "BLE" in the list. Activate "Cycle" and the reader searches for the selected transponders. The
screen shows you the IDs of your presented transponder.
Page 5 of 18

2 Mobile Badge 2.0
Note: The ID of Tag Type BLE is 128 bits (= 16 bytes).
The length of the data sent by the app depends on the application. The minimum data length is 8
bytes.
Page 6 of 18

2 Mobile Badge 2.0
2.1.3 Third Party Reader App
The reading of cards is done with the Standard app. To read "Mobile Badge 2.0" cards, the app must be
extended with the following source code:
...
int main(void)
{
OnStartup();
...
SetTagTypes(LFTAGTYPES,HFTAGTYPES & ~BLE_MASK);
...
if(BLEInit(BLE_MODE_MOBILE_BADGE_2_0))
{
OnBLEStarted();
}
// Main loop
while (true)
{
...
}
}
Page 7 of 18

2 Mobile Badge 2.0
2.2 Phone Applications
2.2.1 Mobile Bagde 2.0 Android
Please download "Mobile Badge 2.0" from Play Store, install the software, start the app and accomplish
your authentication.
2.2.2 Mobile Bagde 2.0 iPhone
Please download "Mobile Badge 2.0" from Apple Store, install the software, start the app and accomplish
your authentication.
2.2.3 Third Party Application
The authentication procedures with TWN4 BLE reader can be implemented in third party applications. The
following steps helps with implementations.
2.2.3.1 Advertise-String
The TWN4 reader in the initialized mode "Mobile Badge 2.0" advertises with a preset reader string, which
you can change with your own information.
The default advertiser string sent by the reader has the following properties: "Bluetooth Low Energy"
device, reader name "ELATEC" and the manufacturer block with manufacturer ID 0x0752 (from SIG =
"ELATEC GmbH").
To change this environment, use the BLEPresetUserData (...) function.
2.2.3.2 GATT Server
The TWN4 reader is the GATT client. To implement a data exchange, create your own GATT server
with own GATT service and GATT characteristic in the application. Set the UUIDs for the GATT server
and the GATT characteristic. The data length for the characteristic should be equal to or greater than 16
bytes.
To set the UUIDs for GATT service and characteristic in the TWN4 Reader software, use the BLEStreamin-
gUUID(...) function.
2.2.3.3 AES128 MasterKey
When the connection between the GATT server and the GATT client is established, the authentication
process begins. AES128 authentication requires a 16-byte master key.
To set the Master Key use the function BLESecuritySetOob(BLE_SET_MOBILE_BADGE_MASTERKEY,
...).
Page 8 of 18

2 Mobile Badge 2.0
2.2.3.4 The Authentication Process
Start the function BLEInit(BLE_MODE_MOBILE_BADGE_2_0) and the fetch/read routine with Search-
Tag().
Use the application to connect to the TWN4 reader (the default requirement is "Bluetooth Low Energy"
Type, Reader Name "ELATEC", Manufacturer ID "ELATEC", and RSSI in the desired range).
Now the TWN4 reader checks the GATT service and GATT characteristic UUIDs and activates the notifi-
cation on the GATT server characteristic.
The whole procedure with authentication sequence is shown in this diagram:
Annotation: RND_twn4 and RND_phone are 16 bytes random numbers.
The encryption and decryption is done using AES128 with the Master Key.
The phone ID sent from your application must be at least 8 bytes long.
Page 9 of 18

3 Cable Replacement
3 Cable Replacement
The streaming mode is an operating mode for transferring individual bytes or blocks (up to 200 bytes at
once) from one device to another and vice versa. One device is a TWN4 BLE reader and the other a
second TWN4 device, a phone, a PC or another device.
3.1 Datatransfer = BLOCKWISE
3.1.1 Simple Protocol Reader with Third Party Reader Apps
This chapter describes transferring Simple Protokol commands beetween two TWN4 BLE reader. One
reader is connected to the PC and acts like a gateway which transfers commands between USB and BLE.
The other TWN4 is executing the Simple Protocol commands sent by Director.
3.1.1.1 Reader A as Advertiser, GATT Server and Simple Command Executer
The reader A is a BLE Advertiser and has the GATT Server for data saving. Following parts of the source
code describes this in outline:
void OnStartup(void)
{
LEDInit(REDLED | YELLOWLED | GREENLED);
LEDOff(REDLED);
Page 10 of 18