Bluetooth Smart Ready Software API Reference Manual for BT121

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