Terminal I/O Profile Client Implementation Guide

Terminal I/O Profile Client Implementation Guide
Terminal I/O Profile
Client Implementation Guide
[04.2016]
30507ST10753A Rev. 05 – 2016-08-18
Mod. 0809 2016-08 Rev.7
SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE
NOTICE
While reasonable efforts have been made to assure the accuracy of this document, Telit
assumes no liability resulting from any inaccuracies or omissions in this document, or from
use of the information obtained herein. The information in this document has been carefully
checked and is believed to be reliable. However, no responsibility is assumed for
inaccuracies or omissions. Telit reserves the right to make changes to any products
described herein and reserves the right to revise this document and to make changes from
time to time in content hereof with no obligation to notify any person of revisions or changes.
Telit does not assume any liability arising out of the application or use of any product,
software, or circuit described herein; neither does it convey license under its patent rights
or the rights of others.
It is possible that this publication may contain references to, or information about Telit
products (machines and programs), programming, or services that are not announced in
your country. Such references or information must not be construed to mean that Telit
intends to announce such Telit products, programming, or services in your country.
COPYRIGHTS
This instruction manual and the Telit products described in this instruction manual may be,
include or describe copyrighted Telit material, such as computer programs stored in
semiconductor memories or other media. Laws in the Italy and other countries preserve for
Telit and its licensors certain exclusive rights for copyrighted material, including the
exclusive right to copy, reproduce in any form, distribute and make derivative works of the
copyrighted material. Accordingly, any copyrighted material of Telit and its licensors
contained herein or in the Telit products described in this instruction manual may not be
copied, reproduced, distributed, merged or modified in any manner without the express
written permission of Telit. Furthermore, the purchase of Telit products shall not be deemed
to grant either directly or by implication, estoppel, or otherwise, any license under the
copyrights, patents or patent applications of Telit, as arises by operation of law in the sale
of a product.
COMPUTER SOFTWARE COPYRIGHTS
The Telit and 3rd Party supplied Software (SW) products described in this instruction
manual may include copyrighted Telit and other 3rd Party supplied computer programs
stored in semiconductor memories or other media. Laws in the Italy and other countries
preserve for Telit and other 3rd Party supplied SW certain exclusive rights for copyrighted
computer programs, including the exclusive right to copy or reproduce in any form the
copyrighted computer program. Accordingly, any copyrighted Telit or other 3rd Party
supplied SW computer programs contained in the Telit products described in this instruction
manual may not be copied (reverse engineered) or reproduced in any manner without the
express written permission of Telit or the 3rd Party SW supplier. Furthermore, the purchase
of Telit products shall not be deemed to grant either directly or by implication, estoppel, or
otherwise, any license under the copyrights, patents or patent applications of Telit or other
3rd Party supplied SW, except for the normal non-exclusive, royalty free license to use that
arises by operation of law in the sale of a product.
30507ST10753A Rev. 05
Page 2 of 23
2016-08-18
USAGE AND DISCLOSURE RESTRICTIONS
I.
License Agreements
The software described in this document is the property of Telit and its licensors. It is
furnished by express license agreement only and may be used only in accordance with the
terms of such an agreement.
II.
Copyrighted Materials
Software and documentation are copyrighted materials. Making unauthorized copies is
prohibited by law. No part of the software or documentation may be reproduced,
transmitted, transcribed, stored in a retrieval system, or translated into any language or
computer language, in any form or by any means, without prior written permission of Telit
III.
High Risk Materials
Components, units, or third-party products used in the product described herein are NOT
fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control
equipment in the following hazardous environments requiring fail-safe controls: the
operation of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air
Traffic Control, Life Support, or Weapons Systems (High Risk Activities"). Telit and its
supplier(s) specifically disclaim any expressed or implied warranty of fitness for such High
Risk Activities.
IV.
Trademarks
TELIT and the Stylized T Logo are registered in Trademark Office. All other product or
service names are the property of their respective owners.
V.
Third Party Rights
The software may include Third Party Right software. In this case you agree to comply with
all terms and conditions imposed on you in respect of such separate software. In addition
to Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this
License shall apply to the Third Party Right software.
TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED
FROM ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY
MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY MATERIALS FROM
WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE
USE OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH THE SOFTWARE,
INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY
QUALITY OR FITNESS FOR A PARTICULAR PURPOSE.
NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED
AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY,
ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE
OR THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS
LICENSE AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
30507ST10753A Rev. 05
Page 3 of 23
2016-08-18
APPLICABILITY TABLE
PRODUCTS
BLUEMOD+SR
BLUEMOD+S
BLUEMOD+S42
30507ST10753A Rev. 05
Page 4 of 23
2016-08-18
CONTENTS
NOTICE
..................................................................................................... 2
COPYRIGHTS ................................................................................................ 2
COMPUTER SOFTWARE COPYRIGHTS ...................................................... 2
USAGE AND DISCLOSURE RESTRICTIONS ............................................... 3
I.
License Agreements ..................................................................... 3
II.
Copyrighted Materials ................................................................... 3
III.
High Risk Materials ....................................................................... 3
IV.
Trademarks .................................................................................. 3
V.
Third Party Rights ......................................................................... 3
APPLICABILITY TABLE ................................................................................ 4
CONTENTS .................................................................................................... 5
1.
INTRODUCTION .......................................................................... 7
2.
GENERALS ................................................................................ 10
3.
TERMINAL I/O PROFILE OVERVIEW ....................................... 11
Generic Attribute Profile (GATT) ................................................. 11
GATT Structure of Terminal I/O Profile ....................................... 11
4.
TERMINAL I/O CONNECTION SETUP ...................................... 13
5.
TERMINAL I/O UART DATA EXCHANGE ................................. 15
Receiving UART Data ................................................................. 15
Sending UART Data ................................................................... 15
6.
TERMINAL I/O BONDING AND SECURITY .............................. 16
7.
TERMINAL I/O GATT STRUCTURE IN DETAIL ........................ 17
Terminal I/O Service ................................................................... 17
7.1.1.
Terminal I/O Manufacturer Specific Advertisement Data ............. 17
UART Data TX Characteristics ................................................... 17
UART Data RX Characteristics ................................................... 18
UART Credits TX Characteristics ................................................ 18
UART Credits RX Characteristics ............................................... 18
8.
TERMINAL I/O V2.0 VERSUS LEGACY V1.0 ............................ 19
Credit Based Flow Control Mechanism ....................................... 19
30507ST10753A Rev. 05
Page 5 of 23
2016-08-18
Uni-directional GATT Characteristics .......................................... 19
Unified UUID Definition ............................................................... 19
Defined Connected State for Profile Level Connection................ 20
Optional Enforcing of Secure and Encrypted Data Exchange ..... 20
Reduction of Required Advertisement Data ................................ 20
9.
GLOSSARY AND ACRONYMS ................................................. 21
10.
DOCUMENT HISTORY .............................................................. 22
30507ST10753A Rev. 05
Page 6 of 23
2016-08-18
1.
INTRODUCTION
1.1.
Scope
This document describes the Terminal I/O client implementation.
1.2.
Audience
This document is intended for Telit customers about to implement the Terminal I/O profile
in their application.
1.3.
Contact Information, Support
For general contact, technical support services, technical questions and report
documentation errors contact Telit Technical Support at:

TS-SRD@telit.com
Alternatively, use:
http://www.telit.com/support
For detailed information about where you can buy the Telit modules or for recommendations
on accessories and components visit:
http://www.telit.com
Our aim is to make this guide as helpful as possible. Keep us informed of your comments
and suggestions for improvements.
Telit appreciates feedback from the users of our information.
30507ST10753A Rev. 05
Page 7 of 23
2016-08-18
1.4.
Text Conventions
Danger – This information MUST be followed or catastrophic equipment
failure or bodily injury may occur.
Caution or Warning – Alerts the user to important points about integrating the
module, if these points are not followed, the module and end user equipment
may fail or malfunction.
Tip or Information – Provides advice and suggestions that may be useful
when integrating the module.
All dates are in ISO 8601 format, i.e. YYYY-MM-DD.
30507ST10753A Rev. 05
Page 8 of 23
2016-08-18
1.5.
Related Documents
The Terminal I/O Service Specification [3] specifies the Terminal I/O Service and its
characteristics.
The Terminal I/O Profile Specification [2] specifies the Terminal /IO Profile including server
operating modes, server and client role requirements and connection, configuration and
data exchange procedures.



[1] Bluetooth SIG, „GENERIC ATTRIBUTE PROFILE (GATT),“ 2013. [Online]
Available: https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx
[2] Terminal I/O Profile Specification
[3] Terminal I/O Service Specification
30507ST10753A Rev. 05
Page 9 of 23
2016-08-18
2.
GENERALS
Terminal I/O is a proprietary Bluetooth Low Energy GATT profile for bidirectional serial data
communication and GPIO status information exchange developed by Telit.
Bluetooth Low Energy GATT communication is generally carried out between a server
("peripheral") and a client ("central").
With Terminal I/O, the server role is typically implemented by a Telit embedded module (e.g.
BlueMod+SR, BlueMod+S etc.) meanwhile the client role - if not taken over by an embedded
module as well - is implemented on a smart device.
While the Bluetooth Low Energy GATT functionality is regularly implemented within the
smart device's operating system / Bluetooth protocol stack, the Terminal I/O client
implementation must be provided by the application developer.
For App development under Apple iOS® and Google Android® Telit provides ready-touse sample code of complete Terminal I/O client implementations including sample apps.
Please contact Telit for further details.
30507ST10753A Rev. 05
Page 10 of 23
2016-08-18
3.
TERMINAL I/O PROFILE OVERVIEW
Generic Attribute Profile (GATT)
A Bluetooth Low Energy connection always consists of a GATT server and a GATT client.
The GATT server stores data values, which are hierarchically structured in services and
characteristics (see figure below), while the GATT client can read and write these values
and can be notified by the server on value changes. Each Characteristic has its own
properties and can have an optional Client Characteristic Configuration, which allows
configuration of the characteristic (e.g. enable notifications).
A short introduction to GATT is given in the document “GENERIC ATTRIBUTE PROFILE
(GATT)” from Bluetooth SIG [1].
Terminal I/O is a proprietary Bluetooth Low Energy GATT profile for bidirectional serial data
communication and GPIO status information exchange developed by Telit.
Figure 1: Hierarchical structure of GATT
GATT Structure of Terminal I/O Profile
The figure below shows the GATT structure of Terminal I/O (optional elements grayed out)
defined in the Terminal I/O Profile Specification [2].
Figure 2: GATT structure of Terminal I/O Server
30507ST10753A Rev. 05
Page 11 of 23
2016-08-18
The UART data RX/TX characteristics are used for serial data exchange (see 7.2, 7.3).
The UART credits RX/TX characteristics are used for serial data flow control (see 7.4, 7.5).
The (optional) GPIO status RX/TX characteristics are used for transmission of GPIO status
information.
The (optional) Command & Control In/Out characteristics are used for command exchange.
In the following chapters, only the mandatory characteristics (UART data, UART credits)
will be discussed.
30507ST10753A Rev. 05
Page 12 of 23
2016-08-18
4.
TERMINAL I/O CONNECTION SETUP
The figure below shows the Terminal I/O connection setup procedure.
Figure 3: Terminal I/O connection setup
30507ST10753A Rev. 05
Page 13 of 23
2016-08-18
In detail, the Terminal I/O connection setup consists of the following steps:








The Terminal I/O client scans for Bluetooth Low Energy devices advertising
the Terminal I/O service.
The Terminal I/O client establishes a Bluetooth Low Energy GATT
connection to a detected Terminal I/O server.
The Terminal I/O client performs a service discovery on the Terminal I/O
server.
For the retrieved Terminal I/O service, the Terminal I/O client performs a
characteristics discovery.
The Terminal I/O client subscribes to indications of the UART credits TX
characteristic (see 7.4).
The Terminal I/O client subscribes to notifications of the UART data TX
characteristic (see 7.2).
The Terminal I/O client transmits initial UART credits to the server (see 7.5).
Once the Terminal I/O client has received the response for the transmitted
UART credits, the Terminal I/O connection is considered established and
indications for the UART credits TX characteristic and notifications for the
UART data characteristic shall be expected at any time.
The order of the connection setup sequence is mandatory. Especially, the subscription to
the UART credits TX characteristic has to be completed before subscribing to the UART
data TX characteristic.
It depends on the number of UART credits granted by the Terminal I/O server whether the
client may write UART data to the server (see 5.2).
30507ST10753A Rev. 05
Page 14 of 23
2016-08-18
5.
TERMINAL I/O UART DATA EXCHANGE
Receiving UART Data
The Terminal I/O server uses the UART data TX characteristic to send UART data to the
Terminal I/O client via notifications.
In order to receive UART data, the Terminal I/O client has to entitle the Terminal I/O server
to send data by granting UART credits via writing the number of credits to be granted to the
UART credits RX characteristic (see 7.5).
1 UART credit refers to 1 UART data notification regardless of how many bytes (1 - 20) it
may contain.
It is the Terminal I/O client's responsibility to grant an appropriate number of UART credits
in order to ensure a smooth data flow and to avoid unnecessary data traffic on the UART
credits RX characteristic.
Sending UART Data
The Terminal I/O client uses the UART data RX characteristic to send UART data to the
Terminal I/O server.
UART data are sent by writing 1 - 20 bytes to the characteristic's value without response
(see 7.3).
The Terminal I/O client shall send UART data only when UART credits granted by the
Terminal I/O server (peripheral) are available.
1 UART credit refers to 1 UART data notification regardless of how many bytes (1 - 20) it
may contain.
The Terminal I/O client receives a specific number of UART credits from the Terminal I/O
server via indications on the UART credits TX characteristic (see 7.4).
It is the Terminal I/O client's responsibility to track the number of UART credits granted by
the server (peripheral) by adding the number of received credits to a credit counter and
decrementing the credit counter for each UART data packet written to the server. Once the
credit counter reaches 0, the Terminal I/O client shall not send any UART data until having
received additional UART credits from the server.
30507ST10753A Rev. 05
Page 15 of 23
2016-08-18
6.
TERMINAL I/O BONDING AND SECURITY
For Terminal I/O connections, security requirements are determined by the Terminal I/O
server (peripheral).
The Terminal I/O client performs the connection setup described in chapter 4. If the Terminal
I/O server is configured to require a secure link, an appropriate authentication will be
requested from the client during the subscription to the UART credits TX indications.
The client side of the bonding procedure will be carried out by the operating system's
Bluetooth protocol stack.
After successfully finishing the bonding procedure, the Terminal I/O client shall proceed with
the connection setup as described in chapter 4.
30507ST10753A Rev. 05
Page 16 of 23
2016-08-18
7.
TERMINAL I/O GATT STRUCTURE IN DETAIL
Terminal I/O Service
UUID: 0xFEFB
This is the Terminal I/O GATT service containing all Terminal I/O characteristics.
7.1.1.
Terminal I/O Manufacturer Specific Advertisement Data
The Terminal I/O server advertisements contain the following manufacturer specific data:
Figure 4: Terminal I/O manufacturer specific data
BYTE
ID
DESCRIPTION
VALUE
0
(1)
Length of manufacturer data
0x8
6
(2)
Advertising compatibility version
0x01
7
(3)
Terminal I/O server operation mode
see Table 2
8
(4)
Connection requested
0x01=true; 0x00=false
Table 1: Terminal I/O manufacturer specific data
VALUE
OPERATING MODE
0x00
Bonding only
0x01
Functional
0x10
Bondable and functional
Table 2: Terminal I/O operating mode values
UART Data TX Characteristics
UUID: 00000002-0000-1000-8000-008025000000
Type: uint8 array (20 bytes)
Properties: Notify
The Terminal I/O client uses the UART Data TX characteristic to receive UART data from
the server (peripheral) via notifications.
30507ST10753A Rev. 05
Page 17 of 23
2016-08-18
UART Data RX Characteristics
UUID: 00000001-0000-1000-8000-008025000000
Type: uint8 array (20 bytes)
Properties: Write without response
The Terminal I/O client uses the UART Data RX characteristic to write UART data to the
server (peripheral).
UART Credits TX Characteristics
UUID: 00000004-0000-1000-8000-008025000000
Type: uint8 (1 byte)
Properties: Indicate
The Terminal I/O client uses the UART Credits TX characteristic to receive UART credits
(0 - 255) from the server (peripheral) via indications.
UART Credits RX Characteristics
UUID: 00000003-0000-1000-8000-008025000000
Type: uint8 (1 byte)
Properties: Write
The Terminal I/O client uses the UART Credits RX characteristic to grant UART credits
(0 - 255) to the server (peripheral).
30507ST10753A Rev. 05
Page 18 of 23
2016-08-18
8.
TERMINAL I/O V2.0 VERSUS LEGACY V1.0
Compared with Terminal I/O v1.0, the v2.0 introduces several enhancements.
Credit Based Flow Control Mechanism
In general, GATT provides two mechanisms for over the air data exchange: exchange data
“with response” or “without response”.
The mechanism “with response” allows a reliable data exchange since the sender of the
data receives a response for every data packet send to the remote device as soon as the
data is received and processed by the remote device. This allows all sorts of error signaling
and ensures that the receiving device can keep up with the data received (e.g. can forward
it via UART that might have a slow baud rate or flow control mechanisms). The backdrop of
this “with response” mechanism is that the sender of the data has to wait for a response
after sending data before the next data can be send (single window operation), thus this
mechanism does not allow high data throughput.
The mechanism “without response” allows the sending device to continuously sent data
without having to wait for responses but provides no mechanism to prevent the sender from
overrun the receiving device (e.g. forward data via UART is delayed due to a slow baud rate
or flow control mechanisms) so the backdrop of the “without response” mechanism is that
the data exchange is not reliable under non optimal conditions.
Terminal I/O v2.0 introduces a “credit based flow control” mechanism that combines the
advantages of both of this mechanisms by allowing the data to be exchanged with the fast
“without response” mechanism while providing an additional signaling channel for the
reliable exchange of flow control information with the “with response” mechanism.
Due to this, Terminal I/O v2.0 allows fast and reliable data exchange while the legacy
Terminal I/O v1.0 allowed only fast or reliable data exchange.
Uni-directional GATT Characteristics
Any data exchange via GATT is based on “characteristics” that may signal that they can
receive, send or bidirectional exchange data.
Terminal I/O v1.0 was based on complex bidirectional characteristics but while Bluetooth
low energy support became more popular in mobile devices, it turned out that such solution
became not common and several popular mobile platforms had their difficulties with
handling such complex bidirectional nature.
Due to this, Terminal I/O v2.0 now uses separate characteristics for each data exchange
direction. This simplifies the profile implementation since every characteristic has a simple,
clear functionality.
Unified UUID Definition
The Terminal I/O v1.0 service definition was completely based on 128bit UUIDs did not
have any relation to each other. Such service definition requires that a remote device must
handle each UUID completely separate what increases complexity and resource
requirements.
Due to that Telit applied and received a unique and officially assigned 16bit UUID for the
Terminal I/O profile from the Bluetooth SIG that is now used to identify the Terminal I/O v2.0
service. Additionally Telit assigned an own 128bit “base UUID” and ensured that all 128bit
UUIDs used in the Terminal I/O v2.0 service are based on that base UUID what can simplify
the profile implementation and reduce the resource requirements.
30507ST10753A Rev. 05
Page 19 of 23
2016-08-18
Defined Connected State for Profile Level Connection
Since the Terminal I/O profile is GATT based, but the GATT layer might shared with several
other GATT based profiles on a given mobile platform, a Terminal I/O v1.0 implementation
in such platform had their difficulties when it came to determine when exactly a Terminal
I/O profile level connection is established and data exchange can be started.
Due to this, Terminal I/O v2.0 now defines the exact procedure how to signal on Terminal
I/O profile level when an implementation can expect to receive and is allowed to send its
first data.
Optional Enforcing of Secure and Encrypted Data Exchange
Certain use cases require that data is only exchanged encrypted between trusted devices
that are re-authenticated for each new connection. Bluetooth low energy provides
mechanisms to enforce such requirements but Terminal I/O v1.0 did not clearly specify how
those security mechanisms are to be enforced.
Terminal I/O v2.0 clearly defines how to enforce security if required and ensures that every
connection is authenticated so only encrypted data is exchanged in such cases.
Reduction of Required Advertisement Data
Terminal I/O defines information that must be included in the advertisement data to signal
that a device can receive connections on Terminal I/O profile level. Since advertisement
data can only have a defined limited size that might have to be shared with other
information, Telit applied and received a unique and officially assigned 16bit UUID for the
Terminal I/O profile from the Bluetooth SIG that replaces the proprietary 128Bit UUID that
was previously used for Terminal I/O v1.0.
Due to this, additional device information can be included in the advertisement data of
Terminal I/O v2.0 capable devices and the recognition and handling of such device is
simplified for each implementation on a mobile platform that have to initiate a connection.
30507ST10753A Rev. 05
Page 20 of 23
2016-08-18
9.
GLOSSARY AND ACRONYMS
Description
TTSC
Telit Technical Support Centre
USB
Universal Serial Bus
DTE
Data Terminal Equipment
UART
Universal Asynchronous Receiver Transmitter
I/O
Input Output
GPIO
General Purpose Input Output
GAP
Generic Access Profile
GATT
Generic Attribute Profile
UUID
Universal Unique Identifier
30507ST10753A Rev. 05
Page 21 of 23
2016-08-18
10.
DOCUMENT HISTORY
Revision
Date
Changes
01
2013-09-19
First issue
02
2014-06-13
Adoption of Terminal I/O V2.1 Specification
03
2014-09-15
Introduced chapter “Terminal I/O v2.0 Versus Legacy v1.0”
04
2016-05-25
Telit cover page added
05
2016-08-18
Added BlueMod+S42
Converted to new Telit template
30507ST10753A Rev. 05
Page 22 of 23
2016-08-18
[04.2016]
Mod. 0809 2016-08 Rev.7
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising