BLUEGIGA BLUETOOTH SMART READY STACK API REFERENCE Wednesday, 20 May 2015 Document Version: 1.0 Copyright © Silicon Labs All rights reserved. Silicon Labs assumes no liability or responsibility for any errors, mistakes or inaccuracies in content. Silicon Labs reserves the right to change products or specifications without notice, and does not make any commitment to update the information herein. Silicon Labs’ products are not authorized for use as critical components in life support devices or systems. The Bluetooth® word mark and logos are registered trademarks owned by the Bluetooth® SIG, Inc. USA. All other trademarks and trade names listed herein belong to their respective owners. Information is subject to change without notice. Bluegiga – A Silicon Labs Company Table of Contents 1. Introduction ................................................................................................................................................... 2 2. The Bluegiga Bluetooth Smart Ready Software ........................................................................................... 3 2.1. The Bluegiga Bluetooth Smart Ready Stack .............................................................................................. 3 2.2. The Bluegiga Bluetooth Smart Ready SDK................................................................................................ 4 2.3. The BGAPI™ serial protocol API ............................................................................................................... 4 2.4. The BGLIB™ Host Library.......................................................................................................................... 5 2.5. The BGScript™ Scripting Language .......................................................................................................... 6 2.6. BGAPI™ vs. BGScript™ ............................................................................................................................ 8 2.7. Profile Toolkit™ .......................................................................................................................................... 8 2.8. BGBuild compiler........................................................................................................................................ 9 2.9. DFU tools ................................................................................................................................................... 9 2.10. BGTool test application............................................................................................................................. 9 3. Features of the Bluetooth Smart Ready Stack ........................................................................................... 11 4. API Reference ............................................................................................................................................. 12 4.1. Connection management for classic BT (bt_connection) ......................................................................... 13 4.2. Generic Access Profile, Classic (bt_gap) ................................................................................................. 27 4.3. Rfcommm (bt_rfcomm)............................................................................................................................. 48 4.4. Service Discovery Profile (bt_sdp) ........................................................................................................... 55 4.5. Device Firmware Upgrade (dfu) ............................................................................................................... 60 4.6. Endpoint (endpoint) .................................................................................................................................. 67 4.7. Persistent Store (flash) ............................................................................................................................. 83 4.8. Generic Attribute Profile (gatt) .................................................................................................................. 90 4.9. Generic Attribute Profile Server (gatt_server) ........................................................................................ 130 4.10. Hardware (hardware) ........................................................................................................................... 145 4.11. Identity Profile (identity) ........................................................................................................................ 163 4.12. Connection management for low energy (le_connection) .................................................................... 167 4.13. Generic Access Profile, Low Energy (le_gap) ...................................................................................... 174 4.14. Security Manager (sm) ......................................................................................................................... 194 4.15. System (system)................................................................................................................................... 218 4.16. testing commands (test) ....................................................................................................................... 231 4.17. Utilities for BGScript (util) ..................................................................................................................... 235 4.18. Error codes ........................................................................................................................................... 237 1 1. Introduction This document contains the API reference for the Bluegiga Bluetooth Smart Ready Software stack. The document describes the BGAPI serial protocol API, the BGLIB C API and also the BGScript scripting API. This document also contains a brief introduction of the Bluegiga Bluetooth Smart software, the SDK, all the available APIs and tools. 2 2. The Bluegiga Bluetooth Smart Ready Software This section contains a short description of the Bluegiga Bluetooth Smart Ready software, the components, APIs and the tools it includes. 2.1. The Bluegiga Bluetooth Smart Ready Stack The main components of the Bluegiga Bluetooth Smart Ready and stack are shown in the figure below. The figure shows the layers the Bluetooth Smart Ready stack as well also shows the APIs that can be used to interface to the Bluegiga Bluetooth Smart Stack. Key features of the Bluegiga Bluetooth Smart Ready stack include: • Bluetooth 4.1 Smart Ready compatible ◦ Bluetooth GAP and Security Manager ◦ Bluetooth SPP and Apple iAP profiles ◦ GATT over BR profile ◦ Any GATT based Bluetooth Smart profile 3 • High performance features ◦ 6 simultaneous BR/EDR connections ◦ 7 simultaneous LE connections ◦ 1 x BR/EDR and 7x BLE connections simultaneously ◦ Up to 1 Mbps throughput over SPP ◦ Up to 150 kbps throughput over iAP2 2.2. The Bluegiga Bluetooth Smart Ready SDK The Bluegiga Bluetooth Smart Ready SDK is a software development kit, which enables the device and software vendors to develop applications on top of the Bluegiga's Bluetooth Smart Ready hardware and stack software. The Bluetooth Smart Ready SDK supports multiple development models and the application developers can decide whether the application software runs on a separate host (a low power MCU) or whether they want to make fully standalone devices and execute their code on the MCU embedded in the Bluegiga Bluetooth Smart Ready modules. The SDK also contains documentation, tools for compiling the firmware, installing it into the hardware and lot of example applications speeding up the development process. The Bluegiga Bluetooth Smart Ready SDK includes the following APIs, components and tools: • The Bluetooth Smart Ready stack as described in the previous chapter. • BGAPI™ is a binary serial protocol API to the Bluegiga Bluetooth Smart Ready stack over UART or SPI interfaces. BGAPI is target for users, who want to use both Bluetooth BR/EDR and LE functionality and use all the features in the Bluetooth Smart Ready stack form an external host such as a low power MCU. • BGLIB™ is a host library for external MCUs and implements a reference parser for the BGAPI serial protocol. BGLIB is delivered in C source code as part of the Bluetooth Smart Ready SDK and it can be easily ported to various processor architectures. • BGScript™ interpreter and scripting language allow applications to be developed into the Bluetooth Smart Ready modules built-in MCU. It allows simple end user applications or enhanced functionality to be developed directly into the Bluetooth Smart Ready module which means no external host MCU is necessarily needed. BGScript applications can be executed at the same time as the BGAPI is used, allowing the possibility to implement some functionality on the Bluetooth module and some on the host. • Profile Toolkit™ is a simple XML based description language which can be used to easily and quickly develop GATT based service and characteristic databases for the Bluetooth Smart module. • BGBuild compiler is a free-of-charge compiler that compiles the Bluetooth Smart Ready Stack, the BGScript application and the Bluetooth GATT services into the firmware binary that can be installed to the Bluetooth Smart Ready modules. • BGTool is a graphical user interface application and a developer tool, which allows the Bluetooth smart module to be controller over the host interface using the BGAPI serial protocol. BGTool is a useful tool for testing the Bluetooth Smart module and evaluating it's functionality and APIs. • DFU Tools are also included as part of the SDK allowing the firmware to be updated over the UART and SPI interfaces. 2.3. The BGAPI™ serial protocol API The BGAPI is a serial protocol allows external hosts to interface to the Bluetooth Smart Ready modules over UART or SPI interfaces. The BGAPI serial protocol is a lightweight and well defined binary protocol which allows command and data to be sent to the Bluetooth Smart Ready module and it also provides a way to receive responses and events and data from the module. 4 The BGAPI provides access to the following layers in the Bluetooth Smart Stack: • BT GAP - BT GAP provides access to basic Bluetooth BR/EDR features, like device discovery and connection establishment. • LE GAP - LE GAP provides access to basic Bluetooth LE features, like device advertisement, discovery and connection establishment. • Security manager - Security manager is used to configure the local devices security features and establish secure connections • RFCOMM - RFCOMM provides basic serial data transmission over Bluetooth RD/EDR. • iAP - iAP provides basic serial data transmission to Apple iOS devices using Bluetooth BR/EDR. iAP is only available to Apple MFI licenses and not included in the standard SDK. • Hardware - Access to local hardware features and interfaces like SPI, I2C, GPIO and ADC • Persistent Store - A data storage that allows data to be stored to and read from the internal flash • System - Local device's status and management functions 2.4. The BGLIB™ Host Library The BGLIB host library is a reference implementation of the BGAPI serial protocol parser and it's provided in an ANSI C source code in the Bluetooth Smart Ready SDK. It abstracts the complexity of the BGAPI serial protocol and instead provides high level C functions and call-back handlers to the application developer, which makes the application development easier and faster. The BGLIB library can be ported to various host systems ranging from low cost MCUs to devices running Linux, Windows or OSX. 5 2.5. The BGScript™ Scripting Language BGScript is a simple BASIC-style programming language that allows end-user applications to be embedded to the Bluegiga Bluetooth Smart Ready modules. Although being a simple and easy-to-learn programming language BGScript does provide features and functions to create fairly complex and powerful applications and it provides access to all the same APIs as the BGAPI serial protocol. BGScript is fully event based programming language and code execution is started when events such as system start-up, Bluetooth connection, I/O interrupt etc. occur. BGScript applications are developed with Bluegiga's free-of-charge Bluetooth Smart Ready SDK and the BGScript applications are executed in the BGScript Virtual Machine (VM) that is part of the Bluegiga Bluetooth Smart Ready software. The Bluetooth Smart Ready SDK comes with all the necessary tools for code editing and compilation and also the needed tools for installing the complied firmware binary to the Bluegiga Bluetooth Smart Ready modules. BGScript applications can also be used at the same time as BGAPI and they can be for example used to automate some simple actions. 6 7 2.6. BGAPI™ vs. BGScript™ This section describes the differences between using BGAPI and BGScript. In brief the difference is: • BGScript is our custom scripting language used for on-module applications. BGScript applications only run on Bluegiga modules and dongles. • BGAPI is a custom serial protocol used to externally control the modules over the host interface and BGLIB is an ANSI C reference implementation of the BGAPI serial protocol and only runs outside of our modules and dongles. So the main difference between BGScript and BGLIB is that BGScript allows you to run an application right on the Bluetooth module, whereas BGLIB uses the BGAPI serial protocol API to send commands and receive events from an external device - typically a microcontroller. Note however that BGScript and BGLIB implement the exact same functionality. Every BGScript command, response, and event has a counterpart in the BGAPI serial protocol and BGLIB host library. One other thing to keep in mind is that BGScript has some performance penalties compared to external API control due to the fact that BGScript is an interpreted scripting language and requires extra overhead in order to use. It makes the Bluetooth module do the work that could otherwise be done elsewhere. If you are trying to achieve maximum performance or you have an application which is fairly complex (lots of fast timers, interrupts, or communicating with many external sensors over I2C or SPI for example), it is often a good idea to use a small external microcontroller and BGLIB/BGAPI instead. Question BGAPI™ BGScript™ An external host needed? Yes No Host interface UART or SPI** No separate host needed Bluetooth API BGAPI or BGLIB APIs BGScript API Peripheral interface APIs and support Host dependent (* APIs for UART, SPI, I2C, GPIO, ADC and PS store Custom peripheral interface drivers Can be developed to the host Peripheral drivers are part of the Bluegiga Bluetooth Smart Ready stack RAM available for application Host dependent TBD Flash available for application Host dependent (** 0 - 24kB Execution speed Host dependent TBD Application development SDK Host dependent + BGAPI and BGLIB Bluetooth firmware / application updates DFU over UART or SPI** Bluegiga Bluetooth Smart Ready SDK DFU over UART or SPI** *) The Bluetooth Smart modules peripheral interfaces are still available via BGAPI commands and can be used to extend the host MCUs I/Os. **) Check SPI host interface support status. 2.7. Profile Toolkit™ The Bluetooth Smart profile toolkit is a simple set of tools, which can used to describe GATT based service and characteristic databases used with Bluetooth Smart and GATT over BR profiles. The profile toolkit consists of a simple XML based description language and templates, which can be used to describe the services and characteristics and their properties in a devices GATT database. 8 The GATT database developed with the Profile Toolkit is included as part of the devices firmware when the firmware is compiled. 2.8. BGBuild compiler BGBUILD compiler is a simple compiler that is used to build a firmware images for the Bluetooth Smart Ready modules. The BGBuild compiler compiles the Bluetooth Smart Ready stack, the GATT database and optionally also a BGScript application into a single firmware binary image that can be installed into a Bluetooth Smart Module. 2.9. DFU tools The Device Firmware Update (DFU) protocol is an open serial protocol that can be used to perform field updates to the Bluetooth Smart Ready modules. DFU protocol allows any firmware image generated with the BGBuild compiler to be installed into a Bluetooth Smart Module. The Bluetooth Smart Ready SDK contains command line binaries versions and source code for the DFU protocol and tools. DFU protocol and available commands are described in the API reference document. 2.10. BGTool test application BGTool application can be used to test and evaluate the Bluetooth Smart module and issue BGAPI commands to it over UART host interface. It's a useful tool for testing the Bluetooth module and its functionality. 9 10 3. Features of the Bluetooth Smart Ready Stack Feature Value Simultaneous BR/EDR connections 6 Simultaneous LE connectons 7 Combined BR/EDR and LE connections 1 x BR/EDR + 7 x LE MAX data rate 1000 kbps SPP (transparent mode) 570 kbps SPP (BGAPI mode) 150 kbps iAP2 (both transparent and BGAPI mode) MAX UART baud rate 4 000 000 bps Data transmission delay over BR TBD Supported encryptions E0 for Bluetooth BR/EDR (128-bit) AES-128 for Bluetooth LE MAX simultaneous pairings MAX Friendly name length L2CAP packet size Supported Bluetooth BR/EDR profiles Supported Bluetooth LE profiles Apple iAP support Supported power saving modes Bluetooth QD ID Secure Simple Pairing modes 32 Configurable up to 30 characters 255 bytes GAP, SPP, DI and GATT over BR Any with profile toolkit iAP2 (Devices with lightning connector) Sniff mode, slave latency and two MCU sleep modes TBA Just works mode Man-in-the-middle protection (MITM) 11 4. API Reference 12 4.1. Connection management for classic BT (bt_connection) Commands and events in this class are related to Bluetooth BR/EDR connection management and provide the means to open, close and monitor Bluetooth BR/EDR connections. 4.1.1. bt_connection commands 4.1.1.1. bt_connection_list This command can be used to list all RFCOMM connections. Command Byte Type Name 0 1 2 0x20 0x00 0x07 hilen lolen class 3 0x00 method Description Message type: Command Minimum payload length Message class:Connection management for classic BT Message ID Response Byte Type Name 0 1 2 0x20 0x02 0x07 hilen lolen class 3 4-5 0x00 uint16 method result Description Message type: Response Minimum payload length Message class:Connection management for classic BT Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_connection_list()(result) 13 BGLIB C API /* Function */ void dumo_cmd_bt_connection_list(); /* Callback */ struct dumo_msg_bt_connection_list_rsp_t { uint16 result } void dumo_rsp_bt_connection_list( const struct dumo_msg_bt_connection_list_rsp_t *msg ) 14 4.1.1.2. bt_connection_set_active This command can be used to set connection state active. Command Byte Type Name 0 1 2 0x20 0x01 0x07 hilen lolen class 3 4 0x01 uint8 method endpoint Description Message type: Command Minimum payload length Message class:Connection management for classic BT Message ID Bluetooth connection endpoint handle Response Byte Type Name 0 1 2 0x20 0x02 0x07 hilen lolen class 3 4-5 0x01 uint16 method result Description Message type: Response Minimum payload length Message class:Connection management for classic BT Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_connection_set_active(endpoint)(result) BGLIB C API /* Function */ void dumo_cmd_bt_connection_set_active(uint8 endpoint); /* Callback */ struct dumo_msg_bt_connection_set_active_rsp_t { uint16 result } void dumo_rsp_bt_connection_set_active( const struct dumo_msg_bt_connection_set_active_rsp_t *msg ) 15 4.1.1.3. bt_connection_set_role This command can be used to set the Bluetooth connection role. Command Byte Type Name 0 1 2 0x20 0x02 0x07 hilen lolen class 3 4 5 0x03 uint8 uint8 method endpoint role Description Message type: Command Minimum payload length Message class:Connection management for classic BT Message ID Bluetooth connection endpoint handle Bluetooth connection role Values see link Response Byte Type Name 0 1 2 0x20 0x02 0x07 hilen lolen class 3 4-5 0x03 uint16 method result Description Message type: Response Minimum payload length Message class:Connection management for classic BT Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_connection_set_role(endpoint, role)(result) BGLIB C API /* Function */ void dumo_cmd_bt_connection_set_role(uint8 endpoint, uint8 role); /* Callback */ struct dumo_msg_bt_connection_set_role_rsp_t { uint16 result } void dumo_rsp_bt_connection_set_role( const struct dumo_msg_bt_connection_set_role_rsp_t *msg ) 16 4.1.1.4. bt_connection_set_sniff This command can be used to set the sniff parameters for a connection. Please see BLUETOOTH SPECIFICATION Version 4.1 [Vol 2] Part E chapter 7.2.2 for more information regarding the use of the related parameters. Command Byte Type Name 0 1 2 0x20 0x09 0x07 hilen lolen class 3 4 5-6 0x02 uint8 uint16 method endpoint max Description Message type: Command Minimum payload length Message class:Connection management for classic BT Message ID Bluetooth connection endpoint handle Maximum sniff interval. Range: 0x04 to 0xfffe Only even values are valid 7-8 uint16 Sniff interval = 0.625ms x max Time range 2.5 ms to 40959 ms Minimum sniff interval. min Range: 0x02 to 0xfffe Only even values are valid 9-10 11-12 uint16 uint16 Sniff interval = 0.625ms x max Time range 1.25 ms to 40959 ms Number of baseband receive slots for sniff attempt. attemp timeout Range: 0x01 to 0x7fff Time range 0.625 ms to 40959 ms Number of baseband receive slots for sniff timeout. Range: 0x00 to 0x7fff Time range 0.0 ms to 40959 ms: 17 Response Byte Type Name 0 1 2 0x20 0x02 0x07 hilen lolen class 3 4-5 0x02 uint16 method result Description Message type: Response Minimum payload length Message class:Connection management for classic BT Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_connection_set_sniff(endpoint, max, min, attemp, timeout)(result) BGLIB C API /* Function */ void dumo_cmd_bt_connection_set_sniff(uint8 endpoint, uint16 max, uint16 min, uint16 attemp, uint16 timeout); /* Callback */ struct dumo_msg_bt_connection_set_sniff_rsp_t { uint16 result } void dumo_rsp_bt_connection_set_sniff( const struct dumo_msg_bt_connection_set_sniff_rsp_t *msg ) 18 4.1.2. bt_connection events 4.1.2.1. bt_connection_opened This event indicates that a new connection is opened. Event 0 1 2 Byte 0xa0 0x09 0x07 hilen lolen class 3 4-9 0x00 bd_addr method address 10 uint8 master Description Message type: Event Minimum payload length Message class:Connection management for classic BT Message ID Bluetooth address of the remote device in little endian formats Bluetooth role of the local device connection bonding Values 1: master Bluetooth connection handle Bonding handle of the remote device 11 12 Type uint8 uint8 Name 0xff: no bonding Other: Bonding handle BGScript event event bt_connection_opened(address,master,connection,bonding) C Functions /* Callback */ struct dumo_msg_bt_connection_opened_evt_t { bd_addr address, uint8 master, uint8 connection, uint8 bonding } void dumo_evt_bt_connection_opened( const struct dumo_msg_bt_connection_opened_evt_t *msg ) 19 4.1.2.2. bt_connection_closed This event indicates that a connection is closed. Event Byte Type Name 0 1 2 0xa0 0x03 0x07 hilen lolen class 3 4-5 0x01 uint16 method reason Description Message type: Event Minimum payload length Message class:Connection management for classic BT Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 connection For other values refer to the Error codes Bluetooth connection handle BGScript event event bt_connection_closed(reason,connection) C Functions /* Callback */ struct dumo_msg_bt_connection_closed_evt_t { uint16 reason, uint8 connection } void dumo_evt_bt_connection_closed( const struct dumo_msg_bt_connection_closed_evt_t *msg ) 20 4.1.2.3. bt_connection_parameters This event indicates details of a single RFCOMM connection. Event Byte Type Name 0 1 2 0xa0 0x14 0x07 hilen lolen class 3 4-7 8 9 10-15 0x02 uint32 uint8 uint8 bd_addr method block_size local_msc remote_msc address 16 uint8 direction 17 uint8 powermode 18 uint8 role 19 20-23 uint8 uint32 encryption input_buffer Description Message type: Event Minimum payload length Message class:Connection management for classic BT Message ID Size of single packet over RFCOMM Bit mask for MSC at local device Bit mask for MSC at remote device Bluetooth address of remote device in little endian format Direction of connection see link for values Powermode of connection see link for values Role in the connection see link for values Amount of data in RFCOMM receive buffer BGScript event event bt_connection_parameters(block_size,local_msc,remote_msc,address,direction,powermode,role, C Functions /* Callback */ struct dumo_msg_bt_connection_parameters_evt_t { uint32 block_size, uint8 local_msc, uint8 remote_msc, bd_addr address, uint8 direction, uint8 powermode, uint8 role, uint8 encryption, uint32 input_buffer } void dumo_evt_bt_connection_parameters( const struct dumo_msg_bt_connection_parameters_evt_t *msg ) 21 4.1.2.4. bt_connection_list_complete This event indicates that all connections have been listed Event Byte Type Name 0 1 2 0xa0 0x00 0x07 hilen lolen class 3 0x03 method Description Message type: Event Minimum payload length Message class:Connection management for classic BT Message ID BGScript event event bt_connection_list_complete() C Functions /* Callback */ struct dumo_msg_bt_connection_list_complete_evt_t { } void dumo_evt_bt_connection_list_complete( const struct dumo_msg_bt_connection_list_complete_evt_t *msg ) 22 4.1.3. bt_connection enumerations 4.1.3.1. bt_connection_direction These values indicate the direction of the connection Enumerations Value 0 1 Name bt_connection_outgoing bt_connection_incoming 23 Description outgoing incoming 4.1.3.2. bt_connection_powermode power mode of a connection Enumerations Value 0 2 Name bt_connection_active bt_connection_sniff 24 Description active sniff 4.1.3.3. bt_connection_role These values indicate the connection role of the local device. Enumerations Value 0 1 Name bt_connection_master bt_connection_slave 25 Description master slave 4.1.3.4. bt_connection_encryption These values indicate the encryption status of the connection. Enumerations Value 0 1 Name bt_connection_encrypted bt_connection_plain 26 Description encrypted plain 4.2. Generic Access Profile, Classic (bt_gap) Generic Access Profile for Classic Bluetooth 4.2.1. bt_gap commands 4.2.1.1. bt_gap_cancel_discovery This command cancels the ongoing device discovery (inquiry) procedure. Command Byte Type Name 0 1 2 0x20 0x00 0x02 hilen lolen class 3 0x01 method Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Response Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4-5 0x01 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_gap_cancel_discovery()(result) 27 BGLIB C API /* Function */ void dumo_cmd_bt_gap_cancel_discovery(); /* Callback */ struct dumo_msg_bt_gap_cancel_discovery_rsp_t { uint16 result } void dumo_rsp_bt_gap_cancel_discovery( const struct dumo_msg_bt_gap_cancel_discovery_rsp_t *msg ) Events generated Event Description 28 4.2.1.2. bt_gap_discover This command can be used to find other Bluetooth devices in the area i.e. to make a device discovery. This command utilizes the Inquiry procedure. Command Byte Type Name 0 1 2 0x20 0x05 0x02 hilen lolen class 3 4 0x00 uint8 method timeout Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID The maximum amount of time (in units of 1.28 seconds) before the inquiry process is halted. Range: 1 to 48. 5-8 int32 Example: Value 5 corresponds to 5 x 1.28 seconds = 6.4 seconds. Flag which select whether to seek only devices that are in general discovery mode (GIAC) or in limited discovery mode (LIAC). lap Response Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4-5 0x00 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_gap_discover(timeout, lap)(result) 29 BGLIB C API /* Function */ void dumo_cmd_bt_gap_discover(uint8 timeout, int32 lap); /* Callback */ struct dumo_msg_bt_gap_discover_rsp_t { uint16 result } void dumo_rsp_bt_gap_discover( const struct dumo_msg_bt_gap_discover_rsp_t *msg ) Events generated Event Description 30 4.2.1.3. bt_gap_get_mode This command can be used to read the device's Classic Bluetooth visibility and connectability settings. Command Byte Type Name 0 1 2 0x20 0x00 0x02 hilen lolen class 3 0x04 method Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Response Byte Type Name 0 1 2 0x20 0x05 0x02 hilen lolen class 3 4-5 0x04 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred 6 7 8 uint8 uint8 uint8 connectable discoverable For other values refer to the Error codes Informs whether the device accepts incoming connections or not Values 0: not connectable 1: connectable Informs whether the device is visible for inquiry Values: 0: not discoverable 1: discoverable Informs whether the device is visible only in limited mode inquiry(LIAC) or in general mode inquiry (GIAC) limited BGScript API call bt_gap_get_mode()(result, connectable, discoverable, limited) 31 BGLIB C API /* Function */ void dumo_cmd_bt_gap_get_mode(); /* Callback */ struct dumo_msg_bt_gap_get_mode_rsp_t { uint16 result, uint8 connectable, uint8 discoverable, uint8 limited } void dumo_rsp_bt_gap_get_mode( const struct dumo_msg_bt_gap_get_mode_rsp_t *msg ) 32 4.2.1.4. bt_gap_get_remote_name This command can be used to read the name of the remote device. Command Byte Type Name 0 1 2 0x20 0x06 0x02 hilen lolen class 3 4-9 0x02 bd_addr method address Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Bluetooth address of the remote device in little endian format Response Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4-5 0x02 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_gap_get_remote_name(address)(result) BGLIB C API /* Function */ void dumo_cmd_bt_gap_get_remote_name(bd_addr address); /* Callback */ struct dumo_msg_bt_gap_get_remote_name_rsp_t { uint16 result } void dumo_rsp_bt_gap_get_remote_name( const struct dumo_msg_bt_gap_get_remote_name_rsp_t *msg ) 33 4.2.1.5. bt_gap_open This command can be used to open a BR/EDR connection to a remote device. Command Byte Type Name 0 1 2 0x20 0x06 0x02 hilen lolen class 3 4-9 0x08 bd_addr method address Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Bluetooth address Response Byte Type Name 0 1 2 0x20 0x03 0x02 hilen lolen class 3 4-5 0x08 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 connection BGScript API call bt_gap_open(address)(result, connection) BGLIB C API /* Function */ void dumo_cmd_bt_gap_open(bd_addr address); /* Callback */ struct dumo_msg_bt_gap_open_rsp_t { uint16 result, uint8 connection } void dumo_rsp_bt_gap_open( const struct dumo_msg_bt_gap_open_rsp_t *msg ) 34 For other values refer to the Error codes Unique connection handle Events generated Event Description bt_connection_opened 35 4.2.1.6. bt_gap_set_max_power This command can be used to set the maximum TX power for Classic Bluetooth. Command Byte Type Name 0 1 2 0x20 0x01 0x02 hilen lolen class 3 4 0x07 int8 method max_power Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Maximum radio TX power Range: -20 to 12 Response Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4-5 0x07 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_gap_set_max_power(max_power)(result) BGLIB C API /* Function */ void dumo_cmd_bt_gap_set_max_power(int8 max_power); /* Callback */ struct dumo_msg_bt_gap_set_max_power_rsp_t { uint16 result } void dumo_rsp_bt_gap_set_max_power( const struct dumo_msg_bt_gap_set_max_power_rsp_t *msg ) 36 4.2.1.7. bt_gap_set_mode This command can be used to set Classic Bluetooth visibility and connectability. Command Byte Type Name 0 1 2 0x20 0x03 0x02 hilen lolen class 3 4 0x03 uint8 method connectable 5 uint8 6 discoverable uint8 Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Determines whether the device accepts incoming connections or not Values 0: not connectable 1: connectable Determines whether the device is visible for inquiry Values: 0: not discoverable 1: discoverable Determines whether the device is visible only in limited mode inquiry(LIAC) or in general mode inquiry (GIAC) limited Response Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4-5 0x03 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_gap_set_mode(connectable, discoverable, limited)(result) 37 BGLIB C API /* Function */ void dumo_cmd_bt_gap_set_mode(uint8 connectable, uint8 discoverable, uint8 limited); /* Callback */ struct dumo_msg_bt_gap_set_mode_rsp_t { uint16 result } void dumo_rsp_bt_gap_set_mode( const struct dumo_msg_bt_gap_set_mode_rsp_t *msg ) 38 4.2.1.8. bt_gap_set_parameters Set default pagetimeout and scan mode. Command Byte Type Name 0 1 2 0x20 0x06 0x02 hilen lolen class 3 4-5 0x06 uint16 method pagetimeout Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Page timeout defines how long the connection establishment can take before an error occurs. Value In multiples of 1.28 seconds. 6-7 uint16 scan_interval 8-9 uint16 scan_window Range: 1 - 65535 Page scan interval in multiples of 0.625ms, values from 0x12 to 0x1000 and only even numbers are allowed, see BT Core spec Vol. 2 part D chapter 7.3 Recommended value 0x800 Page scan Window in multiples of 0.625ms, values from 0x11 to 0x1000, must be less or equal to page scan interval. See BT Core spec Vol. 2 part D chapter 7.3 Recommended value 0x800 Response Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4-5 0x06 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_gap_set_parameters(pagetimeout, scan_interval, scan_window)(result) 39 BGLIB C API /* Function */ void dumo_cmd_bt_gap_set_parameters(uint16 pagetimeout, uint16 scan_interval, uint16 scan_window); /* Callback */ struct dumo_msg_bt_gap_set_parameters_rsp_t { uint16 result } void dumo_rsp_bt_gap_set_parameters( const struct dumo_msg_bt_gap_set_parameters_rsp_t *msg ) 40 4.2.1.9. bt_gap_set_policy This command can be used to set default policies for connections. For more information on the use of policies please BLUETOOTH SPECIFICATION Version 4.1 [Vol 2] Part E chapter 7.2.10. Command Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4 0x05 uint8 method allow_role_change 5 uint8 allow_sniff Description Message type: Command Minimum payload length Message class:Generic Access Profile, Classic Message ID Defines if the local device accepts role change requests or not Values 0: Do not allow role change 1: Allow role change This flag defines whether sniff mode is allowed or not Values 0: Do not allow sniff mode 1: Allow sniff mode Response Byte Type Name 0 1 2 0x20 0x02 0x02 hilen lolen class 3 4-5 0x05 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_gap_set_policy(allow_role_change, allow_sniff)(result) 41 BGLIB C API /* Function */ void dumo_cmd_bt_gap_set_policy(uint8 allow_role_change, uint8 allow_sniff); /* Callback */ struct dumo_msg_bt_gap_set_policy_rsp_t { uint16 result } void dumo_rsp_bt_gap_set_policy( const struct dumo_msg_bt_gap_set_policy_rsp_t *msg ) 42 4.2.2. bt_gap events 4.2.2.1. bt_gap_discovery_result Discovery result for a single remote device Event Byte Type 0 1 2 0xa0 0x0e 0x02 3 4-9 0x00 bd_addr 10 uint8 11-14 15 uint32 int8 Name Description Message type: Event Minimum payload length Message class:Generic Access Profile, Classic method Message ID bd_addr Bluetooth address of the discovered device in little endian format page_scan_repetition_mode Remote devices page scan repetition mode class_of_device Class of Device for the device rssi RSSI value of the connection hilen lolen class Range: -127 to +20 16 17 uint8 uint8array bonding Units: dBm Remove devices bonding handle Values 0xff: Device is not bonded Others: Bonding handlee Remote devices Bluetooth BR/ EDR friendly name parsed from the EIR data name BGScript event event bt_gap_discovery_result(bd_addr,page_scan_repetition_mode,class_of_device,rssi,bonding,nam 43 C Functions /* Callback */ struct dumo_msg_bt_gap_discovery_result_evt_t { bd_addr bd_addr, uint8 page_scan_repetition_mode, uint32 class_of_device, int8 rssi, uint8 bonding, uint8 name_len, const uint8* name_data } void dumo_evt_bt_gap_discovery_result( const struct dumo_msg_bt_gap_discovery_result_evt_t *msg ) 44 4.2.2.2. bt_gap_discovery_complete This event indicates that discovery has been completed Event Byte Type Name 0 1 2 0xa0 0x02 0x02 hilen lolen class 3 4-5 0x01 uint16 method status Description Message type: Event Minimum payload length Message class:Generic Access Profile, Classic Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript event event bt_gap_discovery_complete(status) C Functions /* Callback */ struct dumo_msg_bt_gap_discovery_complete_evt_t { uint16 status } void dumo_evt_bt_gap_discovery_complete( const struct dumo_msg_bt_gap_discovery_complete_evt_t *msg ) 45 4.2.2.3. bt_gap_remote_name This event indicates a reply to a remote name request. Event Byte Type Name 0 1 2 0xa0 0x07 0x02 hilen lolen class 3 4-9 0x02 bd_addr method address 10 uint8array remote_name Description Message type: Event Minimum payload length Message class:Generic Access Profile, Classic Message ID Bluetooth address of the remote device in little endian format Name of the remote device BGScript event event bt_gap_remote_name(address,remote_name_len,remote_name_data) C Functions /* Callback */ struct dumo_msg_bt_gap_remote_name_evt_t { bd_addr address, uint8 remote_name_len, const uint8* remote_name_data } void dumo_evt_bt_gap_remote_name( const struct dumo_msg_bt_gap_remote_name_evt_t *msg ) 46 4.2.3. bt_gap enumerations 4.2.3.1. bt_gap_discover_mode GAP Discoverable modes Enumerations 1 Value Name bt_gap_discover_limited 2 bt_gap_discover_generic Description Discover only devices which are in limited discoverable mode Discover devices which are in general discoverable mode. 47 4.3. Rfcommm (bt_rfcomm) Rfcomm connections 4.3.1. bt_rfcomm commands 4.3.1.1. bt_rfcomm_open Open RFCOMM channel to remote device Command Byte Type 0 1 2 3 4-9 0x20 0x08 0x04 0x00 bd_addr 10 uint8 11 uint8array Name Description Message type: Command Minimum payload length Message class:Rfcommm Message ID Bluetooth device address of the remote device in little endian format streaming_destination Streaming destination for connection endpoint uuid UUID of the profile to connect to: hilen lolen class method address uuid16, 2 bytes 16-bit UUID for searching RFCOMM port uuid32, 4 bytes 32-bit UUID for searching RFCOMM port uuid128, 16 bytes 128-bit UUID for searching RFCOMM port Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x04 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Rfcommm Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 endpoint 48 For other values refer to the Error codes Unsigned 8bit integer BGScript API call bt_rfcomm_open(address, streaming_destination, uuid_len, uuid_data)(result, endpoint) BGLIB C API /* Function */ void dumo_cmd_bt_rfcomm_open(bd_addr address, uint8 streaming_destination, uint8 uuid_len, const uint8 *uuid_data); /* Callback */ struct dumo_msg_bt_rfcomm_open_rsp_t { uint16 result, uint8 endpoint } void dumo_rsp_bt_rfcomm_open( const struct dumo_msg_bt_rfcomm_open_rsp_t *msg ) Events generated Event Description bt_rfcomm_opened 49 4.3.1.2. bt_rfcomm_open_port This command can be used to open a RFCOMM channel to a remote device using a fixed RFCOMM port. Command Byte Type 0 1 2 3 4-9 0x20 0x08 0x04 0x02 bd_addr 10 uint8 11 uint8 Name Description hilen Message type: Command lolen Minimum payload length class Message class:Rfcommm method Message ID address Bluetooth device address of the remote device in little endian format streaming_destination Streaming destination for connection endpoint Endpoint can be one of the fixed endpoints or one of the dynamic endpoints for example another RFCOMM endpoint. RFCOMM port port Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x04 0x02 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Rfcommm Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 endpoint For other values refer to the Error codes Unsigned 8bit integer BGScript API call bt_rfcomm_open_port(address, streaming_destination, port)(result, endpoint) 50 BGLIB C API /* Function */ void dumo_cmd_bt_rfcomm_open_port(bd_addr address, uint8 streaming_destination, uint8 port); /* Callback */ struct dumo_msg_bt_rfcomm_open_port_rsp_t { uint16 result, uint8 endpoint } void dumo_rsp_bt_rfcomm_open_port( const struct dumo_msg_bt_rfcomm_open_port_rsp_t *msg ) 51 4.3.1.3. bt_rfcomm_start_server This command can be used to start a RFCOMM server as defined by the referenced XML file. Command Byte 0 1 2 3 4 Type 0x20 0x03 0x04 0x01 uint8 Name hilen lolen class method channel Description Message type: Command Minimum payload length Message class:Rfcommm Message ID RFCOMM channel assigned for the SPP service. Must match the RFCOMM channel defined in SDP entry. 5 uint8 6 uint8 See Bluetooth Smart Ready Configuration Guide for details. sdp_id ID of SDP entry defined in project configuration file streaming_destination Streaming destination for connection endpoint Endpoint can be one of the fixed endpoints. Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x04 0x01 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Rfcommm Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_rfcomm_start_server(channel, sdp_id, streaming_destination)(result) 52 BGLIB C API /* Function */ void dumo_cmd_bt_rfcomm_start_server(uint8 channel, uint8 sdp_id, uint8 streaming_destination); /* Callback */ struct dumo_msg_bt_rfcomm_start_server_rsp_t { uint16 result } void dumo_rsp_bt_rfcomm_start_server( const struct dumo_msg_bt_rfcomm_start_server_rsp_t *msg ) 53 4.3.2. bt_rfcomm events 4.3.2.1. bt_rfcomm_opened This event indicates establishment of RFCOMM connection. Event 0 1 2 3 4 Byte 0xa0 0x07 0x04 0x00 uint8 Type Name hilen lolen class method endpoint 5-10 bd_addr address BGScript event event bt_rfcomm_opened(endpoint,address) C Functions /* Callback */ struct dumo_msg_bt_rfcomm_opened_evt_t { uint8 endpoint, bd_addr address } void dumo_evt_bt_rfcomm_opened( const struct dumo_msg_bt_rfcomm_opened_evt_t *msg ) 54 Description Message type: Event Minimum payload length Message class:Rfcommm Message ID Endpoint ID assigned for the RFCOMM connection Bluetooth device address of the remote device in little endian format. 4.4. Service Discovery Profile (bt_sdp) Service Discovery Profile related commands and events 4.4.1. bt_sdp commands 4.4.1.1. bt_sdp_load_entry This command can be used to load an SDP entry from internal filesystem to the SDP server. Command Byte Type Name 0 1 2 0x20 0x04 0x06 hilen lolen class 3 4-7 0x01 uint32 method sdp_id Description Message type: Command Minimum payload length Message class:Service Discovery Profile Message ID ID of SDP entry defined in the project configuration file See Bluetooth Smart Ready Configuration Guide for details Response Byte Type Name 0 1 2 0x20 0x02 0x06 hilen lolen class 3 4-5 0x01 uint16 method result Description Message type: Response Minimum payload length Message class:Service Discovery Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_sdp_load_entry(sdp_id)(result) 55 BGLIB C API /* Function */ void dumo_cmd_bt_sdp_load_entry(uint32 sdp_id); /* Callback */ struct dumo_msg_bt_sdp_load_entry_rsp_t { uint16 result } void dumo_rsp_bt_sdp_load_entry( const struct dumo_msg_bt_sdp_load_entry_rsp_t *msg ) 56 4.4.1.2. bt_sdp_search_rfcomm_port This command can be used to search for existing services in a Bluetooth device. The reply is an event specifying the RFCOMM port. Command Byte Type Name 0 1 2 0x20 0x07 0x06 hilen lolen class 3 4-9 0x00 bd_addr method address 10 uint8array uuid Description Message type: Command Minimum payload length Message class:Service Discovery Profile Message ID Bluetooth device address of the remote device in little endian format UUID is one of the following: uuid16, 2 bytes 16-bit UUID for searching RFCOMM port uuid32, 4 bytes 32-bit UUID for searching RFCOMM port uuid128, 16 bytes 128-bit UUID for searching service Response Byte Type Name 0 1 2 0x20 0x02 0x06 hilen lolen class 3 4-5 0x00 uint16 method result Description Message type: Response Minimum payload length Message class:Service Discovery Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call bt_sdp_search_rfcomm_port(address, uuid_len, uuid_data)(result) 57 BGLIB C API /* Function */ void dumo_cmd_bt_sdp_search_rfcomm_port(bd_addr address, uint8 uuid_len, const uint8 *uuid_data); /* Callback */ struct dumo_msg_bt_sdp_search_rfcomm_port_rsp_t { uint16 result } void dumo_rsp_bt_sdp_search_rfcomm_port( const struct dumo_msg_bt_sdp_search_rfcomm_port_rsp_t *msg ) 58 4.4.2. bt_sdp events 4.4.2.1. bt_sdp_search_rfcomm_port This event indicates the SDP search result. Event Byte Type Name 0 1 2 0xa0 0x08 0x06 hilen lolen class 3 4-7 8-9 0x00 uint32 uint16 method request_handle status Description Message type: Event Minimum payload length Message class:Service Discovery Profile Message ID NOT IN USE Result code 0 : success Non-zero : an error occurred 10 11 uint8 uint8array port service_name For other values refer to the Error codes RFCOMM port number RFCOMM service name BGScript event event bt_sdp_search_rfcomm_port(request_handle,status,port,service_name_len,service_name_data) C Functions /* Callback */ struct dumo_msg_bt_sdp_search_rfcomm_port_evt_t { uint32 request_handle, uint16 status, uint8 port, uint8 service_name_len, const uint8* service_name_data } void dumo_evt_bt_sdp_search_rfcomm_port( const struct dumo_msg_bt_sdp_search_rfcomm_port_evt_t *msg ) 59 4.5. Device Firmware Upgrade (dfu) DFU class commands can be used to perform a firmware update. The commands and events are only available when the module has been booted into DFU mode. The DFU process: 1. 2. 3. 4. 5. 6. Boot device to DFU mode with DFU reset command Wait for DFU boot event Send command Flash Set Address to start the firmware update Upload the firmware with Flash Upload commands until all the data has been uploaded Send Flash Upload Finish to when all the data has been uploaded Finalize the DFU firmware update with Reset command. 4.5.1. dfu commands 4.5.1.1. dfu_flash_set_address After re-booting the local device into DFU mode, this command can be used to define the starting address on the flash where the new firmware will be written in. Command Byte Type Name 0 1 2 0x20 0x04 0x00 hilen lolen class 3 4-7 0x01 uint32 method address Description Message type: Command Minimum payload length Message class:Device Firmware Upgrade Message ID The offset in the flash where the new firmware is uploaded to. Values Always use the value 0x0000 Response Byte Type Name 0 1 2 0x20 0x02 0x00 hilen lolen class 3 4-5 0x01 uint16 method result Description Message type: Response Minimum payload length Message class:Device Firmware Upgrade Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes 60 BGScript API call dfu_flash_set_address(address)(result) BGLIB C API /* Function */ void dumo_cmd_dfu_flash_set_address(uint32 address); /* Callback */ struct dumo_msg_dfu_flash_set_address_rsp_t { uint16 result } void dumo_rsp_dfu_flash_set_address( const struct dumo_msg_dfu_flash_set_address_rsp_t *msg ) 61 4.5.1.2. dfu_flash_upload This command us used to upload the firmware update file to the Wi-Fi Module. The payload of the data is 128 bytes, so multiple commands need to be used to upload the full firmware update file. Command Byte Type Name 0 1 2 0x20 0x01 0x00 hilen lolen class 3 4 0x02 uint8array method data Description Message type: Command Minimum payload length Message class:Device Firmware Upgrade Message ID An array of data upto 128 bytes which will be written into the flash. Response Byte Type Name 0 1 2 0x20 0x02 0x00 hilen lolen class 3 4-5 0x02 uint16 method result Description Message type: Response Minimum payload length Message class:Device Firmware Upgrade Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call dfu_flash_upload(data_len, data_data)(result) BGLIB C API /* Function */ void dumo_cmd_dfu_flash_upload(uint8 data_len, const uint8 *data_data); /* Callback */ struct dumo_msg_dfu_flash_upload_rsp_t { uint16 result } void dumo_rsp_dfu_flash_upload( const struct dumo_msg_dfu_flash_upload_rsp_t *msg ) 62 4.5.1.3. dfu_flash_upload_finish This command can be used to tell to the device that the DFU file has been fully uploaded. To return the device back to normal mode the command DFU Reset must be issued next. Command Byte Type Name 0 1 2 0x20 0x00 0x00 hilen lolen class 3 0x03 method Description Message type: Command Minimum payload length Message class:Device Firmware Upgrade Message ID Response Byte Type Name 0 1 2 0x20 0x02 0x00 hilen lolen class 3 4-5 0x03 uint16 method result Description Message type: Response Minimum payload length Message class:Device Firmware Upgrade Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call dfu_flash_upload_finish()(result) BGLIB C API /* Function */ void dumo_cmd_dfu_flash_upload_finish(); /* Callback */ struct dumo_msg_dfu_flash_upload_finish_rsp_t { uint16 result } void dumo_rsp_dfu_flash_upload_finish( const struct dumo_msg_dfu_flash_upload_finish_rsp_t *msg ) 63 4.5.1.4. dfu_reset This command can be used to reset the system. This command does not have a response, but it triggers one of the boot events (normal reset or boot to DFU mode) after re-boot. Command Byte Type Name 0 1 2 0x20 0x01 0x00 hilen lolen class 3 4 0x00 uint8 method dfu Description Message type: Command Minimum payload length Message class:Device Firmware Upgrade Message ID Boot mode: 0:Normal reset 1:Boot to DFU mode C o m m a n d d o e s n o t h a v e r e s p o n s e BGScript API call dfu_reset(dfu) 64 BGLIB C API /* Function */ void dumo_cmd_dfu_reset(uint8 dfu); /* Command does not have callback */ Events generated Event Description system_boot Sent after the device has booted to normal mode dfu_boot Sent after the device has booted to DFU mode 65 4.5.2. dfu events 4.5.2.1. dfu_boot This event indicates that the module booted in DFU mode, and is now ready to receive commands related to device firmware upgade (DFU). Event Byte Type Name 0 1 2 0xa0 0x04 0x00 hilen lolen class 3 4-7 0x00 uint32 method version BGScript event event dfu_boot(version) C Functions /* Callback */ struct dumo_msg_dfu_boot_evt_t { uint32 version } void dumo_evt_dfu_boot( const struct dumo_msg_dfu_boot_evt_t *msg ) 66 Description Message type: Event Minimum payload length Message class:Device Firmware Upgrade Message ID The version of the bootloader 4.6. Endpoint (endpoint) Endpoint class functions provide the control of endpoints and allow them to be created and deleted and they also allow data routing configuration. 4.6.1. endpoint commands 4.6.1.1. endpoint_close This command can be used to close an endpoint. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0b 0x02 uint8 Name hilen lolen class method endpoint Description Message type: Command Minimum payload length Message class:Endpoint Message ID The index of the endpoint to close Endpoint index is provided by events which indicate Bluetooth connection establishment. Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x0b 0x02 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 endpoint BGScript API call endpoint_close(endpoint)(result, endpoint) 67 For other values refer to the Error codes The endpoint that was closed BGLIB C API /* Function */ void dumo_cmd_endpoint_close(uint8 endpoint); /* Callback */ struct dumo_msg_endpoint_close_rsp_t { uint16 result, uint8 endpoint } void dumo_rsp_endpoint_close( const struct dumo_msg_endpoint_close_rsp_t *msg ) Events generated Event endpoint_status Description Sent when endpoint status changes 68 4.6.1.2. endpoint_clr_flags This command can be used to clear endpoint flags. Command Byte 0 1 2 3 4 5-8 Type 0x20 0x05 0x0b 0x04 uint8 uint32 Name hilen lolen class method endpoint flags Description Message type: Command Minimum payload length Message class:Endpoint Message ID Endpoint of the connection Flags to be cleared Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x0b 0x04 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes 6 uint8 endpoint BGScript API call endpoint_clr_flags(endpoint, flags)(result, endpoint) BGLIB C API /* Function */ void dumo_cmd_endpoint_clr_flags(uint8 endpoint, uint32 flags); /* Callback */ struct dumo_msg_endpoint_clr_flags_rsp_t { uint16 result, uint8 endpoint } void dumo_rsp_endpoint_clr_flags( const struct dumo_msg_endpoint_clr_flags_rsp_t *msg ) 69 Events generated Event endpoint_status Description Sent when endpoint status changes 70 4.6.1.3. endpoint_read_counters This command can be used to read the data performance counters (data sent counter and data received counter) of an endpoint. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0b 0x05 uint8 Name hilen lolen class method endpoint Description Message type: Command Minimum payload length Message class:Endpoint Message ID Endpoint of the connection Response Byte 0 1 2 3 4-5 Type 0x20 0x0b 0x0b 0x05 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes 6 7-10 11-14 uint8 uint32 uint32 endpoint tx rx Amount of data sent to this endpoint Amount of data received from this endpoint BGScript API call endpoint_read_counters(endpoint)(result, endpoint, tx, rx) BGLIB C API /* Function */ void dumo_cmd_endpoint_read_counters(uint8 endpoint); /* Callback */ struct dumo_msg_endpoint_read_counters_rsp_t { uint16 result, uint8 endpoint, uint32 tx, uint32 rx } void dumo_rsp_endpoint_read_counters( const struct dumo_msg_endpoint_read_counters_rsp_t *msg ) 71 4.6.1.4. endpoint_send This command can be used to send data to the defined endpoint. Command Byte Type Name 0 1 2 3 4 0x20 0x02 0x0b 0x00 uint8 hilen lolen class method endpoint 5 uint8array data Description Message type: Command Minimum payload length Message class:Endpoint Message ID The index of the endpoint to which the data will be sent. The RAW data which will be written or sent Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x0b 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 endpoint For other values refer to the Error codes The endpoint to which the data was written BGScript API call endpoint_send(endpoint, data_len, data_data)(result, endpoint) BGLIB C API /* Function */ void dumo_cmd_endpoint_send(uint8 endpoint, uint8 data_len, const uint8 *data_data); /* Callback */ struct dumo_msg_endpoint_send_rsp_t { uint16 result, uint8 endpoint } void dumo_rsp_endpoint_send( const struct dumo_msg_endpoint_send_rsp_t *msg ) 72 4.6.1.5. endpoint_set_flags This command can be used to set endpoint flags to control and/or indicate in which mode the endpoint connection is operating. Command Byte 0 1 2 3 4 5-8 Type 0x20 0x05 0x0b 0x03 uint8 uint32 Name hilen lolen class method endpoint flags Description Message type: Command Minimum payload length Message class:Endpoint Message ID The endpoint which to control Flags to be set Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x0b 0x03 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes 6 uint8 endpoint BGScript API call endpoint_set_flags(endpoint, flags)(result, endpoint) BGLIB C API /* Function */ void dumo_cmd_endpoint_set_flags(uint8 endpoint, uint32 flags); /* Callback */ struct dumo_msg_endpoint_set_flags_rsp_t { uint16 result, uint8 endpoint } void dumo_rsp_endpoint_set_flags( const struct dumo_msg_endpoint_set_flags_rsp_t *msg ) 73 Events generated Event endpoint_status Description Sent when endpoint status changes 74 4.6.1.6. endpoint_set_streaming_destination This command can be used to set the destination into which data from an endpoint will be routed to. Command Byte 0 1 2 3 4 5 Type 0x20 0x02 0x0b 0x01 uint8 uint8 Name hilen lolen class method endpoint destination_endpoint Description Message type: Command Minimum payload length Message class:Endpoint Message ID The endpoint which to control The destination for the data Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x0b 0x01 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 endpoint For other values refer to the Error codes Endpoint of the connection BGScript API call endpoint_set_streaming_destination(endpoint, destination_endpoint)(result, endpoint) BGLIB C API /* Function */ void dumo_cmd_endpoint_set_streaming_destination(uint8 endpoint, uint8 destination_endpoint); /* Callback */ struct dumo_msg_endpoint_set_streaming_destination_rsp_t { uint16 result, uint8 endpoint } void dumo_rsp_endpoint_set_streaming_destination( const struct dumo_msg_endpoint_set_streaming_destination_rsp_t *msg ) 75 Events generated Event endpoint_status Description Sent when endpoint status changes 76 4.6.2. endpoint events 4.6.2.1. endpoint_syntax_error This event indicates that a protocol error was detected in BGAPI command parser. This event is triggered if a BGAPI command from the host contains syntax error(s), or if a command is only partially sent, in which case the BGAPI parser has a 1 second command timeout. If a valid command is not transmitted within this timeout an error event is generated and the partial or wrong command will be ignored. Event Byte 0 1 2 3 4-5 Type 0xa0 0x03 0x0b 0x00 uint16 Name hilen lolen class method result Description Message type: Event Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 endpoint For other values refer to the Error codes Endpoint of the connection BGScript event event endpoint_syntax_error(result,endpoint) C Functions /* Callback */ struct dumo_msg_endpoint_syntax_error_evt_t { uint16 result, uint8 endpoint } void dumo_evt_endpoint_syntax_error( const struct dumo_msg_endpoint_syntax_error_evt_t *msg ) 77 4.6.2.2. endpoint_data This event indicates incoming data from an endpoint. Event Byte Type Name 0 1 2 3 4 0xa0 0x02 0x0b 0x01 uint8 hilen lolen class method endpoint 5 uint8array data BGScript event event endpoint_data(endpoint,data_len,data_data) C Functions /* Callback */ struct dumo_msg_endpoint_data_evt_t { uint8 endpoint, uint8 data_len, const uint8* data_data } void dumo_evt_endpoint_data( const struct dumo_msg_endpoint_data_evt_t *msg ) 78 Description Message type: Event Minimum payload length Message class:Endpoint Message ID The endpoint which received this data, i.e. to which it was sent. The raw data 4.6.2.3. endpoint_status This event indicates an endpoint's status. Event Byte Type 0 1 2 3 4 0xa0 0x07 0x0b 0x02 uint8 5-8 9 uint32 int8 10 uint8 Name Description hilen Message type: Event lolen Minimum payload length class Message class:Endpoint method Message ID endpoint The index of the endpoint whose status this event describes type Unsigned 32bit integer destination_endpoint The index of the endpoint to which the incoming data goes. flags Flags which indicate the mode of endpoint BGScript event event endpoint_status(endpoint,type,destination_endpoint,flags) C Functions /* Callback */ struct dumo_msg_endpoint_status_evt_t { uint8 endpoint, uint32 type, int8 destination_endpoint, uint8 flags } void dumo_evt_endpoint_status( const struct dumo_msg_endpoint_status_evt_t *msg ) 79 4.6.2.4. endpoint_closing This event indicates that an endpoint is closing or indicates that the remote end has terminated the connection. This event should be acknowledged by calling the endpoint close command or otherwise the firmware will not re-use the endpoint index. Event Byte 0 1 2 3 4-5 Type 0xa0 0x03 0x0b 0x03 uint16 Name hilen lolen class method reason Description Message type: Event Minimum payload length Message class:Endpoint Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 endpoint For other values refer to the Error codes Endpoint handle Value 0xff: connection failed without associated endpoint BGScript event event endpoint_closing(reason,endpoint) C Functions /* Callback */ struct dumo_msg_endpoint_closing_evt_t { uint16 reason, uint8 endpoint } void dumo_evt_endpoint_closing( const struct dumo_msg_endpoint_closing_evt_t *msg ) 80 4.6.3. endpoint enumerations 4.6.3.1. endpoint_types These values define the endpoint types. Predefined endpoint ID's in BT121 are: 0:UART 1:SCRIPT 3:SPI1 4:SPI2 31:DROP Enumerations Value 0 1 2 4 16 32 64 128 512 Name endpoint_free endpoint_uart endpoint_script endpoint_reserved endpoint_drop endpoint_rfcomm endpoint_spi endpoint_connection endpoint_iap Description Endpoint is not in use UART Scripting Reserved for future use Drop all data sent to this endpoint RFCOMM channel SPI Connection iAP 81 4.6.4. endpoint defines 4.6.4.1. endpoint_endpoint_flags Defines 1 Value Name endpoint_FLAG_UPDATED 2 endpoint_FLAG_ACTIVE 4 endpoint_FLAG_STREAMING 8 endpoint_FLAG_BGAPI 16 endpoint_FLAG_WAIT_CLOSE 32 endpoint_FLAG_CLOSING 82 Description endpoint status has been changed since last indication endpoint is active and can send and receive data endpoint is in streaming mode. Data is sent and received from endpoint without framing endpoint is configured for BGAPI. Data received is parsed as BGAPI commands. Also all BGAPI events and responses are sent to this endpoint endpoint is closed from the device side. Host needs to acknowledge by sending endpoint_close command to device with this endpoint as parameter endpoint is closed from the host side and is waiting for the device to acknowledge closing of the endpoint 4.7. Persistent Store (flash) Flash and Persistent Store management functions 4.7.1. flash commands 4.7.1.1. flash_ps_dump This command can be used to dump all PS keys with their corresponding values as events. Command Byte 0 1 2 3 Type 0x20 0x00 0x0d 0x00 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:Persistent Store Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0d 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Persistent Store Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call flash_ps_dump()(result) BGLIB C API /* Function */ void dumo_cmd_flash_ps_dump(); /* Callback */ struct dumo_msg_flash_ps_dump_rsp_t { uint16 result } void dumo_rsp_flash_ps_dump( const struct dumo_msg_flash_ps_dump_rsp_t *msg ) 83 Events generated Event flash_ps_key Description PS Key contents 84 4.7.1.2. flash_ps_erase This command can be used to erase a single PS key and its value from the persistent store.. Command Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0d 0x04 uint16 Name hilen lolen class method key Description Message type: Command Minimum payload length Message class:Persistent Store Message ID PS key to erase Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0d 0x04 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Persistent Store Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call flash_ps_erase(key)(result) BGLIB C API /* Function */ void dumo_cmd_flash_ps_erase(uint16 key); /* Callback */ struct dumo_msg_flash_ps_erase_rsp_t { uint16 result } void dumo_rsp_flash_ps_erase( const struct dumo_msg_flash_ps_erase_rsp_t *msg ) 85 4.7.1.3. flash_ps_erase_all This command can be used to erase all PS keys and their corresponding value. Command Byte 0 1 2 3 Type 0x20 0x00 0x0d 0x01 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:Persistent Store Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0d 0x01 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Persistent Store Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call flash_ps_erase_all()(result) BGLIB C API /* Function */ void dumo_cmd_flash_ps_erase_all(); /* Callback */ struct dumo_msg_flash_ps_erase_all_rsp_t { uint16 result } void dumo_rsp_flash_ps_erase_all( const struct dumo_msg_flash_ps_erase_all_rsp_t *msg ) 86 4.7.1.4. flash_ps_load This command can be used for retrieving the value of the specified PS key. Command Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0d 0x03 uint16 Name hilen lolen class method key Description Message type: Command Minimum payload length Message class:Persistent Store Message ID PS key of the value to be retrieved Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x0d 0x03 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Persistent Store Message ID Result code 0 : success Non-zero : an error occurred 6 uint8array For other values refer to the Error codes Value returned of the specified PS key value BGScript API call flash_ps_load(key)(result, value_len, value_data) BGLIB C API /* Function */ void dumo_cmd_flash_ps_load(uint16 key); /* Callback */ struct dumo_msg_flash_ps_load_rsp_t { uint16 result, uint8 value_len, const uint8 *value_data } void dumo_rsp_flash_ps_load( const struct dumo_msg_flash_ps_load_rsp_t *msg ) 87 4.7.1.5. flash_ps_save This command can be used to store a value specified by the defined PS key. Command Byte 0 1 2 3 4-5 6 Type 0x20 0x03 0x0d 0x02 uint16 uint8array Name hilen lolen class method key value Description Message type: Command Minimum payload length Message class:Persistent Store Message ID PS key Value to be stored under the specified PS key Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0d 0x02 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Persistent Store Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call flash_ps_save(key, value_len, value_data)(result) BGLIB C API /* Function */ void dumo_cmd_flash_ps_save(uint16 key, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_flash_ps_save_rsp_t { uint16 result } void dumo_rsp_flash_ps_save( const struct dumo_msg_flash_ps_save_rsp_t *msg ) 88 4.7.2. flash events 4.7.2.1. flash_ps_key This event indicates that the flash_ps_dump command was given. It returns a single PS key with it's corresponding value. There can be multiple events if multiple PS keys exist. Event Byte 0 1 2 3 4-5 6 Type 0xa0 0x03 0x0d 0x00 uint16 uint8array Name hilen lolen class method key value BGScript event event flash_ps_key(key,value_len,value_data) C Functions /* Callback */ struct dumo_msg_flash_ps_key_evt_t { uint16 key, uint8 value_len, const uint8* value_data } void dumo_evt_flash_ps_key( const struct dumo_msg_flash_ps_key_evt_t *msg ) 89 Description Message type: Event Minimum payload length Message class:Persistent Store Message ID PS key Value currently stored under the specified PS key 4.8. Generic Attribute Profile (gatt) 4.8.1. gatt commands 4.8.1.1. gatt_discover_characteristics This command can be used to discover all characteristics of given GATT service from a remote GATT database. This command generates a unique gatt_characteristic event for every discovered characteristic. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error. Command Byte Type Name 0 1 2 0x20 0x05 0x09 hilen lolen class 3 4 5-8 0x03 uint8 uint32 method connection service Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT service handle This value is received from gatt_service event. Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x03 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_discover_characteristics(connection, service)(result) 90 BGLIB C API /* Function */ void dumo_cmd_gatt_discover_characteristics(uint8 connection, uint32 service); /* Callback */ struct dumo_msg_gatt_discover_characteristics_rsp_t { uint16 result } void dumo_rsp_gatt_discover_characteristics( const struct dumo_msg_gatt_discover_characteristics_rsp_t *msg ) Events generated Event Description gatt_characteristic Discovered characteristic from remote GATT database. gatt_procedure_completed Procedure has been successfully completed or failed with error. 91 4.8.1.2. gatt_discover_characteristics_by_uuid This command can be used to discover characteristics by UUID of a given GATT service from a remote GATT database. This command generates a unique gatt_characteristic event for every discovered characteristic. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error. Command Byte Type Name 0 1 2 0x20 0x06 0x09 hilen lolen class 3 4 5-8 0x04 uint8 uint32 method connection service 9 uint8array uuid Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT service handle This value is received from gatt_service event. Service UUID Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x04 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_discover_characteristics_by_uuid(connection, service, uuid_len, uuid_data)(result) 92 BGLIB C API /* Function */ void dumo_cmd_gatt_discover_characteristics_by_uuid(uint8 connection, uint32 service, uint8 uuid_len, const uint8 *uuid_data); /* Callback */ struct dumo_msg_gatt_discover_characteristics_by_uuid_rsp_t { uint16 result } void dumo_rsp_gatt_discover_characteristics_by_uuid( const struct dumo_msg_gatt_discover_characteristics_by_uuid_rsp_t *msg ) Events generated Event Description gatt_characteristic Discovered characteristic from remote GATT database. gatt_procedure_completed Procedure has been successfully completed or failed with error. 93 4.8.1.3. gatt_discover_descriptors This command can be used to discover all descriptors of a given GATT characteristic from a remote GATT database. This command generates a unique gatt_descriptor event for every discovered descriptor. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error. Command Byte Type Name 0 1 2 0x20 0x03 0x09 hilen lolen class 3 4 5-6 0x06 uint8 uint16 method connection characteristic Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x06 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_discover_descriptors(connection, characteristic)(result) 94 BGLIB C API /* Function */ void dumo_cmd_gatt_discover_descriptors(uint8 connection, uint16 characteristic); /* Callback */ struct dumo_msg_gatt_discover_descriptors_rsp_t { uint16 result } void dumo_rsp_gatt_discover_descriptors( const struct dumo_msg_gatt_discover_descriptors_rsp_t *msg ) Events generated Event Description gatt_descriptor Discovered descriptor from remote GATT database. gatt_procedure_completed Procedure has been successfully completed or failed with error. 95 4.8.1.4. gatt_discover_primary_services This command can be used to discover primary services with a given UUID from a remote GATT database. This command generates a unique gatt_service event for every discovered primary service. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error. Command Byte Type Name 0 1 2 0x20 0x01 0x09 hilen lolen class 3 4 0x01 uint8 method connection Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x01 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_discover_primary_services(connection)(result) BGLIB C API /* Function */ void dumo_cmd_gatt_discover_primary_services(uint8 connection); /* Callback */ struct dumo_msg_gatt_discover_primary_services_rsp_t { uint16 result } void dumo_rsp_gatt_discover_primary_services( const struct dumo_msg_gatt_discover_primary_services_rsp_t *msg ) 96 Events generated Event Description gatt_service Discovered service from remote GATT database gatt_procedure_completed Procedure has been successfully completed or failed with error. 97 4.8.1.5. gatt_discover_primary_services_by_uuid Discovers primary services with given UUID from remote GATT database. This command generates unique gatt_service event for every discovered primary service. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error. Command Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4 5 0x02 uint8 uint8array method connection uuid Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle Service UUID Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x02 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_discover_primary_services_by_uuid(connection, uuid_len, uuid_data)(result) BGLIB C API /* Function */ void dumo_cmd_gatt_discover_primary_services_by_uuid(uint8 connection, uint8 uuid_len, const uint8 *uuid_data); /* Callback */ struct dumo_msg_gatt_discover_primary_services_by_uuid_rsp_t { uint16 result } void dumo_rsp_gatt_discover_primary_services_by_uuid( const struct dumo_msg_gatt_discover_primary_services_by_uuid_rsp_t *msg ) 98 Events generated Event Description gatt_service Discovered service from remote GATT database. gatt_procedure_completed Procedure has been successfully completed or failed with error. 99 4.8.1.6. gatt_execute_characteristic_value_write This command can be used to commit or cancel previously queued writes onto a remote GATT server. Writes are sent to queue with prepare_characteristic_value_write command. Content, offset and length of queued values are validated by this procedure. A received gatt_procedure_completed event indicates that all data has been written succesfully or that an error response has been received. Command Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4 5 0x0c uint8 uint8 method connection flags Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle Unsigned 8bit integer Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x0c uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_execute_characteristic_value_write(connection, flags)(result) BGLIB C API /* Function */ void dumo_cmd_gatt_execute_characteristic_value_write(uint8 connection, uint8 flags); /* Callback */ struct dumo_msg_gatt_execute_characteristic_value_write_rsp_t { uint16 result } void dumo_rsp_gatt_execute_characteristic_value_write( const struct dumo_msg_gatt_execute_characteristic_value_write_rsp_t *msg ) 100 Events generated Event gatt_procedure_completed Description Procedure has been successfully completed or failed with error. 101 4.8.1.7. gatt_prepare_characteristic_value_write This command can be used to add a characteristic value to the write queue of a remote GATT server. This procedure allows the application to do multiple atomic writes. A received gatt_characteristic_value event can be used to verify that the data has not been corrupted during transmission. Writes are executed or canceled by execute_characteristic_value_write command. Content, offset and length of given value is verified by the server when execute_characteristic_value_write is executed. Command Byte Type Name 0 1 2 0x20 0x06 0x09 hilen lolen class 3 4 5-6 0x0b uint8 uint16 method connection characteristic 7-8 9 uint16 uint8array offset value Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Offset of characteristic value Characteristic value to written into remote database Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x0b uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_prepare_characteristic_value_write(connection, characteristic, offset, value_len, value_data)(result) 102 BGLIB C API /* Function */ void dumo_cmd_gatt_prepare_characteristic_value_write(uint8 connection, uint16 characteristic, uint16 offset, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_gatt_prepare_characteristic_value_write_rsp_t { uint16 result } void dumo_rsp_gatt_prepare_characteristic_value_write( const struct dumo_msg_gatt_prepare_characteristic_value_write_rsp_t *msg ) Events generated Event Description gatt_characteristic_value Received characteristic value which has been added to the write queue of remote GATT server. Received value can be used to verify that the data has not been corrupted during transmission. gatt_procedure_completed Procedure has been successfully completed or failed with error. 103 4.8.1.8. gatt_read_characteristic_value This command can be used to read the value of a characteristic from a remote GATT database. One or multiple gatt_characteristic_value events are generated when the value has been received. If the length of received value is equal to exchanged GATT MTU, "read long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been read succesfully or that an error response has been received. Command Byte Type Name 0 1 2 0x20 0x03 0x09 hilen lolen class 3 4 5-6 0x07 uint8 uint16 method connection characteristic Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x07 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_read_characteristic_value(connection, characteristic)(result) 104 BGLIB C API /* Function */ void dumo_cmd_gatt_read_characteristic_value(uint8 connection, uint16 characteristic); /* Callback */ struct dumo_msg_gatt_read_characteristic_value_rsp_t { uint16 result } void dumo_rsp_gatt_read_characteristic_value( const struct dumo_msg_gatt_read_characteristic_value_rsp_t *msg ) Events generated Event Description gatt_characteristic_value Received characteristic value from remote GATT server. gatt_procedure_completed Procedure has been successfully completed or failed with error. 105 4.8.1.9. gatt_read_characteristic_value_by_uuid This command can be used to read the value of a characteristic with the given UUID from a remote GATT database. One or multiple gatt_characteristic_value events are generated when the value has been received. If the length of received value is equal to exchanged GATT MTU, read long GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been read succesfully or that an error response has been received. Command Byte Type Name 0 1 2 0x20 0x06 0x09 hilen lolen class 3 4 5-8 0x08 uint8 uint32 method connection service 9 uint8array uuid Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT service handle This value is received from gatt_service event. Service UUID Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x08 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_read_characteristic_value_by_uuid(connection, service, uuid_len, uuid_data)(result) 106 BGLIB C API /* Function */ void dumo_cmd_gatt_read_characteristic_value_by_uuid(uint8 connection, uint32 service, uint8 uuid_len, const uint8 *uuid_data); /* Callback */ struct dumo_msg_gatt_read_characteristic_value_by_uuid_rsp_t { uint16 result } void dumo_rsp_gatt_read_characteristic_value_by_uuid( const struct dumo_msg_gatt_read_characteristic_value_by_uuid_rsp_t *msg ) Events generated Event Description gatt_characteristic_value Received characteristic value from remote GATT server. gatt_procedure_completed Procedure has been successfully completed or failed with error. 107 4.8.1.10. gatt_read_descriptor_value This command can be used to read the value of a characteristic descriptor from a remote GATT database. One or multiple gatt_descriptor_value events are generated when the value has been received. If the length of received value is equal to exchanged GATT MTU, "read long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been read succesfully or that an error response has been received. Command Byte Type Name 0 1 2 0x20 0x03 0x09 hilen lolen class 3 4 5-6 0x0e uint8 uint16 method connection descriptor Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic descriptor handle Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x0e uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_read_descriptor_value(connection, descriptor)(result) BGLIB C API /* Function */ void dumo_cmd_gatt_read_descriptor_value(uint8 connection, uint16 descriptor); /* Callback */ struct dumo_msg_gatt_read_descriptor_value_rsp_t { uint16 result } void dumo_rsp_gatt_read_descriptor_value( const struct dumo_msg_gatt_read_descriptor_value_rsp_t *msg ) 108 Events generated Event Description gatt_descriptor_value Received descriptor value from remote GATT server. gatt_procedure_completed Procedure has been successfully completed or failed with error. 109 4.8.1.11. gatt_send_characteristic_confirmation This command can be used to send a characteristic confirmation to a remote GATT server. Confirmation needs to be sent when gatt_characteristic_value event is received with att_opcode set to handle_value_indication (0x1e). Confirmation needs to be sent within 30 seconds. Otherwise the related GATT connection is dropped by the remote side. Command Byte Type Name 0 1 2 0x20 0x01 0x09 hilen lolen class 3 4 0x0d uint8 method connection Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x0d uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_send_characteristic_confirmation(connection)(result) BGLIB C API /* Function */ void dumo_cmd_gatt_send_characteristic_confirmation(uint8 connection); /* Callback */ struct dumo_msg_gatt_send_characteristic_confirmation_rsp_t { uint16 result } void dumo_rsp_gatt_send_characteristic_confirmation( const struct dumo_msg_gatt_send_characteristic_confirmation_rsp_t *msg ) 110 4.8.1.12. gatt_set_characteristic_notification This command can be used to enable or disable the notifications and indications from a remote GATT server. This procedure discovers a characteristic client configuration descriptor and writes the related configuration flags to a remote GATT database. A received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or that is has failed with an error. Command Byte Type Name 0 1 2 0x20 0x04 0x09 hilen lolen class 3 4 5-6 0x05 uint8 uint16 method connection characteristic 7 uint8 flags Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Characteristic client configration flags Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x05 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_set_characteristic_notification(connection, characteristic, flags)(result) 111 BGLIB C API /* Function */ void dumo_cmd_gatt_set_characteristic_notification(uint8 connection, uint16 characteristic, uint8 flags); /* Callback */ struct dumo_msg_gatt_set_characteristic_notification_rsp_t { uint16 result } void dumo_rsp_gatt_set_characteristic_notification( const struct dumo_msg_gatt_set_characteristic_notification_rsp_t *msg ) Events generated Event Description gatt_characteristic_value Informs that a characteristic value has been indicated or notified by remote GATT server. gatt_procedure_completed Procedure has been successfully completed or failed with error. 112 4.8.1.13. gatt_set_max_mtu This command can be used to set the maximum number of GATT Message Transfer Units (MTU). If max_mtu is non-default, MTU is exchanged automatically after Bluetooth LE connection has been established. Command Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x00 uint16 method max_mtu Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Maximum number of Message Transfer Units (MTU) allowed Range: 23 to 64 Default: 23 Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x00 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_set_max_mtu(max_mtu)(result) BGLIB C API /* Function */ void dumo_cmd_gatt_set_max_mtu(uint16 max_mtu); /* Callback */ struct dumo_msg_gatt_set_max_mtu_rsp_t { uint16 result } void dumo_rsp_gatt_set_max_mtu( const struct dumo_msg_gatt_set_max_mtu_rsp_t *msg ) 113 4.8.1.14. gatt_write_characteristic_value This command can be used to write the value of a characteristic to a remote GATT database. If the length of the given value is greater than the exchanged GATT MTU (Message Transfer Unit), "write long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been written succesfully or that an error response has been received. Command Byte Type Name 0 1 2 0x20 0x04 0x09 hilen lolen class 3 4 5-6 0x09 uint8 uint16 method connection characteristic 7 uint8array value Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Characteristic value Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x09 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_write_characteristic_value(connection, characteristic, value_len, value_data)(result) 114 BGLIB C API /* Function */ void dumo_cmd_gatt_write_characteristic_value(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_gatt_write_characteristic_value_rsp_t { uint16 result } void dumo_rsp_gatt_write_characteristic_value( const struct dumo_msg_gatt_write_characteristic_value_rsp_t *msg ) Events generated Event gatt_procedure_completed Description Procedure has been successfully completed or failed with error. 115 4.8.1.15. gatt_write_characteristic_value_without_response This command can be used to write the value of a characteristic to a remote GATT database. This command doesn't generate any events. All failures on the server are ignored silently. If an error is generated in the remote GATT server the given value is not written into database. Command Byte Type Name 0 1 2 0x20 0x04 0x09 hilen lolen class 3 4 5-6 0x0a uint8 uint16 method connection characteristic 7 uint8array value Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Characteristic value Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x0a uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_write_characteristic_value_without_response(connection, characteristic, value_len, value_data)(result) 116 BGLIB C API /* Function */ void dumo_cmd_gatt_write_characteristic_value_without_response(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_gatt_write_characteristic_value_without_response_rsp_t { uint16 result } void dumo_rsp_gatt_write_characteristic_value_without_response( const struct dumo_msg_gatt_write_characteristic_value_without_response_rsp_t *msg ) 117 4.8.1.16. gatt_write_descriptor_value This command can be used to write the value of a characteristic descriptor to a remote GATT database. If the length of the given value is greater than the exchanged GATT MTU size, "write long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been written succesfully or that an error response has been received. Command Byte Type Name 0 1 2 0x20 0x04 0x09 hilen lolen class 3 4 5-6 7 0x0f uint8 uint16 uint8array method connection descriptor value Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic descriptor handle Descriptor value Response Byte Type Name 0 1 2 0x20 0x02 0x09 hilen lolen class 3 4-5 0x0f uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_write_descriptor_value(connection, descriptor, value_len, value_data)(result) 118 BGLIB C API /* Function */ void dumo_cmd_gatt_write_descriptor_value(uint8 connection, uint16 descriptor, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_gatt_write_descriptor_value_rsp_t { uint16 result } void dumo_rsp_gatt_write_descriptor_value( const struct dumo_msg_gatt_write_descriptor_value_rsp_t *msg ) Events generated Event gatt_procedure_completed Description Procedure has been successfully completed or failed with error. 119 4.8.2. gatt events 4.8.2.1. gatt_mtu_exchanged This event indicates that a GATT MTU exchange procedure has been completed. Event Byte Type Name 0 1 2 0xa0 0x03 0x09 hilen lolen class 3 4 5-6 0x00 uint8 uint16 method connection mtu Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle Exchanged GATT MTU BGScript event event gatt_mtu_exchanged(connection,mtu) C Functions /* Callback */ struct dumo_msg_gatt_mtu_exchanged_evt_t { uint8 connection, uint16 mtu } void dumo_evt_gatt_mtu_exchanged( const struct dumo_msg_gatt_mtu_exchanged_evt_t *msg ) 120 4.8.2.2. gatt_service This event indicates that a GATT service was discovered from a remote GATT database by using the gatt_discover_primary_services or gatt_discover_primary_services_by_uuid command. Event Byte Type Name 0 1 2 0xa0 0x06 0x09 hilen lolen class 3 4 5-8 0x01 uint8 uint32 method connection service 9 uint8array uuid Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT service handle This value is received from gatt_service event. Service UUID BGScript event event gatt_service(connection,service,uuid_len,uuid_data) C Functions /* Callback */ struct dumo_msg_gatt_service_evt_t { uint8 connection, uint32 service, uint8 uuid_len, const uint8* uuid_data } void dumo_evt_gatt_service( const struct dumo_msg_gatt_service_evt_t *msg ) 121 4.8.2.3. gatt_characteristic This event indicates that a GATT characteristic was discovered from a remote GATT database by gatt_discover_characteristics or gatt_discover_primary_characteristics_by_uuid command. Event Byte Type Name 0 1 2 0xa0 0x05 0x09 hilen lolen class 3 4 5-6 0x02 uint8 uint16 method connection characteristic 7 8 uint8 uint8array properties uuid Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Characteristic properties Service UUID BGScript event event gatt_characteristic(connection,characteristic,properties,uuid_len,uuid_data) C Functions /* Callback */ struct dumo_msg_gatt_characteristic_evt_t { uint8 connection, uint16 characteristic, uint8 properties, uint8 uuid_len, const uint8* uuid_data } void dumo_evt_gatt_characteristic( const struct dumo_msg_gatt_characteristic_evt_t *msg ) 122 4.8.2.4. gatt_descriptor This event indicates that a GATT characteristic descriptor was discovered from a remote GATT database by using the gatt_discover_descriptor command. Event Byte Type Name 0 1 2 0xa0 0x04 0x09 hilen lolen class 3 4 5-6 7 0x03 uint8 uint16 uint8array method connection descriptor uuid Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic descriptor handle Service UUID BGScript event event gatt_descriptor(connection,descriptor,uuid_len,uuid_data) C Functions /* Callback */ struct dumo_msg_gatt_descriptor_evt_t { uint8 connection, uint16 descriptor, uint8 uuid_len, const uint8* uuid_data } void dumo_evt_gatt_descriptor( const struct dumo_msg_gatt_descriptor_evt_t *msg ) 123 4.8.2.5. gatt_characteristic_value This event indicates that a characteristic value from a remote GATT server was received. This event is generated by read, indication, notification or prepared write command. Parameter att_opcode defines whichattribute profile procedure has generated this event. The application needs to confirm indication with send_characteristic_confirmation command if att_opcode type is handle_value_indication (0x1d). Event Byte Type Name 0 1 2 0xa0 0x07 0x09 hilen lolen class 3 4 5-6 0x04 uint8 uint16 method connection characteristic 7 uint8 att_opcode 8-9 10 uint16 uint8array offset value Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Attribute opcode which informs the procedure from which attribute the value was received from Value offset Characteristic value BGScript event event gatt_characteristic_value(connection,characteristic,att_opcode,offset,value_len,value_data C Functions /* Callback */ struct dumo_msg_gatt_characteristic_value_evt_t { uint8 connection, uint16 characteristic, uint8 att_opcode, uint16 offset, uint8 value_len, const uint8* value_data } void dumo_evt_gatt_characteristic_value( const struct dumo_msg_gatt_characteristic_value_evt_t *msg ) 124 4.8.2.6. gatt_descriptor_value This event indicates that a descriptor value from a remote GATT server was received. This event is generated by the read_descriptor_value command. Event Byte Type Name 0 1 2 0xa0 0x06 0x09 hilen lolen class 3 4 5-6 7-8 9 0x05 uint8 uint16 uint16 uint8array method connection descriptor offset value Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle GATT characteristic descriptor handle Value offset Descriptor value BGScript event event gatt_descriptor_value(connection,descriptor,offset,value_len,value_data) C Functions /* Callback */ struct dumo_msg_gatt_descriptor_value_evt_t { uint8 connection, uint16 descriptor, uint16 offset, uint8 value_len, const uint8* value_data } void dumo_evt_gatt_descriptor_value( const struct dumo_msg_gatt_descriptor_value_evt_t *msg ) 125 4.8.2.7. gatt_procedure_completed This event indicates that the previous GATT procedure has been completed succesfully or that is has failed with an error. Event Byte Type Name 0 1 2 0xa0 0x03 0x09 hilen lolen class 3 4 5-6 0x06 uint8 uint16 method connection result Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Message ID Connection handle Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript event event gatt_procedure_completed(connection,result) C Functions /* Callback */ struct dumo_msg_gatt_procedure_completed_evt_t { uint8 connection, uint16 result } void dumo_evt_gatt_procedure_completed( const struct dumo_msg_gatt_procedure_completed_evt_t *msg ) 126 4.8.3. gatt enumerations 4.8.3.1. gatt_att_opcode These values indicate which attribute request or response has caused the event. Enumerations Value 8 9 10 11 12 13 14 15 18 19 82 22 23 24 25 27 29 Name gatt_read_by_type_request gatt_read_by_type_response gatt_read_request gatt_read_response gatt_read_blob_request gatt_read_blob_response gatt_read_multiple_request gatt_read_multiple_response gatt_write_request gatt_write_response gatt_write_command gatt_prepare_write_request gatt_prepare_write_response gatt_execute_write_request gatt_execute_write_response gatt_handle_value_notification gatt_handle_value_indication 127 Description Read by type request Read by type response Read request Read response Read blob request Read blob response Read multiple request Read multiple response Write request Write response Write command Prepare write request Prepare write response Excute write request Excute write response Notfication Indication 4.8.3.2. gatt_client_config_flag These values define whether the client is to receive notifications or indications from a remote GATT server. Enumerations Value 1 2 Name Description Notification Indication gatt_notification gatt_indication 128 4.8.3.3. gatt_execute_write_flag These values define whether the GATT server is to cancel all queud writes or commit all queud write to a remote database. Enumerations Value 0 1 Name gatt_cancel gatt_commit Description Cancel all queued writes Commit all queued writes 129 4.9. Generic Attribute Profile Server (gatt_server) 4.9.1. gatt_server commands 4.9.1.1. gatt_server_read_attribute_type This command can be used to read the type of an attribute from a local database. Type is usually 16 or 128-bit UUID. Command Byte Type Name 0 1 2 0x20 0x02 0x0a hilen lolen class 3 4-5 0x01 uint16 method attribute Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Server Message ID Attribute handle Response Byte Type Name 0 1 2 0x20 0x03 0x0a hilen lolen class 3 4-5 0x01 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Server Message ID Result code 0 : success Non-zero : an error occurred 6 uint8array For other values refer to the Error codes Variable length byte array type BGScript API call gatt_server_read_attribute_type(attribute)(result, type_len, type_data) 130 BGLIB C API /* Function */ void dumo_cmd_gatt_server_read_attribute_type(uint16 attribute); /* Callback */ struct dumo_msg_gatt_server_read_attribute_type_rsp_t { uint16 result, uint8 type_len, const uint8 *type_data } void dumo_rsp_gatt_server_read_attribute_type( const struct dumo_msg_gatt_server_read_attribute_type_rsp_t *msg ) 131 4.9.1.2. gatt_server_read_attribute_value This command can be used to read the value of an attribute from a local database. Command Byte Type Name 0 1 2 0x20 0x04 0x0a hilen lolen class 3 4-5 6-7 0x00 uint16 uint16 method attribute offset Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Server Message ID Attribute handle Value offset Response Byte Type Name 0 1 2 0x20 0x03 0x0a hilen lolen class 3 4-5 0x00 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Server Message ID Result code 0 : success Non-zero : an error occurred 6 uint8array For other values refer to the Error codes Variable length byte array value BGScript API call gatt_server_read_attribute_value(attribute, offset)(result, value_len, value_data) BGLIB C API /* Function */ void dumo_cmd_gatt_server_read_attribute_value(uint16 attribute, uint16 offset); /* Callback */ struct dumo_msg_gatt_server_read_attribute_value_rsp_t { uint16 result, uint8 value_len, const uint8 *value_data } void dumo_rsp_gatt_server_read_attribute_value( const struct dumo_msg_gatt_server_read_attribute_value_rsp_t *msg ) 132 4.9.1.3. gatt_server_send_characteristic_notification This command can be used to send notifications and indications to a remote GATT client. Notification or indication is sent only if the client has enabled them by writing corresponding flags to the characetiristic client configuration descriptor. A new notification or indication cannot be sent before a confirmation (gatt_server_characteristic_status_event) is first received. Command Byte Type Name 0 1 2 0x20 0x04 0x0a hilen lolen class 3 4 0x05 uint8 method connection 5-6 7 uint16 uint8array characteristic value Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Server Message ID Connection into which the notification or indication is to be sent to. Values 0xff: Sends notification or indication to all connected devices. Other: Connection handle Characteristic handle Value Response Byte Type Name 0 1 2 0x20 0x02 0x0a hilen lolen class 3 4-5 0x05 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Server Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_server_send_characteristic_notification(connection, characteristic, value_len, value_data)(result) 133 BGLIB C API /* Function */ void dumo_cmd_gatt_server_send_characteristic_notification(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_gatt_server_send_characteristic_notification_rsp_t { uint16 result } void dumo_rsp_gatt_server_send_characteristic_notification( const struct dumo_msg_gatt_server_send_characteristic_notification_rsp_t *msg ) 134 4.9.1.4. gatt_server_send_user_read_response This command can be used to send a response to an user_read_request event. The response needs to be sent within 30 seconds or otherwise this GATT connection is dropped by the remote side. If attr_errorcode is given as 0 the characteristic value is sent to the remote GATT client. Other values will send an attribute protocol error response. Command Byte 0 1 2 0x20 0x05 0x0a hilen lolen class 3 4 5-6 0x03 uint8 uint16 method connection characteristic 7 uint8 att_errorcode Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Server Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Attribute protocol error code value Values 0: No error Other: see link Characteristic value 8 Type uint8array Name Response Byte Type Name 0 1 2 0x20 0x02 0x0a hilen lolen class 3 4-5 0x03 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Server Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_server_send_user_read_response(connection, characteristic, att_errorcode, value_len, value_data)(result) 135 BGLIB C API /* Function */ void dumo_cmd_gatt_server_send_user_read_response(uint8 connection, uint16 characteristic, uint8 att_errorcode, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_gatt_server_send_user_read_response_rsp_t { uint16 result } void dumo_rsp_gatt_server_send_user_read_response( const struct dumo_msg_gatt_server_send_user_read_response_rsp_t *msg ) 136 4.9.1.5. gatt_server_send_user_write_response This command can be used to send a response to an user_write_request event. The response needs to be sent within 30 seconds, otherwise this GATT connection is dropped by remote side. If attr_errorcode is given as 0 the attribute protocol write response is sent to the remote GATT client. Other values will send an attribute protocol error response. Command Byte Type Name 0 1 2 0x20 0x04 0x0a hilen lolen class 3 4 5-6 0x04 uint8 uint16 method connection characteristic 7 uint8 att_errorcode Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Server Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Attribute protocol error code Values 0: No error Other: see link Response Byte Type Name 0 1 2 0x20 0x02 0x0a hilen lolen class 3 4-5 0x04 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Server Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_server_send_user_write_response(connection, characteristic, att_errorcode)(result) 137 BGLIB C API /* Function */ void dumo_cmd_gatt_server_send_user_write_response(uint8 connection, uint16 characteristic, uint8 att_errorcode); /* Callback */ struct dumo_msg_gatt_server_send_user_write_response_rsp_t { uint16 result } void dumo_rsp_gatt_server_send_user_write_response( const struct dumo_msg_gatt_server_send_user_write_response_rsp_t *msg ) 138 4.9.1.6. gatt_server_write_attribute_value This command can be used to write the value of an attribute to the local database. Changing the value of the local database does not send notification or indication automatically. Notifications and indications are sent to the remote GATT client using send_characteristic_notification command. Command Byte Type Name 0 1 2 0x20 0x05 0x0a hilen lolen class 3 4-5 6-7 8 0x02 uint16 uint16 uint8array method attribute offset value Description Message type: Command Minimum payload length Message class:Generic Attribute Profile Server Message ID Attribute handle Value offset Value offset Response Byte Type Name 0 1 2 0x20 0x02 0x0a hilen lolen class 3 4-5 0x02 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Attribute Profile Server Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call gatt_server_write_attribute_value(attribute, offset, value_len, value_data)(result) BGLIB C API /* Function */ void dumo_cmd_gatt_server_write_attribute_value(uint16 attribute, uint16 offset, uint8 value_len, const uint8 *value_data); /* Callback */ struct dumo_msg_gatt_server_write_attribute_value_rsp_t { uint16 result } void dumo_rsp_gatt_server_write_attribute_value( const struct dumo_msg_gatt_server_write_attribute_value_rsp_t *msg ) 139 4.9.2. gatt_server events 4.9.2.1. gatt_server_attribute_value This event indicates that the value of an attribute in the local database has been changed by a remote GATT client. Parameter att_opcode describes which attribute procedure was used to change the value. Event Byte Type Name 0 1 2 0xa0 0x07 0x0a hilen lolen class 3 4 5-6 7 0x00 uint8 uint16 uint8 method connection attribute att_opcode 8-9 10 uint16 uint8array offset value Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Server Message ID Connection handle Attribute Handle Attribute opcode which informs the procedure from which attribute the value was received from Value offset Value BGScript event event gatt_server_attribute_value(connection,attribute,att_opcode,offset,value_len,value_data) C Functions /* Callback */ struct dumo_msg_gatt_server_attribute_value_evt_t { uint8 connection, uint16 attribute, uint8 att_opcode, uint16 offset, uint8 value_len, const uint8* value_data } void dumo_evt_gatt_server_attribute_value( const struct dumo_msg_gatt_server_attribute_value_evt_t *msg ) 140 4.9.2.2. gatt_server_user_read_request This event indicates that a remote GATT client is reading a value which is configured as a user handled value in GATT XML configuration file. Parameter att_opcode describes which attribute procedure is used to read the value. The application needs to respond to this request by using the send_user_read_response command. Event Byte Type Name 0 1 2 0xa0 0x06 0x0a hilen lolen class 3 4 5-6 0x01 uint8 uint16 method connection characteristic 7 uint8 att_opcode 8-9 uint16 offset Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Server Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Attribute opcode which informs the procedure from which attribute the value was received from Value offset BGScript event event gatt_server_user_read_request(connection,characteristic,att_opcode,offset) C Functions /* Callback */ struct dumo_msg_gatt_server_user_read_request_evt_t { uint8 connection, uint16 characteristic, uint8 att_opcode, uint16 offset } void dumo_evt_gatt_server_user_read_request( const struct dumo_msg_gatt_server_user_read_request_evt_t *msg ) 141 4.9.2.3. gatt_server_user_write_request This event indicates that a remote GATT client is writing a value which is configured as a user handled value in GATT XML configuration file. Parameter att_opcode describes which attribute procedure is used to write the value. The application needs to respond to this request by using the send_user_write_response command. Event Byte Type Name 0 1 2 0xa0 0x07 0x0a hilen lolen class 3 4 5-6 0x02 uint8 uint16 method connection characteristic 7 uint8 att_opcode 8-9 10 uint16 uint8array offset value Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Server Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Attribute opcode which informs the procedure from which attribute the value was received from Value offset Value BGScript event event gatt_server_user_write_request(connection,characteristic,att_opcode,offset,value_len,value C Functions /* Callback */ struct dumo_msg_gatt_server_user_write_request_evt_t { uint8 connection, uint16 characteristic, uint8 att_opcode, uint16 offset, uint8 value_len, const uint8* value_data } void dumo_evt_gatt_server_user_write_request( const struct dumo_msg_gatt_server_user_write_request_evt_t *msg ) 142 4.9.2.4. gatt_server_characteristic_status This event indicates either that a characteristic client configuration has been changed or that a characteristic confirmation has been received. Confirmation should be received within30 seconds after an indication has been sent with the send_characteristic_notification command, otherwise GATT connection to the related device is dropped. Event Byte Type Name 0 1 2 0xa0 0x06 0x0a hilen lolen class 3 4 5-6 0x03 uint8 uint16 method connection characteristic 7 uint8 status_flags 8-9 uint16 client_config_flags Description Message type: Event Minimum payload length Message class:Generic Attribute Profile Server Message ID Connection handle GATT characteristic handle This value is received from gatt_characteristic event Defines which status information has changed Value of characteristic client configuration descriptor. This value is connection specific. BGScript event event gatt_server_characteristic_status(connection,characteristic,status_flags,client_config_fla C Functions /* Callback */ struct dumo_msg_gatt_server_characteristic_status_evt_t { uint8 connection, uint16 characteristic, uint8 status_flags, uint16 client_config_flags } void dumo_evt_gatt_server_characteristic_status( const struct dumo_msg_gatt_server_characteristic_status_evt_t *msg ) 143 4.9.3. gatt_server enumerations 4.9.3.1. gatt_server_characteristic_status_flag These values describe whether characteristic client configuration was changed or whether a characteristic confirmation was received. Enumerations 1 Value Name gatt_server_client_config 2 gatt_server_confirmation Description Characteristic client configuration has been changed. Characteristic confirmation has been received. 144 4.10. Hardware (hardware) Functions to control the hardware of the module. 4.10.1. hardware commands 4.10.1.1. hardware_configure_gpio This command can be used to configure the I/O-port mode. Command Byte Type Name 0 1 2 3 4 5-6 0x20 0x05 0x0c 0x01 uint8 uint16 hilen lolen class method port gpio 7 8 uint8 uint8 mode pullup Description Message type: Command Minimum payload length Message class:Hardware Message ID Port index, where A=0, B=1. Index of gpio-pin on the port which this command affects. Pin mode Pin configuration Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0c 0x01 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call hardware_configure_gpio(port, gpio, mode, pullup)(result) 145 BGLIB C API /* Function */ void dumo_cmd_hardware_configure_gpio(uint8 port, uint16 gpio, uint8 mode, uint8 pullup); /* Callback */ struct dumo_msg_hardware_configure_gpio_rsp_t { uint16 result } void dumo_rsp_hardware_configure_gpio( const struct dumo_msg_hardware_configure_gpio_rsp_t *msg ) 146 4.10.1.2. hardware_read_adc This command can be used to read the specified channel of the A/D converter in the module. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0c 0x04 uint8 Name hilen lolen class method input Description Message type: Command Minimum payload length Message class:Hardware Message ID ADC input channel. Response Byte 0 1 2 3 4-5 Type 0x20 0x05 0x0c 0x04 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred 6 7-8 uint8 uint16 For other values refer to the Error codes ADC input channel. ADC value input value BGScript API call hardware_read_adc(input)(result, input, value) BGLIB C API /* Function */ void dumo_cmd_hardware_read_adc(uint8 input); /* Callback */ struct dumo_msg_hardware_read_adc_rsp_t { uint16 result, uint8 input, uint16 value } void dumo_rsp_hardware_read_adc( const struct dumo_msg_hardware_read_adc_rsp_t *msg ) 147 4.10.1.3. hardware_read_gpio This command can be used to read the pins of the specified I/O-port of the module. Command Byte 0 1 2 3 4 5-6 Type 0x20 0x03 0x0c 0x03 uint8 uint16 Name hilen lolen class method port mask Description Message type: Command Minimum payload length Message class:Hardware Message ID Port index to read from, A=0, B=1. Bitmask of which pins on the port should be read Response Byte 0 1 2 3 4-5 Type 0x20 0x04 0x0c 0x03 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred 6-7 uint16 For other values refer to the Error codes Port data data BGScript API call hardware_read_gpio(port, mask)(result, data) BGLIB C API /* Function */ void dumo_cmd_hardware_read_gpio(uint8 port, uint16 mask); /* Callback */ struct dumo_msg_hardware_read_gpio_rsp_t { uint16 result, uint16 data } void dumo_rsp_hardware_read_gpio( const struct dumo_msg_hardware_read_gpio_rsp_t *msg ) 148 4.10.1.4. hardware_read_i2c This command can be used for reading the specified I2C interface. Command Byte 0 1 2 3 4 5-6 7 Type 0x20 0x04 0x0c 0x05 uint8 uint16 uint8 Name hilen lolen class method channel slave_address length Description Message type: Command Minimum payload length Message class:Hardware Message ID I2C channel to use. Slave address to use Amount of data to read Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x0c 0x05 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred 6 uint8array For other values refer to the Error codes Data that was read if command was successful data BGScript API call hardware_read_i2c(channel, slave_address, length)(result, data_len, data_data) 149 BGLIB C API /* Function */ void dumo_cmd_hardware_read_i2c(uint8 channel, uint16 slave_address, uint8 length); /* Callback */ struct dumo_msg_hardware_read_i2c_rsp_t { uint16 result, uint8 data_len, const uint8 *data_data } void dumo_rsp_hardware_read_i2c( const struct dumo_msg_hardware_read_i2c_rsp_t *msg ) 150 4.10.1.5. hardware_set_soft_timer This command can be used to enable the software timer. Multiple concurrent timers can be running simultaneously. Command Byte Type Name 0 1 2 3 4-7 0x20 0x06 0x0c 0x00 uint32 hilen lolen class method time 8 9 uint8 uint8 timer_id single_shot Description Message type: Command Minimum payload length Message class:Hardware Message ID Interval between how often to send events, in milliseconds. If time is 0, removes the scheduled timer Handle that is returned with event Timer mode Values 0: false (Timer is repeating) 1: true (Timer runs only once) Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0c 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call hardware_set_soft_timer(time, timer_id, single_shot)(result) 151 BGLIB C API /* Function */ void dumo_cmd_hardware_set_soft_timer(uint32 time, uint8 timer_id, uint8 single_shot); /* Callback */ struct dumo_msg_hardware_set_soft_timer_rsp_t { uint16 result } void dumo_rsp_hardware_set_soft_timer( const struct dumo_msg_hardware_set_soft_timer_rsp_t *msg ) Events generated Event hardware_soft_timer Description Sent after specified interval 152 4.10.1.6. hardware_set_uart_configuration This command can be used to configure the UART interface. Command Byte 0 1 2 3 4 Type 0x20 0x09 0x0c 0x08 uint8 5-8 9 uint32 uint8 10 uint8 11 uint8 12 uint8 Name hilen lolen class method endpoint Description Message type: Command Minimum payload length Message class:Hardware Message ID Endpoint rate data_bits Values 0: Use only this value Unsigned 32bit integer Data bits stop_bits Values 8: Use only this value Stop bits parity Values 1: 1 stop bit 2: 2 stop bits Parity bit flow_ctrl Values See link UART flow control Values 0: None 1: RTS/CTS Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0c 0x08 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes 153 BGScript API call hardware_set_uart_configuration(endpoint, rate, data_bits, stop_bits, parity, flow_ctrl)(result) BGLIB C API /* Function */ void dumo_cmd_hardware_set_uart_configuration(uint8 endpoint, uint32 rate, uint8 data_bits, uint8 stop_bits, uint8 parity, uint8 flow_ctrl); /* Callback */ struct dumo_msg_hardware_set_uart_configuration_rsp_t { uint16 result } void dumo_rsp_hardware_set_uart_configuration( const struct dumo_msg_hardware_set_uart_configuration_rsp_t *msg ) 154 4.10.1.7. hardware_stop_i2c This command can be used to stop I2C transmission. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0c 0x07 uint8 Name hilen lolen class method channel Description Message type: Command Minimum payload length Message class:Hardware Message ID I2C channel to use. Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0c 0x07 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call hardware_stop_i2c(channel)(result) BGLIB C API /* Function */ void dumo_cmd_hardware_stop_i2c(uint8 channel); /* Callback */ struct dumo_msg_hardware_stop_i2c_rsp_t { uint16 result } void dumo_rsp_hardware_stop_i2c( const struct dumo_msg_hardware_stop_i2c_rsp_t *msg ) 155 4.10.1.8. hardware_write_gpio This command can be used to set the logic states of pins of the specified I/O-port using a bitmask. Command Byte Type Name 0 1 2 3 4 5-6 0x20 0x05 0x0c 0x02 uint8 uint16 hilen lolen class method port mask 7-8 uint16 data Description Message type: Command Minimum payload length Message class:Hardware Message ID Port index, where A=0, B=1. Bitmask of which pins on the port this command affects Bitmask of which pins to set high and which pins to set low Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0c 0x02 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call hardware_write_gpio(port, mask, data)(result) BGLIB C API /* Function */ void dumo_cmd_hardware_write_gpio(uint8 port, uint16 mask, uint16 data); /* Callback */ struct dumo_msg_hardware_write_gpio_rsp_t { uint16 result } void dumo_rsp_hardware_write_gpio( const struct dumo_msg_hardware_write_gpio_rsp_t *msg ) 156 4.10.1.9. hardware_write_i2c This command can be used to write data into I2C interface. Command Byte 0 1 2 3 4 5-6 7 Type 0x20 0x04 0x0c 0x06 uint8 uint16 uint8array Name hilen lolen class method channel slave_address data Description Message type: Command Minimum payload length Message class:Hardware Message ID I2C channel to use. Slave address to use Data to write Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0c 0x06 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Hardware Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call hardware_write_i2c(channel, slave_address, data_len, data_data)(result) BGLIB C API /* Function */ void dumo_cmd_hardware_write_i2c(uint8 channel, uint16 slave_address, uint8 data_len, const uint8 *data_data); /* Callback */ struct dumo_msg_hardware_write_i2c_rsp_t { uint16 result } void dumo_rsp_hardware_write_i2c( const struct dumo_msg_hardware_write_i2c_rsp_t *msg ) 157 4.10.2. hardware events 4.10.2.1. hardware_soft_timer This event indicates that the soft timer has lapsed. Event Byte 0 1 2 3 4 Type 0xa0 0x01 0x0c 0x00 uint8 Name hilen lolen class method timer_id Description Message type: Event Minimum payload length Message class:Hardware Message ID Timer handle BGScript event event hardware_soft_timer(timer_id) C Functions /* Callback */ struct dumo_msg_hardware_soft_timer_evt_t { uint8 timer_id } void dumo_evt_hardware_soft_timer( const struct dumo_msg_hardware_soft_timer_evt_t *msg ) 158 4.10.2.2. hardware_interrupt This event indicates that an external interrupt has occurred and provides a timestamp and a mask which indicates all triggered interrupt channels. Event Byte 0 1 2 3 4-5 6-9 Type 0xa0 0x06 0x0c 0x01 uint16 uint32 Name hilen lolen class method interrupts timestamp Description Message type: Event Minimum payload length Message class:Hardware Message ID Mask of interrupt channels Timestamp BGScript event event hardware_interrupt(interrupts,timestamp) C Functions /* Callback */ struct dumo_msg_hardware_interrupt_evt_t { uint16 interrupts, uint32 timestamp } void dumo_evt_hardware_interrupt( const struct dumo_msg_hardware_interrupt_evt_t *msg ) 159 4.10.3. hardware enumerations 4.10.3.1. hardware_gpio_configuration These values define the mode of the related pin. Enumerations Value 0 1 2 Name hardware_gpio_float hardware_gpio_pullup hardware_gpio_pulldown Description No pull-up,pull-down Pull-up Pull-down 160 4.10.3.2. hardware_gpio_mode These values define the mode of the related pin. Enumerations Value 0 1 2 3 Name hardware_gpio_input hardware_gpio_output hardware_gpio_function hardware_gpio_analog 161 Description Input Output Function Analog 4.10.3.3. hardware_uartparity These values define the parity bit configuration of the related UART connection. Enumerations Value 0 1 2 Name Description hardware_none hardware_odd hardware_even None Odd parity Even parity 162 4.11. Identity Profile (identity) Identity Profile related commands and events. See DEVICE IDENTIFICATION PROFILE SPECIFICATION, v13 4.11.1. identity commands 4.11.1.1. identity_local_identity This command can be used to read Identity Profile information from the local device. Command Byte 0 1 2 3 Type 0x20 0x00 0x05 0x01 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:Identity Profile Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x0b 0x05 0x01 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Identity Profile Message ID Result code 0 : success Non-zero : an error occurred 6-7 8-9 10-11 12-13 14 uint16 uint16 uint16 uint16 uint8array source vendor product version description For other values refer to the Error codes Authority who has issued the vendor id Vendor id Product id Version id Service Description BGScript API call identity_local_identity()(result, source, vendor, product, version, description_len, description_data) 163 BGLIB C API /* Function */ void dumo_cmd_identity_local_identity(); /* Callback */ struct dumo_msg_identity_local_identity_rsp_t { uint16 result, uint16 source, uint16 vendor, uint16 product, uint16 version, uint8 description_len, const uint8 *description_data } void dumo_rsp_identity_local_identity( const struct dumo_msg_identity_local_identity_rsp_t *msg ) 164 4.11.1.2. identity_remote_identity This command can be used to read Identity Profile information from a remote device. Command Byte 0 1 2 3 4-9 Type 0x20 0x06 0x05 0x00 bd_addr Name hilen lolen class method address Description Message type: Command Minimum payload length Message class:Identity Profile Message ID Bluetooth address in BR/EDR in little endian format Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x05 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Identity Profile Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call identity_remote_identity(address)(result) BGLIB C API /* Function */ void dumo_cmd_identity_remote_identity(bd_addr address); /* Callback */ struct dumo_msg_identity_remote_identity_rsp_t { uint16 result } void dumo_rsp_identity_remote_identity( const struct dumo_msg_identity_remote_identity_rsp_t *msg ) Events generated Event Description identity_remote_identity 165 4.11.2. identity events 4.11.2.1. identity_remote_identity This event indicates Identity Profile information from a remote device. Event Byte 0 1 2 3 4-5 Type 0xa0 0x11 0x05 0x00 uint16 Name hilen lolen class method status Description Message type: Event Minimum payload length Message class:Identity Profile Message ID Result code 0 : success Non-zero : an error occurred 6-11 bd_addr address 12-13 14-15 16-17 18-19 20 uint16 uint16 uint16 uint16 uint8array source vendor product version description For other values refer to the Error codes Bluetooth address of remote device in little endian format Authority who has issued the vendor id Vendor ID Product ID Version ID Service Description BGScript event event identity_remote_identity(status,address,source,vendor,product,version,description_len,desc C Functions /* Callback */ struct dumo_msg_identity_remote_identity_evt_t { uint16 status, bd_addr address, uint16 source, uint16 vendor, uint16 product, uint16 version, uint8 description_len, const uint8* description_data } void dumo_evt_identity_remote_identity( const struct dumo_msg_identity_remote_identity_evt_t *msg ) 166 4.12. Connection management for low energy (le_connection) Connection management commands and events for Bluetooth LE. 4.12.1. le_connection commands 4.12.1.1. le_connection_set_parameters This command can be used to request Bluetooth LE connection parameters of a link. 167 Command Byte Type Name 0 1 2 0x20 0x09 0x08 hilen lolen class 3 4 5-6 0x00 uint8 uint16 method connection min_interval Description Message type: Command Minimum payload length Message class:Connection management for low energy Message ID Connection Handle Minimum connection interval Minimum value for the connection event interval. This shall be less than or equal to max_interval 7-8 uint16 max_interval Time = Value x 1.25 ms Range: 0x0006 to 0x0c80 Time Range: 7.5 ms to 4 s Maximum connection interval Maximum value for the connection event interval. This shall be greater than or equal to min_interval 9-10 uint16 latency Time = Value x 1.25 ms Range: 0x0006 to 0x0c80 Time Range: 7.5 ms to 4 s Slave Latency This parameter defines how many intervals the slave can skip if it has no data to send Range: 0x0000 to 0x01f4 11-12 uint16 timeout Use 0x0000 as default Supervision timeout This parameter defines for how long to wait for incoming data via wireless link before timeout disconnection Range: 0x000a to 0x0c80 Time = Value x 10 msec Range: 0x000a to 0x0c80 Time Range: 100 ms to 32 s The minimum value must be atleast maximum interval * (latency + 1) It is recommended to allow the remote end to send at a couple of connection intervals before timeout. 168 Response Byte Type Name 0 1 2 0x20 0x02 0x08 hilen lolen class 3 4-5 0x00 uint16 method result Description Message type: Response Minimum payload length Message class:Connection management for low energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_connection_set_parameters(connection, min_interval, max_interval, latency, timeout)(result) BGLIB C API /* Function */ void dumo_cmd_le_connection_set_parameters(uint8 connection, uint16 min_interval, uint16 max_interval, uint16 latency, uint16 timeout); /* Callback */ struct dumo_msg_le_connection_set_parameters_rsp_t { uint16 result } void dumo_rsp_le_connection_set_parameters( const struct dumo_msg_le_connection_set_parameters_rsp_t *msg ) 169 4.12.2. le_connection events 4.12.2.1. le_connection_opened This event indicates that a new connection was opened. Event 0 1 2 Byte 0xa0 0x0a 0x08 hilen lolen class 3 4-9 10 11 0x00 bd_addr uint8 uint8 method address address_type master Description Message type: Event Minimum payload length Message class:Connection management for low energy Message ID Remote device address Remote device address type Module role in connection connection bonding Values 0: Slave 1: Master Handle for new connection Bonding handle 12 13 Type uint8 uint8 Name Values 0xff: No bonding Other: Bonding handle BGScript event event le_connection_opened(address,address_type,master,connection,bonding) C Functions /* Callback */ struct dumo_msg_le_connection_opened_evt_t { bd_addr address, uint8 address_type, uint8 master, uint8 connection, uint8 bonding } void dumo_evt_le_connection_opened( const struct dumo_msg_le_connection_opened_evt_t *msg ) 170 4.12.2.2. le_connection_closed This event indicates that a connection was closed. Event Byte Type Name 0 1 2 0xa0 0x03 0x08 hilen lolen class 3 4-5 0x01 uint16 method reason Description Message type: Event Minimum payload length Message class:Connection management for low energy Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 connection For other values refer to the Error codes Connection handle BGScript event event le_connection_closed(reason,connection) C Functions /* Callback */ struct dumo_msg_le_connection_closed_evt_t { uint16 reason, uint8 connection } void dumo_evt_le_connection_closed( const struct dumo_msg_le_connection_closed_evt_t *msg ) 171 4.12.2.3. le_connection_parameters This event indicates which connection parameters are in use in the connection. Event Byte Type Name 0 1 2 0xa0 0x08 0x08 hilen lolen class 3 4 5-6 7-8 9-10 11 0x02 uint8 uint16 uint16 uint16 uint8 method connection interval latency timeout security_mode Description Message type: Event Minimum payload length Message class:Connection management for low energy Message ID Connection handle Connection interval Slave latency Supervision timeout Connection security mode BGScript event event le_connection_parameters(connection,interval,latency,timeout,security_mode) C Functions /* Callback */ struct dumo_msg_le_connection_parameters_evt_t { uint8 connection, uint16 interval, uint16 latency, uint16 timeout, uint8 security_mode } void dumo_evt_le_connection_parameters( const struct dumo_msg_le_connection_parameters_evt_t *msg ) 172 4.12.3. le_connection enumerations 4.12.3.1. le_connection_security These values indicate the Bluetooth LE Security Mode. Enumerations Value 0 1 2 Name le_connection_mode1_level1 le_connection_mode1_level2 le_connection_mode1_level3 173 Description No security Unauthenticated pairing with encryption Authenticated pairing with encryption 4.13. Generic Access Profile, Low Energy (le_gap) Generic Access Profile related commands for Bluetooth LE. 4.13.1. le_gap commands 4.13.1.1. le_gap_discover This command can be used to start Bluetooth LE discovery procedure. Command Byte Type Name 0 1 2 0x20 0x01 0x03 hilen lolen class 3 4 0x02 uint8 method mode Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID LE Discovery mode. For values see link Response Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4-5 0x02 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_gap_discover(mode)(result) 174 BGLIB C API /* Function */ void dumo_cmd_le_gap_discover(uint8 mode); /* Callback */ struct dumo_msg_le_gap_discover_rsp_t { uint16 result } void dumo_rsp_le_gap_discover( const struct dumo_msg_le_gap_discover_rsp_t *msg ) Events generated Event le_gap_scan_response Description Discovered device scan response 175 4.13.1.2. le_gap_end_procedure This command can be used to end a current GAP procedure. Command Byte Type Name 0 1 2 0x20 0x00 0x03 hilen lolen class 3 0x03 method Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Response Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4-5 0x03 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_gap_end_procedure()(result) BGLIB C API /* Function */ void dumo_cmd_le_gap_end_procedure(); /* Callback */ struct dumo_msg_le_gap_end_procedure_rsp_t { uint16 result } void dumo_rsp_le_gap_end_procedure( const struct dumo_msg_le_gap_end_procedure_rsp_t *msg ) 176 4.13.1.3. le_gap_open This command can be used to initiate a Bluetooth LE connection procedure. Command Byte Type Name 0 1 2 0x20 0x07 0x03 hilen lolen class 3 4-9 10 0x00 bd_addr uint8 method address address_type Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Address to connect to Address type to connect Response Byte Type Name 0 1 2 0x20 0x03 0x03 hilen lolen class 3 4-5 0x00 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred 6 uint8 connection For other values refer to the Error codes Handle to be used for GATT, valid only if result was success BGScript API call le_gap_open(address, address_type)(result, connection) BGLIB C API /* Function */ void dumo_cmd_le_gap_open(bd_addr address, uint8 address_type); /* Callback */ struct dumo_msg_le_gap_open_rsp_t { uint16 result, uint8 connection } void dumo_rsp_le_gap_open( const struct dumo_msg_le_gap_open_rsp_t *msg ) 177 Events generated Event le_connection_opened Description LE connection has been opened 178 4.13.1.4. le_gap_set_adv_data This command can be used to set the advertisement data when advertising in user data mode. It is recommended to set both the advertisiment data and scan response data at the same time. Command Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4 0x07 uint8 method scan_rsp 5 uint8array adv_data Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Selects which advertisement data is modified Values 0: set adv data 1: set scan rsp Data to be set Maximum length is 30 bytes Response Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4-5 0x07 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_gap_set_adv_data(scan_rsp, adv_data_len, adv_data_data)(result) 179 BGLIB C API /* Function */ void dumo_cmd_le_gap_set_adv_data(uint8 scan_rsp, uint8 adv_data_len, const uint8 *adv_data_data); /* Callback */ struct dumo_msg_le_gap_set_adv_data_rsp_t { uint16 result } void dumo_rsp_le_gap_set_adv_data( const struct dumo_msg_le_gap_set_adv_data_rsp_t *msg ) 180 4.13.1.5. le_gap_set_adv_parameters This command can be used to set Bluetooth LE advertisement parameters. Command Byte Type Name 0 1 2 0x20 0x05 0x03 hilen lolen class 3 4-5 0x04 uint16 method interval_min 6-7 uint16 interval_max Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Minimum connection interval Value multiplied by 0.625 ms Range: 0x0020 to 0x4000 Time range: 20 ms to 10.24 s Maximum connection interval Value multiplied by 0.625 ms Range: 0x0020 to 0x4000 Time range: 20 ms to 10.24 s 8 uint8 channel_map Note: interval_max must be atleast equal to or bigger than interval_min Channel map which determines on which channels to advertise given as a bit mask. Values 1: Advertise on CH37 2: Advertise on CH38 3: Advertise on CH37 and CH38 4: Advertise on CH39 5: Advertise on CH37 and CH39 6: Advertise on CH38 and CH39 7: Advertise on all channels Recommended value: 7 (0x7) 181 Response Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4-5 0x04 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_gap_set_adv_parameters(interval_min, interval_max, channel_map)(result) BGLIB C API /* Function */ void dumo_cmd_le_gap_set_adv_parameters(uint16 interval_min, uint16 interval_max, uint8 channel_map); /* Callback */ struct dumo_msg_le_gap_set_adv_parameters_rsp_t { uint16 result } void dumo_rsp_le_gap_set_adv_parameters( const struct dumo_msg_le_gap_set_adv_parameters_rsp_t *msg ) 182 4.13.1.6. le_gap_set_conn_parameters Set default LE Connection parameters 183 Command Byte Type Name 0 1 2 0x20 0x08 0x03 hilen lolen class 3 4-5 0x05 uint16 method min_interval Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Minimum connection interval Minimum value for the connection event interval. This shall be less than or equal to max_interval 6-7 uint16 max_interval Time = Value x 1.25 ms Range: 0x0006 to 0x0c80 Time Range: 7.5 ms to 4 s Maximum connection interval Maximum value for the connection event interval. This shall be greater than or equal to min_interval 8-9 uint16 latency Time = Value x 1.25 ms Range: 0x0006 to 0x0c80 Time Range: 7.5 ms to 4 s Slave Latency This parameter defines how many intervals the slave can skip if it has no data to send 10-11 uint16 timeout Range: 0x0000 to 0x01F4 Use 0x0000 as default. Supervision timeout This parameter defines for how long to wait for incoming data via wireless link before timeout disconnection Range: 0x000A to 0x0C80 Time = Value x 10 msec Range: 0x000A to 0x0C80 Time Range: 100 ms to 32 s The minimum value must be atleast maximum interval * (latency + 1) It is recommended to allow the remote end to send at a couple of connection intervals before timeout 184 Response Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4-5 0x05 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_gap_set_conn_parameters(min_interval, max_interval, latency, timeout)(result) BGLIB C API /* Function */ void dumo_cmd_le_gap_set_conn_parameters(uint16 min_interval, uint16 max_interval, uint16 latency, uint16 timeout); /* Callback */ struct dumo_msg_le_gap_set_conn_parameters_rsp_t { uint16 result } void dumo_rsp_le_gap_set_conn_parameters( const struct dumo_msg_le_gap_set_conn_parameters_rsp_t *msg ) 185 4.13.1.7. le_gap_set_mode This command is used to set Connectable and Discoverable modes. Command Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4 5 0x01 uint8 uint8 method discover connect Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Discoverable mode Connectable mode Response Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4-5 0x01 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_gap_set_mode(discover, connect)(result) BGLIB C API /* Function */ void dumo_cmd_le_gap_set_mode(uint8 discover, uint8 connect); /* Callback */ struct dumo_msg_le_gap_set_mode_rsp_t { uint16 result } void dumo_rsp_le_gap_set_mode( const struct dumo_msg_le_gap_set_mode_rsp_t *msg ) 186 4.13.1.8. le_gap_set_scan_parameters This command can be used to set scan parameters. Command Byte Type Name 0 1 2 0x20 0x05 0x03 hilen lolen class 3 4-5 0x06 uint16 method scan_interval Description Message type: Command Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Scanner interval This is defined as the time interval from when the module started its last LE scan until it begins the subsequent LE scan, i.e. how often to scan Time = Value x 0.625 ms Range: 0x0004 to 0x4000 Time Range: 2.5 ms to 10.24 s 6-7 uint16 scan_window Default: 0x0010 (10 ms) Scan window The duration of the LE scan. scan_window shall be less than or equal to scan_interval Time = Value x 0.625 ms Range: 0x0004 to 0x4000 Time Range: 2.5 ms to 10.24 s 8 uint8 Default: 0x0010 (10 ms) Scan type indicated by a flag active Values 0: Passive scanning 1: Active scanning Default value: 0 In passive scanning mode the module will not send anything In active scanning mode the module will request scan responsed from scannable advertisers 187 Response Byte Type Name 0 1 2 0x20 0x02 0x03 hilen lolen class 3 4-5 0x06 uint16 method result Description Message type: Response Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call le_gap_set_scan_parameters(scan_interval, scan_window, active)(result) BGLIB C API /* Function */ void dumo_cmd_le_gap_set_scan_parameters(uint16 scan_interval, uint16 scan_window, uint8 active); /* Callback */ struct dumo_msg_le_gap_set_scan_parameters_rsp_t { uint16 result } void dumo_rsp_le_gap_set_scan_parameters( const struct dumo_msg_le_gap_set_scan_parameters_rsp_t *msg ) 188 4.13.2. le_gap events 4.13.2.1. le_gap_scan_response Scan Response Event Byte Type Name 0 1 2 0xa0 0x0b 0x03 hilen lolen class 3 4 0x00 int8 method rssi Description Message type: Event Minimum payload length Message class:Generic Access Profile, Low Energy Message ID Received signal strength indicator (RSSI) Range: -127 to +20 5 uint8 packet_type Units: dBm Advertisement packet type Values 0x00: Connectable undirected advertising0x02: Scannable undirected advertising 0x03: Non connectable undirected advertising 0x04: Scan Response 6-11 bd_addr address 12 uint8 address_type 13 14 uint8 uint8array bonding Note: Scan response (0x04) is only received if module is in active scan mode and the previous related packet is also received. Bluetooth address of the remove device Advertiser address type Values 0: Public address 1: Random address Bonding handle if there is known bond for this device Values 0xff: No bonding Other: Bonding handle Advertisement or scan response data data 189 BGScript event event le_gap_scan_response(rssi,packet_type,address,address_type,bonding,data_len,data_data) C Functions /* Callback */ struct dumo_msg_le_gap_scan_response_evt_t { int8 rssi, uint8 packet_type, bd_addr address, uint8 address_type, uint8 bonding, uint8 data_len, const uint8* data_data } void dumo_evt_le_gap_scan_response( const struct dumo_msg_le_gap_scan_response_evt_t *msg ) 190 4.13.3. le_gap enumerations 4.13.3.1. le_gap_connectable_mode These values indicate which connectable mode the module is currently in. Enumerations Value 0 1 2 3 Name le_gap_non_connectable le_gap_directed_connectable Description Not connectable Direct Connectable le_gap_undirected_connectable le_gap_scannable_non_connectable DO NOT USE Undirected connectable Not connectable but responds to scan_req-packets 191 4.13.3.2. le_gap_discoverable_mode These values indicate which discoverable mode the module is to be set in. Enumerations Value 0 1 Name le_gap_non_discoverable le_gap_limited_discoverable 2 le_gap_general_discoverable 3 le_gap_broadcast 4 Description Not discoverable Discoverable using both limited discoverable mode Discoverable using general discoverable mode Limited or general discoverable bits not in flags ad type Device is not discoverable in limited or generic discoverable procedure Send advertisement and/or scan response data defined by user using le_gap_set_adv_data command le_gap_user_data 192 4.13.3.3. le_gap_discover_mode These values indicate which discovery mode to use. Enumerations Value 0 1 Name le_gap_discover_limited le_gap_discover_generic 2 le_gap_discover_observation 193 Description Discover only limited discoverable devices Discover limited and generic discoverable devices Discover all devices 4.14. Security Manager (sm) Security Manager commands are used to start encryption or bonding, and for handling bondings and configuring module security. 4.14.1. sm commands 4.14.1.1. sm_configure Configure security manager requirements and device I/O capabilities. Command Byte 0 1 2 3 4 Type 0x20 0x02 0x0f 0x01 uint8 5 uint8 Name hilen lolen class method mitm_required io_capabilities Description Message type: Command Minimum payload length Message class:Security Manager Message ID Require MITM flag Values 0: Allow bonding without MITM protection : Require MITM protection I/O Capabilities. See link Response Byte 0 1 2 3 Type 0x20 0x00 0x0f 0x01 Name hilen lolen class method Description Message type: Response Minimum payload length Message class:Security Manager Message ID BGScript API call sm_configure(mitm_required, io_capabilities)() BGLIB C API /* Function */ void dumo_cmd_sm_configure(uint8 mitm_required, uint8 io_capabilities); /* Callback */ struct dumo_msg_sm_configure_rsp_t { } void dumo_rsp_sm_configure( const struct dumo_msg_sm_configure_rsp_t *msg ) 194 4.14.1.2. sm_delete_bonding This command can be used to delete specified bonding information from persistent store. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0f 0x06 uint8 Name hilen lolen class method bonding Description Message type: Command Minimum payload length Message class:Security Manager Message ID Bonding handle Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x06 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_delete_bonding(bonding)(result) BGLIB C API /* Function */ void dumo_cmd_sm_delete_bonding(uint8 bonding); /* Callback */ struct dumo_msg_sm_delete_bonding_rsp_t { uint16 result } void dumo_rsp_sm_delete_bonding( const struct dumo_msg_sm_delete_bonding_rsp_t *msg ) 195 4.14.1.3. sm_delete_bondings This command can be used to delete all bonding information from persistent store. Command Byte 0 1 2 3 Type 0x20 0x00 0x0f 0x07 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:Security Manager Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x07 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_delete_bondings()(result) BGLIB C API /* Function */ void dumo_cmd_sm_delete_bondings(); /* Callback */ struct dumo_msg_sm_delete_bondings_rsp_t { uint16 result } void dumo_rsp_sm_delete_bondings( const struct dumo_msg_sm_delete_bondings_rsp_t *msg ) 196 4.14.1.4. sm_enter_passkey This command can be used to enter a passkey after receiving a passkey request event. Command Byte 0 1 2 3 4 5-8 Type 0x20 0x05 0x0f 0x08 uint8 uint32 Name hilen lolen class method connection passkey Description Message type: Command Minimum payload length Message class:Security Manager Message ID Connection handle Passkey Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x08 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_enter_passkey(connection, passkey)(result) BGLIB C API /* Function */ void dumo_cmd_sm_enter_passkey(uint8 connection, uint32 passkey); /* Callback */ struct dumo_msg_sm_enter_passkey_rsp_t { uint16 result } void dumo_rsp_sm_enter_passkey( const struct dumo_msg_sm_enter_passkey_rsp_t *msg ) 197 4.14.1.5. sm_increase_security This command can be used to enhance the security of a connection to current security requirements. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0f 0x04 uint8 Name hilen lolen class method connection Description Message type: Command Minimum payload length Message class:Security Manager Message ID Connection handle Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x04 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_increase_security(connection)(result) BGLIB C API /* Function */ void dumo_cmd_sm_increase_security(uint8 connection); /* Callback */ struct dumo_msg_sm_increase_security_rsp_t { uint16 result } void dumo_rsp_sm_increase_security( const struct dumo_msg_sm_increase_security_rsp_t *msg ) 198 4.14.1.6. sm_list_all_bondings This command can be used to list all bondings stored in the bonding database. Bondings are reported by using the sm_list_bonding_event for each bonding and the report is ended with sm_list_all_bonding_complete event. Recommended to be used only for debugging purposes. Command Byte 0 1 2 3 Type 0x20 0x00 0x0f 0x0b Name hilen lolen class method Description Message type: Command Minimum payload length Message class:Security Manager Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x0b uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_list_all_bondings()(result) BGLIB C API /* Function */ void dumo_cmd_sm_list_all_bondings(); /* Callback */ struct dumo_msg_sm_list_all_bondings_rsp_t { uint16 result } void dumo_rsp_sm_list_all_bondings( const struct dumo_msg_sm_list_all_bondings_rsp_t *msg ) 199 4.14.1.7. sm_passkey_confirm This command can be used for confirming the reported confirm value. Command Byte 0 1 2 3 4 5 Type 0x20 0x02 0x0f 0x09 uint8 uint8 Name hilen lolen class method connection confirm Description Message type: Command Minimum payload length Message class:Security Manager Message ID Connection handle Accept confirm value Values 0: Reject 1: Accept confirm value Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x09 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_passkey_confirm(connection, confirm)(result) BGLIB C API /* Function */ void dumo_cmd_sm_passkey_confirm(uint8 connection, uint8 confirm); /* Callback */ struct dumo_msg_sm_passkey_confirm_rsp_t { uint16 result } void dumo_rsp_sm_passkey_confirm( const struct dumo_msg_sm_passkey_confirm_rsp_t *msg ) 200 4.14.1.8. sm_read_bonding This command can be used to read the encryption key for a specific bonding. Used in debugging for reading encryption keys which can be used e.g. for protocol sniffing. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0f 0x05 uint8 Name hilen lolen class method bonding Description Message type: Command Minimum payload length Message class:Security Manager Message ID Bonding index of bonding data Response Byte 0 1 2 3 4-5 Type 0x20 0x0a 0x0f 0x05 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred 6-11 12 13 bd_addr uint8 uint8array address address_type bonding_key For other values refer to the Error codes Bluetooth address of the remote device Address type Encryption key Maximum 16 bytes BGScript API call sm_read_bonding(bonding)(result, address, address_type, bonding_key_len, bonding_key_data) 201 BGLIB C API /* Function */ void dumo_cmd_sm_read_bonding(uint8 bonding); /* Callback */ struct dumo_msg_sm_read_bonding_rsp_t { uint16 result, bd_addr address, uint8 address_type, uint8 bonding_key_len, const uint8 *bonding_key_data } void dumo_rsp_sm_read_bonding( const struct dumo_msg_sm_read_bonding_rsp_t *msg ) 202 4.14.1.9. sm_read_bonding_configuration This command can be used for reading the maximum allowed bonding count. Command Byte 0 1 2 3 Type 0x20 0x00 0x0f 0x03 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:Security Manager Message ID Response Byte 0 1 2 3 4 5 Type 0x20 0x04 0x0f 0x03 uint8 uint8 Name hilen lolen class method max_bonding_count Description Message type: Response Minimum payload length Message class:Security Manager Message ID Maximum allowed bonding count policy_flags Range: 1 to 32 Bonding policy Values 0: If database is full bonding fails 1: New bonding will overwrite the oldest existing bond 6-7 uint16 NOT IMPLEMENTED YET Result code result 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_read_bonding_configuration()(max_bonding_count, policy_flags, result) 203 BGLIB C API /* Function */ void dumo_cmd_sm_read_bonding_configuration(); /* Callback */ struct dumo_msg_sm_read_bonding_configuration_rsp_t { uint8 max_bonding_count, uint8 policy_flags, uint16 result } void dumo_rsp_sm_read_bonding_configuration( const struct dumo_msg_sm_read_bonding_configuration_rsp_t *msg ) 204 4.14.1.10. sm_set_bondable_mode This command can be used to set the device into bondable mode. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0f 0x00 uint8 Name hilen lolen class method bondable Description Message type: Command Minimum payload length Message class:Security Manager Message ID Bondable mode Values 0: New bondings not accepted 1: Bondings allowed Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_set_bondable_mode(bondable)(result) BGLIB C API /* Function */ void dumo_cmd_sm_set_bondable_mode(uint8 bondable); /* Callback */ struct dumo_msg_sm_set_bondable_mode_rsp_t { uint16 result } void dumo_rsp_sm_set_bondable_mode( const struct dumo_msg_sm_set_bondable_mode_rsp_t *msg ) 205 4.14.1.11. sm_set_oob_data This command can be used to set the oob data (out-of-band encryption data) for a device. The oob data is commonly referred to as the PIN code. The device does not allow any other kind of pairing except oob if oob data is set. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0f 0x0a uint8array Name hilen lolen class method oob Description Message type: Command Minimum payload length Message class:Security Manager Message ID OOB data Values Empty: Clear oob data 16 bytes: Set oob data to value Response Byte 0 1 2 3 Type 0x20 0x00 0x0f 0x0a Name hilen lolen class method Description Message type: Response Minimum payload length Message class:Security Manager Message ID BGScript API call sm_set_oob_data(oob_len, oob_data)() BGLIB C API /* Function */ void dumo_cmd_sm_set_oob_data(uint8 oob_len, const uint8 *oob_data); /* Callback */ struct dumo_msg_sm_set_oob_data_rsp_t { } void dumo_rsp_sm_set_oob_data( const struct dumo_msg_sm_set_oob_data_rsp_t *msg ) 206 4.14.1.12. sm_store_bonding_configuration Set maximum allowed bonding count. Command Byte 0 1 2 3 4 Type 0x20 0x02 0x0f 0x02 uint8 5 uint8 Name hilen lolen class method max_bonding_count Description Message type: Command Minimum payload length Message class:Security Manager Message ID Maximum allowed bonding count policy_flags Range: 1 to 32 Bonding policy Values 0: If database is full bonding fails 1: New bonding will overwrite the oldest existing bond NOT IMPLEMENTED YET Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0f 0x02 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:Security Manager Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call sm_store_bonding_configuration(max_bonding_count, policy_flags)(result) 207 BGLIB C API /* Function */ void dumo_cmd_sm_store_bonding_configuration(uint8 max_bonding_count, uint8 policy_flags); /* Callback */ struct dumo_msg_sm_store_bonding_configuration_rsp_t { uint16 result } void dumo_rsp_sm_store_bonding_configuration( const struct dumo_msg_sm_store_bonding_configuration_rsp_t *msg ) 208 4.14.2. sm events 4.14.2.1. sm_passkey_display This event indicates a request to display the passkey to the user. Event Byte 0 1 2 3 4 5-8 Type 0xa0 0x05 0x0f 0x00 uint8 uint32 Name hilen lolen class method connection passkey Description Message type: Event Minimum payload length Message class:Security Manager Message ID Connection handle Passkey Range: 0 to 999999 NOTE! When displaying the passkey to the user insert prefix zeros in order to obtain a 6 digit number Example: Passkey value is 42 Number to display to user is 000042 BGScript event event sm_passkey_display(connection,passkey) C Functions /* Callback */ struct dumo_msg_sm_passkey_display_evt_t { uint8 connection, uint32 passkey } void dumo_evt_sm_passkey_display( const struct dumo_msg_sm_passkey_display_evt_t *msg ) 209 4.14.2.2. sm_passkey_request This event indicates a request for the user to enter the passkey displayed on the other device. Event Byte 0 1 2 3 4 Type 0xa0 0x01 0x0f 0x01 uint8 Name hilen lolen class method connection Description Message type: Event Minimum payload length Message class:Security Manager Message ID Connection handle BGScript event event sm_passkey_request(connection) C Functions /* Callback */ struct dumo_msg_sm_passkey_request_evt_t { uint8 connection } void dumo_evt_sm_passkey_request( const struct dumo_msg_sm_passkey_request_evt_t *msg ) 210 4.14.2.3. sm_confirm_passkey This event indicates a request to display the passkey to the user and for the user to confirm the displayed passkey. Event Byte 0 1 2 3 4 5-8 Type 0xa0 0x05 0x0f 0x02 uint8 uint32 Name hilen lolen class method connection passkey Description Message type: Event Minimum payload length Message class:Security Manager Message ID Connection handle Passkey Range: 0 to 999999 NOTE! When displaying the passkey to the user insert prefix zeros in order to obtain a 6 digit number Example: Passkey value is 42 Number to display to user is 000042 BGScript event event sm_confirm_passkey(connection,passkey) C Functions /* Callback */ struct dumo_msg_sm_confirm_passkey_evt_t { uint8 connection, uint32 passkey } void dumo_evt_sm_confirm_passkey( const struct dumo_msg_sm_confirm_passkey_evt_t *msg ) 211 4.14.2.4. sm_bonded This event indicates that the pairing procedure is completed. Event Byte 0 1 2 3 4 5 Type 0xa0 0x02 0x0f 0x03 uint8 uint8 Name hilen lolen class method connection bonding Description Message type: Event Minimum payload length Message class:Security Manager Message ID Connection handle Bonding handle Values 0xff: Procedure completed but bonding was not created Other: Procedure completed, bonding handle BGScript event event sm_bonded(connection,bonding) C Functions /* Callback */ struct dumo_msg_sm_bonded_evt_t { uint8 connection, uint8 bonding } void dumo_evt_sm_bonded( const struct dumo_msg_sm_bonded_evt_t *msg ) 212 4.14.2.5. sm_bonding_failed This event indicates that bonding procedure failed. Event Byte 0 1 2 3 4 5-6 Type 0xa0 0x03 0x0f 0x04 uint8 uint16 Name hilen lolen class method connection reason BGScript event event sm_bonding_failed(connection,reason) C Functions /* Callback */ struct dumo_msg_sm_bonding_failed_evt_t { uint8 connection, uint16 reason } void dumo_evt_sm_bonding_failed( const struct dumo_msg_sm_bonding_failed_evt_t *msg ) 213 Description Message type: Event Minimum payload length Message class:Security Manager Message ID Connection handle Describes error that occurred during bonding 4.14.2.6. sm_list_bonding_entry This event indicates a single bonding entry. Event Byte 0 1 2 3 4 5-10 11 Type 0xa0 0x08 0x0f 0x05 uint8 bd_addr uint8 Name hilen lolen class method bonding address address_type Description Message type: Event Minimum payload length Message class:Security Manager Message ID Bonding index of bonding data Bluetooth address of the remote device Address type BGScript event event sm_list_bonding_entry(bonding,address,address_type) C Functions /* Callback */ struct dumo_msg_sm_list_bonding_entry_evt_t { uint8 bonding, bd_addr address, uint8 address_type } void dumo_evt_sm_list_bonding_entry( const struct dumo_msg_sm_list_bonding_entry_evt_t *msg ) 214 4.14.2.7. sm_list_all_bondings_complete This event indicates that listing of bonding entries is completed. Event Byte 0 1 2 3 Type 0xa0 0x00 0x0f 0x06 Name hilen lolen class method Description Message type: Event Minimum payload length Message class:Security Manager Message ID BGScript event event sm_list_all_bondings_complete() C Functions /* Callback */ struct dumo_msg_sm_list_all_bondings_complete_evt_t { } void dumo_evt_sm_list_all_bondings_complete( const struct dumo_msg_sm_list_all_bondings_complete_evt_t *msg ) 215 4.14.3. sm enumerations 4.14.3.1. sm_bonding_key These values define the bonding information of the bonded device stored in persistent store. Enumerations 1 2 4 8 Value Name sm_bonding_key_ltk sm_bonding_key_addr_public sm_bonding_key_addr_static sm_bonding_key_irk 16 32 64 sm_bonding_key_edivrand sm_bonding_key_csrk sm_bonding_key_masterid 216 Description LTK saved in master Public Address Static Address Identity resolving key for resolvable private addresses EDIV+RAND received from slave Connection signature resolving key EDIV+RAND sent to master 4.14.3.2. sm_io_capability These values define the security management related I/O capabilities supported by the module Enumerations Value 0 1 2 3 4 Name sm_io_capability_displayonly sm_io_capability_displayyesno sm_io_capability_keyboardonly sm_io_capability_noinputnooutput sm_io_capability_keyboarddisplay 217 Description Display Only Display with Yes/No-buttons Keyboard Only No Input and No Output Display with Keyboard 4.15. System (system) System class provides simple functions to access and query the local device. 4.15.1. system commands 4.15.1.1. system_get_bt_address This command can be used to read the Bluetooth address used by the module. Command Byte 0 1 2 3 Type 0x20 0x00 0x01 0x03 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:System Message ID Response Byte 0 1 2 3 4-9 Type 0x20 0x06 0x01 0x03 bd_addr Name hilen lolen class method address Description Message type: Response Minimum payload length Message class:System Message ID Local devices BR/EDR Bluetooth address and BLE public address in little endian format. BGScript API call system_get_bt_address()(address) BGLIB C API /* Function */ void dumo_cmd_system_get_bt_address(); /* Callback */ struct dumo_msg_system_get_bt_address_rsp_t { bd_addr address } void dumo_rsp_system_get_bt_address( const struct dumo_msg_system_get_bt_address_rsp_t *msg ) 218 4.15.1.2. system_get_class_of_device This command can be used to read the device's Class Of Device (COD) information. Command Byte 0 1 2 3 Type 0x20 0x00 0x01 0x04 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:System Message ID Response Byte 0 1 2 3 4-7 8-9 Type 0x20 0x06 0x01 0x04 uint32 uint16 Name hilen lolen class method cod Description Message type: Response Minimum payload length Message class:System Message ID Class of Device Follows conventions listed in the Bluetooth specification published by Bluetooth SIG Example: 0x001f00 Uncategorized device Result code result 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call system_get_class_of_device()(cod, result) BGLIB C API /* Function */ void dumo_cmd_system_get_class_of_device(); /* Callback */ struct dumo_msg_system_get_class_of_device_rsp_t { uint32 cod, uint16 result } void dumo_rsp_system_get_class_of_device( const struct dumo_msg_system_get_class_of_device_rsp_t *msg ) 219 4.15.1.3. system_get_local_name This command can be used to read the friendly name of the local BR/EDR device. Note that for Bluetooth LE the device name is stored in the GAP Service of the GATT database. Command Byte 0 1 2 3 Type 0x20 0x00 0x01 0x08 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:System Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x03 0x01 0x08 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:System Message ID Result code 0 : success Non-zero : an error occurred 6 uint8array For other values refer to the Error codes Local devices Bluetooth BR/EDR friendly name name BGScript API call system_get_local_name()(result, name_len, name_data) BGLIB C API /* Function */ void dumo_cmd_system_get_local_name(); /* Callback */ struct dumo_msg_system_get_local_name_rsp_t { uint16 result, uint8 name_len, const uint8 *name_data } void dumo_rsp_system_get_local_name( const struct dumo_msg_system_get_local_name_rsp_t *msg ) 220 4.15.1.4. system_hello This command can be used to check whether the communication between the software and hardware works. Command Byte 0 1 2 3 Type 0x20 0x00 0x01 0x00 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:System Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x01 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:System Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call system_hello()(result) BGLIB C API /* Function */ void dumo_cmd_system_hello(); /* Callback */ struct dumo_msg_system_hello_rsp_t { uint16 result } void dumo_rsp_system_hello( const struct dumo_msg_system_hello_rsp_t *msg ) 221 4.15.1.5. system_reset This command can be used to reset the system. It does not have a response, but it triggers one of the boot events (normal reset or boot to DFU mode). Command Byte 0 1 2 3 4 Type 0x20 0x01 0x01 0x01 uint8 Name hilen lolen class method dfu Description Message type: Command Minimum payload length Message class:System Message ID Boot mode: 0:Normal reset 1:Boot to DFU mode C o m m a n d d o e s n o t h a v e r e s p o n s e BGScript API call system_reset(dfu) 222 BGLIB C API /* Function */ void dumo_cmd_system_reset(uint8 dfu); /* Command does not have callback */ Events generated Event Description system_boot Sent after the device has booted to normal mode dfu_boot Sent after the device has booted to DFU mode 223 4.15.1.6. system_reset_factory_settings This command can be used to clear all settings including all pairing information. This command resets also the friendly name to default value. Also cleared are the iAP configuration and the PS Store (persistent store). Note that Bluetooth address is conserved. Command Byte 0 1 2 3 Type 0x20 0x00 0x01 0x06 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:System Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x01 0x06 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:System Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call system_reset_factory_settings()(result) BGLIB C API /* Function */ void dumo_cmd_system_reset_factory_settings(); /* Callback */ struct dumo_msg_system_reset_factory_settings_rsp_t { uint16 result } void dumo_rsp_system_reset_factory_settings( const struct dumo_msg_system_reset_factory_settings_rsp_t *msg ) 224 4.15.1.7. system_set_class_of_device This command is used to set the Class Of Device (COD) setting.. Command Byte 0 1 2 3 4-7 Type 0x20 0x04 0x01 0x05 uint32 Name hilen lolen class method cod Description Message type: Command Minimum payload length Message class:System Message ID Class of Device Follows conventions listed in the Bluetooth specification published by Bluetooth SIG Example: 0x001f00 Uncategorized device Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x01 0x05 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:System Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call system_set_class_of_device(cod)(result) BGLIB C API /* Function */ void dumo_cmd_system_set_class_of_device(uint32 cod); /* Callback */ struct dumo_msg_system_set_class_of_device_rsp_t { uint16 result } void dumo_rsp_system_set_class_of_device( const struct dumo_msg_system_set_class_of_device_rsp_t *msg ) 225 4.15.1.8. system_set_local_name This command can be used to set the local devices Bluetooth BR/EDR friendly name. For BLE the device name should be stored in the GAP Service local name parameter of the GATT database. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x01 0x07 uint8array Name hilen lolen class method name Description Message type: Command Minimum payload length Message class:System Message ID Local devices Bluetooth BR/EDR friendly name. Maximum name length is 30 bytes Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x01 0x07 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:System Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call system_set_local_name(name_len, name_data)(result) BGLIB C API /* Function */ void dumo_cmd_system_set_local_name(uint8 name_len, const uint8 *name_data); /* Callback */ struct dumo_msg_system_set_local_name_rsp_t { uint16 result } void dumo_rsp_system_set_local_name( const struct dumo_msg_system_set_local_name_rsp_t *msg ) 226 4.15.1.9. system_set_max_power_mode This command can be used to set the maximum power saving state allowed for the system. Command Byte 0 1 2 3 4 Type 0x20 0x01 0x01 0x02 uint8 Name hilen lolen class method power_mode Description Message type: Command Minimum payload length Message class:System Message ID Maximum power mode. Values 1: CPU allowed to enter idle mode 2: CPU allowed to enter idle and sleep modes Default: 2 See BT121 data sheet for details concerning power modes. Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x01 0x02 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:System Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call system_set_max_power_mode(power_mode)(result) 227 BGLIB C API /* Function */ void dumo_cmd_system_set_max_power_mode(uint8 power_mode); /* Callback */ struct dumo_msg_system_set_max_power_mode_rsp_t { uint16 result } void dumo_rsp_system_set_max_power_mode( const struct dumo_msg_system_set_max_power_mode_rsp_t *msg ) 228 4.15.2. system events 4.15.2.1. system_boot This event indicates the device has started and is ready to receive commands. Event Byte 0 1 2 3 4-5 6-7 8-9 10-11 12-13 14-15 Type 0xa0 0x0c 0x01 0x00 uint16 uint16 uint16 uint16 uint16 uint16 Name hilen lolen class method major minor patch build bootloader hw Description Message type: Event Minimum payload length Message class:System Message ID Major release version Minor release version Patch release number Build number Bootloader version Hardware type BGScript event event system_boot(major,minor,patch,build,bootloader,hw) C Functions /* Callback */ struct dumo_msg_system_boot_evt_t { uint16 major, uint16 minor, uint16 patch, uint16 build, uint16 bootloader, uint16 hw } void dumo_evt_system_boot( const struct dumo_msg_system_boot_evt_t *msg ) 229 4.15.2.2. system_initialized This event indicates that Bluetooth radio is initialized and is ready to be used. Event Byte 0 1 2 3 4-9 Type 0xa0 0x06 0x01 0x01 bd_addr Name hilen lolen class method address Description Message type: Event Minimum payload length Message class:System Message ID Bluetooth address in BR/EDR or public address in LE in little endian format BGScript event event system_initialized(address) C Functions /* Callback */ struct dumo_msg_system_initialized_evt_t { bd_addr address } void dumo_evt_system_initialized( const struct dumo_msg_system_initialized_evt_t *msg ) 230 4.16. testing commands (test) Command used in production testing, RF development testing and for debug support. 4.16.1. test commands 4.16.1.1. test_device_under_test_mode This command can be used to enable the DUT mode (Device Under Test). Command Byte 0 1 2 3 Type 0x20 0x00 0x0e 0x02 Name hilen lolen class method Description Message type: Command Minimum payload length Message class:testing commands Message ID Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0e 0x02 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:testing commands Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call test_device_under_test_mode()(result) BGLIB C API /* Function */ void dumo_cmd_test_device_under_test_mode(); /* Callback */ struct dumo_msg_test_device_under_test_mode_rsp_t { uint16 result } void dumo_rsp_test_device_under_test_mode( const struct dumo_msg_test_device_under_test_mode_rsp_t *msg ) 231 4.16.1.2. test_ssp_debug Turn simple pairing debug key on Command Byte 0 1 2 3 4 Type 0x20 0x01 0x0e 0x01 uint8 Name hilen lolen class method enable Description Message type: Command Minimum payload length Message class:testing commands Message ID debug enable flag Response Byte 0 1 2 3 Type 0x20 0x00 0x0e 0x01 Name hilen lolen class method BGScript API call test_ssp_debug(enable)() BGLIB C API /* Function */ void dumo_cmd_test_ssp_debug(uint8 enable); /* Callback */ struct dumo_msg_test_ssp_debug_rsp_t { } void dumo_rsp_test_ssp_debug( const struct dumo_msg_test_ssp_debug_rsp_t *msg ) 232 Description Message type: Response Minimum payload length Message class:testing commands Message ID 4.16.1.3. test_tx_test This command can be used to start the TX test mode with continuous transmission. Command Byte 0 1 2 3 4 Type 0x20 0x03 0x0e 0x00 uint8 Name hilen lolen class method modulation 5 uint8 channel 6 uint8 power Description Message type: Command Minimum payload length Message class:testing commands Message ID Modulation type Values 0: CW 1: 1 Mbit GFSK 2: 2 Mbit Pi/4-DQPSK 3: 3 Mbit 8-PSK 4: 1 Mbit GFSK (BLE) Bluetooth channel/frequency to use in testing Range 0 to 76 F = 2402 + 2k, when k from 0 to 39 F = 2403 +2(k-40) when k from 40 to 78 TX power level Range: 0 to 15 0: Max TX power 15: Min TX power Response Byte 0 1 2 3 4-5 Type 0x20 0x02 0x0e 0x00 uint16 Name hilen lolen class method result Description Message type: Response Minimum payload length Message class:testing commands Message ID Result code 0 : success Non-zero : an error occurred For other values refer to the Error codes BGScript API call test_tx_test(modulation, channel, power)(result) 233 BGLIB C API /* Function */ void dumo_cmd_test_tx_test(uint8 modulation, uint8 channel, uint8 power); /* Callback */ struct dumo_msg_test_tx_test_rsp_t { uint16 result } void dumo_rsp_test_tx_test( const struct dumo_msg_test_tx_test_rsp_t *msg ) 234 4.17. Utilities for BGScript (util) Utilities for simplifying BGScript development. These commands are typically not used in any other applications. 4.17.1. util commands 4.17.1.1. util_atoi Convers decimal value in ascii string to 32bit signed integer Command Byte 0 1 2 3 4 Type 0x20 0x01 0x11 0x00 uint8array Name hilen lolen class method string Description Message type: Command Minimum payload length Message class:Utilities for BGScript Message ID String to convert Response Byte 0 1 2 3 4-7 Type 0x20 0x04 0x11 0x00 int32 Name hilen lolen class method value Description Message type: Response Minimum payload length Message class:Utilities for BGScript Message ID Conversion result presenting the decimal value input as a string as a 32-bit signed integer value BGScript API call util_atoi(string_len, string_data)(value) BGLIB C API /* Function */ void dumo_cmd_util_atoi(uint8 string_len, const uint8 *string_data); /* Callback */ struct dumo_msg_util_atoi_rsp_t { int32 value } void dumo_rsp_util_atoi( const struct dumo_msg_util_atoi_rsp_t *msg ) 235 4.17.1.2. util_itoa This command can be used to convert a 32-bit signed integer value into a decimal value presented as a string. Command Byte 0 1 2 3 4-7 Type 0x20 0x04 0x11 0x01 int32 Name hilen lolen class method value Description Message type: Command Minimum payload length Message class:Utilities for BGScript Message ID 32-bit number to convert Response Byte 0 1 2 3 4 Type 0x20 0x01 0x11 0x01 uint8array Name hilen lolen class method string BGScript API call util_itoa(value)(string_len, string_data) BGLIB C API /* Function */ void dumo_cmd_util_itoa(int32 value); /* Callback */ struct dumo_msg_util_itoa_rsp_t { uint8 string_len, const uint8 *string_data } void dumo_rsp_util_itoa( const struct dumo_msg_util_itoa_rsp_t *msg ) 236 Description Message type: Response Minimum payload length Message class:Utilities for BGScript Message ID Conversion result presenting the 32-bit signed integer value input as a decimal value presented by a string 4.18. Error codes Errors related to hardware Code 0x0501 0x0502 0x0503 0x0504 0x0505 Name ps_store_full ps_key_not_found i2c_ack_missing i2c_timeout not_configured Description PS Store is full PS key not found i2c ack missing i2c timeout Not configured Errors related to BGAPI protocol Code 0x0101 0x0102 0x0180 0x0181 0x0182 0x0183 0x0184 0x0185 0x0186 0x0187 0x0188 0x0189 0x018a 0x018b 0x018c 0x018d 0x018e 0x018f 0x0190 0x0191 Name invalid_conn_handle waiting_response invalid_param wrong_state out_of_memory not_implemented invalid_command timeout not_connected flow user_attribute invalid_license_key command_too_long out_of_bonds unspecified hardware buffers_full disconnected too_many_requests not_supported Description Invalid connection handle Waiting response Invalid Parameter Device in Wrong State Out Of Memory Feature Not Implemented Command Not Recognized Timeout Not Connected flow User Attribute Invalid License Key Command Too Long Out of Bonds Unspecified error Hardware failure Internal buffers are full Disconnected Too many requests Feature Not Supported SDP errors Code 0x0601 0x0602 Name record_not_found record_already_exist Description Service Record not found Service Record already exist 237 Errors from Security Manager Protocol Code 0x0301 0x0302 0x0303 0x0304 0x0305 0x0306 0x0307 0x0308 0x0309 0x030a Name passkey_entry_failed oob_not_available authentication_requirements confirm_value_failed pairing_not_supported encryption_key_size command_not_supported unspecified_reason repeated_attempts invalid_parameters Description Passkey Entry Failed OOB Data is not available Authentication Requirements Confirm Value Failed Pairing Not Supported Encryption Key Size Command Not Supported Unspecified Reason Repeated Attempts Invalid Parameters 238 Bluetooth errors Code 0x0204 0x0205 0x0206 0x0207 0x0208 0x0209 0x020a 0x020b 0x020c 0x020d 0x020e 0x020f 0x0210 0x0211 0x0212 0x0213 0x0214 0x0215 0x0216 0x0217 0x0218 0x0219 0x021a 0x021b 0x021c 0x021d 0x021e 0x021f 0x0220 0x0221 0x0222 0x0223 0x0224 0x0225 0x0226 0x0227 0x0228 0x0229 0x022a 0x022c 0x022d 0x022e 0x022f Name Description page_timeout Page Timeout authentication_failure Authentication Failure pin_or_key_missing Pin or Key Missing memory_capacity_exceeded Memory Capacity Exceeded connection_timeout Connection Timeout connection_limit_exceeded Connection Limit Exceeded synchronous_connectiontion_limit_exceed Synchronous connection limit to a device ed exceeded acl_connection_already_exists ACL Connection already exists command_disallowed Command Disallowed connection_rejected_due_to_limited_reso Connection rejected due to limited urces resources connection_rejected_due_to_security_rea Connection rejected due to security sons reasons connection_rejected_due_to_unacceptabl Connection rejected due to unacceptable e_bd_addr Bluetooth address connection_accept_timeout_exceeded Connection accept timeout exceeded unsupported_feature_or_parameter_value Unsupported feature or parameter value invalid_command_parameters Invalid Command Parameters remote_user_terminated Remote User Terminated Connection remote_device_terminated_connection_d Remote device terminated connection due ue_to_low_resources to low resources remote_powering_off Remote Device Terminated Connection due to Power Off connection_terminated_by_local_host Connection Terminated by Local Host repeated_attempts Repeated attempts pairing_not_allowed Pairing not allowed unknown_lmp_pdu Unknown LMP PDU unsupported_remote_feature Unsupported remote feature / unsupported LMP feature sco_offset_rejected SCO offset rejected sco_interval_rejected SCO interval rejected sco_air_mode_rejected SCO air mode rejected invalid_lmp_parameters Invalid LMP parameters / Invalid LL parameters unspecified_error Unspecified error unsupported_lmp_parameter_value Unsupported LMP Parameter value / unsupported LL parameter value role_change_not_allowed Role change not allowed ll_response_timeout LL Response Timeout lmp_error_transaction_collision LMP error transaction collision lmp_pdu_not_allowed LMP PDU not allowed encryption_mode_not_acceptable Encryption mode not acceptable link_key_cannot_be_changed Link key cannot be changed requested_qos_not_supported Requested QoS not supported instant_passed Instant passed pairing_with_unit_key_not_supported Pairing with unit key not supported different_transaction_collision Different transaction collision qos_unacceptable_parameter QoS unacceptable parameter qos_rejected QoS rejected channel_assesment_not_supported Channel assessment not supported insufficient_security Insufficient security 239 0x0230 0x0232 0x0234 0x0235 0x0236 0x0237 0x0238 0x0239 parameter_out_of_mandatory_range Parameter out of mandatory range role_switch_pending Role switch pending reserved_slot_violation Reserved slot violation role_switch_failed Role switch failed extended_inquiry_response_too_large Extended inquiry response too large simple_pairing_not_supported_by_host Simple pairing not supported by host host_busy_pairing Host bysy-pairing connection_rejected_due_to_no_suitable_ Connection rejected due to no suitable channel_found channel found controller_busy Controller Busy unacceptable_connection_interval Unacceptable Connection Interval directed_advertising_timeout Directed Advertising Timeout connection_terminated_due_to_mic_failur MIC Failure e connection_failed_to_be_established Connection Failed to be Established mac_connection_failed MAC connection failed coarse_clock_adjustment_rejected_but_w Coarse clock adjustment rejected but will ill_try_to_adjust_using_clock_dragging try to adjust using clock dragging 0x023a 0x023b 0x023c 0x023d 0x023e 0x023f 0x0240 Application errors Code 0x0a01 0x0a02 0x0a03 0x0a04 Name file_open_failed xml_parse_failed device_connection_failed device_comunication_failed Description File open failed XML parse failed Device connection failed Device communication failed Errors from Attribute Protocol Code 0x0401 0x0402 0x0403 0x0404 0x0405 0x0406 0x0407 0x0408 0x0409 0x040a 0x040b 0x040c 0x040d 0x040e 0x040f 0x0410 0x0411 0x0480 Name invalid_handle read_not_permitted write_not_permitted invalid_pdu insufficient_authentication request_not_supported invalid_offset insufficient_authorization prepare_queue_full att_not_found att_not_long insufficient_enc_key_size invalid_att_length unlikely_error insufficient_encryption unsupported_group_type insufficient_resources application Description Invalid Handle Read Not Permitted Write Not Permitted Invalid PDU Insufficient Authentication Request Not Supported Invalid Offset Insufficient Authorization Prepare Queue Full Attribute Not Found Attribute Not Long Insufficient Encryption Key Size Invalid Attribute Value Length Unlikely Error Insufficient Encryption Unsupported Group Type Insufficient Resources Application Error Codes Filesystem errors Code 0x0901 Name Description file_not_found File not found 240 Contact information Sales: www.bluegiga.com Technical Support: www.bluegiga.com/support Orders: [email protected] WWW: www.bluegiga.com SILICON LABS Phone: +1 877.444.3032 400 West Cesar Chavez Austin, TX 78701 USA FINLAND OFFICE Phone: +358 9 435 5060 Fax: +358 9 435 50660 Sinikalliontie 5A, 5th floor 02630 Espoo, Finland