Bluetooth API migration guide - TOSHIBA Semiconductor & Storage

TC356xx
Application note
Bluetooth API migration guide
TOSHIBA TC356xx
Version 2.0.1
2.0.1
Bluetooth API migration guide
TC356xx
Contents
1 Abstract
2
2 Introduction
2
3 Fixed problems
3.1 Incorrect behaviour of hci_api_read_eeprom() . . . . . . . . . . . . . . . . .
3.2 Stack corruption in TcuMngSspSet_Response() . . . . . . . . . . . . . . .
3.3 Incorrect implementation of TcuLeGattSerReadCharValAccept_Response()
3.4 Incorrect implementation of TcuMngDiscoverRemoteServiceEvent() . . . .
3.5 Incorrect defitnition of battery service . . . . . . . . . . . . . . . . . . . . . .
3.6 Timer handling in heart rate service . . . . . . . . . . . . . . . . . . . . . .
3.7 Incorrect data length in advertising and scan response data . . . . . . . . .
3.8 Incorrect setting of BR/EDR flag in advertising data . . . . . . . . . . . . . .
3.9 Security manager protocol (SMP) may fail under certain conditions . . . . .
.
.
.
.
.
.
.
.
.
3
3
3
3
3
3
3
4
4
4
4 Known problems
4.1 Devices using both public and random addresses . . . . . . . . . . . . . . . . . . . . .
4.2 Health thermometer service implementation . . . . . . . . . . . . . . . . . . . . . . . .
4
4
4
5 External changes
5.1 heart_rate_api.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 spp_over_ble_api.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
5
5
6 Internal changes
6.1 List of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Compile-test environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
6
6
6
7 Disclaimer
7
2.0.1
Bluetooth API migration guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1/8
TC356xx
1 Abstract
The purpose of this document is to explain how to migrate an existing software using v2.0 of Toshiba's
Bluetooth API to version v2.0.1. It also explains problems that have been fixed and new features that
have been added to the Bluetooth API.
This application note is applicable for TOSHIBA TC35661 Chiron ROM version 501 and all versions
of TOSHIBA TC35667 BLE Single.
2 Introduction
Toshiba's Bluetooth API is constantly developed further. New features are added that make profiles
and services easier to implement.
Sometimes it is inevitable to make changes to the APIs that connect the Bluetooth API to the user
application.
This document describes which changes are necessary to the user application code in order to make
it work with a newer version of the Bluetooth API.
It also explains new features that have been added during the development, so that the user application can make use of it.
2.0.1
Bluetooth API migration guide
2/8
TC356xx
3 Fixed problems
3.1 Incorrect behaviour of hci_api_read_eeprom()
The offset parameter for the EEPROM location in hci_api_read_eeprom() was calculated incorrectly.
Because of this, an incorrect Bluetooth device address was read from EEPROM. If all 0 was read,
the default Bluetooth device address of TC35661 was used.
In any case the device was fully functional, but with an incorrect Bluetooth device address.
3.2 Stack corruption in TcuMngSspSet_Response()
The function TcuMngSspSet_Response() was not implemented correctly and could corrupt the stack.
This could lead to undefined behaviour of the application.
This problem only affected systems using Bluetooth Classic.
3.3 Incorrect implementation of TcuLeGattSerReadCharValAccept_Response()
The function TcuLeGattSerReadCharValAccept_Response() was not implemented correctly.
The extraction of the GATT status parameter was not done correctly. If the application checked the
return code it could think that the operation failed, even though it was successfull.
3.4 Incorrect implementation of TcuMngDiscoverRemoteServiceEvent()
The function TcuMngDiscoverRemoteServiceEvent() was not implemented correctly.
When the Bluetooth API was used to discover the SPP services of a remote device, an incorrect
number of SPP services was reported when the remote device did not have any SPP services at all.
This problem only affected systems using Bluetooth Classic that tried to connect to a remote device.
3.5 Incorrect defitnition of battery service
A problem in the definition of stBatteryMeasurementCharacteristic was fixed.
This problem lead to a NULL pointer dereference and resulted in a crash of the Bluetooth API.
Because the battery service is not used by any of the profile implementations, this problem is never
triggered.
If you included the battery service in a profile yourself, then the implementation now works as expected.
3.6 Timer handling in heart rate service
The timer handling in the heart rate service was not correct.
The heart rate measurement value timer would continue to fire after a disconnection, but the API
notices that notifications have been disabled due to the disconnect.
No further notifications are sent, just the timer continues to fire, which could lead to increased powerconsumption due to unnecessary timer events.
2.0.1
Bluetooth API migration guide
3/8
TC356xx
3.7 Incorrect data length in advertising and scan response data
The advertising and scan response data was always transmitted with the maximum length of 0x1f
and was padded with zeros.
The correct length is now calculated and reported.
3.8 Incorrect setting of BR/EDR flag in advertising data
In dual-mode functionality the BR/EDR flag is was not set correctly in advertising, so a remote device
could think that the peripheral supports BR/EDR but in fact it was not.
The Bluetooth API will now always set the BR/EDR flag correctly depending on the system configuration.
3.9 Security manager protocol (SMP) may fail under certain conditions
The security manager protocol has been reworked to work correctly. It now supports resolvable
address handling as well.
4 Known problems
4.1 Devices using both public and random addresses
Usually devices either use their public Bluetooth address or they use random addresses.
Examples for devices using their public Bluetooth address are older Android-based devices, running a
version of Android prior to v5.0. Newer Android-devices and all Apple devices will always use random
addresses.
This setting is a system setting and cannot be changed by the user.
For all of these devices connecting, pairing and re-connecting will always work.
If a device changes between these two modes, however, the security keys are currently not correctly
managed. If a device pairs with a random address, then changes to a public address and pairs again,
2 entries in the internal database will be created.
The next time the device changes back to using random addresses, the wrong security information
will be fetched.
Please note that this problem cannot be triggered by currently available devices as explained above.
All devices will always either use public Bluetooth address or random addresses, but never change
between these two settings.
This will be fixed in v2.1.
4.2 Health thermometer service implementation
The current implementation of the health thermometer service does not work according to the current
health thermometer specification, version 1.0.
2.0.1
Bluetooth API migration guide
4/8
TC356xx
Enabling and disabling notifications for the intermediate temperature characteristic will enable and
disable the temperature measurement, but this should only be done when indications are enabled or
disabled for the temperate measurement characteristic.
The measurment interval characteristic does not work as described as well. When the measurment
interval characteristic value is set, new temperature measurements should be indicated according to
the interval that is set. In the current implementation, the measurement is stopped after a successfull
indication and restarted after the interval has passed.
The implementation of the health thermometer service will be changed to match the behaviour of the
service specification for v2.1.
5 External changes
The following changes may directly affect the customer application, if the relevant APIs have been
used.
5.1 heart_rate_api.h
Two new function declarations have been added to the heart rate API. These functions need to be
implemented by the user application.
1. extern int heart_rate_measurement_start(void);
2. extern int heart_rate_measurement_stop(void);
The Bluetooth API will call these functions when heart rate measurements are needed or not needed
any more.
The purpose of these functions is to give the user application more information about heart rate
measurements are actually needed, so that it can shutdown any heart rate measurement hardware
to save power, for example.
5.2 spp_over_ble_api.h
Two new function declarations have been added to the spp-over-bleAPI. These functions need to be
implemented by the user application.
1. extern void spp_over_ble_connect_callback(uint8_t *bd_addr);
2. extern void spp_over_ble_disconnect_callback(void);
The Bluetooth API will call these functions when heart a spp-over-bleconnection is established or shut
down.
The purpose of these functions is to give the user application more information about when a sppover-bleconnection is established or not. This information was not available until now, so the user
application could never know if calling spp_over_ble_send() would actually send data to a connected
device or fail immediately.
6 Internal changes
The following brief and non-complete list of changes lists internal modifications that do not need
modifications to the user applications.
2.0.1
Bluetooth API migration guide
5/8
TC356xx
Please note that they may change the behaviour of the resulting application anyway.
6.1 List of changes
1. Internal variables, function arguments, internal global variables, structures or structure member
variables have been renamed in order to match the code style.
2. All files have been re-indented to match the coding style.
3. The code has been modified so that it compiles warning-free with the compilers mentioned
above.
4. The AD flags have been removed from the scan response data, because the Bluetooth Core
Specification says so.
5. The advertising name is now transmitted as part of the scan response data to allow longer
device names.
6.2 New features
A brief and non-complete list of new features that are only internal and do not affect the user application.
1. Some file names for the stub functions have been renamed to avoid a name clash with other
files of the API.
2. HCI functions for controlling RTS/CTS handling have been added.
6.3 Compile-test environments
The Bluetooth API is now compile-tested with the following compilers:
1.
2.
3.
4.
5.
2.0.1
IAR 7.10.3.6932
Keil µVision V5.12.0.0
Microsoft Visual C++ 2012
gcc version 4.8.2
g++ version 4.8.2
Bluetooth API migration guide
6/8
TC356xx
7 Disclaimer
RESTRICTIONS ON PRODUCT USE
• Toshiba Corporation, and its subsidiaries and affiliates (collectively "TOSHIBA"), reserve the
right to make changes to the information in this document, and related hardware, software and
systems (collectively "Product") without notice.
• This document and any information herein may not be reproduced without prior written permission from TOSHIBA. Even with TOSHIBA’s written permission, reproduction is permissible only
if reproduction is without alteration/omission.
• Though TOSHIBA works continually to improve Product's quality and reliability, Product can
malfunction or fail. Customers are responsible for complying with safety standards and for
providing adequate designs and safeguards for their hardware, software and systems which
minimize risk and avoid situations in which a malfunction or failure of Product could cause loss
of human life, bodily injury or damage to property, including data loss or corruption. Before customers use the Product, create designs including the Product, or incorporate the Product into
their own applications, customers must also refer to and comply with (a) the latest versions of all
relevant TOSHIBA information, including without limitation, this document, the specifications,
the data sheets and application notes for Product and the precautions and conditions set forth in
the "TOSHIBA Semiconductor Reliability Handbook" and (b) the instructions for the application
with which the Product will be used with or for. Customers are solely responsible for all aspects of their own product design or applications, including but not limited to (a) determining the
appropriateness of the use of this Product in such design or applications; (b) evaluating and determining the applicability of any information contained in this document, or in charts, diagrams,
programs, algorithms, sample application circuits, or any other referenced documents; and (c)
validating all operating parameters for such designs and applications. TOSHIBA ASSUMES
NO LIABILITY FOR CUSTOMERS' PRODUCT DESIGN OR APPLICATIONS.
• Product is intended for use in general electronics applications (e.g., computers, personal equipment, office equipment, measuring equipment, industrial robots and home electronics appliances) or for specific applications as expressly stated in this document. Product is neither
intended nor warranted for use in equipment or systems that require extraordinarily high levels
of quality and/or reliability and/or a malfunction or failure of which may cause loss of human
life, bodily injury, serious property damage or serious public impact ("Unintended Use"). Unintended Use includes, without limitation, equipment used in nuclear facilities, equipment used
in the aerospace industry, medical equipment, equipment used for automobiles, trains, ships
and other transportation, traffic signaling equipment, equipment used to control combustions
or explosions, safety devices, elevators and escalators, devices related to electric power, and
equipment used in finance-related fields. Do not use Product for Unintended Use unless specifically permitted in this document.
• Do not disassemble, analyze, reverse-engineer, alter, modify, translate or copy Product, whether
in whole or in part.
• Product shall not be used for or incorporated into any products or systems whose manufacture,
use, or sale is prohibited under any applicable laws or regulations.
• The information contained herein is presented only as guidance for Product use. No responsibility is assumed by TOSHIBA for any infringement of patents or any other intellectual property
rights of third parties that may result from the use of Product. No license to any intellectual property right is granted by this document, whether express or implied, by estoppel or otherwise.
• ABSENT A WRITTEN SIGNED AGREEMENT, EXCEPT AS PROVIDED IN THE RELEVANT
TERMS AND CONDITIONS OF SALE FOR PRODUCT, AND TO THE MAXIMUM EXTENT
2.0.1
Bluetooth API migration guide
7/8
TC356xx
ALLOWABLE BY LAW, TOSHIBA (1) ASSUMES NO LIABILITY WHATSOEVER, INCLUDING
WITHOUT LIMITATION, INDIRECT, CONSEQUENTIAL, SPECIAL, OR INCIDENTAL DAMAGES OR LOSS, INCLUDING WITHOUT LIMITATION, LOSS OF PROFITS, LOSS OF OPPORTUNITIES, BUSINESS INTERRUPTION AND LOSS OF DATA, AND (2) DISCLAIMS ANY
AND ALL EXPRESS OR IMPLIED WARRANTIES AND CONDITIONS RELATED TO SALE,
USE OF PRODUCT, OR INFORMATION, INCLUDING WARRANTIES OR CONDITIONS OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OF INFORMATION, OR NONINFRINGEMENT.
• Do not use or otherwise make available Product or related software or technology for any military
purposes, including without limitation, for the design, development, use, stockpiling or manufacturing of nuclear, chemical, or biological weapons or missile technology products (mass destruction weapons). Product and related software and technology may be controlled under the
Japanese Foreign Exchange and Foreign Trade Law and the U.S. Export Administration Regulations. Export and re-export of Product or related software or technology are strictly prohibited
except in compliance with all applicable export laws and regulations.
• Product may include products subject to foreign exchange and foreign trade control laws.
• The technical information described in this document is subject to foreign exchange and foreign
trade control laws.
• Please contact your TOSHIBA sales representative for details as to environmental matters such
as the RoHS compatibility of Product. Please use Product in compliance with all applicable laws
and regulations that regulate the inclusion or use of controlled substances, including without limitation, the EU RoHS Directive. TOSHIBA assumes no liability for damages or losses occurring
as a result of noncompliance with applicable laws and regulations.
2.0.1
Bluetooth API migration guide
8/8