BLUEGIGA BLUETOOTH SMART SOFTWARE

V.1.1 (BETA) API DOCUMENTATION Tuesday, 16 October 2012 Version 2.2

Copyright 2001 - 2012 Bluegiga Technologies Bluegiga Technologies reserves the right to alter the hardware, software, and/or specifications detailed herein at any time without notice, and does not make any commitment to update the information contained herein. Bluegiga Technologies assumes no responsibility for any errors which may appear in this manual. Bluegiga Technologies' products are not authorized for use as critical components in life support devices or systems. Bluegiga Access Server, Access Point, AX4, BSM, iWRAP, BGScript and WRAP THOR are trademarks of Bluegiga Technologies. The Bluetooth trademark and logo are registered trademarks and are owned by the Bluetooth SIG, Inc. ARM and ARM9 are trademarks of ARM Ltd. Linux is a trademark of Linus Torvalds. All other trademarks listed herein belong to their respective owners.

TABLE OF CONTENTS
1. Version History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Introduction to Bluetooth Smart SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Bluetooth 4.0 single mode stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 BGAPI protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 BGLib library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4 BGScript scripting language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5 Profile Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. Introduction to Bluetooth Smart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Physical layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Packet format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.1 Generic packet format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.2 Advertisement packet format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.3 Data packet format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Link layer state machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 Link layer operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.1 Passive scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.2 Active scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.3 Connection establishment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5 Topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6 Connections and packet timings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8 L2CAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.9 Security Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.10 Attribute Protocol (ATT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.11 Generic Attribute Profile (GATT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.12 Generic Access Profile (GAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. API definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1 BGAPI protocol definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 BGLib functions definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 BGScript API definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 Attribute Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.1 Attribute Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.2 Execute Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.3 Find By Type Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.4 Find Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.5 Indicate Confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.6 Prepare Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.7 Read By Group Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.8 Read By Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.9 Read By Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.10 Read Long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.11 Read Multiple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1.12 Write Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.2 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.2.1 Attribute Value Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.3.1 Attribute Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.3.2 Find Information Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.3.3 Group Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.3.4 Indicated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.3.5 Procedure Completed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.3.6 Read Multiple Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Attribute Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1.1 Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1.2 Read Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1.3 User Read Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1.4 User Write Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1.5 Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 8 8 9 9 10 11 12 12 13 13 13 13 15 16 16 17 17 18 19 21 22 23 24 27 30 31 31 34 35 36 37 38 38 38 40 42 44 46 47 49 51 53 55 57 59 61 61 62 62 63 64 65 66 67 68 68 68 70 71 72 73

5.2.2 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.2.1 Attribute Change Reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.2.2 Attribute Status Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.3.1 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.3.2 User Read Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.3.3 Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1.1 Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1.2 Get Rssi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1.3 Get Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1.4 Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1.5 Version Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.2 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.2.1 Connection Status Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3.1 Disconnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3.2 Feature Ind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3.3 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3.4 Version Ind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4 Generic Access Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.1 Connect Direct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.2 Connect Selective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.3 Discover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.4 End Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.5 Set Adv Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.6 Set Adv Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.7 Set Directed Connectable Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.8 Set Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.9 Set Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.10 Set Privacy Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1.11 Set Scan Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.1 AD_FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.2 AD Type Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.3 Advertising policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.4 Bluetooth Address Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.5 GAP Connectable Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.6 GAP Discoverable Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.7 GAP Discover Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.8 SCAN_HEADER_FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2.9 Scan Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.3.1 Scan Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.1 ADC Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.2 I2c Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.3 I2c Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.4 Io Port Config Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.5 Io Port Config Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.6 IO Port Config IRQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.7 Io Port Config Pull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.8 Io Port Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.9 Io Port Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.10 Set Soft Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.11 Set Txpower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.12 Spi Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.13 Spi Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.1.14 Timer Comparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.2 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.2.1 ADC Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

74 74 75 76 76 77 78 79 79 79 81 82 83 85 87 87 88 88 89 90 91 92 92 92 94 96 98 99 100 102 104 105 107 108 109 109 110 111 112 113 114 115 116 117 118 118 120 120 120 122 124 126 128 129 131 133 134 135 137 138 140 142 144 144

5.5.2.2 IO Port Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5.2.3 Soft Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6 Persistent Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.1.1 PS Defrag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.1.2 PS Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.1.3 PS Erase All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.1.4 PS Erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.1.5 PS Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.1.6 PS Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.2 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6.2.1 PS Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7 Security Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1.1 Delete Bonding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1.2 Encrypt Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1.3 Get Bonds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1.4 Passkey Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1.5 Set Bondable Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1.6 Set Oob Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.1.7 Set Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.2 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.2.1 Bonding Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.2.2 SMP IO Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.3.1 Bonding Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.3.2 Bond Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.3.3 Passkey Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7.3.4 Passkey Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8 System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.1 Address Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.2 Endpoint Rx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.3 Endpoint Set Watermarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.4 Endpoint Tx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.5 Get Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.6 Get Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.7 Get Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.8 Hello . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.9 Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.10 Whitelist Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.11 Whitelist Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.1.12 Whitelist Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.2 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.2.1 Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.3.1 Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.3.2 Endpoint Watermark Rx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.3.3 Endpoint Watermark Tx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8.3.4 Script Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1 BGAPI Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.1 Invalid Parameter (0x0180) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.2 Device in Wrong State (0x0181) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.3 Out Of Memory (0x0182) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.4 Feature Not Implemented (0x0183) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.5 Command Not Recognized (0x0184) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.6 Timeout (0x0185) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.7 Not Connected (0x0186) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.8 flow (0x0187) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.1.9 User Attribute (0x0188) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2 Bluetooth Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.1 Authentication Failure (0x0205) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.2 Pin or Key Missing (0x0206) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

145 146 147 147 147 148 149 150 151 152 153 153 154 154 154 156 158 159 160 161 162 163 163 164 165 165 166 167 168 169 169 169 170 171 173 174 175 176 178 179 180 181 182 183 183 184 184 185 186 187 188 188 188 188 188 189 189 189 189 189 189 189 189 189

5.9.2.3 Memory Capacity Exceeded (0x0207) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.4 Connection Timeout (0x0208) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.5 Connection Limit Exceeded (0x0209) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.6 Command Disallowed (0x020C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.7 Invalid Command Parameters (0x0212) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.8 Remote User Terminated Connection (0x0213) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.9 Connection Terminated by Local Host (0x0216) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.10 LL Response Timeout (0x0222) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.11 LL Instant Passed (0x0228) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.12 Controller Busy (0x023A) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.13 Directed Advertising Timeout (0x023C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.14 MIC Failure (0x023D) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.2.15 Connection Failed to be Established (0x023E) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3 Security Manager Protocol Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.1 Passkey Entry Failed (0x0301) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.2 OOB Data is not available (0x0302) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.3 Authentication Requirements (0x0303) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.4 Confirm Value Failed (0x0304) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.5 Pairing Not Supported (0x0305) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.6 Encryption Key Size (0x0306) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.7 Command Not Supported (0x0307) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.8 Unspecified Reason (0x0308) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.9 Repeated Attempts (0x0309) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.3.10 Invalid Parameters (0x030A) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4 Attribute Protocol Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.1 Invalid Handle (0x0401) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.2 Read Not Permitted (0x0402) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.3 Write Not Permitted (0x0403) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.4 Invalid PDU (0x0404) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.5 Insufficient Authentication (0x0405) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.6 Request Not Supported (0x0406) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.7 Invalid Offset (0x0407) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.8 Insufficient Authorization (0x0408) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.9 Prepare Queue Full (0x0409) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.10 Attribute Not Found (0x040A) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.11 Attribute Not Long (0x040B) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.12 Insufficient Encryption Key Size (0x040C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.13 Invalid Attribute Value Length (0x040D) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.14 Unlikely Error (0x040E) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.15 Insufficient Encryption (0x040F) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.16 Unsupported Group Type (0x0410) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.17 Insufficient Resources (0x0411) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9.4.18 Application Error Codes (0x0480) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. Contact information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

190 190 190 190 190 190 190 190 190 190 190 190 190 190 191 191 191 191 191 191 191 191 192 192 192 192 192 192 193 193 193 193 193 193 193 193 193 193 193 193 193 193 194 195

1 Version History
Version 1.3 2.0 2.1 API documentation for SW version v.1.0.3 (Build 43) API documentation for v.1.1.0 beta (Build 46) API documentation for v.1.1.0 beta (Build 55) Note: API changes history is now included here (not separate) Changed APIs: * Attribute Database User Read Response (function implemented for Beta 2) * Connection Connection Status Flags (fixed) Doc improved for following APIs: * Attribute Client Attribute Value, Indicated, Procedure Completed, Group Found * Attribute Database User Read Request * Generic Access Profile Discover, Set Adv Parameters * Hardware I2c Read, I2c Write, Set Soft Timer, Set Txpower * Security Manager Delete Bonding, Get Bonds * System Whitelist Append Other sections (outside API reference) has also been updated to improve the document 2.2 Added documentation how to use BGAPI protocol without UART flow control. Section updated: BGAPI protocol definition

Copyright 2001-2012 Bluegiga Technologies

Page 7 of 195

2 Introduction to Bluetooth Smart SDK

Bluegigas Bluetooth Smart SDK suite provides a complete development framework for Bluetooth low energy application developers. The Bluetooth Smart SDK supports two architectural modes: Standalone architecture: All software including: Bluetooth 4.0 single mode stack, profiles and end user application all run on the Bluegiga's Bluetooth 4.0 single mode hardware. Hosted architecture: The Bluetooth 4.0 single mode stack and profiles run on the Bluegiga 4.0 single mode hardware but the end user application runs on a separate host (a low power MCU). The benefit of the Bluetooth Smart SDK in both use cases is that it provides the user with a complete Bluetooth 4.0 single mode stack, so that no Bluetooth protocol development is required. A well-defined transport protocol exists between the host and the Bluetooth 4.0 stack and also simple development tools are available for embedding the end user applications on the Bluetooth 4.0 single mode hardware. The Bluetooth Smart SDK suite consists of several components: A Bluetooth 4.0 single mode stack Binary based communication protocol (BGAPI) between the host and the Bluetooth stack A C library (BGLib) for the host that implements the BGAPI protocol BGScript scripting language and interpreter for implementing applications on the Bluetooth Smart mode hardware A Profile Toolkit for quick and easy development of GATT based Bluetooth services and profiles

2.1 Bluetooth 4.0 single mode stack

The Bluetooth 4.0 single mode stack is a full, embedded implementation of Bluetooth v.4.0 compatible stack software and its dedicated for Bluegigas Bluetooth 4.0 single mode modules such as the BLE112. The stack implements all mandatory functionality for a single mode device. The structure and layers of the stack are illustrated in the figure below.

Figure 1: Bluetooth low energy single mode stack

Copyright 2001-2012 Bluegiga Technologies

Page 8 of 195

2.2 BGAPI protocol

For applications where a separate host (MCU) is used to implement the end user application, a transport protocol is needed between the host and the Bluetooth stack. The transport protocol is used to control with the Bluetooth stack as well to transmit and receive data packets. This transport protocol is called BGAPI and it's a binary based communication protocol designed specifically for ease of implementation within host devices with limited resources. The BGAPI provides access to the following layers: Generic Access Profile - GAP allows the management of discoverability and connetability modes and open connections Security manager - Provides access the Bluetooth low energy security functions Attribute database - An class to access the local attribute database Attribute client - Provides an interface to discover, read and write remote attributes Connection - Provides an interface to manage Bluetooth low energy connections Hardware - An interface to access the various hardware layers such as timers, ADC and other hardware interfaces Persistent Store - User to access the parameters of the radio hardware and read/write data to non-volatile memory System - Various system functions, such as querying the hardware status or reset it The BGAPI protocol is intended to be used with: a serial UART link or a USB connection

2.3 BGLib library

For easy implementation of the BGAPI protocol a host library is available refer as BGLib. This library is easily portable ANSI C code delivered within the Bluetooth Smart SDK. The purpose is to simplify the application development to various host environments.

Figure 2: Host using BGLib

Copyright 2001-2012 Bluegiga Technologies

Page 9 of 195

2.4 BGScript scripting language

Bluegiga's Bluetooth Smart mode products allow application developers to create standalone devices without the need of a separate host. The Bluetooth Smart modules can run simple applications along the Bluetooth 4.0 single mode stack and this provides a benefit when one needs to minimize the end product size, cost and current consumption. For developing standalone Bluetooth Smart applications the development suite provides a simple BGScript scripting language. With BGScript provides access to the same software and hardware interfaces as the BGAPI protocol. The BGScript code can be developed and compiled with free tools provided by Bluegiga. When the BGScript approach is used the BGAPI host interface is not needed nor is it available.

Figure 3: Standalone application model A BGScript code example:

# System Started event system_boot(major, minor, patch, build, ll_version, protocol_version, hw) #Enable advertising mode call gap_set_mode(gap_general_discoverable,gap_undirected_connectable) #Enable bondable mode call sm_set_bondable_mode(1) #Start timer at 1 second interval (32768 = crystal frequency) call hardware_set_soft_timer(32768) end

Copyright 2001-2012 Bluegiga Technologies

Page 10 of 195

2.5 Profile Toolkit

The Bluetooth low energy profile toolkit a simple set of tools, which can used to create GATT based Bluetooth services and profiles. The profile toolkit consists of a simple XML based service description language template, which describes the devices local GATT database as a set of services. The profile toolkit also contains a compiler, which converts the XML to binary format and generates API to access the characteristic values.

Figure 4: A profile toolkit example of GAP service

Copyright 2001-2012 Bluegiga Technologies

Page 11 of 195

3 Introduction to Bluetooth Smart

This section gives a quick introduction to Bluetooth Smart technology and its most important features. The chapter does not contain complete detailed technology walkthrough but gives developers more insight into the technology and to help them develop Bluetooth Smart applications.

3.1 Physical layer

The features of physical the layer in Bluetooth low energy are: Feature Frequency band Modulation Modulation index Channel spacing Value 2.4GHz (2402Mhz - 2480MHz GFSK, 1 Mbps 0.5 2 MHz

Advertising channels 3 Data channels Frequency hopping 37 Adaptive FHSS

The requirements for the Bluetooth low energy radio are: Feature Minimum TX power Maximum TX power Value 0.01mW (-20 dBm) 10 mW (10 dBm)

Minimum RX sensitivity -70 dBm (BER 0.1%) The typical range for Bluetooth low energy radios is: TX power RX sensitivity Range 0 dBm 10 dBm -70 dBm -90 dBm ~30 meters 100+ meters

The figure below illustrates the link layer channels. There are 37 data channels and 3 advertisement channels.

Figure 5: Link layer channels

Copyright 2001-2012 Bluegiga Technologies

Page 12 of 195

3.2 Packet format

3.2.1 Generic packet format
Bluetooth low energy has one generic packet format used for both advertisement and data packets.

Figure 6: Generic packet format Preamble: either 010101010 or 101010101 Access address: advertisement packets use a fixed access address of 0x8E89BED6. Data packets use a random access address depending on the connection. PDU: protocol data unit depends on the packet type. CRC: a 24-bit CRC checksum is used to protect the PDU.

3.2.2 Advertisement packet format

The advertisement packets use the following structure and can contain 0 to 31 bytes of advertisement data.

Figure 7: Advertisement packet structure

3.2.3 Data packet format

The data packets on the other hand use the following structure. An unencrypted data packet can have 0 to 27 bytes of payload.

Figure 8: Unencrypted data packet

Copyright 2001-2012 Bluegiga Technologies

Page 13 of 195

An encrypted data packet can have 0 to 31 bytes of payload length, but MIC (Message Integrity Check) is part of it.

Figure 9: Encrypted data packet

Copyright 2001-2012 Bluegiga Technologies

Page 14 of 195

3.3 Link layer state machine

The Bluetooth low energy link layer state machine and state transitions are illustrated in the figure below.

Figure 10: Link layer state machine and state transitions

Copyright 2001-2012 Bluegiga Technologies

Page 15 of 195

3.4 Link layer operations

This section describes the Bluetooth low energy link layer operations.

3.4.1 Passive scanning

In passive scanning mode the advertiser simply broadcasts advertisement packets and a scanner and listen to incoming advertisements. Typically in passive scanning scenario: Advertiser sends three advertisement packet one on each advertisement channel separated by 150us. Scanner only listens to one advertisement channel at a time, but keeps switching between the three advertisement channels. The advertisement events are separated by a time called advertisement interval, which can vary from 20ms to 10240ms. On addition a random delay is added to the advertisement interval to avoid interference with other devices.

Figure 11: Passive scanning

The advertisement packets typically contains information like: Discoverability and connectability modes The address of advertiser TX power level Supported services Application data

Copyright 2001-2012 Bluegiga Technologies

Page 16 of 195

3.4.2 Active scanning

In active scanning mode the scanner will request more information from the Advertiser after it has received an advertisement packet.

Figure 12: Active scanning The scan response packets typically contains information like: Device friendly name Supported services (profiles)

3.4.3 Connection establishment

The figure below illustrates how the connection establishment happens at the link layer level.

Figure 13: Bluetooth low energy connection establisment

Copyright 2001-2012 Bluegiga Technologies

Page 17 of 195

3.5 Topologies
Bluetooth low energy has four device roles: advertiser, scanner, master and slave. The technology supports point-to-point and start topologies. The figure below illustrates the device roles, and topologies. Advetiser : Broadcasts advertisement packets, but is not able to receive them Scanner : Listens for advertisement packets sent out by advertisers. Can try to connect an advertiser. Master : A device that is connected to one or several slaves Slave : A deivce that is connected to a master. Can only be connected to one master at a time

Figure 14: Bluetooth low energy topologies Devices can change roles and topologies as illustrated below.

Figure 15: Topology and role change

Copyright 2001-2012 Bluegiga Technologies

Page 18 of 195

3.6 Connections and packet timings

Connections allow application data to be transmitted reliably and robustly. The data sent in a connection can be acknowledged, integrity is protected by CRC and to protect privacy the data can also be encrypted. On addition the Adaptive Frequency Hopping (AFH) guarantees reliable data transmission even in noisy environments. In Bluetooth Smart technology the connection procedures are very simple and connections are always starts when master sends a connection request packet to the slave. The connection request packet can only be sent right after a successful reception of an advertisement packet. The connection request packet contains the following information: Parameter Conn_Interval_Min Conn_Interval_Max Description Minimum value for the connection event interval Range: 7.5 ms to 4000ms Maximum value for the connection event interval Range: 7.5 ms to 4000ms Shall be greater then Conn_Interval_Min Slave latency for the connection in number of connection events. Slave latency allows the slave devices to skip a number of connection events in case it does not have any data to send. Range: 0 to 500 Supervision timeout Range: 100ms to 32 seconds Shall be greater than Connection Interval

Conn_Latency

Supervision_Timeout

The connection parameters can be updated during the connection. The connection timeline and events are illustrated below.

Figure 16: Bluetooth LE connection The connection event starts, when master sends a packet to the slave at the defined connection interval. The slave can respond 150us after it has received a packet from the master. However if the slave has no data to send it can skip a certain number of connection events defined by the slave latency parameter. If no packets are received by the master or slave within the time defined by the supervision timeout, the connection is terminated. If the slave has more data to send than what can be fitted into a single packet, the connection event will automatically extend and the slave can send as many packets as there is time until the beginning of next connection interval. This however can only be used with attribute protocol operations, that do not require an acknowledgement.

Copyright 2001-2012 Bluegiga Technologies

Page 19 of 195

Figure 17: Slave latency in function (latency=3)

Copyright 2001-2012 Bluegiga Technologies

Page 20 of 195

3.7 Encryption
Bluetooth low energy uses AES-128 link layer encryption block with Counter Mode CBC MAC (defined in RFC 3610). The data packets are encrypted as show below.

Figure 18: Encrypted data packet The full AES encryption procedure is illustrated below.

Figure 19: AES encryption procedure

Limitations of link layer encryption Maximum 2^39 packets per Long Term Key (LTK) 13.7 TB of data / connection ~12 years at maximum data rate

Copyright 2001-2012 Bluegiga Technologies

Page 21 of 195

3.8 L2CAP
L2CAP stands for Logical Link Control and Adaptation Protocol and it is acts as a protocol multiplexer and handles segmentation and reassembly of packets. It also provides logical channels, which are multiplexed over a or more logical links. All application data is sent over L2CAP packets and the L2CAP structure is illustrated below.

Figure 20: L2CAP packet format The following CIDs are defined: CID Description Notes Not used BR/EDR only BR/EDR only BR/EDR only LE only

0x0000 Null identifier 0x0001 L2CAP Signaling Channel 0x0002 Connectionless Channel 0x0003 AMP Manager Protocol 0x0004 Attribute Protocol

0x0005 LE L2CAP Signaling Channel LE only 0x0006 Security Manager Protocol LE only

Copyright 2001-2012 Bluegiga Technologies

Page 22 of 195

3.9 Security Manager

The security manager protocol is responsible of: Pairing Key distribution Generating hashes and short term keys The security manager uses asymmetric model and more responsibility is given to the master device, so the memory and processing requirements on the slaves can be kept to minimum. The basic security manager concepts include: Distributing key model Slave generates and distributes key information to master Master can use this key information when reconnecting Pairing Authentication of devices based on their capabilities and security requirements Signing Data Signing allows authentication of sender without encryption Bonding GAP concept device save keys for bonded devices Three pairing methods are supported: Just works pairing, similar to Bluetooth 2.1 Pin code pairing (6 digit pin code from 000000 to 999999) Out-of-band pairing, where security keys are exchanged over an other medium like NFC

I/O capabilities and Man-in-the-Middle (MITM) protection

Same I/O capabilities and MITM features are supported as in Bluetooth 2.1 + EDR.

Figure 21: I/O capabilities

Copyright 2001-2012 Bluegiga Technologies

Page 23 of 195

3.10 Attribute Protocol (ATT)

Bluetooth low energy profiles expose a state of a device. The state is exposed as one or several values called attributes and the protocol to access these attributes is called the Attribute protocol (ATT). The attribute protocol uses a client server architecture and has two roles: Server Service is the device that exposes the information as one or several attributes Client Client device that collects the information for one or more servers

Figure 22: Device roles Attribute types: Attributes are values: Arrays of octets From 0 to 512 octets Can be fixed or variable length Example: Value 0x0000 0x426c75656769676120546563686e6f6c6f67696573 Attribute have handles, which are used to address an individual attribute. The client accesses the server's attributes using this handle. Example: Handle Value 0x0001 0x0000 0x0002 0x426c75656769676120546563686e6f6c6f6769657

Attributes also have a type, described by a UUID. UUID determines what the attribute value means.

Copyright 2001-2012 Bluegiga Technologies

Page 24 of 195

Two types of UUIDs are used: Globally unique 16-bit UUID defined in the characteristics specifications (http://developer.bluetooth.org/) Manufacturer specific 128-bit UUIDs, which can for example be generated online. ( http://www.uuidgenerator.com/) Example: Handle UUID Value Description TX power as dBm

0x0001 0x1804 0x0000

0x0002 0x2a00 0x426c75656769676120546563686e6f6c6f6769657 Device name, UTF-8 Attribute permissions: Attributes also have permissions, which can be: Readable / Not readable Writable / Not writable Readable and writable / Not readable and not writable The attributes may also require: Authentication to read or write Authorization to read or write Encryption and pairing to read or write The attribute types and handles are public information, but the permissions are not. Therefore and read or write request may result an error Read/Write Not Permitted or Insufficient authentication.

Copyright 2001-2012 Bluegiga Technologies

Page 25 of 195

Attribute protocol methods: The attribute protocol is a stateless sequential protocol, meaning that no state is stored in the protocol and only one operation can be performed at a time. The available Attribute Protocol methods are described in the table below: Method Find Information (starting handle, ending handle) Find By Type Value (starting handle, ending handle, type, value) Read By Group Type (starting handle, ending handle, type) Read By Type (starting handle, ending handle, type) Read (handle) Read Blob (handle, offset) Description Used to discover attribute handles and their types (UUIDs) Returns the handles of all attributes matching the type and value Reads the value of each attribute of a given type in a range Reads the value of each attribute of a given type in a range Reads the value of given handle Maximum payload : 22 bytes Can be used to read long attributes larger than 22 bytes. Maximum payload: 64 kBytes Used to read multiple values at the same time Writes the value to the given handle, with no response Maximum payload: 20 bytes Prepares a write procedure, which is queued in server until the write is executed. Direction Client -> Server Client -> Server Client -> Server Client -> Server Client -> Server Client -> Server Client -> Server Client -> Server Client -> Server Server -> Client Server -> Client Server -> Client

Read Multiple ([Handle]*) Write (handle, value) Prepare Write (handle, offset, value) and Execute (exec/cancel)

Handle Value Notification (handle, value) Server notifies client of an attribute with a new value Maximum payload: 20 bytes Handle Value Indication (handle, value) Server indicates to client an attribute with a new value. Client must confirm reception. Maximum payload: 20 bytes Any request can cause an error and error response contains information about the error

Error response

Copyright 2001-2012 Bluegiga Technologies

Page 26 of 195

3.11 Generic Attribute Profile (GATT)

The Generic ATTribute profile (GATT) has similar client server structure as Attribute Protocol. However the GATT encapsulates data (attributes) into services and the data is exposed as characteristics.

Figure 23: GATT architecture GATT defines concepts of: Service Group Characteristic Group Declarations Descriptors It's important also to understand that GATT does not does not define rules for their use. Characteristics Characteristic is a value, with a known type, and a known format. They characteristics are defined in Characteristic Specification available at http://developer.bluetooth.org. Characteristics consist of: Characteristic Declaration Describes the properties of characteristic value (read, write, indicate etc.), characteristic value handle and characteristic value type (UUID) Characteristic Value Contains the value of the characteristic. Characteristic Descriptor(s) Provide additional information about the characteristic (characteristic user description, characteristic client configuration, vendor specific information etc.)

Figure 24: Characteristic format

Copyright 2001-2012 Bluegiga Technologies

Page 27 of 195

Service A service is: defined in a service specification (http://developer.bluetooth.org) collection of characteristics references to other services There are two types of service: Primary services A primary service exposes primary functionality of a device. It can be included by an other service. Secondary services Secondary service is a subservient of another primary or a secondary service. It's only relevant in the context of an other service. Attributes alone are just flat:

Figure 25: List of attributes Grouping attributes into services gives structure:

Figure 26: Attributes grouped into services

Copyright 2001-2012 Bluegiga Technologies

Page 28 of 195

GATT procedures The available Attribute Protocol methods are described in the table below: Procedure Server Configuration Primary Service Discovery Relationship Discovery Characteristic Discovery Sub-Procedures Exchange MTU Discovery All Primary Service Discover Primary Service by Service UUID. Find Included Services Discover All Characteristics of a Service Discover Characteristics by UUID

Characteristic Descriptor Discovery Discover All Characteristic Descriptors Characteristic Value Read Characteristic Value Read Read Characteristic Value Read Using Characteristic UUID Read Long Characteristic Values Read Multiple Characteristic Values Characteristic Value Write Write Without Response Write Without Response With Authentication Write Characteristic Value Write Long Characteristic Values Reliable Writes Notifications Indications Read Characteristic Descriptors Read Long Characteristic Descriptors Write Characteristic Descriptors Write Long Characteristic Descriptors

Characteristic Value Notifications Characteristic Value Indications Characteristic Descriptors

Copyright 2001-2012 Bluegiga Technologies

Page 29 of 195

3.12 Generic Access Profile (GAP)

GAP defines device roles: Broadcaster : Sends advertising events, including characteristics, including service data (does not need RX) Observer : Receives advertising events, listens for characteristics, listens for service data (does not need TX) Peripheral : Has RX and TX, is always slave, is connectable and advertising Central : Has RX and TX, is always master, never advertises GAP also defines modes and procedures for Discovery Connections Bonding Privacy Non-Resolvable and Resolvable Private Addresses

Copyright 2001-2012 Bluegiga Technologies

Page 30 of 195

4 API definition
This section contains the generic Bluetooth low energy stack API definition. The definition consist of three parts: The BGAPI protocol definition The BGLib C library description The BGScript scriting API description This section of the document only provides the generic definition and description of the API and the actual commands, responses and event are described in the API reference section.

4.1 BGAPI protocol definition

The general format of the binary host protocol is described in this section.
The maximum allowed packet size transferred to the stack is 64 bytes, which leads to the maximum payload of 60 bytes.

Packet format
Packets in either direction use the following format. Table 1: BGAPI packet format Octet Octet 0 ... Octet bits Length 7 6:3 1 bit 4 bits Description Message Type (MT) Notes 0: Command/Response 1: Event

Technology Type (TT) 0000: Bluetooth 4.0 single mode 0001: Wi-Fi

... Octet 1 Octet 2 Octet 3

2:0 7:0 7:0 7:0

3 bits 8 bits 8 bits 8 bits

Length High (LH) Length Low (LL) Class ID (CID) Command ID (CMD)

Payload length (high bits) Payload length (low bits) Command class ID Command ID Up to 2048 bytes of payload

Octet 4-n -

0 - 2048 Bytes Payload (PL)

Message types
The following message types exist in the BGAPI protocol. Table 2: BGAPI message types Message type Command Response Event Value Description 0x00 0x00 0x80 Command from host to the stack Response from stack to the host Event from stack to the host

Copyright 2001-2012 Bluegiga Technologies

Page 31 of 195

Command Class IDs

The following command classes exist. Table 3: BGAPI command classes Class ID Description 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 System Persistent Store Attribute database Connection Attribute client Security Manager Explanation Provides access to system functions Provides access the persistence store (parameters) Provides access to local GATT database Provides access to connection management functions Functions to access remote devices GATT database Bluetooth low energy security functions

Generic Access Profile GAP functions Hardware Provides access to hardware such as timers and ADC

Packet Exchange
The BGAPI protocol is a simple command / response protocol. The host should wait for the response to a command before issuing another command.

Copyright 2001-2012 Bluegiga Technologies

Page 32 of 195

Packet format without the use of HW flow control

BGAPI protocol can also be used without UART hardware (RTS/CTS) flow control. Typically this is not possible, because UART buffer overflow can cause a loss of data and it could cause the loss of synchronization between the Bluetooth smart stack and the host, especially if the BGAPI header bytes are lost because of buffer overflow. BGAPI however has an alternate mode where, which allows the use of BGAPI over a simple 2-wire (TX and RX) UART interface. This however requires that an additional length byte is added in front of all the BGAPI protocol commands, which tells the total length of the BGAPI command excluding the length byte itself. This operational mode needs to be especially enabled in the hardware configuration ( hardware.xml) of your Bluetooth Smart project and is not used by default. In this case the BGAPI protocol has the following format: Table 4: BGAPI packet format Octet Octet 0 Octet 1 ... ... Octet 2 Octet 3 Octet 4 Octet 5-n Octet bits 7:0 7 6:3 2:0 7:0 7:0 7:0 Length 8 bits 1 bit 4 bits 3 bits 8 bits 8 bits 8 bits 0 - 2048 Bytes Description BGAPI command length Message Type (MT) Technology Type (TT) Length High (LH) Length Low (LL) Class ID (CID) Command ID (CMD) Payload (PL) Notes Tells the length of the BGAPI command excluding the length byte itself 0: Command/Response 1: Event 0000: Bluetooth 4.0 single mode 0001: Wi-Fi Payload length (high bits) Payload length (low bits) Command class ID Command ID Up to 2048 bytes of payload

Below is a simple example which shows how a System Get Info (Raw: 0x00 0x00 0x00 0x08) is sent in this BGAPI packet format.

Copyright 2001-2012 Bluegiga Technologies

Page 33 of 195

4.2 BGLib functions definition

All the BGAPI commands are also available as ANSI C functions as a separate host library called BGLib. The responses and event on the other hand are handled as function call backs. The ANSI C functions are also documented in the API reference section. The functions and callbacks are documented as follows: C Functions
/* Function */ void ble_cmd_gap_connect_direct( bd_addr address , uint8 addr_type , uint16 conn_interval_min , uint16 conn_interval_max , uint16 timeout ); /* Callback */ void ble_rsp_gap_connect_direct( uint16 result , uint8 conn );

The command parameters and return values are the same as used in the BGAPI binary protocol and they are not documented separately. Callback programming Callback programming is a style of computer programming, which allows lower layer of software to call functions defined on a higher layer. Callback is piece of code or a reference to a piece of code that is passed as an argument. The figure below illustrates the callback architecture used with BGLib.

Figure 27: Callback arhitecture If you are not familiar with callback programming a basic tutorial can for example be found from here: http://www.codeguru.com/cpp/cpp/cpp_mfc/callbacks/article.php/c10557

Copyright 2001-2012 Bluegiga Technologies

Page 34 of 195

4.3 BGScript API definition

The BGScript functions are also documented in the API reference section. The format of the commands varies slightly from the C-library functions and instead of using call backs the BGScript functions take the return values as parameters. BGScript commands are documented as follows: BGScript Functions
CALL gap_connect_direct(address ,addr_type ,conn_interval_min ,conn_interval_max ,timeout )(result ,conn )

The BGScript command parameters and return values are the same as used in the BGAPI binary protocol and they are not documented separately.

Copyright 2001-2012 Bluegiga Technologies

Page 35 of 195

4.4 Data Types

The following data types used in documentation. Table 5: Used data types Type int8 uint8 uint16 uint32 Description signed integer stored in 1 byte twos complement form unsigned integer stored in 1 byte unsigned integer stored in 2 bytes little endian format unsigned integer stored in 4 bytes little endian format Example: Human readable -42 42 1701 1000000 "Hello" 00:07:80:c0:ff:ee Example Packet data in hex 0xd6 0x2a 0xa5 0x06 0x40 0x42 0x0f 0x00 0x05 0x68 0x65 0x6c 0x6c 0x6f 0xee 0xff 0xc0 0x80 0x07 0x00

uint8array byte array, first byte is array size bd_addr Bluetooth address in little endian format

Copyright 2001-2012 Bluegiga Technologies

Page 36 of 195

5 API Reference
This section of the document contains the actual API description, so the description of commands, responses, events and enumerations. The high level categorizationis made based on the command classes, which are: Description System Persistent Store Attribute database Connection Attribute client Security Manager Explanation Provides access to system functions Provides access the persistence store (parameters) Provides access to local GATT database Provides access to connection management functions Functions to access remote devices GATT database Bluetooth low energy security functions

Generic Access Profile GAP functions Hardware Provides access to hardware such as timers and ADC

Final section of the API reference contains description of the error codes categorized as follows: Description BGAPI errors Bluetooth errors Security manager errors Attribute protocols errors

Copyright 2001-2012 Bluegiga Technologies

Page 37 of 195

5.1 Attribute Client

The Attribute Client class implements the Attribute Protocol (ATT) and provides access to the ATT protocol methods. The Attribute Client can be used to discover services and characteristics from ATT server, read and write values and manage indications and notifications.

5.1.1 Commands
Attribute Client commands

Attribute Write
Writes a remote attribute's value with given handle and value. Attribute write operation will be acknowledged by the remote end, telling the write was successful. Attribute write can be used to write attribute values up to 20 bytes. Table 6: COMMAND Byte Type 0 1 2 3 4 0x00 0x04 0x04 0x05 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection handle atthandle Attribute handle to write to Attribute value Table 7: RESPONSE

5 - 6 uint16 7

uint8array data

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x05 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Attribute Client Message ID

connection Connection handle 0 : write was successful Otherwise error occurred Table 8: EVENTS

5 - 6 uint16 result

Event

Description

attclient procedure_completed Write operation has been acknowledged by remote end

Copyright 2001-2012 Bluegiga Technologies

Page 38 of 195

C Functions
/* Function */ void ble_cmd_attclient_attribute_write( uint8 connection, uint16 atthandle, uint8 data_len, const uint8* data_data ); /* Callback */ struct ble_msg_attclient_attribute_write_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_attribute_write( const struct ble_msg_attclient_attribute_write_rsp_t * msg )

BGScript Functions
call attclient_attribute_write(connection, atthandle, data_len, data_data)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 39 of 195

Execute Write
Executes or Cancels previously queued prepare_write commands on remote host Table 9: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x04 hilen lolen class Description Message type: command Minimum payload length Message class: Attribute Client Message ID

0x0A method

uint8 connection Connection Handle uint8 commit 1 - commits queued writes, 0- cancels Table 10: RESPONSE

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x0A uint8

Name hilen lolen class method

Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle Command result Table 11: EVENTS

5 - 6 uint16 result

Event

Description

attclient procedure_completed Write operation has been acknowledged by remote end

C Functions
/* Function */ void ble_cmd_attclient_execute_write( uint8 connection, uint8 commit ); /* Callback */ struct ble_msg_attclient_execute_write_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_execute_write( const struct ble_msg_attclient_execute_write_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 40 of 195

BGScript Functions
call attclient_execute_write(connection, commit)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 41 of 195

Find By Type Value

Used to find specific attributes. Returns the handles of all attributes matching the type (UUID) and value. Table 12: COMMAND Byte 0 1 2 3 4 5-6 7-8 Type 0x00 0x08 0x04 0x00 uint8 uint16 uint16 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection handle start end uuid First requested handle number Last requested handle number 2 octet UUID to find Attribute value to find Table 13: RESPONSE

9 - 10 uint16 11

uint8array value

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x00 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Attribute Client Message ID

connection Connection handle 0 : the operation was successful

5 - 6 uint16 result

Otherwise error occurred Table 14: EVENTS Event attclient group_found attclient procedure_completed Description Attributes found Procedure has completed and new procedure can be started on GATT server

Copyright 2001-2012 Bluegiga Technologies

Page 42 of 195

C Functions

/* Function */ void ble_cmd_attclient_find_by_type_value( uint8 connection, uint16 start, uint16 end, uint16 uuid, uint8 value_len, const uint8* value_data ); /* Callback */ struct ble_msg_attclient_find_by_type_value_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_find_by_type_value( const struct ble_msg_attclient_find_by_type_value_rsp_t * msg )

BGScript Functions

call attclient_find_by_type_value(connection, start, end, uuid, value_len, value_data)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 43 of 195

Find Information
This command is used to discover attribute handles and their types (UUIDs) in a given handle range. Table 15: COMMAND Byte Type 0 1 2 3 4 0x00 0x05 0x04 0x03 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection handle First attribute handle Last attribute handle Table 16: RESPONSE

5 - 6 uint16 start 7 - 8 uint16 end

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x03 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Attribute Client Message ID

connection Connection handle 0 if the command was successful

5 - 6 uint16 result

Otherwise error occurred Table 17: EVENTS Event Description

attclient find_information_found Handle, type - mapping found attclient procedure_completed Find information procedure has completed

Copyright 2001-2012 Bluegiga Technologies

Page 44 of 195

C Functions
/* Function */ void ble_cmd_attclient_find_information( uint8 connection, uint16 start, uint16 end ); /* Callback */ struct ble_msg_attclient_find_information_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_find_information( const struct ble_msg_attclient_find_information_rsp_t * msg )

BGScript Functions
call attclient_find_information(connection, start, end)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 45 of 195

Indicate Confirm
Send confirmation for received indication. Use only if manual indications are enabled in config.xml Table 18: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x04 0x07 hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

uint8 connection Connection Handle Table 19: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x04 0x07

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Attribute Client

method Message ID Command result

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_attclient_indicate_confirm( uint8 connection ); /* Callback */ struct ble_msg_attclient_indicate_confirm_rsp_t{ uint16 result } void ble_rsp_attclient_indicate_confirm( const struct ble_msg_attclient_indicate_confirm_rsp_t * msg )

BGScript Functions
call attclient_indicate_confirm(connection)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 46 of 195

Prepare Write
Send prepare write request to remote host for queueing. Queued writes are executed or canceled with attclient_execute_write command. NOTE: It is not mandatory for server to support this command. It is recommended to use this command to only write long-attributes which do not fit in single att-packet. Table 20: COMMAND Byte Type 0 1 2 3 4 0x00 0x06 0x04 0x09 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle atthandle offset Attribute handle Offset to write to data to write Table 21: RESPONSE

5 - 6 uint16 7 - 8 uint16 9

uint8array data

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x09 uint8

Name hilen lolen class method

Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle Command result Table 22: EVENTS

5 - 6 uint16 result

Event

Description

attclient procedure_completed Write operation has been acknowledged by remote end

Copyright 2001-2012 Bluegiga Technologies

Page 47 of 195

C Functions
/* Function */ void ble_cmd_attclient_prepare_write( uint8 connection, uint16 atthandle, uint16 offset, uint8 data_len, const uint8* data_data ); /* Callback */ struct ble_msg_attclient_prepare_write_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_prepare_write( const struct ble_msg_attclient_prepare_write_rsp_t * msg )

BGScript Functions
call attclient_prepare_write(connection, atthandle, offset, data_len, data_data)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 48 of 195

Read By Group Type

This command reads the value of each attribute of a given type and in a given handle range. The command is typically used for primary (UUID: 0x2800) and secondary (UUID: 0x2801) service discovery. Discovered services are reported by Group Found - event. When procedure is completed Procedure Completed - event is generated. Table 23: COMMAND Byte Type 0 1 2 3 4 0x00 0x06 0x04 0x01 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection handle start end First requested attribute handle Last requested attribute handle group UUID to find Table 24: RESPONSE

5 - 6 uint16 7 - 8 uint16 9

uint8array uuid

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x01 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Attribute Client Message ID

connection Connection handle 0 : the command was successful

5 - 6 uint16 result

Otherwise error occurred Table 25: EVENTS Event attclient group_found attclient procedure_completed Description Attributes found Procedure has completed and new procedure can be started on GATT server

Copyright 2001-2012 Bluegiga Technologies

Page 49 of 195

C Functions
/* Function */ void ble_cmd_attclient_read_by_group_type( uint8 connection, uint16 start, uint16 end, uint8 uuid_len, const uint8* uuid_data ); /* Callback */ struct ble_msg_attclient_read_by_group_type_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_read_by_group_type( const struct ble_msg_attclient_read_by_group_type_rsp_t * msg )

BGScript Functions
call attclient_read_by_group_type(connection, start, end, uuid_len, uuid_data)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 50 of 195

Read By Handle
This command reads a remote attribute's value with the given handle. Read by handle can be used to read attributes up to 22 bytes. Table 26: COMMAND Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x04 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle Attribute handle Table 27: RESPONSE

5 - 6 uint16 chrhandle

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x04 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Attribute Client Message ID

connection Connection handle 0 : the command was successful

5 - 6 uint16 result

Otherwise error occurred Table 28: EVENTS Event attclient attribute_value Description Attribute value received

attclient procedure_completed ATT command failed

Copyright 2001-2012 Bluegiga Technologies

Page 51 of 195

C Functions
/* Function */ void ble_cmd_attclient_read_by_handle( uint8 connection, uint16 chrhandle ); /* Callback */ struct ble_msg_attclient_read_by_handle_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_read_by_handle( const struct ble_msg_attclient_read_by_handle_rsp_t * msg )

BGScript Functions
call attclient_read_by_handle(connection, chrhandle)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 52 of 195

Read By Type
Reads the value of each attribute of a given type (UUID) and in a given attribute handle range. The command for example used to discover the characteristic declarations (UUID: 0x2803) of a service. Table 29: COMMAND Byte Type 0 1 2 3 4 0x00 0x06 0x04 0x02 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection handle start end First attribute handle Last attribute handle Attribute type (UUID) Table 30: RESPONSE

5 - 6 uint16 7 - 8 uint16 9

uint8array uuid

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x02 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle 0 : the command was successful

5 - 6 uint16 result

Otherwise an error occurred Table 31: EVENTS Event attclient attribute_value Description Attribute value read from GATT server

attclient procedure_completed Returned if error occurred

Copyright 2001-2012 Bluegiga Technologies

Page 53 of 195

C Functions

/* Function */ void ble_cmd_attclient_read_by_type( uint8 connection, uint16 start, uint16 end, uint8 uuid_len, const uint8* uuid_data ); /* Callback */ struct ble_msg_attclient_read_by_type_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_read_by_type( const struct ble_msg_attclient_read_by_type_rsp_t * msg )

BGScript Functions

call attclient_read_by_type(connection, start, end, uuid_len, uuid_data)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 54 of 195

Read Long
Use this command to read long attribute values. Starts a procedure where client first sends normal read to the server. and if returned attribute value length is equal to MTU, sends read long read requests until rest of the attribute is read. Table 32: COMMAND Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x08 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle Attribute handle Table 33: RESPONSE

5 - 6 uint16 chrhandle

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x08 uint8

Name hilen lolen class method

Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle 0: Command executed successfully

5 - 6 uint16 result

Non-zero : An error occurred Table 34: EVENTS Event attclient attribute_value Description Data received from remote end

attclient procedure_completed Full attribute has read, or error occurred

Copyright 2001-2012 Bluegiga Technologies

Page 55 of 195

C Functions
/* Function */ void ble_cmd_attclient_read_long( uint8 connection, uint16 chrhandle ); /* Callback */ struct ble_msg_attclient_read_long_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_read_long( const struct ble_msg_attclient_read_long_rsp_t * msg )

BGScript Functions
call attclient_read_long(connection, chrhandle)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 56 of 195

Read Multiple
Read multiple attributes from server Table 35: COMMAND Byte Type 0 1 2 3 4 5 0x00 0x02 0x04 0x0B uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection handle List of attribute handles to read from remote end Table 36: RESPONSE

uint8array handles

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x0B uint8

Name hilen lolen class method

Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle Command result Table 37: EVENTS

5 - 6 uint16 result

Event

Description

attclient read_multiple_response Attribute data if command was succesful attclient procedure_completed Operation has failed

C Functions
/* Function */ void ble_cmd_attclient_read_multiple( uint8 connection, uint8 handles_len, const uint8* handles_data ); /* Callback */ struct ble_msg_attclient_read_multiple_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_read_multiple( const struct ble_msg_attclient_read_multiple_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 57 of 195

BGScript Functions
call attclient_read_multiple(connection, handles_len, handles_data)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 58 of 195

Write Command
Writes a remote attribute's value with given handle and value. Write command will NOT be acknowledged by the remote end. Write command can be used to write attribute values up to 20 bytes. Table 38: COMMAND Byte Type 0 1 2 3 4 0x00 0x04 0x04 0x06 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection handle atthandle Attribute handle to write Value for the attribute Table 39: RESPONSE

5 - 6 uint16 7

uint8array data

Byte Type 0 1 2 3 4 0x00 0x03 0x04 0x06 uint8

Name hilen lolen class method

Description Message type: command Minimum payload length Message class: Attribute Client Message ID

connection Connection Handle 0: Command executed successfully

5 - 6 uint16 result

Non-zero: An error occurred

C Functions
/* Function */ void ble_cmd_attclient_write_command( uint8 connection, uint16 atthandle, uint8 data_len, const uint8* data_data ); /* Callback */ struct ble_msg_attclient_write_command_rsp_t{ uint8 connection, uint16 result } void ble_rsp_attclient_write_command( const struct ble_msg_attclient_write_command_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 59 of 195

BGScript Functions
call attclient_write_command(connection, atthandle, data_len, data_data)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 60 of 195

5.1.2 Enumerations
Attribute Client commands

Attribute Value Types

Attribute Value Types Table 40: VALUES Value Name 0 1 2 3 4 5 attclient_attribute_value_type_read attclient_attribute_value_type_notify attclient_attribute_value_type_indicate attclient_attribute_value_type_read_by_type attclient_attribute_value_type_read_blob Description Value was read Value was notified Value was indicated Value was read Value was part of long attribute

attclient_attribute_value_type_indicate_rsp_req Value was indicated and remote end is waiting for confirmation, use Indicate Confirm to send confirmation to other end.

Copyright 2001-2012 Bluegiga Technologies

Page 61 of 195

5.1.3 Events
Attribute Client events

Attribute Value
This event is produced at the GATT client side when an attribute value is passed from the GATT server to the GATT client, typically after a Read by Handle command. This is also received at the GATT client side when an attribute is indicated or notified by the GATT server to the GATT client. Table 41: EVENT Byte Type 0 1 2 3 4 0x80 0x05 0x04 0x05 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Client Message ID

connection Connection handle atthandle type Attribute handle Attribute type Attribute value (data)

5 - 6 uint16 7 8 uint8

uint8array value

C Functions
/* Callback */ struct ble_msg_attclient_attribute_value_evt_t{ uint8 connection, uint16 atthandle, uint8 type, uint8 value_len, const uint8* value_data } void ble_evt_attclient_attribute_value( const struct ble_msg_attclient_attribute_value_evt_t * msg )

BGScript Functions
event attclient_attribute_value(connection, atthandle, type, value_len, value_data)

Copyright 2001-2012 Bluegiga Technologies

Page 62 of 195

Find Information Found

This event is generated when characteristics type mappings are found. Typically after Find Information command has been issued to discover all attributes of a service. Table 42: EVENT Byte Type 0 1 2 3 4 0x80 0x04 0x04 0x04 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Client Message ID

connection Connection handle chrhandle Characteristics handle Characteristics type (UUID)

5 - 6 uint16 7

uint8array uuid

C Functions
/* Callback */ struct ble_msg_attclient_find_information_found_evt_t{ uint8 connection, uint16 chrhandle, uint8 uuid_len, const uint8* uuid_data } void ble_evt_attclient_find_information_found( const struct ble_msg_attclient_find_information_found_evt_t * msg )

BGScript Functions
event attclient_find_information_found(connection, chrhandle, uuid_len, uuid_data)

Copyright 2001-2012 Bluegiga Technologies

Page 63 of 195

Group Found
This event is produced when an attribute group (service) is found. Typically this event is produced after Read by Group Type command. Table 43: EVENT Byte Type 0 1 2 3 4 0x80 0x06 0x04 0x02 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Client Message ID

connection Connection handle start end Starting handle Ending handle (Note "end" is a reserver word and in BG script, "end" cannot be used as such. UUID if the service Length is 0 if no services are found

5 - 6 uint16 7 - 8 uint16 9

uint8array uuid

C Functions
/* Callback */ struct ble_msg_attclient_group_found_evt_t{ uint8 connection, uint16 start, uint16 end, uint8 uuid_len, const uint8* uuid_data } void ble_evt_attclient_group_found( const struct ble_msg_attclient_group_found_evt_t * msg )

BGScript Functions
event attclient_group_found(connection_handle, start_handle, end_handle, uuid_len, uuid_data)

Copyright 2001-2012 Bluegiga Technologies

Page 64 of 195

Indicated
This event is produced at the GATT server side when an attribute is successfully indicated by the GATT server to the GATT client. That is, the event is only produced at the GATT server if the indication is acknowledged by the GATT client at the remote side. Table 44: EVENT Byte Type 0 1 2 3 4 0x80 0x03 0x04 0x00 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Client Message ID

connection Connection handle Attribute handle

5 - 6 uint16 attrhandle

C Functions
/* Callback */ struct ble_msg_attclient_indicated_evt_t{ uint8 connection, uint16 attrhandle } void ble_evt_attclient_indicated( const struct ble_msg_attclient_indicated_evt_t * msg )

BGScript Functions
event attclient_indicated(connection, attrhandle)

Copyright 2001-2012 Bluegiga Technologies

Page 65 of 195

Procedure Completed
This event is produced at the GATT client when an attribute protocol event is completed. This event is produced for example after the attclient_attribute_write is used by the GATT client, to indicate if the GATT server has written the intended attribute. Table 45: EVENT Byte Type 0 1 2 3 4 0x80 0x05 0x04 0x01 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Client Message ID

connection Object Handle 0 Characteristic handle at which the event ended

5 - 6 uint16 result 7 - 8 uint16 chrhandle

C Functions
/* Callback */ struct ble_msg_attclient_procedure_completed_evt_t{ uint8 connection, uint16 result, uint16 chrhandle } void ble_evt_attclient_procedure_completed( const struct ble_msg_attclient_procedure_completed_evt_t * msg )

BGScript Functions
event attclient_procedure_completed(connection, result, chrhandle)

Copyright 2001-2012 Bluegiga Technologies

Page 66 of 195

Read Multiple Response

Response to read multiple request Table 46: EVENT Byte Type 0 1 2 3 4 5 0x80 0x02 0x04 0x06 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Client Message ID

connection Connection handle List of attribute handles to read from remote end

uint8array handles

C Functions
/* Callback */ struct ble_msg_attclient_read_multiple_response_evt_t{ uint8 connection, uint8 handles_len, const uint8* handles_data } void ble_evt_attclient_read_multiple_response( const struct ble_msg_attclient_read_multiple_response_evt_t * msg )

BGScript Functions
event attclient_read_multiple_response(connection, handles_len, handles_data)

Copyright 2001-2012 Bluegiga Technologies

Page 67 of 195

5.2 Attribute Database

The Attribute Database class provides methods to read and write attributes to the devices local attribute database. This class is usually only needed on sensor devices (Attribute server) to update attribute values.

5.2.1 Commands
Attribute database commands

Read
The command reads the given attribute's value from the local database. Table 47: COMMAND Byte Type 0 1 2 3 0x00 0x04 0x02 0x01 Name hilen lolen class Description Message type: command Minimum payload length Message class: Attribute Database

method Message ID

4 - 5 uint16 handle Handle of the attribute to read 6 - 7 uint16 offset Offset to read from Table 48: RESPONSE Byte Type 0 1 2 3 0x00 0x07 0x02 0x01 Name hilen lolen class Description Message type: response Minimum payload length Message class: Attribute Database

method Message ID handle Handle of the attribute which was read offset result Offset read from 0 : the read was successful Non-zero: An error occurred

4 - 5 uint16 6 - 7 uint16 8 - 9 uint16

10

uint8array value

Value of the attribute

Copyright 2001-2012 Bluegiga Technologies

Page 68 of 195

C Functions
/* Function */ void ble_cmd_attributes_read( uint16 handle, uint16 offset ); /* Callback */ struct ble_msg_attributes_read_rsp_t{ uint16 handle, uint16 offset, uint16 result, uint8 value_len, const uint8* value_data } void ble_rsp_attributes_read( const struct ble_msg_attributes_read_rsp_t * msg )

BGScript Functions
call attributes_read(handle, offset)(handle, offset, result, value_len, value_data)

Copyright 2001-2012 Bluegiga Technologies

Page 69 of 195

Read Type
This command reads the given attribute's type (UUID) from the local database. Table 49: COMMAND Byte Type 0 1 2 3 0x00 0x02 0x02 0x02 Name hilen lolen class Description Message type: command Minimum payload length Message class: Attribute Database

method Message ID

4 - 5 uint16 handle Handle of the attribute to read Table 50: RESPONSE Byte Type 0 1 2 3 0x00 0x05 0x02 0x02 Name hilen lolen class Description Message type: response Minimum payload length Message class: Attribute Database

method Message ID handle Handle of the attribute which was read result 0: if the read was successful Non-zero: An error occurred

4 - 5 uint16 6 - 7 uint16

uint8array value

Value of the attribute type (UUID)

C Functions
/* Function */ void ble_cmd_attributes_read_type( uint16 handle ); /* Callback */ struct ble_msg_attributes_read_type_rsp_t{ uint16 handle, uint16 result, uint8 value_len, const uint8* value_data } void ble_rsp_attributes_read_type( const struct ble_msg_attributes_read_type_rsp_t * msg )

BGScript Functions
call attributes_read_type(handle)(handle, result, value_len, value_data)

Copyright 2001-2012 Bluegiga Technologies

Page 70 of 195

User Read Response

Respond to user attribute read request. Table 51: COMMAND Byte Type 0 1 2 3 4 5 6 0x00 0x03 0x02 0x03 uint8 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Database Message ID

connection Connection handle to respond to att_error Attribute errorcode to send if error, set to 0 to send datafield Data to send Table 52: RESPONSE

uint8array value

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x02 class

Description Message type: command Minimum payload length Message class: Attribute Database

0x03 method Message ID

C Functions
/* Function */ void ble_cmd_attributes_user_read_response( uint8 connection, uint8 att_error, uint8 value_len, const uint8* value_data ); /* Callback * void ble_rsp_attributes_user_read_response( const void *nul )

BGScript Functions
call attributes_user_read_response(connection, att_error, value_len, value_data)

Copyright 2001-2012 Bluegiga Technologies

Page 71 of 195

User Write Response

Response to attribute_changed event where reason is user-attribute write. Table 53: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x02 0x04 hilen lolen class method Description Message type: command Minimum payload length Message class: Attribute Database Message ID

uint8 connection Connection handle to respond to uint8 att_error Attribute errorcode to send if error, set to 0 to accept write Table 54: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x02 class

Description Message type: command Minimum payload length Message class: Attribute Database

0x04 method Message ID

C Functions
/* Function */ void ble_cmd_attributes_user_write_response( uint8 connection, uint8 att_error ); /* Callback * void ble_rsp_attributes_user_write_response( const void *nul )

BGScript Functions
call attributes_user_write_response(connection, att_error)

Copyright 2001-2012 Bluegiga Technologies

Page 72 of 195

Write
This command writes an attribute's value to the local database. Table 55: COMMAND Byte Type 0 1 2 3 0x00 0x04 0x02 0x00 Name hilen lolen class Description Message type: command Minimum payload length Message class: Attribute Database

method Message ID handle Handle of the attribute to write offset Attribute offset to write data Value of the attribute to write Table 56: RESPONSE

4 - 5 uint16 6 7 uint8

uint8array value

Byte Type 0 1 2 3 0x00 0x02 0x02 0x00

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Attribute Database

method Message ID 0 : the write was successful Non-zero: An error occured

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_attributes_write( uint16 handle, uint8 offset, uint8 value_len, const uint8* value_data ); /* Callback */ struct ble_msg_attributes_write_rsp_t{ uint16 result } void ble_rsp_attributes_write( const struct ble_msg_attributes_write_rsp_t * msg )

BGScript Functions
call attributes_write(handle, offset, value_len, value_data)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 73 of 195

5.2.2 Enumerations
Attribute Database enumerations

Attribute Change Reason

Reason for attribute change Table 57: VALUES Value Name 0 1 2 attributes_attribute_change_reason_write_request attributes_attribute_change_reason_write_command Description Value was written by remote end using write request Value was written by remote end using write command

attributes_attribute_change_reason_write_request_user Value was written by remote end, stack is waiting for write response to be sent to other end. Use User Write Response to send response.

Copyright 2001-2012 Bluegiga Technologies

Page 74 of 195

Attribute Status Flags

Attribute status flags Table 58: VALUES Value Name 1 2 attributes_attribute_status_flag_notify Description Notifications are enabled

attributes_attribute_status_flag_indicate Indications are enabled

Copyright 2001-2012 Bluegiga Technologies

Page 75 of 195

5.2.3 Events
Attribute Database events

Status
This event indicates the attribute status flags have changed Table 59: EVENT Byte Type 0 1 2 3 0x80 0x03 0x02 0x02 Name hilen lolen class Description Message type: event Minimum payload length Message class: Attribute Database

method Message ID

4 - 5 uint16 handle Attribute handle 6 uint8 flags Attribute status flags See: Attribute Status Flags

C Functions
/* Callback */ struct ble_msg_attributes_status_evt_t{ uint16 handle, uint8 flags } void ble_evt_attributes_status( const struct ble_msg_attributes_status_evt_t * msg )

BGScript Functions
event attributes_status(handle, flags)

Copyright 2001-2012 Bluegiga Technologies

Page 76 of 195

User Read Request

User-backed attribute data requested. This event is sent when remote end is reading user attribute. Respond to this event using attributes_user_read_response. Table 60: EVENT Byte Type 0 1 2 3 4 0x80 0x05 0x02 0x01 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Database Message ID

connection Connection ID which requested attribute Attribute handle requested Attribute offset to send data from Maximum data size to respond with, if more data is sent extra bytes are ignored

5 - 6 uint16 handle 7 - 8 uint16 offset 9 uint8 maxsize

C Functions
/* Callback */ struct ble_msg_attributes_user_read_request_evt_t{ uint8 connection, uint16 handle, uint16 offset, uint8 maxsize } void ble_evt_attributes_user_read_request( const struct ble_msg_attributes_user_read_request_evt_t * msg )

BGScript Functions
event attributes_user_read_request(connection, handle, offset, maxsize)

Copyright 2001-2012 Bluegiga Technologies

Page 77 of 195

Value
This event is produced at the GATT server side when a local attribute value is being written by a remote GATT client. Table 61: EVENT Byte Type 0 1 2 3 4 5 0x80 0x07 0x02 0x00 uint8 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Attribute Database Message ID

connection Connection handle reason handle offset Reason why value has changed see:[enum attributes_attribute_change_reason] Attribute handle, which was changed Offset into attribute value where data starts Attribute value

6 - 7 uint16 8 - 9 uint16 10

uint8array value

C Functions
/* Callback */ struct ble_msg_attributes_value_evt_t{ uint8 connection, uint8 reason, uint16 handle, uint16 offset, uint8 value_len, const uint8* value_data } void ble_evt_attributes_value( const struct ble_msg_attributes_value_evt_t * msg )

BGScript Functions
event attributes_value(connection, reason, handle, offset, value_len, value_data)

Copyright 2001-2012 Bluegiga Technologies

Page 78 of 195

5.3 Connection
The Connection class provides methods to manage Bluetooth low energy connections and their statuses.

5.3.1 Commands
Connection class commands

Disconnect
This command disconnects an active connection. The command sends a request to link layer to start disconnection procedure. When link is disconnected Disconnected - event is produced. Table 62: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x03 0x00 hilen lolen class method Description Message type: command Minimum payload length Message class: Connection Message ID

uint8 connection Connection handle Table 63: RESPONSE

Byte Type 0 1 2 3 4 0x00 0x03 0x03 0x00 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Connection Message ID

connection Connection handle 0: disconnection procedure succesfully started

5 - 6 uint16 result

Non-zero: An error occurred Table 64: EVENTS Event Description

connection disconnected Sent after connection has disconnected

Copyright 2001-2012 Bluegiga Technologies

Page 79 of 195

C Functions
/* Function */ void ble_cmd_connection_disconnect( uint8 connection ); /* Callback */ struct ble_msg_connection_disconnect_rsp_t{ uint8 connection, uint16 result } void ble_rsp_connection_disconnect( const struct ble_msg_connection_disconnect_rsp_t * msg )

BGScript Functions
call connection_disconnect(connection)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 80 of 195

Get Rssi
This commands returns the Receiver Signal Strength Indication (RSSI) of an active connection.
At -38 dBm the BLE112 receiver is saturated. The measurement value may depend on the used hardware and design.

Table 65: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x03 0x01 hilen lolen class method Description Message type: command Minimum payload length Message class: Connection Message ID

uint8 connection Connection handle Table 66: RESPONSE

Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x03 0x01 hilen lolen class method

Description Message type: response Minimum payload length Message class: Connection Message ID

uint8 connection Connection handle int8 rssi RSSI value of the connection in dBm.

Range: -103 to -38

C Functions
/* Function */ void ble_cmd_connection_get_rssi( uint8 connection ); /* Callback */ struct ble_msg_connection_get_rssi_rsp_t{ uint8 connection, int8 rssi } void ble_rsp_connection_get_rssi( const struct ble_msg_connection_get_rssi_rsp_t * msg )

BGScript Functions
call connection_get_rssi(connection)(connection, rssi)

Copyright 2001-2012 Bluegiga Technologies

Page 81 of 195

Get Status
This command returns the status of the given connection. Status is returned in Status event. Table 67: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x03 0x07 hilen lolen class method Description Message type: command Minimum payload length Message class: Connection Message ID

uint8 connection Connection handle Table 68: RESPONSE

Byte Type Name 0 1 2 3 4 0x00 0x01 0x03 0x07 hilen lolen class method

Description Message type: response Minimum payload length Message class: Connection Message ID

uint8 connection Connection handle Table 69: EVENTS

Event

Description

connection status Reports the status of a connection

C Functions

/* Function */ void ble_cmd_connection_get_status( uint8 connection ); /* Callback */ struct ble_msg_connection_get_status_rsp_t{ uint8 connection } void ble_rsp_connection_get_status( const struct ble_msg_connection_get_status_rsp_t * msg )

BGScript Functions

call connection_get_status(connection)(connection)

Copyright 2001-2012 Bluegiga Technologies

Page 82 of 195

Update
This command updates the connection parameters of given connection. If sent from a master, sends parameter update request to the link layer. If sent from a slave, sends L2CAP connection parameter update request to the master. Table 70: COMMAND Byte 0 1 2 3 4 5-6 7-8 9 - 10 Type 0x00 0x09 0x03 0x02 uint8 Name hilen lolen class method connection Description Message type: command Minimum payload length Message class: Connection Message ID Connection handle Minimum connection interval

uint16 interval_min

uint16 interval_max Maximum connection interval uint16 latency Slave latency Supervision timeout Table 71: RESPONSE

11 - 12 uint16 timeout

Byte Type 0 1 2 3 4 0x00 0x03 0x03 0x02 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Connection Message ID

connection Connection handle 0 : the update was successful

5 - 6 uint16 result

Non-zero: An error occurred.

Copyright 2001-2012 Bluegiga Technologies

Page 83 of 195

C Functions
/* Function */ void ble_cmd_connection_update( uint8 connection, uint16 interval_min, uint16 interval_max, uint16 latency, uint16 timeout ); /* Callback */ struct ble_msg_connection_update_rsp_t{ uint8 connection, uint16 result } void ble_rsp_connection_update( const struct ble_msg_connection_update_rsp_t * msg )

BGScript Functions
call connection_update(connection, interval_min, interval_max, latency, timeout)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 84 of 195

Version Update
This command requests a version exchange of a given connection. Table 72: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x03 0x03 hilen lolen class method Description Message type: command Minimum payload length Message class: Connection Message ID

uint8 connection Connection handle Table 73: RESPONSE

Byte Type 0 1 2 3 4 0x00 0x03 0x03 0x03 uint8

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Connection Message ID

connection Connection handle 0 : the request was successful

5 - 6 uint16 result

Non-zero: An error occurred Table 74: EVENTS Event Description

connection version_ind Sent after receiving version indication from other end

C Functions

/* Function */ void ble_cmd_connection_version_update( uint8 connection ); /* Callback */ struct ble_msg_connection_version_update_rsp_t{ uint8 connection, uint16 result } void ble_rsp_connection_version_update( const struct ble_msg_connection_version_update_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 85 of 195

BGScript Functions

call connection_version_update(connection)(connection, result)

Copyright 2001-2012 Bluegiga Technologies

Page 86 of 195

5.3.2 Enumerations
Connection class enumerations

Connection Status Flags

The possible connection status flags are described in the table below. The flags field is a bit mask, so multiple flags can be set at a time. If the bit is 1 the flag is active and if the bit is 0 the flag is inactive. Table 75: VALUES Value Name bit 0 bit 1 bit 2 bit 3 connection_connected connection_encrypted connection_completed Description This status flag tells the connection exists to a remote device. This flag tells the connection is encrypted. Connection completed flag, which is used to tell a new connection has been created.

connection_parameters_change This flag tells that connection parameters have changed and. It is set when connection parameters have changed due to a link layer operation.

Copyright 2001-2012 Bluegiga Technologies

Page 87 of 195

5.3.3 Events
Connection class events

Disconnected
This event is produces when a connection is disconnected. Table 76: EVENT Byte Type 0 1 2 3 4 0x80 0x03 0x03 0x04 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Connection Message ID

connection Connection handle Disconnection reason code 0 : disconnected by local user

5 - 6 uint16 reason

C Functions
/* Callback */ struct ble_msg_connection_disconnected_evt_t{ uint8 connection, uint16 reason } void ble_evt_connection_disconnected( const struct ble_msg_connection_disconnected_evt_t * msg )

BGScript Functions
event connection_disconnected(connection, reason)

Copyright 2001-2012 Bluegiga Technologies

Page 88 of 195

Feature Ind
This event indicates the remote devices features. Table 77: EVENT Byte Type 0 1 2 3 4 5 0x80 0x02 0x03 0x02 uint8 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Connection Message ID

connection Connection handle CtrData field from LL_FEATURE_RSP - packet

uint8array features

C Functions
/* Callback */ struct ble_msg_connection_feature_ind_evt_t{ uint8 connection, uint8 features_len, const uint8* features_data } void ble_evt_connection_feature_ind( const struct ble_msg_connection_feature_ind_evt_t * msg )

BGScript Functions
event connection_feature_ind(connection, features_len, features_data)

Copyright 2001-2012 Bluegiga Technologies

Page 89 of 195

Status
This event indicates the connection status and parameters. Table 78: EVENT Byte 0 1 2 3 4 5 6 - 11 12 Type 0x80 0x10 0x03 0x00 uint8 uint8 Name hilen lolen class method connection flags Description Message type: event Minimum payload length Message class: Connection Message ID Connection handle Connection status flags use connstatus-enumerator Remote devices Bluetooth address

bd_addr address uint8

address_type Remote address type see: Bluetooth Address Types--gap conn_interval Current connection interval timeout latency bonding Current supervision timeout Slave latency bonding handle if there is stored bonding for this device 0xff otherwise

13 - 14 uint16 15 - 16 uint16 17 - 18 uint16 19 uint8

C Functions
/* Callback */ struct ble_msg_connection_status_evt_t{ uint8 connection, uint8 flags, bd_addr address, uint8 address_type, uint16 conn_interval, uint16 timeout, uint16 latency, uint8 bonding } void ble_evt_connection_status( const struct ble_msg_connection_status_evt_t * msg )

BGScript Functions
event connection_status(connection, flags, address, address_type, conn_interval, timeout, latency, bonding)

Copyright 2001-2012 Bluegiga Technologies

Page 90 of 195

Version Ind
This event indicates the remote devices version. Table 79: EVENT Byte Type 0 1 2 3 4 5 0x80 0x06 0x03 0x01 uint8 uint8 Name hilen lolen class method connection vers_nr Description Message type: event Minimum payload length Message class: Connection Message ID Connection handle Bluetooth controller specification version Manufacturer of Bluetooth controller

6 - 7 uint16 comp_id

8 - 9 uint16 sub_vers_nr Bluetooth controller version

C Functions
/* Callback */ struct ble_msg_connection_version_ind_evt_t{ uint8 connection, uint8 vers_nr, uint16 comp_id, uint16 sub_vers_nr } void ble_evt_connection_version_ind( const struct ble_msg_connection_version_ind_evt_t * msg )

BGScript Functions
event connection_version_ind(connection, vers_nr, comp_id, sub_vers_nr)

Copyright 2001-2012 Bluegiga Technologies

Page 91 of 195

5.4 Generic Access Profile

The Generic Access Profile (GAP) class provides methods to control the GAP level functionality such as: device discovery, connection establishment and local devices connection and discovery modes. The GAP class also allows the control of local devices privacy mode.

5.4.1 Commands
Generic Access Profile class commands

Connect Direct
This command will start the GAP direct connection establishment procedure to a dedicated Bluetooth low energy device. The device will enter scanning state and when connectable advertisement packet is received from a remote device, that matches given address, connection is opened to that device. Procedure is cancelled with End Procedure - command Table 80: COMMAND Byte Type 0 1 2 3 0x00 0x0F 0x06 0x03 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID Bluetooth address of the target device see: Bluetooth Address Types Minimum connection interval (unit1.25ms)

4 - 9 bd_addr address 10 11 12 13 14 15 16 17 18 uint8 uint16 uint16 uint16 uint16 addr_type conn_interval_min

conn_interval_max Maximum connection interval (unit 1.25ms) timeout latency Supervision timeout (unit 10ms) Slave latency. Defines how many connection intervals slave can skip. 0 prevents slave from skipping connection intervals on purpose. 0 is good value to start with. Increasing slave latency can decrease the energy consumption of the slave. Table 81: RESPONSE

Copyright 2001-2012 Bluegiga Technologies

Page 92 of 195

Byte Type 0 1 2 3 0x00 0x03 0x06 0x03

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: Generic Access Profile Message ID 0 : procedure was succesfully started Non-zero: An error occurred

4 - 5 uint16 result

uint8

connection_handle Connection handle that is reserved for new connection

Table 82: EVENTS Event Description

connection status Sent after connection is established

C Functions
/* Function */ void ble_cmd_gap_connect_direct( bd_addr address, uint8 addr_type, uint16 conn_interval_min, uint16 conn_interval_max, uint16 timeout, uint16 latency ); /* Callback */ struct ble_msg_gap_connect_direct_rsp_t{ uint16 result, uint8 connection_handle } void ble_rsp_gap_connect_direct( const struct ble_msg_gap_connect_direct_rsp_t * msg )

BGScript Functions
call gap_connect_direct(address, addr_type, conn_interval_min, conn_interval_max, timeout, latency)(result, connection_handle)

Copyright 2001-2012 Bluegiga Technologies

Page 93 of 195

Connect Selective
This command will open a connection to any Bluetooth low energy device on the local devices white list. Table 83: COMMAND Byte 0 1 2 3 4-5 6-7 8-9 Type 0x00 0x08 0x06 0x05 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID Minimum connection interval

uint16 conn_interval_min

uint16 conn_interval_max Maximum connection interval uint16 timeout Supervision timeout Slave latency Table 84: RESPONSE

10 - 11 uint16 latency

Byte Type 0 1 2 3 0x00 0x03 0x06 0x05

Name hilen lolen class method

Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID 0: Command was executed successfully Non-zero: An error occurred

4 - 5 uint16 result

uint8

connection_handle Connection handle reserved for connection

Table 85: EVENTS Event Description

connection status Sent after connected to any whitelisted device

Copyright 2001-2012 Bluegiga Technologies

Page 94 of 195

C Functions
/* Function */ void ble_cmd_gap_connect_selective( uint16 conn_interval_min, uint16 conn_interval_max, uint16 timeout, uint16 latency ); /* Callback */ struct ble_msg_gap_connect_selective_rsp_t{ uint16 result, uint8 connection_handle } void ble_rsp_gap_connect_selective( const struct ble_msg_gap_connect_selective_rsp_t * msg )

BGScript Functions
call gap_connect_selective(conn_interval_min, conn_interval_max, timeout, latency)(result, connection_handle)

Copyright 2001-2012 Bluegiga Technologies

Page 95 of 195

Discover
This command starts the GAP discovery procedure to scan for advertising devices. Scanning parameters can be configured with the set_scan_parameters command. To cancel succesfully started procedure use End Procedure - command Table 86: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x06 0x02 hilen lolen class Description Message type: command Minimum payload length Message class: Generic Access Profile

method Message ID see:GAP Discover Mode Table 87: RESPONSE

uint8 mode

Byte Type 0 1 2 3 0x00 0x02 0x06 0x02

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Generic Access Profile

method Message ID 0: Scan procedure was successfully started

4 - 5 uint16 result

Non-zero: An error occurred Table 88: EVENTS Event Description

gap scan_response Discovered device scan response

C Functions
/* Function */ void ble_cmd_gap_discover( uint8 mode ); /* Callback */ struct ble_msg_gap_discover_rsp_t{ uint16 result } void ble_rsp_gap_discover( const struct ble_msg_gap_discover_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 96 of 195

BGScript Functions
call gap_discover(mode)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 97 of 195

End Procedure
This command ends the current GAP procedure. Table 89: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x06 class Description Message type: command Minimum payload length Message class: Generic Access Profile

0x04 method Message ID Table 90: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x06 0x04

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Generic Access Profile

method Message ID 0: the command was successful Non-zero: An error occurred

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_gap_end_procedure( void ); /* Callback */ struct ble_msg_gap_end_procedure_rsp_t{ uint16 result } void ble_rsp_gap_end_procedure( const struct ble_msg_gap_end_procedure_rsp_t * msg )

BGScript Functions
call gap_end_procedure()(result)

Copyright 2001-2012 Bluegiga Technologies

Page 98 of 195

Set Adv Data

Set advertisement or scan response data. Use broadcast mode to advertise data Table 91: COMMAND Byte Type 0 1 2 3 4 0x00 0x02 0x06 0x09 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID

set_scanrsp Advertisement data type 0 : sets advertisement data 1 : sets scan response data Advertisement data to send Table 92: RESPONSE

uint8array adv_data

Byte Type 0 1 2 3 0x00 0x02 0x06 0x09

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Generic Access Profile

method Message ID Command result

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_gap_set_adv_data( uint8 set_scanrsp, uint8 adv_data_len, const uint8* adv_data_data ); /* Callback */ struct ble_msg_gap_set_adv_data_rsp_t{ uint16 result } void ble_rsp_gap_set_adv_data( const struct ble_msg_gap_set_adv_data_rsp_t * msg )

BGScript Functions
call gap_set_adv_data(set_scanrsp, adv_data_len, adv_data_data)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 99 of 195

Set Adv Parameters

This command sets the advertising parameters Device sends advertisement packet on each selected channel at each advertisement interval. Interval_min and max defines recommended advertisement interval values for link-layer. Table 93: COMMAND Byte Type 0 1 2 3 0x00 0x05 0x06 0x08 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID Minimum advertisement interval in units of 625us Range: 0x20 to 0x4000 (Default 0x200 = 320ms) Explanation: 0x200 = 512 512 * 625us = 320000us = 320ms 6 - 7 uint16 adv_interval_max Maximum advertisement interval in units of 625us.

4 - 5 uint16 adv_interval_min

Range: 0x20 to 0x4000 (Default 0x200 = 320ms) 8 uint8 adv_channels A bit mask to identify which of the three advertisement channels are used. Examples: 0x07: All three channels are used 0x03: Advertisement channels 37 and 38 are used. 0x04: Only advertisement channel 39 is used Table 94: RESPONSE Byte Type 0 1 2 3 0x00 0x02 0x06 0x08 Name hilen lolen class Description Message type: command Minimum payload length Message class: Generic Access Profile

method Message ID 0: Command was successfully executed

4 - 5 uint16 result

Non-zero: An error occurred

Copyright 2001-2012 Bluegiga Technologies

Page 100 of 195

C Functions
/* Function */ void ble_cmd_gap_set_adv_parameters( uint16 adv_interval_min, uint16 adv_interval_max, uint8 adv_channels ); /* Callback */ struct ble_msg_gap_set_adv_parameters_rsp_t{ uint16 result } void ble_rsp_gap_set_adv_parameters( const struct ble_msg_gap_set_adv_parameters_rsp_t * msg )

BGScript Functions
call gap_set_adv_parameters(adv_interval_min, adv_interval_max, adv_channels)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 101 of 195

Set Directed Connectable Mode

This command sets device to Directed Connectable mode. In this mode the device uses fast advertisement procedure for 1.28 seconds, after which the device enters non-connectable mode. If device has a valid re-connection characteristic value, it will be used for connection. Otherwise the address and address type passed as parameters are used. Re-connection characteristic is a conditional characteristic, which may be included in the GAP service. Table 95: COMMAND Byte Type 0 1 2 3 0x00 0x07 0x06 0x0A Name hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID Address to connect to

4 - 9 bd_addr address 10 uint8

addr_type Address type to connect see:enum gap_address_type Table 96: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x06 0x0A

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Generic Access Profile

method Message ID Command result Table 97: EVENTS

4 - 5 uint16 result

Event

Description

connection status Sent after connection is established

C Functions
/* Function */ void ble_cmd_gap_set_directed_connectable_mode( bd_addr address, uint8 addr_type ); /* Callback */ struct ble_msg_gap_set_directed_connectable_mode_rsp_t{ uint16 result } void ble_rsp_gap_set_directed_connectable_mode( const struct ble_msg_gap_set_directed_connectable_mode_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 102 of 195

BGScript Functions
call gap_set_directed_connectable_mode(address, addr_type)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 103 of 195

Set Filtering
Set scan and advertising filtering parameters Table 98: COMMAND Byte Type Name 0 1 2 3 4 5 6 0x00 0x03 0x06 0x06 hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID see: enum gap_scan_policy see: enum gap_advertising_policy

uint8 scan_policy uint8 adv_policy

uint8 scan_duplicate_filtering 0: Do not filter duplicate advertisers 1: Filter duplicates Table 99: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x06 0x06

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Generic Access Profile

method Message ID 0: The command was successfully executed Non-zero: An error occurred

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_gap_set_filtering( uint8 scan_policy, uint8 adv_policy, uint8 scan_duplicate_filtering ); /* Callback */ struct ble_msg_gap_set_filtering_rsp_t{ uint16 result } void ble_rsp_gap_set_filtering( const struct ble_msg_gap_set_filtering_rsp_t * msg )

BGScript Functions
call gap_set_filtering(scan_policy, adv_policy, scan_duplicate_filtering)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 104 of 195

Set Mode
This command configures the current GAP discoverability and connectability mode. Table 100: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x06 0x01 hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID

uint8 discover see:GAP Discoverable Mode uint8 connect see:GAP Connectable Mode Table 101: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x06 0x01

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Generic Access Profile

method Message ID 0: the command was executed successfully

4 - 5 uint16 result

Non-zero: An error occurred Table 102: EVENTS Event Description

connection status Sent if device was connectable and master connected to device

C Functions
/* Function */ void ble_cmd_gap_set_mode( uint8 discover, uint8 connect ); /* Callback */ struct ble_msg_gap_set_mode_rsp_t{ uint16 result } void ble_rsp_gap_set_mode( const struct ble_msg_gap_set_mode_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 105 of 195

BGScript Functions
call gap_set_mode(discover, connect)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 106 of 195

Set Privacy Flags

Set GAP central/peripheral privacy flags NOTE: it is not recommended to manually adjust peripheral privacy because not all implementations can decode resolvable private addresses. It is here only for testing purposes Table 103: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x06 0x00 hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID

uint8 peripheral_privacy 1-enable peripheral privacy, 0- disable, all other values no effect on flag uint8 central_privacy 1-enable central privacy, 0- disable, all other values no effect on flag Table 104: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x06 class

Description Message type: command Minimum payload length Message class: Generic Access Profile

0x00 method Message ID

C Functions
/* Function */ void ble_cmd_gap_set_privacy_flags( uint8 peripheral_privacy, uint8 central_privacy ); /* Callback * void ble_rsp_gap_set_privacy_flags( const void *nul )

BGScript Functions
call gap_set_privacy_flags(peripheral_privacy, central_privacy)

Copyright 2001-2012 Bluegiga Technologies

Page 107 of 195

Set Scan Parameters

Set scan parameters Table 105: COMMAND Byte Type 0 1 2 3 0x00 0x05 0x06 0x07 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Generic Access Profile Message ID

4 - 5 uint16 scan_interval At what intervals is scanner started, unit is 625us 6 - 7 uint16 scan_window How long to scan at each interval, unit is 625us must be equal or smaller than interval 8 uint8 active 1 - use active scanning, 0 - use passive scanning Table 106: RESPONSE Byte Type 0 1 2 3 0x00 0x02 0x06 0x07 Name hilen lolen class Description Message type: command Minimum payload length Message class: Generic Access Profile

method Message ID 0: The command was executed successfully

4 - 5 uint16 result

Non-zero: An error occurred

C Functions
/* Function */ void ble_cmd_gap_set_scan_parameters( uint16 scan_interval, uint16 scan_window, uint8 active ); /* Callback */ struct ble_msg_gap_set_scan_parameters_rsp_t{ uint16 result } void ble_rsp_gap_set_scan_parameters( const struct ble_msg_gap_set_scan_parameters_rsp_t * msg )

BGScript Functions
call gap_set_scan_parameters(scan_interval, scan_window, active)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 108 of 195

5.4.2 Enumerations
Generic Access Profile class enumerations

AD_FLAGS
Scan header flags Table 107: VALUES Value Name 0x01 0x02 0x04 0x10 0x20 0x1f GAP_AD_FLAG_LIMITED_DISCOVERABLE GAP_AD_FLAG_GENERAL_DISCOVERABLE GAP_AD_FLAG_BREDR_NOT_SUPPORTED Description Limited discoverability General discoverability BR/EDR not supported

GAP_AD_FLAG_SIMULTANEOUS_LEBREDR_CTRL BR/EDR controller GAP_AD_FLAG_SIMULTANEOUS_LEBREDR_HOST BE/EDR host GAP_AD_FLAG_MASK -

Copyright 2001-2012 Bluegiga Technologies

Page 109 of 195

AD Type Flags
Table 108: VALUES Value Name 0 1 2 3 4 5 6 7 8 9 10 gap_ad_type_none gap_ad_type_flags gap_ad_type_services_16bit_more gap_ad_type_services_16bit_all gap_ad_type_services_32bit_more gap_ad_type_services_32bit_all gap_ad_type_services_128bit_more gap_ad_type_services_128bit_all gap_ad_type_localname_short gap_ad_type_localname_complete gap_ad_type_txpower Description

Copyright 2001-2012 Bluegiga Technologies

Page 110 of 195

Advertising policy
Advertising policy Table 109: VALUES Value Name 0 1 2 3 gap_adv_policy_all gap_adv_policy_whitelist_scan Description Allow scan from any, allow connection from any Allow scan from whitelist only, allow connection from any

gap_adv_policy_whitelist_connect Allow scan from any, allow connection from whitelist only gap_adv_policy_whitelist_all Allow scan from whitelist only, allow connection from whitelist only

Copyright 2001-2012 Bluegiga Technologies

Page 111 of 195

Bluetooth Address Types

Bluetooth address type Table 110: VALUES Value Name 0 1 gap_address_type_public Description Public Address

gap_address_type_random Random Address

Copyright 2001-2012 Bluegiga Technologies

Page 112 of 195

GAP Connectable Mode

GAP connectable mode Table 111: VALUES Value Name 0 1 2 3 gap_non_connectable gap_directed_connectable Description Not connectable Direct Connectable

gap_undirected_connectable Undirected connectable gap_scannable_connectable Same as undirected connectable, but uses ADV_SCAN_IND packets

Copyright 2001-2012 Bluegiga Technologies

Page 113 of 195

GAP Discoverable Mode

Gap discoverable mode Table 112: VALUES Value Name 0 1 2 3 4 gap_non_discoverable gap_limited_discoverable Description Not discoverable Discoverable using limited scanning mode

gap_general_discoverable Discoverable using general scanning mode gap_broadcast gap_user_data Discoverable in observation scanning mode. Limited or general discoverable bits not enabled in flags ad type. Send advertisement data defined by user.

Copyright 2001-2012 Bluegiga Technologies

Page 114 of 195

GAP Discover Mode

GAP Discoverable modes Table 113: VALUES Value Name 0 1 2 gap_discover_limited gap_discover_generic Description Discover only limited discoverable devices Discover limited and generic discoverable devices

gap_discover_observation Discover All devices

Copyright 2001-2012 Bluegiga Technologies

Page 115 of 195

SCAN_HEADER_FLAGS
Scan header flags Table 114: VALUES Value Name 0 1 2 3 4 5 6 GAP_SCAN_HEADER_ADV_IND GAP_SCAN_HEADER_ADV_DIRECT_IND Description Connectable undirected advertising event Connectable directed advertising event

GAP_SCAN_HEADER_ADV_NONCONN_IND Non-connectable undirected advertising event GAP_SCAN_HEADER_SCAN_REQ GAP_SCAN_HEADER_SCAN_RSP GAP_SCAN_HEADER_CONNECT_REQ Scanner wants information from Advertiser Advertiser gives more information to Scanner Initiator wants to connect to Advertiser

GAP_SCAN_HEADER_ADV_DISCOVER_IND Non-connectable undirected advertising event

Copyright 2001-2012 Bluegiga Technologies

Page 116 of 195

Scan Policy
Scan Policy Table 115: VALUES Value Name 0 1 gap_scan_policy_all Description Accept All advertisement Packets

gap_scan_policy_whitelist Ignore advertisement packets not in whitelist

Copyright 2001-2012 Bluegiga Technologies

Page 117 of 195

5.4.3 Events
Generic Access Profile class events

Scan Response
This is a scan response event. Table 116: EVENT Byte 0 1 2 3 4 Type 0x80 0x0B 0x06 0x00 int8 Name hilen lolen class method rssi Description Message type: event Minimum payload length Message class: Generic Access Profile Message ID RSSI value (dBm) Range: -103 to -38 5 uint8 packet_type Scan response header 0: Connectable Advertisement packet 2: Non Connectable Advertisement packet 4: Scan response packet 6: Discoverable advertisement packet 6 - 11 bd_addr 12 uint8 sender Advertisers Bluetooth address

address_type Advertiser address type 1: random address 0: public address

13 14

uint8

bond

Bond handle if there is known bond for this device, 0xff otherwise Scan response data

uint8array data

C Functions
/* Callback */ struct ble_msg_gap_scan_response_evt_t{ int8 rssi, uint8 packet_type, bd_addr sender, uint8 address_type, uint8 bond, uint8 data_len, const uint8* data_data } void ble_evt_gap_scan_response( const struct ble_msg_gap_scan_response_evt_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 118 of 195

BGScript Functions
event gap_scan_response(rssi, packet_type, sender, address_type, bond, data_len, data_data)

Copyright 2001-2012 Bluegiga Technologies

Page 119 of 195

5.5 Hardware
The Hardware class provides methods to access the local devices hardware interfaces such as : A/D converters, IO and timers, I2C interface etc.

5.5.1 Commands
Hardware class commands

ADC Read
This command reads the devices local A/D converter. Table 117: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x03 0x07 0x02 hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID Selects the ADC input. 0x0: AIN0 0x1: AIN1 0x2: AIN2 0x3: AIN3 0x4: AIN4 0x5: AIN5 0x6: AIN6 0x7: AIN7 0x8: AIN0--AIN1 differential 0x9: AIN2--AIN3 differential 0xa: AIN4--AIN5 differential 0xb: AIN6--AIN7 differential 0xc: GND 0xd: Reserved 0xe: Temperature sensor 0xf: VDD/3 5 uint8 decimation Select resolution and conversion rate for conversion, result is always stored in MSB bits. 0: 7 effective bits 1: 9 effective bits 2: 10 effective bits 3: 12 effective bits 6 uint8 reference_selection Selects the reference for the ADC. Reference corresponds to the maximum allowed input value. 0: Internal reference (1.15V) 1: External reference on AIN7 pin 2: AVDD pin 3: External reference on AIN6--AIN7 differential input Table 118: RESPONSE

uint8 input

Copyright 2001-2012 Bluegiga Technologies

Page 120 of 195

Byte Type 0 1 2 3 0x00 0x02 0x07 0x02

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Hardware

method Message ID 0: Command was executed successfully

4 - 5 uint16 result

Non-zero: An error occurred

Table 119: EVENTS Event Description

hardare adc result ADC read operation has completed

C Functions
/* Function */ void ble_cmd_hardware_adc_read( uint8 input, uint8 decimation, uint8 reference_selection ); /* Callback */ struct ble_msg_hardware_adc_read_rsp_t{ uint16 result } void ble_rsp_hardware_adc_read( const struct ble_msg_hardware_adc_read_rsp_t * msg )

BGScript Functions
call hardware_adc_read(input, decimation, reference_selection)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 121 of 195

I2c Read
Read data from I2C bus using bit-bang method. On BLE112 module the I2C CLK is fixed to P1_7 and I2C data in P1_6. Pull-up must be enabled on both pins.
To convert a 7-bit I2C address to an 8-bit one, shift left by one bit. For example, a 7-bit address of 0x40 (dec 64) would be used as 0x80 (dec 128).

Table 120: COMMAND Byte Type Name 0 1 2 3 4 5 6 0x00 0x03 0x07 hilen lolen class Description Message type: command Minimum payload length Message class: Hardware Message ID

0x0A method

uint8 address I2C's 8-bit slave address with the read/write bit (LSB) set to zero. uint8 stop uint8 length If nonzero Send I2C stop condition after transmission Number of bytes to read Table 121: RESPONSE

Byte Type 0 1 2 3 0x00 0x03 0x07 0x0A

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

method Message ID result Command result Data read

4 - 5 uint16 6

uint8array data

C Functions
/* Function */ void ble_cmd_hardware_i2c_read( uint8 address, uint8 stop, uint8 length ); /* Callback */ struct ble_msg_hardware_i2c_read_rsp_t{ uint16 result, uint8 data_len, const uint8* data_data } void ble_rsp_hardware_i2c_read( const struct ble_msg_hardware_i2c_read_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 122 of 195

BGScript Functions
call hardware_i2c_read(address, stop, length)(result, data_len, data_data)

Copyright 2001-2012 Bluegiga Technologies

Page 123 of 195

I2c Write
Write data to I2C bus using bit-bang method. I2C CLK is fixed to P1_7 and I2C data in P1_6. Pull-up must be enabled on both pins.
To convert a 7-bit address to an 8-bit one, shift left by one bit. For example, a 7-bit address of 0x40 (dec 64) would be used as 0x80 (dec 128).

Table 122: COMMAND Byte Type 0 1 2 3 4 5 6 0x00 0x03 0x07 0x0B uint8 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID

address I2C's 8-bit slave address with the read/write bit (LSB) set to zero. stop If nonzero Send I2C stop condition after transmission Data to write Table 123: RESPONSE

uint8array data

Byte Type Name 0 1 2 3 4 0x00 0x01 0x07 hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

0x0B method Message ID uint8 written Bytes written

C Functions
/* Function */ void ble_cmd_hardware_i2c_write( uint8 address, uint8 stop, uint8 data_len, const uint8* data_data ); /* Callback */ struct ble_msg_hardware_i2c_write_rsp_t{ uint8 written } void ble_rsp_hardware_i2c_write( const struct ble_msg_hardware_i2c_write_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 124 of 195

BGScript Functions
call hardware_i2c_write(address, stop, data_len, data_data)(written)

Copyright 2001-2012 Bluegiga Technologies

Page 125 of 195

Io Port Config Direction

Configure I/O-port directions Table 124: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x07 0x03 hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID I/0 PORT index: 0, 1 or 2

uint8 port

uint8 direction Bitmask for each individual pin direction bit0 means input (default) bit1 means output Example: for all port's pins as output use $FF

Table 125: RESPONSE Byte Type 0 1 2 3 0x00 0x02 0x07 0x03 Name hilen lolen class Description Message type: command Minimum payload length Message class: Hardware

method Message ID 0: Command was executed successfully

4 - 5 uint16 result

Non-zero: An error occurred

C Functions
/* Function */ void ble_cmd_hardware_io_port_config_direction( uint8 port, uint8 direction ); /* Callback */ struct ble_msg_hardware_io_port_config_direction_rsp_t{ uint16 result } void ble_rsp_hardware_io_port_config_direction( const struct ble_msg_hardware_io_port_config_direction_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 126 of 195

BGScript Functions
call hardware_io_port_config_direction(port, direction)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 127 of 195

Io Port Config Function

This command configures the I/O-ports function. If bit is set in function parameter then the corresponding I/O port is set to peripheral function, otherwise it is general purpose I/O pin. Table 126: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x07 0x04 hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID I/O port 0,1,2

uint8 port

uint8 function peripheral selection bit for pins

Table 127: RESPONSE Byte Type 0 1 2 3 0x00 0x02 0x07 0x04 Name hilen lolen class Description Message type: command Minimum payload length Message class: Hardware

method Message ID 0: Command was executed successfully

4 - 5 uint16 result

Non-zero: An error occurred

C Functions
/* Function */ void ble_cmd_hardware_io_port_config_function( uint8 port, uint8 function ); /* Callback */ struct ble_msg_hardware_io_port_config_function_rsp_t{ uint16 result } void ble_rsp_hardware_io_port_config_function( const struct ble_msg_hardware_io_port_config_function_rsp_t * msg )

BGScript Functions
call hardware_io_port_config_function(port, function)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 128 of 195

IO Port Config IRQ

This command configures the locals I/O-port interrupts
Currently interrupts can not be enabled on I/O-port 2.

Table 128: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x03 0x07 0x00 hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID I/O port selection Possible values. 0,1 or 2 5 6 uint8 enable_bits interrupt enable mask for pins

uint8 port

uint8 falling_edge Interrupt sense for port. 0 : rising edge 1 : falling edge Note: affects all pins on port Table 129: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x07 0x00

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

method Message ID error code, 0-success Table 130: EVENTS

4 - 5 uint16 result

Event

Description

hardware io_port_status Sent after pin change edge detected, and pin irq is enabled

Copyright 2001-2012 Bluegiga Technologies

Page 129 of 195

C Functions
/* Function */ void ble_cmd_hardware_io_port_config_irq( uint8 port, uint8 enable_bits, uint8 falling_edge ); /* Callback */ struct ble_msg_hardware_io_port_config_irq_rsp_t{ uint16 result } void ble_rsp_hardware_io_port_config_irq( const struct ble_msg_hardware_io_port_config_irq_rsp_t * msg )

BGScript Functions
call hardware_io_port_config_irq(port, enable_bits, falling_edge)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 130 of 195

Io Port Config Pull

Configure I/O-port pull-up/pull-down
Pins P1_0 and P1_1 do not have pullup/pulldown.

Table 131: COMMAND Byte Type Name 0 1 2 3 4 5 6 0x00 0x03 0x07 0x05 hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID I/O port select: 0, 1 or 2

uint8 port

uint8 tristate_mask If bit is set, disabled pull on pin uint8 pull_up 1: pull all port's pins up 0: pull all port's pins down Table 132: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x07 0x05

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

method Message ID error code, 0-success

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_hardware_io_port_config_pull( uint8 port, uint8 tristate_mask, uint8 pull_up ); /* Callback */ struct ble_msg_hardware_io_port_config_pull_rsp_t{ uint16 result } void ble_rsp_hardware_io_port_config_pull( const struct ble_msg_hardware_io_port_config_pull_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 131 of 195

BGScript Functions
call hardware_io_port_config_pull(port, tristate_mask, pull_up)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 132 of 195

Io Port Read
Read I/O-port Table 133: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x07 0x07 hilen lolen class Description Message type: command Minimum payload length Message class: Hardware

method Message ID I/O port to read 0,1,2 I/O pins to read Table 134: RESPONSE

uint8 port uint8 mask

Byte Type 0 1 2 3 0x00 0x04 0x07 0x07

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

method Message ID error code, 0-success I/O port read I/O port pin state

4 - 5 uint16 result 6 7 uint8 uint8 port data

C Functions
/* Function */ void ble_cmd_hardware_io_port_read( uint8 port, uint8 mask ); /* Callback */ struct ble_msg_hardware_io_port_read_rsp_t{ uint16 result, uint8 port, uint8 data } void ble_rsp_hardware_io_port_read( const struct ble_msg_hardware_io_port_read_rsp_t * msg )

BGScript Functions
call hardware_io_port_read(port, mask)(result, port, data)

Copyright 2001-2012 Bluegiga Technologies

Page 133 of 195

Io Port Write
Write I/O-port Table 135: COMMAND Byte Type Name 0 1 2 3 4 5 6 0x00 0x03 0x07 0x06 hilen lolen class Description Message type: command Minimum payload length Message class: Hardware

method Message ID I/O port to write to 0,1,2 Pins to modify Pin values to set Table 136: RESPONSE

uint8 port uint8 mask uint8 data

Byte Type 0 1 2 3 0x00 0x02 0x07 0x06

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

method Message ID error code, 0-success

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_hardware_io_port_write( uint8 port, uint8 mask, uint8 data ); /* Callback */ struct ble_msg_hardware_io_port_write_rsp_t{ uint16 result } void ble_rsp_hardware_io_port_write( const struct ble_msg_hardware_io_port_write_rsp_t * msg )

BGScript Functions
call hardware_io_port_write(port, mask, data)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 134 of 195

Set Soft Timer

This command configures the local software timer. The timer is 22 bits so the maximum value with BLE112 is 2^22 = 4194304/32768Hz = 256 seconds. With BLED112 USB dongle the maximum value is 2^22 = 4194304/32000Hz = 261 seconds Table 137: COMMAND Byte Type 0 1 2 3 0x00 0x06 0x07 0x01 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID Timer interrupt period in units of local crystal frequency.

4 - 7 uint32 time

time = 1/32768 seconds if sleep oscillator is installed time = 1/32000 seconds if internal RC oscillator is used

If time is 0, removes scheduled timer 8 9 uint8 uint8 handle Handle that is sent back in event

single_shot Timer mode 0: if timer is repeating 1: sent timer event only once Table 138: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x07 0x01

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

method Message ID Command result Table 139: EVENTS

4 - 5 uint16 result

Event

Description

hardware soft_timer Sent after specified interval

Copyright 2001-2012 Bluegiga Technologies

Page 135 of 195

C Functions
/* Function */ void ble_cmd_hardware_set_soft_timer( uint32 time, uint8 handle, uint8 single_shot ); /* Callback */ struct ble_msg_hardware_set_soft_timer_rsp_t{ uint16 result } void ble_rsp_hardware_set_soft_timer( const struct ble_msg_hardware_set_soft_timer_rsp_t * msg )

BGScript Functions
call hardware_set_soft_timer(time, handle, single_shot)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 136 of 195

Set Txpower
Set TX Power Table 140: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x07 hilen lolen class Description Message type: command Minimum payload length Message class: Hardware

0x0C method Message ID uint8 power TX power level to use Range: 0 to 15 which give the real TX power from -23 to +3 dBm

Table 141: RESPONSE Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x07 class Description Message type: command Minimum payload length Message class: Hardware

0x0C method Message ID

C Functions
/* Function */ void ble_cmd_hardware_set_txpower( int8 power ); /* Callback * void ble_rsp_hardware_set_txpower( const void *nul )

BGScript Functions
call hardware_set_txpower(power)

Copyright 2001-2012 Bluegiga Technologies

Page 137 of 195

Spi Config
Configure SPI Table 142: COMMAND Byte Type Name 0 1 2 3 4 5 6 7 8 9 0x00 0x06 0x07 0x08 hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID USART channel 0,1 Clock polarity 0,1 Clock phase 0,1

uint8 channel uint8 polarity uint8 phase

uint8 bit_order Endianness select, 0-LSB 1-MSB first uint8 baud_e uint8 baud_m baud rate exponent value baud rate mantissa value Table 143: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x07 0x08

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Hardware

method Message ID error code, 0-success

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_hardware_spi_config( uint8 channel, uint8 polarity, uint8 phase, uint8 bit_order, uint8 baud_e, uint8 baud_m ); /* Callback */ struct ble_msg_hardware_spi_config_rsp_t{ uint16 result } void ble_rsp_hardware_spi_config( const struct ble_msg_hardware_spi_config_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 138 of 195

BGScript Functions
call hardware_spi_config(channel, polarity, phase, bit_order, baud_e, baud_m)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 139 of 195

Spi Transfer
Transfer SPI data Table 144: COMMAND Byte Type 0 1 2 3 4 5 0x00 0x02 0x07 0x09 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: Hardware Message ID

channel SPI channel used 0,1 Data to transmit Table 145: RESPONSE

uint8array data

Byte Type 0 1 2 3 0x00 0x04 0x07 0x09

Name hilen lolen class method result

Description Message type: command Minimum payload length Message class: Hardware Message ID error code, 0-success

4 - 5 uint16 6 7 uint8

channel SPI channel used data received

uint8array data

C Functions
/* Function */ void ble_cmd_hardware_spi_transfer( uint8 channel, uint8 data_len, const uint8* data_data ); /* Callback */ struct ble_msg_hardware_spi_transfer_rsp_t{ uint16 result, uint8 channel, uint8 data_len, const uint8* data_data } void ble_rsp_hardware_spi_transfer( const struct ble_msg_hardware_spi_transfer_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 140 of 195

BGScript Functions
call hardware_spi_transfer(channel, data_len, data_data)(result, channel, data_len, data_data)

Copyright 2001-2012 Bluegiga Technologies

Page 141 of 195

Timer Comparator
Set comparator for timer channel. This command may be used to generate e.g. PWM signals with hardware timer. More information on different comparator modes and their usage may be found from Texas Instruments CC2540 User's Guide (SWRU191B), section 9.8 Output Compare Mode. Table 146: COMMAND Byte Type 0 1 2 3 4 5 6 0x00 0x05 0x07 0x0D uint8 uint8 uint8 Name hilen lolen class method timer channel mode Description Message type: command Minimum payload length Message class: Hardware Message ID Timer Timer channel Comparator mode

7 - 8 uint16 comparator_value Comparator value Table 147: RESPONSE Byte Type 0 1 2 3 0x00 0x02 0x07 0x0D Name hilen lolen class Description Message type: command Minimum payload length Message class: Hardware

method Message ID Command result

4 - 5 uint16 result

C Functions

/* Function */ void ble_cmd_hardware_timer_comparator( uint8 timer, uint8 channel, uint8 mode, uint16 comparator_value ); /* Callback */ struct ble_msg_hardware_timer_comparator_rsp_t{ uint16 result } void ble_rsp_hardware_timer_comparator( const struct ble_msg_hardware_timer_comparator_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 142 of 195

BGScript Functions

call hardware_timer_comparator(timer, channel, mode, comparator_value)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 143 of 195

5.5.2 Events
Hardware class events

ADC Result
This events is produced when an A/D converter result is received. Table 148: EVENT Byte Type Name 0 1 2 3 4 0x80 0x03 0x07 0x02 hilen lolen class Description Message type: event Minimum payload length Message class: Hardware

method Message ID A/D input from which value is received from A/D value

uint8 input

5 - 6 int16 value

C Functions
/* Callback */ struct ble_msg_hardware_adc_result_evt_t{ uint8 input, int16 value } void ble_evt_hardware_adc_result( const struct ble_msg_hardware_adc_result_evt_t * msg )

BGScript Functions
event hardware_adc_result(input, value)

Copyright 2001-2012 Bluegiga Technologies

Page 144 of 195

IO Port Status
This event is produced when I/O port status changes. Table 149: EVENT Byte Type 0 1 2 3 0x80 0x07 0x07 0x00 Name hilen lolen class method Description Message type: event Minimum payload length Message class: Hardware Message ID

4 - 7 uint32 timestamp Value of internal timer Range : 0 to 2^24-1 8 9 uint8 uint8 port irq I/O port I/O flags Tells which port caused interrupt (bitmask). Current status of all I/Os in port (bitmask).

10

uint8

state

C Functions
/* Callback */ struct ble_msg_hardware_io_port_status_evt_t{ uint32 timestamp, uint8 port, uint8 irq, uint8 state } void ble_evt_hardware_io_port_status( const struct ble_msg_hardware_io_port_status_evt_t * msg )

BGScript Functions
event hardware_io_port_status(timestamp, port, irq, state)

Copyright 2001-2012 Bluegiga Technologies

Page 145 of 195

Soft Timer
This event is produced when software timer interrupt is generated. Table 150: EVENT Byte Type Name 0 1 2 3 4 0x80 0x01 0x07 0x01 hilen lolen class Description Message type: event Minimum payload length Message class: Hardware

method Message ID

uint8 handle The software timer handle

C Functions
/* Callback */ struct ble_msg_hardware_soft_timer_evt_t{ uint8 handle } void ble_evt_hardware_soft_timer( const struct ble_msg_hardware_soft_timer_evt_t * msg )

BGScript Functions
event hardware_soft_timer(handle)

Copyright 2001-2012 Bluegiga Technologies

Page 146 of 195

5.6 Persistent Store

The Persistent Store (PS) class provides methods to read write and dump the local devices parameters (PS keys).

5.6.1 Commands
Persistent Store class commands

PS Defrag
This command defragments the Persistent Store. Table 151: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x01 class Description Message type: command Minimum payload length Message class: Persistent Store

0x00 method Message ID Table 152: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x01 class

Description Message type: response Minimum payload length Message class: Persistent Store

0x00 method Message ID

C Functions
/* Function */ void ble_cmd_flash_ps_defrag( void ); /* Callback * void ble_rsp_flash_ps_defrag( const void *nul )

BGScript Functions
call flash_ps_defrag()

Copyright 2001-2012 Bluegiga Technologies

Page 147 of 195

PS Dump
This command dumps all Persistent Store keys. Table 153: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x01 class Description Message type: command Minimum payload length Message class: Persistent Store

0x01 method Message ID Table 154: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x01 class

Description Message type: response Minimum payload length Message class: Persistent Store

0x01 method Message ID Table 155: EVENTS

Event

Description

flash ps_key PS Key contents

C Functions

/* Function */ void ble_cmd_flash_ps_dump( void ); /* Callback * void ble_rsp_flash_ps_dump( const void *nul )

BGScript Functions

call flash_ps_dump()

Copyright 2001-2012 Bluegiga Technologies

Page 148 of 195

PS Erase All
This command erases all Persistent Store keys. Table 156: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x01 class Description Message type: command Minimum payload length Message class: Persistent Store

0x02 method Message ID Table 157: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x01 class

Description Message type: response Minimum payload length Message class: Persistent Store

0x02 method Message ID

C Functions
/* Function */ void ble_cmd_flash_ps_erase_all( void ); /* Callback * void ble_rsp_flash_ps_erase_all( const void *nul )

BGScript Functions
call flash_ps_erase_all()

Copyright 2001-2012 Bluegiga Technologies

Page 149 of 195

PS Erase
This command erases a Persistent Store key given as parameter. Table 158: COMMAND Byte Type 0 1 2 3 0x00 0x02 0x01 0x05 Name hilen lolen class Description Message type: command Minimum payload length Message class: Persistent Store

method Message ID Key to erase Table 159: RESPONSE

4 - 5 uint16 key

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x01 class

Description Message type: response Minimum payload length Message class: Persistent Store

0x05 method Message ID

C Functions
/* Function */ void ble_cmd_flash_ps_erase( uint16 key ); /* Callback * void ble_rsp_flash_ps_erase( const void *nul )

BGScript Functions
call flash_ps_erase(key)

Copyright 2001-2012 Bluegiga Technologies

Page 150 of 195

PS Load
This command reads a Persistent Store key from the local device. Table 160: COMMAND Byte Type 0 1 2 3 0x00 0x02 0x01 0x04 Name hilen lolen class Description Message type: command Minimum payload length Message class: Persistent Store

method Message ID Key to load Keys 8000 to 807F can be read. Table 161: RESPONSE

4 - 5 uint16 key

Byte Type 0 1 2 3 0x00 0x03 0x01 0x04

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Persistent Store

method Message ID result 0 : the read was successful Key's value

4 - 5 uint16 6

uint8array value

C Functions
/* Function */ void ble_cmd_flash_ps_load( uint16 key ); /* Callback */ struct ble_msg_flash_ps_load_rsp_t{ uint16 result, uint8 value_len, const uint8* value_data } void ble_rsp_flash_ps_load( const struct ble_msg_flash_ps_load_rsp_t * msg )

BGScript Functions
call flash_ps_load(key)(result, value_len, value_data)

Copyright 2001-2012 Bluegiga Technologies

Page 151 of 195

PS Save
This command saves a Persistent Store (PS) key to the local device. The size of a single PS-key is 32 bytes and a total of 128 keys are available. Table 162: COMMAND Byte Type 0 1 2 3 0x00 0x03 0x01 0x03 Name hilen lolen class Description Message type: command Minimum payload length Message class: Persistent Store

method Message ID key Key to save. Keys 8000 to 807F can be used for persistent storage of user data.

4 - 5 uint16

uint8array value

Value of the key Table 163: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x01 0x03

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Persistent Store

method Message ID 0 : the write was successful

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_flash_ps_save( uint16 key, uint8 value_len, const uint8* value_data ); /* Callback */ struct ble_msg_flash_ps_save_rsp_t{ uint16 result } void ble_rsp_flash_ps_save( const struct ble_msg_flash_ps_save_rsp_t * msg )

BGScript Functions
call flash_ps_save(key, value_len, value_data)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 152 of 195

5.6.2 Events
Persistent Store class events

PS Key
This event is produced during a Persistent Store key dump for every dumped key. Table 164: EVENT Byte Type 0 1 2 3 0x80 0x03 0x01 0x00 Name hilen lolen class Description Message type: event Minimum payload length Message class: Persistent Store

method Message ID key Persistent Store key ID Key value

4 - 5 uint16 6

uint8array value

C Functions
/* Callback */ struct ble_msg_flash_ps_key_evt_t{ uint16 key, uint8 value_len, const uint8* value_data } void ble_evt_flash_ps_key( const struct ble_msg_flash_ps_key_evt_t * msg )

BGScript Functions
event flash_ps_key(key, value_len, value_data)

Copyright 2001-2012 Bluegiga Technologies

Page 153 of 195

5.7 Security Manager

The Security Manager (SM) class provides access to the Bluetooth low energy Security Manager methods such as : bonding management and modes and encryption control.

5.7.1 Commands
Security Manager class commands

Delete Bonding
This command deletes a bonding from the local security database. There can be a maximum of 8 bonded devices stored at the same time, and one of them must be deleted if you need bonding with a 9th device. Table 165: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x05 0x02 hilen lolen class Description Message type: command Minimum payload length Message class: Security Manager

method Message ID

uint8 handle Table 166: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x05 0x02

Name hilen lolen class

Description Message type: command Minimum payload length Message class: Security Manager

method Message ID Command result

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_sm_delete_bonding( uint8 handle ); /* Callback */ struct ble_msg_sm_delete_bonding_rsp_t{ uint16 result } void ble_rsp_sm_delete_bonding( const struct ble_msg_sm_delete_bonding_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 154 of 195

BGScript Functions
call sm_delete_bonding(handle)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 155 of 195

Encrypt Start
This command starts the encryption for a given connection. | Table 167: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x05 0x00 hilen lolen class method Description Message type: command Minimum payload length Message class: Security Manager Message ID Connection handle

uint8 handle

uint8 bonding Create bonding if devices are not already bonded Table 168: RESPONSE

Byte Type 0 1 2 3 4 0x00 0x03 0x05 0x00 uint8

Name hilen lolen class

Description Message type: response Minimum payload length Message class: Security Manager

method Message ID handle Connection handle 0 : the encryption was started successfully Table 169: EVENTS

5 - 6 uint16 result

Event sm_bonding_fail

Description Sent if encryption or bonding fails

connection_status Sent when connectino is encrypted

Copyright 2001-2012 Bluegiga Technologies

Page 156 of 195

C Functions

/* Function */ void ble_cmd_sm_encrypt_start( uint8 handle, uint8 bonding ); /* Callback */ struct ble_msg_sm_encrypt_start_rsp_t{ uint8 handle, uint16 result } void ble_rsp_sm_encrypt_start( const struct ble_msg_sm_encrypt_start_rsp_t * msg )

BGScript Functions

call sm_encrypt_start(handle, bonding)(handle, result)

Copyright 2001-2012 Bluegiga Technologies

Page 157 of 195

Get Bonds
List all bonded devices. There can be a maximum of 8 bonded devices. The information related to the bonded devices is stored in the Flash memory, so it is persistent across resets and power-cycles. Table 170: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x05 class Description Message type: command Minimum payload length Message class: Security Manager

0x05 method Message ID Table 171: RESPONSE

Byte Type Name 0 1 2 3 4 0x00 0x01 0x05 0x05 hilen lolen class

Description Message type: command Minimum payload length Message class: Security Manager

method Message ID Num of currently bonded devices Table 172: EVENTS

uint8 bonds

Event

Description

sm bond_status Bond status for each bonded device

C Functions
/* Function */ void ble_cmd_sm_get_bonds( void ); /* Callback */ struct ble_msg_sm_get_bonds_rsp_t{ uint8 bonds } void ble_rsp_sm_get_bonds( const struct ble_msg_sm_get_bonds_rsp_t * msg )

BGScript Functions
call sm_get_bonds()(bonds)

Copyright 2001-2012 Bluegiga Technologies

Page 158 of 195

Passkey Entry
User entered passkey Table 173: COMMAND Byte Type 0 1 2 3 4 0x00 0x05 0x05 0x04 uint8 Name hilen lolen class method handle Description Message type: command Minimum payload length Message class: Security Manager Message ID Connection Handle

5 - 8 uint32 passkey Passkey range 000000-999999 Table 174: RESPONSE Byte Type 0 1 2 3 0x00 0x02 0x05 0x04 Name hilen lolen class Description Message type: command Minimum payload length Message class: Security Manager

method Message ID

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_sm_passkey_entry( uint8 handle, uint32 passkey ); /* Callback */ struct ble_msg_sm_passkey_entry_rsp_t{ uint16 result } void ble_rsp_sm_passkey_entry( const struct ble_msg_sm_passkey_entry_rsp_t * msg )

BGScript Functions
call sm_passkey_entry(handle, passkey)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 159 of 195

Set Bondable Mode

Set device to bondable mode Table 175: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x05 0x01 hilen lolen class method Description Message type: command Minimum payload length Message class: Security Manager Message ID

uint8 bondable Enables or disables bonding mode 0 : the device is not bondable 1 : the device is bondable Table 176: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x05 class

Description Message type: command Minimum payload length Message class: Security Manager

0x01 method Message ID

C Functions
/* Function */ void ble_cmd_sm_set_bondable_mode( uint8 bondable ); /* Callback * void ble_rsp_sm_set_bondable_mode( const void *nul )

BGScript Functions
call sm_set_bondable_mode(bondable)

Copyright 2001-2012 Bluegiga Technologies

Page 160 of 195

Set Oob Data

Set out-of-band encryption data for device Device does not allow any other kind of pairing except oob if oob data is set. Table 177: COMMAND Byte Type 0 1 2 3 4 0x00 0x01 0x05 0x06 Name hilen lolen class Description Message type: command Minimum payload length Message class: Security Manager

method Message ID OOB data to set, if empty clear oob data Table 178: RESPONSE

uint8array oob

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x05 class

Description Message type: command Minimum payload length Message class: Security Manager

0x06 method Message ID

C Functions
/* Function */ void ble_cmd_sm_set_oob_data( uint8 oob_len, const uint8* oob_data ); /* Callback * void ble_rsp_sm_set_oob_data( const void *nul )

BGScript Functions
call sm_set_oob_data(oob_len, oob_data)

Copyright 2001-2012 Bluegiga Technologies

Page 161 of 195

Set Parameters
Configure Security Manager Table 179: COMMAND Byte Type Name 0 1 2 3 4 5 6 0x00 0x03 0x05 0x03 hilen lolen class method Description Message type: command Minimum payload length Message class: Security Manager Message ID Man-in-the-middle protection required minimum key size in bytes range 7-16

uint8 mitm uint8 min_key_size

uint8 io_capabilities see:SMP IO Capabilities Table 180: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x05 class

Description Message type: command Minimum payload length Message class: Security Manager

0x03 method Message ID

C Functions
/* Function */ void ble_cmd_sm_set_parameters( uint8 mitm, uint8 min_key_size, uint8 io_capabilities ); /* Callback * void ble_rsp_sm_set_parameters( const void *nul )

BGScript Functions
call sm_set_parameters(mitm, min_key_size, io_capabilities)

Copyright 2001-2012 Bluegiga Technologies

Page 162 of 195

5.7.2 Enumerations
Security Manager commands

Bonding Keys
Bonding information stored Table 181: VALUES Value Name 0x01 0x02 0x04 0x08 0x10 0x20 0x40 sm_bonding_key_ltk Description LTK saved in master

sm_bonding_key_addr_public Public Address sm_bonding_key_addr_static sm_bonding_key_irk sm_bonding_key_edivrand sm_bonding_key_csrk sm_bonding_key_masterid Static Address Identity resolving key for resolvable private addresses EDIV+RAND received from slave Connection signature resolving key EDIV+RAND sent to master

Copyright 2001-2012 Bluegiga Technologies

Page 163 of 195

SMP IO Capabilities
SMP IO Capabilities Table 182: VALUES Value Name 0 1 2 3 4 sm_io_capability_displayonly sm_io_capability_displayyesno sm_io_capability_keyboardonly Description Display Only Display with Yes/No-buttons Keyboard Only

sm_io_capability_noinputnooutput No Input and No Output sm_io_capability_keyboarddisplay Display with Keyboard

Copyright 2001-2012 Bluegiga Technologies

Page 164 of 195

5.7.3 Events
Security Manager class events

Bonding Fail
Link bonding has failed Table 183: EVENT Byte Type 0 1 2 3 4 0x80 0x03 0x05 0x01 uint8 Name hilen lolen class Description Message type: event Minimum payload length Message class: Security Manager

method Message ID handle Connection handle Encryption status, describes error that occurred during bonding

5 - 6 uint16 result

C Functions
/* Callback */ struct ble_msg_sm_bonding_fail_evt_t{ uint8 handle, uint16 result } void ble_evt_sm_bonding_fail( const struct ble_msg_sm_bonding_fail_evt_t * msg )

BGScript Functions
event sm_bonding_fail(handle, result)

Copyright 2001-2012 Bluegiga Technologies

Page 165 of 195

Bond Status
Bond status information Table 184: EVENT Byte Type Name 0 1 2 3 4 5 6 7 0x80 0x04 0x05 0x04 hilen lolen class method Description Message type: event Minimum payload length Message class: Security Manager Message ID Bond handle

uint8 bond

uint8 keysize Encryption key size used in long-term key uint8 mitm uint8 keys Was mitm used in pairing Keys stored for bond see:[enum sm_bonding_key]

C Functions
/* Callback */ struct ble_msg_sm_bond_status_evt_t{ uint8 bond, uint8 keysize, uint8 mitm, uint8 keys } void ble_evt_sm_bond_status( const struct ble_msg_sm_bond_status_evt_t * msg )

BGScript Functions
event sm_bond_status(bond, keysize, mitm, keys)

Copyright 2001-2012 Bluegiga Technologies

Page 166 of 195

Passkey Display
Passkey to be entered to remote device Table 185: EVENT Byte Type 0 1 2 3 4 0x80 0x05 0x05 0x02 uint8 Name hilen lolen class method handle Description Message type: event Minimum payload length Message class: Security Manager Message ID

5 - 8 uint32 passkey Passkey range 000000-999999

C Functions
/* Callback */ struct ble_msg_sm_passkey_display_evt_t{ uint8 handle, uint32 passkey } void ble_evt_sm_passkey_display( const struct ble_msg_sm_passkey_display_evt_t * msg )

BGScript Functions
event sm_passkey_display(handle, passkey)

Copyright 2001-2012 Bluegiga Technologies

Page 167 of 195

Passkey Request
Security Manager requests user to enter passkey Use Passkey Entry - command to respond to request Table 186: EVENT Byte Type Name 0 1 2 3 4 0x80 0x01 0x05 0x03 hilen lolen class Description Message type: event Minimum payload length Message class: Security Manager

method Message ID

uint8 handle Connection handle

C Functions
/* Callback */ struct ble_msg_sm_passkey_request_evt_t{ uint8 handle } void ble_evt_sm_passkey_request( const struct ble_msg_sm_passkey_request_evt_t * msg )

BGScript Functions
event sm_passkey_request(handle)

Copyright 2001-2012 Bluegiga Technologies

Page 168 of 195

5.8 System
The System class provides access to the local device and contains functions for example to query Bluetooth address, firmware version, packet counters etc.

5.8.1 Commands
System class commands

Address Get
This command reads the local devices public Bluetooth address. Table 187: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class Description Message type: command Minimum payload length Message class: System

0x02 method Message ID Table 188: RESPONSE

Byte Type 0 1 2 3 0x00 0x06 0x00 0x02

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: System Message ID

4 - 9 bd_addr address Bluetooth address of the local device

C Functions
/* Function */ void ble_cmd_system_address_get( void ); /* Callback */ struct ble_msg_system_address_get_rsp_t{ bd_addr address } void ble_rsp_system_address_get( const struct ble_msg_system_address_get_rsp_t * msg )

BGScript Functions
call system_address_get()(address)

Copyright 2001-2012 Bluegiga Technologies

Page 169 of 195

Endpoint Rx
Read data from an endpoint (i.e., data souce, e.g., UART), error is returned if endpoint does not have enough data. Table 189: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x02 0x00 hilen lolen class Description Message type: command Minimum payload length Message class: System Message ID

0x0D method

uint8 endpoint Endpoint index to read data from uint8 size Size of data to read Table 190: RESPONSE

Byte Type 0 1 2 3 0x00 0x03 0x00 0x0D

Name hilen lolen class

Description Message type: command Minimum payload length Message class: System

method Message ID result Command result Data read from endpoint

4 - 5 uint16 6

uint8array data

C Functions
/* Function */ void ble_cmd_system_endpoint_rx( uint8 endpoint, uint8 size ); /* Callback */ struct ble_msg_system_endpoint_rx_rsp_t{ uint16 result, uint8 data_len, const uint8* data_data } void ble_rsp_system_endpoint_rx( const struct ble_msg_system_endpoint_rx_rsp_t * msg )

BGScript Functions
call system_endpoint_rx(endpoint, size)(result, data_len, data_data)

Copyright 2001-2012 Bluegiga Technologies

Page 170 of 195

Endpoint Set Watermarks

Set watermarks on both input and output sides of an endpoint. Table 191: COMMAND Byte Type Name 0 1 2 3 4 5 0x00 0x03 0x00 hilen lolen class Description Message type: command Minimum payload length Message class: System Message ID

0x0E method

uint8 endpoint Endpoint index to set watermarks. uint8 rx Watermark position on receive buffer 0xFF : watermark is not modified 0 : disables watermark

uint8 tx

Watermark position on transmit buffer 0xFF : watermark is not modified 0 : disables watermark Table 192: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x00 0x0E

Name hilen lolen class

Description Message type: command Minimum payload length Message class: System

method Message ID Command result

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_system_endpoint_set_watermarks( uint8 endpoint, uint8 rx, uint8 tx ); /* Callback */ struct ble_msg_system_endpoint_set_watermarks_rsp_t{ uint16 result } void ble_rsp_system_endpoint_set_watermarks( const struct ble_msg_system_endpoint_set_watermarks_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 171 of 195

BGScript Functions
call system_endpoint_set_watermarks(endpoint, rx, tx)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 172 of 195

Endpoint Tx
Send data to endpoint, error is returned if endpoint does not have enough space Table 193: COMMAND Byte Type 0 1 2 3 4 5 0x00 0x02 0x00 0x09 uint8 Name hilen lolen class method Description Message type: command Minimum payload length Message class: System Message ID

endpoint Endpoint index to send data to data to send Table 194: RESPONSE

uint8array data

Byte Type 0 1 2 3 0x00 0x02 0x00 0x09

Name hilen lolen class

Description Message type: command Minimum payload length Message class: System

method Message ID Command result

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_system_endpoint_tx( uint8 endpoint, uint8 data_len, const uint8* data_data ); /* Callback */ struct ble_msg_system_endpoint_tx_rsp_t{ uint16 result } void ble_rsp_system_endpoint_tx( const struct ble_msg_system_endpoint_tx_rsp_t * msg )

BGScript Functions
call system_endpoint_tx(endpoint, data_len, data_data)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 173 of 195

Get Connections
This command reads the number of supported connections from the local device. Table 195: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class Description Message type: command Minimum payload length Message class: System

0x06 method Message ID Table 196: RESPONSE

Byte Type Name 0 1 2 3 4 0x00 0x01 0x00 0x06 hilen lolen class method

Description Message type: response Minimum payload length Message class: System Message ID

uint8 maxconn Max supported connections Table 197: EVENTS

Event

Description

connection status Connection status for each connection handle

C Functions
/* Function */ void ble_cmd_system_get_connections( void ); /* Callback */ struct ble_msg_system_get_connections_rsp_t{ uint8 maxconn } void ble_rsp_system_get_connections( const struct ble_msg_system_get_connections_rsp_t * msg )

BGScript Functions
call system_get_connections()(maxconn)

Copyright 2001-2012 Bluegiga Technologies

Page 174 of 195

Get Counters
Read packet counters and resets them, also returns available packet buffers. Table 198: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class Description Message type: command Minimum payload length Message class: System

0x05 method Message ID Table 199: RESPONSE

Byte Type Name 0 1 2 3 4 5 6 7 8 0x00 0x05 0x00 0x05 hilen lolen class

Description Message type: command Minimum payload length Message class: System

method Message ID Acknowledgements received for sent packets Number of packets retransmitted packets received where crc was ok packets received where crc failed Available packet buffers

uint8 txok uint8 txretry uint8 rxok uint8 rxfail uint8 mbuf

C Functions
/* Function */ void ble_cmd_system_get_counters( void ); /* Callback */ struct ble_msg_system_get_counters_rsp_t{ uint8 txok, uint8 txretry, uint8 rxok, uint8 rxfail, uint8 mbuf } void ble_rsp_system_get_counters( const struct ble_msg_system_get_counters_rsp_t * msg )

BGScript Functions
call system_get_counters()(txok, txretry, rxok, rxfail, mbuf)

Copyright 2001-2012 Bluegiga Technologies

Page 175 of 195

Get Info
This command reads the local devices software and hardware versions. Table 200: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class Description Message type: command Minimum payload length Message class: System

0x08 method Message ID Table 201: RESPONSE

Byte 0 1 2 3 4-5 6-7 8-9

Type 0x00 0x0C 0x00 0x08

Name hilen lolen class method

Description Message type: response Minimum payload length Message class: System Message ID Major software version Minor software version Patch ID Build version Link layer version

uint16 major uint16 minor uint16 patch

10 - 11 uint16 build 12 - 13 uint16 ll_version 14 15 uint8 uint8

protocol_version BGAPI protocol version hw Hardware version

C Functions
/* Function */ void ble_cmd_system_get_info( void ); /* Callback */ struct ble_msg_system_get_info_rsp_t{ uint16 major, uint16 minor, uint16 patch, uint16 build, uint16 ll_version, uint8 protocol_version, uint8 hw } void ble_rsp_system_get_info( const struct ble_msg_system_get_info_rsp_t * msg )

Copyright 2001-2012 Bluegiga Technologies

Page 176 of 195

BGScript Functions
call system_get_info()(major, minor, patch, build, ll_version, protocol_version, hw)

Copyright 2001-2012 Bluegiga Technologies

Page 177 of 195

Hello
This command can be used to test if the local device is functional. Similar to a typical "AT" -> "OK" test. Table 202: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class Description Message type: command Minimum payload length Message class: System

0x01 method Message ID Table 203: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class

Description Message type: response Minimum payload length Message class: System

0x01 method Message ID

C Functions
/* Function */ void ble_cmd_system_hello( void ); /* Callback * void ble_rsp_system_hello( const void *nul )

BGScript Functions
call system_hello()

Copyright 2001-2012 Bluegiga Technologies

Page 178 of 195

Reset
This command resets the local device immediately. The command does not have a response. Table 204: COMMAND Byte Type Name 0 1 2 3 4 0x00 0x01 0x00 0x00 hilen lolen class method Description Message type: command Minimum payload length Message class: System Message ID

uint8 boot_in_dfu Selects the boot mode 0 : boot to main program 1 : boot to DFU Table 205: EVENTS

Event

Description

system boot Sent when device has completed reset

C Functions
/* Function */ void ble_cmd_system_reset( uint8 boot_in_dfu );

BGScript Functions
call system_reset(boot_in_dfu)

Copyright 2001-2012 Bluegiga Technologies

Page 179 of 195

Whitelist Append
Add an entry to the running white list defining the remote devices which are allowed to establish a connection. If list is empty, calls from all devices will be accepted. Do not use this command while advertising or while being connected. The current list is discarded upon reset or power-cycle.

Table 206: COMMAND Byte Type 0 1 2 3 0x00 0x07 0x00 0x0A Name hilen lolen class method Description Message type: command Minimum payload length Message class: System Message ID Bluetooth device address to add to the running white list

4 - 9 bd_addr address 10 uint8

address_type Bluetooth address type. Table 207: RESPONSE

Byte Type 0 1 2 3 0x00 0x02 0x00 0x0A

Name hilen lolen class

Description Message type: command Minimum payload length Message class: System

method Message ID

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_system_whitelist_append( bd_addr address, uint8 address_type ); /* Callback */ struct ble_msg_system_whitelist_append_rsp_t{ uint16 result } void ble_rsp_system_whitelist_append( const struct ble_msg_system_whitelist_append_rsp_t * msg )

BGScript Functions
call system_whitelist_append(address, address_type)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 180 of 195

Whitelist Clear
Delete alll entries of the white list at once. Do not use this command while advertising or while being connected.

Table 208: COMMAND Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class Description Message type: command Minimum payload length Message class: System

0x0C method Message ID Table 209: RESPONSE

Byte Type Name 0 1 2 3 0x00 hilen 0x00 lolen 0x00 class

Description Message type: command Minimum payload length Message class: System

0x0C method Message ID

C Functions
/* Function */ void ble_cmd_system_whitelist_clear( void ); /* Callback * void ble_rsp_system_whitelist_clear( const void *nul )

BGScript Functions
call system_whitelist_clear()

Copyright 2001-2012 Bluegiga Technologies

Page 181 of 195

Whitelist Remove
Remove an entry from the running white list. Do not use this command while advertising or while being connected.

Table 210: COMMAND Byte Type 0 1 2 3 0x00 0x07 0x00 0x0B Name hilen lolen class method Description Message type: command Minimum payload length Message class: System Message ID

4 - 9 bd_addr address 10 uint8 address_type Table 211: RESPONSE Byte Type 0 1 2 3 0x00 0x02 0x00 0x0B Name hilen lolen class Description Message type: command Minimum payload length Message class: System

method Message ID

4 - 5 uint16 result

C Functions
/* Function */ void ble_cmd_system_whitelist_remove( bd_addr address, uint8 address_type ); /* Callback */ struct ble_msg_system_whitelist_remove_rsp_t{ uint16 result } void ble_rsp_system_whitelist_remove( const struct ble_msg_system_whitelist_remove_rsp_t * msg )

BGScript Functions
call system_whitelist_remove(address, address_type)(result)

Copyright 2001-2012 Bluegiga Technologies

Page 182 of 195

5.8.2 Enumerations
System class enumerations

Endpoints
Data Endpoints used in data routing and interface configuration Table 212: VALUES Value Name 0 1 2 3 4 5 system_endpoint_api system_endpoint_test Description Command Parser Radio Test

system_endpoint_script BGScript system_endpoint_usb USB Interface

system_endpoint_uart0 USART 0 system_endpoint_uart1 USART 1

Copyright 2001-2012 Bluegiga Technologies

Page 183 of 195

5.8.3 Events
System class events

Boot
This event is produced when the device boots up and is ready to receive commands This event is not sent over USB interface. Table 213: EVENT Byte 0 1 2 3 4-5 6-7 8-9 Type 0x80 0x0C 0x00 0x00 Name hilen lolen class method Description Message type: event Minimum payload length Message class: System Message ID Major software version Minor software version Patch ID Build version Link layer version

uint16 major uint16 minor uint16 patch

10 - 11 uint16 build 12 - 13 uint16 ll_version 14 15 uint8 uint8

protocol_version BGAPI protocol version hw Hardware version

C Functions
/* Callback */ struct ble_msg_system_boot_evt_t{ uint16 major, uint16 minor, uint16 patch, uint16 build, uint16 ll_version, uint8 protocol_version, uint8 hw } void ble_evt_system_boot( const struct ble_msg_system_boot_evt_t * msg )

BGScript Functions
event system_boot(major, minor, patch, build, ll_version, protocol_version, hw)

Copyright 2001-2012 Bluegiga Technologies

Page 184 of 195

Endpoint Watermark Rx
This event is generated if the endpoint has reached the threshold defined by the watermark. Table 214: EVENT Byte Type Name 0 1 2 3 4 5 0x80 0x02 0x00 0x02 hilen lolen class method Description Message type: event Minimum payload length Message class: System Message ID

uint8 endpoint Endpoint index where data was received uint8 data Received data size

C Functions
/* Callback */ struct ble_msg_system_endpoint_watermark_rx_evt_t{ uint8 endpoint, uint8 data } void ble_evt_system_endpoint_watermark_rx( const struct ble_msg_system_endpoint_watermark_rx_evt_t * msg )

BGScript Functions
event system_endpoint_watermark_rx(endpoint, data)

Copyright 2001-2012 Bluegiga Technologies

Page 185 of 195

Endpoint Watermark Tx
This event is generated if the endpoint (transmitting buffer) has reached the threshold of the watermark. Table 215: EVENT Byte Type Name 0 1 2 3 4 5 0x80 0x02 0x00 0x03 hilen lolen class method Description Message type: event Minimum payload length Message class: System Message ID

uint8 endpoint Endpoint index where data was sent uint8 data Space available

C Functions
/* Callback */ struct ble_msg_system_endpoint_watermark_tx_evt_t{ uint8 endpoint, uint8 data } void ble_evt_system_endpoint_watermark_tx( const struct ble_msg_system_endpoint_watermark_tx_evt_t * msg )

BGScript Functions
event system_endpoint_watermark_tx(endpoint, data)

Copyright 2001-2012 Bluegiga Technologies

Page 186 of 195

Script Failure
Script failure detected Table 216: EVENT Byte Type 0 1 2 3 0x80 0x04 0x00 0x04 Name hilen lolen class method Description Message type: event Minimum payload length Message class: System Message ID

4 - 5 uint16 address Address where failure was detected 6 - 7 uint16 reason Reason for failure

C Functions
/* Callback */ struct ble_msg_system_script_failure_evt_t{ uint16 address, uint16 reason } void ble_evt_system_script_failure( const struct ble_msg_system_script_failure_evt_t * msg )

BGScript Functions
event system_script_failure(address, reason)

Copyright 2001-2012 Bluegiga Technologies

Page 187 of 195

5.9 Error Codes

This section describes the error codes the API commands may produce.

5.9.1 BGAPI Errors

Errors related to BGAPI protocol

Invalid Parameter (0x0180)

Command contained invalid parameter

Device in Wrong State (0x0181)

Device is in wrong state to receive command

Out Of Memory (0x0182)

Device has run out of memory

Copyright 2001-2012 Bluegiga Technologies

Page 188 of 195

Feature Not Implemented (0x0183)

Feature is not implemented

Command Not Recognized (0x0184)

Command was not recognized

Timeout (0x0185)
Command or Procedure failed due to timeout

Not Connected (0x0186)

Connection handle passed is to command is not a valid handle

flow (0x0187)
Command would cause either underflow or overflow error

User Attribute (0x0188)

User attribute was accessed through API which is not supported

5.9.2 Bluetooth Errors

Bluetooth errors

Authentication Failure (0x0205)

Pairing or authentication failed due to incorrect results in the pairing or authentication procedure. This could be due to an incorrect PIN or Link Key

Pin or Key Missing (0x0206)

Pairing failed because of missing PIN, or authentication failed because of missing Key.

Copyright 2001-2012 Bluegiga Technologies

Page 189 of 195

Memory Capacity Exceeded (0x0207)

Controller is out of memory.

Connection Timeout (0x0208)

Link supervision timeout has expired.

Connection Limit Exceeded (0x0209)

Controller is at limit of connections it can support.

Command Disallowed (0x020C)

Command requested cannot be executed because the Controller is in a state where it cannot process this command at this time.

Invalid Command Parameters (0x0212)

Command contained invalid parameters.

Remote User Terminated Connection (0x0213)

User on the remote device terminated the connection.

Connection Terminated by Local Host (0x0216)

Local device terminated the connection.

LL Response Timeout (0x0222)

Connection terminated due to link-layer procedure timeout.

LL Instant Passed (0x0228)

Received link-layer control packet where instant was in the past.

Controller Busy (0x023A)

Operation was rejected because the controller is busy and unable to process the request.

Directed Advertising Timeout (0x023C)

Directed advertising completed without a connection being created.

MIC Failure (0x023D)

Connection was terminated because the Message Integrity Check (MIC) failed on a received packet.

Connection Failed to be Established (0x023E)

LL initiated a connection but the connection has failed to be established. Controller did not receive any packets from remote end.

5.9.3 Security Manager Protocol Errors

Errors from Security Manager Protocol

Copyright 2001-2012 Bluegiga Technologies

Page 190 of 195

Passkey Entry Failed (0x0301)

The user input of passkey failed, for example, the user cancelled the operation

OOB Data is not available (0x0302)

Out of Band data is not available for authentication

Authentication Requirements (0x0303)

The pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices

Confirm Value Failed (0x0304)

The confirm value does not match the calculated compare value

Pairing Not Supported (0x0305)

Pairing is not supported by the device

Encryption Key Size (0x0306)

The resultant encryption key size is insufficient for the security requirements of this device

Command Not Supported (0x0307)

The SMP command received is not supported on this device

Unspecified Reason (0x0308)

Pairing failed due to an unspecified reason

Copyright 2001-2012 Bluegiga Technologies

Page 191 of 195

Repeated Attempts (0x0309)

Pairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request

Invalid Parameters (0x030A)

The Invalid Parameters error code indicates: the command length is invalid or a parameter is outside of the specified range.

5.9.4 Attribute Protocol Errors

Errors from Attribute Protocol

Invalid Handle (0x0401)

The attribute handle given was not valid on this server

Read Not Permitted (0x0402)

The attribute cannot be read

Write Not Permitted (0x0403)

The attribute cannot be written

Copyright 2001-2012 Bluegiga Technologies

Page 192 of 195

Invalid PDU (0x0404)

The attribute PDU was invalid

Insufficient Authentication (0x0405)

The attribute requires authentication before it can be read or written.

Request Not Supported (0x0406)

Attribute Server does not support the request received from the client.

Invalid Offset (0x0407)

Offset specified was past the end of the attribute

Insufficient Authorization (0x0408)

The attribute requires authorization before it can be read or written.

Prepare Queue Full (0x0409)

Too many prepare writes have been queueud

Attribute Not Found (0x040A)

No attribute found within the given attribute handle range.

Attribute Not Long (0x040B)

The attribute cannot be read or written using the Read Blob Request

Insufficient Encryption Key Size (0x040C)

The Encryption Key Size used for encrypting this link is insufficient.

Invalid Attribute Value Length (0x040D)

The attribute value length is invalid for the operation

Unlikely Error (0x040E)

The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested.

Insufficient Encryption (0x040F)

The attribute requires encryption before it can be read or written.

Unsupported Group Type (0x0410)

The attribute type is not a supported grouping attribute as defined by a higher layer specification.

Insufficient Resources (0x0411)

Insufficient Resources to complete the request

Copyright 2001-2012 Bluegiga Technologies

Page 193 of 195

Application Error Codes (0x0480)

Application error code defined by a higher layer specification.

Copyright 2001-2012 Bluegiga Technologies

Page 194 of 195

6 Contact information
Sales: [email protected]

Technical support:

[email protected] http://techforum.bluegiga.com

Orders:

[email protected]

WWW:

http://www.bluegiga.com http://www.bluegiga.hk

Head Office / Finland:

Phone: +358-9-4355 060 Fax: +358-9-4355 0660 Sinikalliontie 5 A 02630 ESPOO FINLAND

Head address / Finland:

P.O. Box 120 02631 ESPOO FINLAND

Sales Office / USA:

Phone: +1 770 291 2181 Fax: +1 770 291 2183 Bluegiga Technologies, Inc. 3235 Satellite Boulevard, Building 400, Suite 300 Duluth, GA, 30096, USA

Sales Office / Hong-Kong: Phone: +852 3182 7321 Fax: +852 3972 5777 Bluegiga Technologies, Inc. 19/F Silver Fortune Plaza, 1 Wellington Street, Central Hong Kong

Copyright 2001-2012 Bluegiga Technologies

Page 195 of 195