Document number: 23330871
Release: Apr 14, 2015 15:45
Document version: 3
This document describes how to develop customer specific applications on the connectBlue cB-OBS421 module using the cB-OBP421 SDK (a subset of the connectBlue Serial Port Adapter application and the connectBlue Embedded Bluetooth Stack). When a custom application is embedded in the OBS421 module, the module is referred to as OBP421. To get access to the cB-OBP421 SDK, the OBP421 Development kit cB-WDK-12-A must be purchased and the cB-OBP421 Software license agreement (SLA) must be signed and sent to connectBlue.
Please note that this document is not intended as a complete system description. It is intended to be an overview and for details the header files and sample projects must be used.
Currently the following modules are supported:
The supported modules are further on referred to as OBP421.
Table of Content
- 1 Abstract
- 2 Table of Content
- 3 Related Documents
- 4 Overview
- 5 Development Environment
- 5.1 Visual Studio
- 5.2 GNU Toolchain for ARM Processors
- 5.3 Additional Build Tools
- 5.4 Debugging Environment
- 5.5 connectBlue Flash Loader
- 6 Flash Memory Configuration
- 7 Sample Applications
- 7.1 Initialization & Configuration
- 7.2 AT (obp_at.h/c)
- 7.3 External AT Commands (obp_ext_at_cmds.h/c)
- 7.4 Bluetooth Echo demo (obp_app.h/c)
- 7.5 Bluetooth GATT demo (obp_app.h/c)
- 7.6 Sample Project Memory Configuration
- 8 SPA
- 8.1 Bluetooth
- 8.2 AT Parser
- 8.3 LED
- 9 Run-Time Support Library
- 9.1 Operating System (cbOS)
- 9.1.1 Start Sequence
- 9.1.2 Create Process
- 9.1.3 Send Event and Message
- 9.1.4 Mutual Exclusion and Interrupts
- 9.1.5 Dynamic Memory Allocation
- 9.1.6 Watchdog
- 9.2 Assert (cb_ASSERT)
- 9.3 Power Management (cbPM)
- 9.4 Timer (cbTIMER)
- 9.5 Non-Volatile Data Storage (cbNVDS)
- 9.6 Peripheral Input/Output (cbPIO)
- 9.7 UART (cbUART)
- 10 Mandatory Test Requirement
- 11 Appendix A
- The cB-OBS421 Electrical Mechanical Datasheet contains important information about the Bluetooth OEM Serial Port Adapter.
- The cB-OBP421 Electrical Addendum Data Sheet describes the available interfaces and signals on a lower level not specific for the Bluetooth OEM Serial Port Adapter product. Consider this as an addition to the Bluetooth Serial Port Adapter Electrical Mechanical Datasheet.
- The cB-OBP421 SDK is the software development kit that enables customers to develop applications embedded in the OBS421 module.
- The describes the contents of the development kits available for the OBP421.
- The cB-OBP421 Software license agreement is the license agreement that must be signed before using the cB-OBP421 SDK.
- The Bluetooth Qualification Guide describes how to do the Bluetooth End Product listing which is nowadays mandatory. This document is valid both for customers that use the connectBlue Serial Port Adapter product (cB-OBS421) directly and for customers that develop their own applications using the cB-OBP421 platform.
- The Bluetooth Serial Port Adapter - Getting Started document describes the basic concepts and functionality of the connectBlue Serial Port Adapter products.
- The Bluetooth Serial Port Adapter AT Commands document contains a short introduction to the concepts of the Serial Port Adapter as well as a description of the AT commands supported.
- The Serial Port Adapter - Extended Data Mode document describes the Extended Data Mode protocol, which is a lightweight protocol for the serial port to enable individual control of a Bluetooth channel. This is needed to transmit data to a specific Bluetooth channel and to know from what Bluetooth channel data is received.
- The Bluetooth Serial Port Adapter Security document describes the extensions to the security modes, of the cB-OBS421.
- The Bluetooth Low Energy Serial Port Adapter - Getting Started document describes Bluetooth low energy additions to the Serial Port Adapter.
- The connectBlue Low Energy Serial Port Service document describes how this service can be used by other devices/applications.
- The Bluetooth Serial Port Adapter AT Commands GATT document describes the Bluetooth low energy GATT commands that can be used by a Central to read/write attributes of a peripheral.
The cB-OBP421 is a ready-to-use module with a subset of the connectBlue Serial Port Adapter application and the connectBlue embedded Bluetooth stack.
The most important features are:
- Dual-mode which means that both Classic Bluetooth and Bluetooth low energy can be used at the same time.
- Simple Bluetooth handling, which means it is basically enough to implement the connect / dataAvailable / writeComplete event functions and read/write command functions.
- Ready-to-use AT commands. For example, the AT commands to configure the Bluetooth client / server / remote peer functionality (how and when to connect) is available in the same way as for the standard connectBlue Serial Port Adapter.
- Easy to add customer specific AT commands to the existing AT parser.
- The module can be configured using the Serial Port Adapter Toolbox in more or less exactly the same way as the standard connectBlue Serial Port Adapter.
The customer implements their own main application, which may be something different than transferring data between the UART and Bluetooth connection.
Note that Bluetooth low energy is disabled by default. See the sample applications code (obpINIT_init in obp_init.c) for info how Bluetooth low energy is enabled.
There is a mandatory requirement, described in Section "Mandatory Test Requirement", for connectBlue to make Bluetooth tests on a module with the customer application. This is to ensure that the radio behaves as expected.
The OBP421 has the following hardware configuration:
- ST STM32F103RD microcontroller
- TI CC2564/BL6450L Bluetooth radio
The module fulfills the ETSI regulations and is modular approved for FCC and IC. It is also Bluetooth qualified as a Bluetooth controller subsystem. The embedded Bluetooth stack is qualified as a Bluetooth host subsystem. This allows for customer specific Bluetooth applications developed directly for the STM32F10x microcontroller.
The OBP421 module supports a variety of interfaces such as Bluetooth, UART, SPI, I2C, ADC, JTAG and a number of IO pins. Many of the interfaces and IO pins are multiplexed. For details see the cB-OBP421 Electrical Addendum Data Sheet.
The embedded Bluetooth Stack is optimized for small embedded industrial systems with high requirements on performance and robustness. For Classic Bluetooth it contains the SPP, DUN, GAP profiles. For Bluetooth low energy it contains GAP, GATT, Device Info and connectBlue Serial Port Service (SPS). The PAN profile or the Apple MFi solution support is not yet included in this offer.
The included software package contains Microsoft Visual Studio projects and makefiles to build two sample applications. Both applications are also provided as binaries (obp421_echo_demo.bin and obp421_gatt_demo.bin).
There are four available software components used by the sample applications:
- Subset of the connectBlue Serial Port Adapter (SPA): This enables easy Bluetooth handling and AT command execution. It is available as header files and a pre-compiled library (obp421RD_spa.a). Note that even if it is only a subset of the connectBlue Serial Port Adapter application, the component will hereafter be called Serial Port Adapter or simply SPA.
- connectBlue Embedded Bluetooth Stack: Available as header files and a pre-compiled library (cB-2253.a). This component is used by the SPA and it is not recommended to use the API directly from the application.
- Run-Time Support Library (RTSL): Basically a high level abstraction of the operating system and some of the drivers. It is included as source code. Some of the functions are used by the connectBlue Embedded Bluetooth Stack and must be available for the project to successfully build. Most of them are not needed.
- ST Firmware Library: A free to download driver packet from www.st.com. It is included as source code. It is possible that there are one or more modifications or bug fixes done by connectBlue in this packet compared to the one available for download from the ST site.
The development environment for the cB-OBP421 target consists of several different parts:
- Visual Studio makefile project.
- Makefile for the application
- GNU Toolchain for ARM Processors
- make/sed/rm tools
- connectBlue Flash Loader application
- Target debugging environment (JTAG based)
The sample applications are edited and built using Visual Studio makefile projects. The file rules.mk defines what files that shall be compiled and linked with the application. When a file is added to the Visual Studio project it must also be added in the list of objects in rules.mk. If you a add a file to the Visual Studio project that you want to compile it shall also be added to he list of DEFAULT_OBJECTS in rules.mk.
GNU Toolchain for ARM Processors
The prebuilt GCC toolchain for ARM processors from Code Sourcery is used for the stack and example project.
Register and download at: http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/request?id=e023fac2-e611-476b-a702-90eabb2aeca8&downloadlite=scblite2012&fmpath=/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/form
Choose the IA32 windows installer.
Version: version 4.6.3 (Sourcery CodeBench Lite 2012.03-56)
The GCC toolchain must be installed before the demo can be built. During the installation choose TYPICAL installation. The file rules.mk defines what compiler and linker and their path. If you install the toolchain on a non-default location you will have to update the rules.mk accordingly.
Additional Build Tools
Except for the GCC compiler and linker the following applications are used in the build process:
- make - used for compiling and linking
- sed - tool used to parse data using regular expressions. Used to process the output from make / input to Visual Studio.
- rm - remove command
The executables for the tools are part of the project structure and do not need to be installed. The tools can be found in the following Unix utility package for Windows: http://sourceforge.net/projects/unxutils.
The OBP421 supports debugging via JTAG and the connector is available on the cB-ACC-56 Platform Development Board.
It is recommended to use the Lauterbach Trace32 series of debuggers to debug the application in the target environment. While debugging the application the firmware is still downloaded to target using the connectBlue Flash Loader.
- The example script file obp421_*.cmm can be used to load the sample application using a Lauterbach debugger.
- Make sure to uncomment the COMMON += -DcbHW_WATCHDOG compiler option in the rules.mk file. Otherwise the hardware watchdog will reset the module after a few seconds when stopped on a breakpoint.
- By default, the compiler optimization is set to -Os. During debugging it is a good idea to change it to -O0. At least for the file(s) currently being debugged.
connectBlue Flash Loader
The connectBlue Flash Loader is used to update the firmware of the cB-OBP421. It is part of the delivery and can also be downloaded from support.connectblue.com.
Flash Memory Configuration
The flash memory is divided into a boot area, non-volatile data storage area and program memory.
The boot area contains hardware and radio initialization parameters and code to flash the programming memory over the UART interface. When the module is powered up, the boot typically takes ~0.5 seconds until jumping to the application (unless a flash operation is initiated). The boot time cannot be shortened since it must wait for stable clocks for the Bluetooth radio to start correctly.
The non-volatile data storage (NVDS) area is basically just a reserved area for parameters and link keys storage during power off.
The program memory contains the application program, and the boot sequence ends by jumping to the application in this area.
The package includes two sample applications, one Classic Bluetooth echo demo and one Bluetooth low energy GATT demo. Those two applications have separate project files but they also share some functionality.
The sample application consist of three basic components.
- Bluetooth App (obp421_echo_demo\source\obp_app.h/c and obp421_gatt_demo\source\obp_app.h/c): This application should be replaced or modified by the customer. This is where the Echo demo or GATT demo is implemented.
- AT (obp_at.h/c): Executes AT commands over the UART interface using the SPA AT Parser component. It is recommended to keep this component in all customer implementations for easy configuration and testing.
- External AT Commands (obp_ext_at_cmds.h/c): Implements one read and one write AT command and installs both of them into the SPA AT Parser.
Much of the standard Serial Port Adapter functionality is available. For example, it is possible to configure Bluetooth connections in the same way as for the standard Serial Port Adapter application.
Initialization & Configuration
The application processes (if any) are defined in the obp_cfg.c file. See the Create Process Section of the RTSL component and the sample project for details.
Every application component must be initialized in the obp_init.c file before the component is used. Note that settings that would normally require a restart of the module should be placed in this file. See sample project for details.
The AT component reads data from the UART interface (in RTSL) and forwards the data to the SPA AT Parser component for actual AT command parsing and execution. A response or event received from the SPA AT Parser is transmitted on the UART. Hence, most standard Serial Port Adapter AT commands will execute as long as this component is available in the application. It also means that the Serial Port Adapter Toolbox can be used to configure the module.
It is recommended that this component is part of the customer solution.
External AT Commands (obp_ext_at_cmds.h/c)
It is possible to add AT commands to the SPA AT Parser. The External AT Commands component implements one read (AT*TST?) and one write command (AT*TST=). The commands are dummy commands to illustrate how to implement and register customer specific AT commands.
The commands are defined in the ATP_ExtCmd extAtCmds structure.
The second parameter is the AT command handler which is called by the SPA AT Parser when the associated AT command is executed.
The third parameter defines where (if any) the input parameter list starts. For the AT*TST= command it starts just after the "=" character at position 7. If no parameters are available it is set to 0.
The syntax of the AT commands must follow the conventions defined in the Bluetooth Serial Port Adapter AT Commands document.
The AT command list is registered to the SPA AT Parser with the ATP_RegisterExtAtCmds function call.
For details, see comments in the spa_atparser.h file.
The read command handler (tstHandlerRead), finishes immediately and returns the timeout1 and timeout2 parameters. Note that the result string must comply to the conventions defined in the Bluetooth Serial Port Adapter AT Commands document.
The handler returns SPA_ATP_COMPLETE_DONE to inform the SPA AT Parser that it is done.
The write command handler (tstHandlerWrite) does the following:
- Reads the timeout1, timeout2 and storeInStartupDatabase parameters from the input parameter string. Note that there are some help functions in spa_atparser.h to simplify.
- Verifies that the read parameters are valid.
- If the parameters shall be stored in NVDS (storeInStartupDatabase == 1), the timeout1 and timeout2 parameters are written.
- Two timers are started with a timeout1 seconds time out and a (timeout1 + timeout2) seconds time out.
- The handler returns SPA_ATP_COMPLETE_EXECUTING to inform the SPA AT Parser that the AT command is executing but not yet done.
The time out handler does the following.
- The time out handler (tstHandlerTimeout) for timeout1 is triggered and sends an ATP_RESPONS to the SPA AT Parser.
- The time out handler (tstHandlerTimeout) for timeout2 is triggered and sends an ATP_FINAL_RESPONS to the SPA AT Parser. Since it is a final response it also means that the AT command is done and that the SPA AT Parser can start to execute the next AT command.
Bluetooth Echo demo (obp_app.h/c)
The obp_app.c implements the main functionality of the Bluetooth echo demo application. It should be replaced or modified to fulfill the customer specific requirements.
The basic functionality is to echo incoming data on an active Bluetooth link. There is no code to set up or terminate a Bluetooth connection. Instead this is configured using standard Bluetooth AT commands and configuration is typically done with the Serial Port Adapter Toolbox.
The Echo demo operates in one of two modes selected at compile time.
- Wireless Multidrop Mode: Data received on one link is echoed on all links including the one where data was received.
- Extended Data Mode (EDM): Data received on one link is echoed only on that link.
If obpAPP_EXTENDED_DATA_MODE is defined in obp_app.c, the Extended Data Mode is selected at compile time.
In Extended Data Mode, received data is inserted in an Data Event packet specified by the Extended Data Mode Specification. This means that when the application reads incoming data, there is header and tail with information such as e.g. a link identifier. In Wireless Multidrop Mode, data from different Bluetooth channels are interleaved and cannot be identified by the application when data is read.
Note that this Extended Data Mode is not the full standard Extended Data Mode implementation of the connectBlue Serial Port Adapter application. It is only the Data Event packet, which is re-used to provide a possibility to identify individual packets received on a specific Bluetooth link.
The Echo demo also checks the external connect IO / button to initiate a Bluetooth connection configured for external connect (see AT*ADWDRP).
The simple implementation of the echo demo uses very few functions in the Bluetooth API (spa_bt_serial.h and spa_bt_llc.h). Instead it relies on the possibility to pre-configure the module using existing AT commands. Of course it is possible to implement a more dynamic application which uses the functions available in the spa_bt_serial.h and spa_bt_llc.h components.
Bluetooth GATT demo (obp_app.h/c)
The obp_app.c implements the main functionality of the Bluetooth GATT demo application. It should be replaced or modified to fulfill the customer specific requirements. GATT stands for Generic Attribute profile and is used to discover, read and write attributes on a remote low energy enabled device.
The basic functionality is to check the external connect IO / button and when it is pressed do the following:
- Search for a Bluetooth low energy device, i.e. OLP425
- Connect to the one with best RSSI
- Discover services
- Search for the LED service
- Search for the green LED attribute
- Toggle the remote green LED for 2 sec with 100 ms interval
The implementation of the GATT demo uses very few functions in the spa_bt_llc.h and spa_bt_serial.h interfaces. Instead it uses cb_gatt.h and relies on the possibility to pre-configure the module using existing AT commands. The default settings should be used (use AT&F to restore to factory defaults).
The implementation uses the state machine below. Note that some actions e.g. SPALED are not visible here for simplicity.
The sequence chart below shows a typical behavior after the external connect button has been pressed and a remote device is found and connected to.
See Appendix A for more examples of GATT usage.
Sample Project Memory Configuration
The memory available for a customer application depends very much on how the platform is configured.
- 1-7 Classic Bluetooth / Bluetooth low energy links for rev B (up to 6 low energy links for rev A)
- RAM buffer sizes for e.g. Bluetooth and UARTs
OBP421 has 64 kB RAM and 384 kB Flash memory.
Furthermore, the process stack will use ~2 kB of memory. No exact measurements have been made and as always it depends very much on the use case. Hence, there must be ~2 kB of RAM memory available for the process stack once complete application has been built.
The boot section and NVDS uses the first 32 kB of Flash memory and the last 2 kB of memory are reserved. Hence, there is "384 - 32 - 2 = 350 kB" of Flash memory available for application firmware.
For the demo apps this means the following:
- Maximum 7 Classic Bluetooth / Bluetooth low energy links for rev B(up to 6 low energy links for rev A)
- Available RAM: ~14 kB
- Available Flash: ~112 kB
Note that the heap is then already allocated and that the application may also allocate memory from the heap (see cb_heap.h).
It is possible to optimize a platform for a specific use case.
The sub-set of the Serial Port Adapter (SPA) application contains functionality for easy Bluetooth handling and AT command execution.
Most standard AT commands are available for module configuration and it is also easy to add customer specific AT commands.
It also includes the SPA LED component, which is used by the other SPA components. The SPA LED is included as source and should be changed according to the customer requirements. The functions must be defined but can be left more or less empty if the LED handling should be done elsewhere.
Removed functionality is:
- Extended Data Mode (EDM)
- BNEP (which means PAN is not available)
- Data/AT mode (always executes AT commands since the AT component interprets all data as AT commands)
- Data transfer UART<->BT (should be replaced by the customer specific application)
The Bluetooth functionality is available as implemented in the standard connectBlue Serial Port Adapter. This means that the details of connection set-up and termination is handled as well as the details of data transfer. This is especially good since much of the "unexpected" behaviour and many error cases discovered over the years are handled.
When only a static configuration is needed it is recommended that the customer uses the available AT commands to configure connection set-up and link optimization since this makes application implementation very simple. However, it is possible to use the full API of the SPA BT Serial and SPA BT LLC component for a more dynamic implementation.
The Bluetooth API resembles the concepts found in the AT commands associated with the Bluetooth link. Hence, it is good if the developer is familiar with concepts such as server, client, remote peer, link policy and more.
- Server: Accepts incoming connection.
- Client: Initiates a connection attempt to server.
- Remote Peer: Defines what server a client shall connect to. It also defines when the connection shall be set-up.
- Link Policy: Strategy for link optimization for a specific use case. Typically, it concerns packet size (1, 3 or 5 slots), packet type (DM/DH/2DH/3DH), sniff or QoS.
The functions are described in the associated header files and for many functions there is an associated AT command. Hence, it may then be a good idea to also see the documentation in the Bluetooth Serial Port Adapter AT Commands.
Bluetooth low energy in the platform can be used in three ways:
- Via standard AT-commands, e.g. connect to LE serial port service with AT*ADCP
- Via GATT commands to directly access all attributes of the remote device
- Via GATT API. Provides the same level of access as GATT AT-commands
SPA BT LLC (spa_bt_llc.h)
Basic Bluetooth functionality regarding security, inquiry and basic radio configuration.
SPA BT Serial (spa_bt_serial.h)
Functionality to configure, set-up and terminate connections, transmit and receive data and link watchdog configuration.
GATT (Generic Attribute Profile) is a profile used for setting and getting attribute data from a remote Bluetooth low energy enabled device. It is used by almost all profiles and services used in Bluetooth low energy. GATT for Classic Bluetooth is not supported by this platform.
The GATT API is almost a one to one mapping of the GATT profile specification. The header files cb_gatt.h and cb_gatt_client.h should work as a reference for the different GATT requests and responses. Also the Bluetooth 4.0 specification is a useful resource.
GATT is part of the Bluetooth embedded stack and used by various components in the stack. Only one request at a time is supported from the application. The application must wait until all responses from an outstanding request have been received.
Only one application should register with cbGATT_registerClient. Only one component in the system can register on cbGATT_registerDefaultNotIndHandler. This is used by the AT parser by default but needs to be called by the application if any notifications/indications are enabled. If an application only needs one notification/indication, then cbGATT_registerNotIndHandler can be used.
Caching attribute handles
The platform will not cache any attribute handles that the application has discovered. Caching must be done by the application. If the remote device contains the GATT service changed characteristic the caching should not be done because this is not supported by the platform yet.
If the remote device does not contain the service changed characteristic the caching can be done by the application because the attribute handles are fixed and will never change.
To be able to use the GATT API there must be a low energy connection. This can be made with BTLLC_AclConnectExt. Disconnection is made with BTLLC_AclDisconnectExt. Note that both BTLLC and GATT provide callbacks for the connection/disconnection events. The GATT callbacks provide more information of the connection.
For more info see Bluetooth Specification 4.0 and header files.
This chapter describes how privacy-enabled remote devices are handled. Please read the privacy chapter in the AT command specification first.
Some functions in the platform can resolve a remote's device resolvable address and thus re-connect without re-discover the device again. Those functions can then connect using the original resolvable address used when the devices were bonded.
The list below contains functions/callbacks that use the original resolvable address.
|BTSERL_RemotePeer||Connect to name schemes can NOT be used|
The list below contains functions that can NOT use the original resolvable address but must use the currently used real address. The real address can be found by doing an inquiry.
The AT Parser consists of most of the AT commands available for the connectBlue Serial Port Adapter application. It is also possible for customers to add their own external AT commands.
The following AT commands are not included:
The LED component is used by other SPA components to display e.g. connection attempt in progress, connection active or error. It is available as source code so that the customer can change the behavior.
Since the functions must be defined for successful compilation and linking, the component can not be removed if not needed. Instead the functions must be implemented as empty functions that just returns SPA_OK.
Run-Time Support Library
The run-time support library (RTSL) is an abstraction of a virtual operating system and some selected drivers. It has been ported by connectBlue to a number of different platforms over the years and it contains the functionality that has been important for the connectBlue applications. Therefore, it is not complete especially regarding different peripherals and the ST firmware library must be used in parallel. The existing documentation is scarce and it is recommended that, apart from this document, the header files are used for reference.
Operating System (cbOS)
The operating system mainly contains functionality to create processes, message and event passing between processes, dynamic memory allocation and some watchdog functionality.
The process management is implemented without an RTOS (Real-Time Operating System) and only simulates processes. A message or event is executed until completion which means that true pre-emption is not supported. Processes are prioritized in the sense that higher priority processes will handle their messages and events before lower priority processes. There is only one program stack and all processes execute in the same memory space.
The main function, which is the entry point for the firmware, has the following start sequence:
- The cbOSCFG_init function (typically defined in cb_cfg.c) is called. This creates the virtual processes.
- The cbOS_startHandler is called. The start handler is responsible for initialization of all components.
- Start handling events and messages for the processes.
When no events or messages are available, the idle handler is called. The idle handler manages the low power modes.
See the cb_os.c main function for details.
To define a new process, the cb_cfg.c file must be edited.
- Define the process using the cbOSCFG_DEFINE_PROCESS macro.
- Create the process using the cbOSCFG_CREATE_PROCESS macro.
See the obp_cfg.c file of the sample application(s) for further details.
The process function is implemented using the cbOS_PROCESS_FUNCTION macro. Please note that since an RTOS is not used, the process function must return after processing received messages and events. The longer it takes the longer it blocks other processes.
Send Event and Message
Events and messages are sent to a process in the following manner:
Please note that the functions cbOS_alloc or cbHEAP_malloc must be used to allocate message buffers.
Mutual Exclusion and Interrupts
Since the virtual operating system is not a true RTOS and everything is executed by the main function, mutual exclusion between processes does not need to be considered. However, since code is also executed in interrupt functions, mutual exclusion must be considered between processes and interrupts.
In the OS component there are two macros to disable (cbOS_ENTER_CRITICAL) and enable (cbOS_EXIT_CRITICAL) interrupts. These should be used by the processes to ensure mutual exclusion in regards to interrupt functions. If the source code is investigated, it can be seen that not all interrupts are disabled. The Cortex Basepri register is used to filter out non-critical priority interrupts. Therefore, it is important to define new interrupt functions with a priority lower than the "critical priority" limit (see code for details). In the cb_hw.h/c files in RTSL there is also a function to disable all interrupts if needed.
In RTSL and the Embedded Bluetooth Stack all interrupts except one are defined as non-critical which means they are disabled by the cbOS_ENTER_CRITICAL macro. In the UART component there is one critical interrupt that starts the next DMA transfer when the current one is complete. It does not affect any variables or state except its own and therefore it does not corrupt anything even if not blocked by the cbOS_ENTER_CRITICAL macro. For high baud rates it is important not to block this interrupt to avoid buffer overflow. Therefore, disabling all interrupts function (with cbHW_disableAllIrq) in the cb_hw.h/c component should be avoided if possible.
Dynamic Memory Allocation
The dynamic memory allocation is limited to a fixed number of buffer sizes for efficient use. The number of available sizes has been optimized to the Embedded Bluetooth Stack. It does not mean it is optimized for a general application. It may be that the configuration of buffer sizes and total heap size has to be re-configured according to new requirements. Allocated buffers are re-used for speed and to prevent fragmentation of memory.
The implementation of the heap is done in cb_heap.c/h in RTSL. If cbOS is used, a message header is associated with each allocated buffer and therefore, the buffer can be used for message passing.
- cbOS_alloc uses a little more RAM memory than the corresponding cbHEAP_malloc function.
- In the heap component there is a cbHEAP_mallocStatic function to allocate any size buffer. The allocated buffer cannot be freed using the cbHEAP_free command. Some components use the cbHEAP_mallocStatic function to create the initial class when requested. Those components cannot be deallocated once created.
To re-configure the heap the following options are available.
- The heap size is defined by cbHEAP_SIZE in the rules.mk file.
- The maximum buffer size when using cbHEAP_malloc is defined by cbHEAP_BUF_SIZE_MAX in cb_heap.h.
- The available buffer sizes are defined in cb_heap.h.
There are also some debugging features available in the heap to track memory overwrites and leaks. Please see the cb_heap.c file for details. The implementation is fairly straight forward.
The hardware watchdog is reset by the main loop in the OS component and does not need to be considered by the application. However, the watchdog is disabled by default and needs to be enabled if required. Use the cbOS_enableHwWatchdog function in the OS component to enable the hardware watchdog.
The cb_assert.h file defines some macros to detect errors or exit the code in a controlled manner. If the cb_ASSERT, cb_ASSERT2 or cb_EXIT macros are used, the cbOS_error function (implemented in the cbOS component) is called. By default, the cbOS_error function calls the built-in error handler in the SPA component, which then stores the error code, file and line of the assert in NVDS. Before exiting, the cbOS_error function resets the module.
When debuggning, it is recommended to have a break point set in the cbOS_error function on the line after the interrupts have been disabled. Of course it is also possible to read the last assert from NVDS using the NVDS identifier 154. The assert is stored according to the following structure.
The assert stored in NVDS can also be read using the AT*APDBG? AT command, if AT commands are still available. Please note that the assert is cleared every time it is read from NVDS using the AT*APDBG? AT command.
The SPA component, RTSL and the Embedded Bluetooth Stack uses this feature extensively which means it is possible to identify a file and line if an error occurs (setting a break point in the cbOS_error function or reading the assert from NVDS) and to report this to connectBlue for further investigation.
Power Management (cbPM)
The power management module implements power saving. Three different power saving modes are supported:
- Online - In online mode the CPU is always running.
- Sleep - In sleep mode the CPU will be stopped using the WFE instruction when the idle handler is called and there are no active interrupts. Execution will be continued when the next interrupt occurs.
- Stop - In stop mode the clocks are stopped. The CPU is woken up by external interrupts. When stop mode is entered the radio is requested to enter stop mode. If the radio allows stop mode, clocks will be stopped and the CPU will enter stop mode. The radio does perform page and inquiry scan also in stop mode. The radio will wake up the system on an incoming connection request.
Components that require the clock must register to the power manager and implement a callback that report which power mode that is allowed at a certain time. For example the timer is registered to the power manager and will allow sleep mode when timers are running and stop mode when no timers are running. The power manager will select the lowest power mode allowed by all registered users. Typically an application registers to the power manager and allows stop mode when there are no events or data to process and sleep mode when there is. The sequence diagram below shows the registration to the power manager and how the registered callbacks are used.
The timer component implements a simple software timer class which is driven by the system tick handlers with a default resolution of 10 ms.
The maximum number of active timers as well as the system tick handler resolution can be configured in the cb_timer.h file.
Non-Volatile Data Storage (cbNVDS)
The non-volatile data storage component is intended for parameter storage during power off.
The implementation is based on an EEPROM source code sample available for download from the ST support site. It has been modified/extended to improve robustness in regards to unexpected power failures. The cost is very inefficient use of the memory.
Many AT commands store configuration values in the NVDS, which are then used by different components at startup.
Used by the platform components.
Range that can freely be used by the application.
Peripheral Input/Output (cbPIO)
The peripheral input/ouput component provides for an easy to use API of the IO pins of the cB-OBP421 module.
Many of the pins are multiplexed with other interfaces such as e.g. the UART, SPI and I2C interface. Please read the cB-OBP421 Electrical Addendum Data Sheet for details.
Only use the IO pins listed in thecB-OBP421 Electrical Addendum Data Sheet. If the functionality of any other IO pin is altered the functionality of the module can not be guaranteed. For example the communication with the Bluetooth radio may be disturbed.
The UART component provides basic functionality for reading and writing but also some connectBlue specific extensions such as e.g. the escape sequence handling, logic level / RS232 / RS422 / RS485 pin control and packet consistency (to avoid packets being split at end of the buffer).
The Embedded Bluetooth Stack is dependent on the UART component for the OBP421 platform since the UART2 is used to interface the radio, which means it must be included.
The UART DMA buffer sizes are defined by the cbUART1_DMA_BUF_SIZE and cbUART1_MAX_DMA_BUFS defines in the rules.mk file. The cbUART1_DMA_BUF_SIZE defines the size of each DMA transfer and the cbUART1_MAX_DMA_BUFS defines number of buffers to use before halting.
Do not modify the cbUART2_DMA_BUF_SIZE or the cbUART2_MAX_DMA_BUFS since they have been optimized to fit the data transferred to and from the Bluetooth radio.
The implementation uses DMA transfer and keeps its own internal buffers for efficient use.
There are some special features that makes the implementation a little bit tricky and difficult to understand:
- The use of the "DMA Transfer Complete" interrupt and the SVC interrupt for very fast re-start of DMA transfer when current one is finished.
- RTS flow control not handled by hardware. Instead it is implemented in software.
- Escape sequence handling.
- Receive timeout is implemented using timers and is interleaved with the DMA transfer.
Without the connectBlue design documents of the UART, it is not an easy task to understand it or to make modifications. For the OBP421 the UART2 is used to interface the radio and it is critical that it works as expected. Hence, for the OBP421 it is recommended that the UART driver is not modified.
Mandatory Test Requirement
There is one mandatory requirement that must be fulfilled by the customer application. In order for connectBlue to make module tests regarding the radio behavior some test commands must be implemented. Those commands are different for Classic Bluetooth and Bluetooth low energy.
Mandatory Test Requirement: It must be possible, for connectBlue, to mount the module, with the customer specific firmware, on an existing connectBlue adapter or development board and to enable test mode.
One solution is to use IO pin(s) at application start after system (and radio) initialization. If one pin is in a specified state, the application enables the test mode. Another pin must be used for Classic Bluetooth test mode and Bluetooth low energy test mode because the modes can not be used at the same time. In the customer system, the pin(s) could be hard wired to one value to avoid test mode. When the module is mounted on a development board it is then possible to wire the IO pin(s) to the specific value that enables test mode.
The test mode is enabled with BTLLC_EnableDUT. If the customer keeps the AT parser and possibility to execute AT commands, the test mode can be enabled with existing AT commands. However, if the AT parser and possibility to execute AT commands is discarded, it is the responsibility of the customer to implement a way to enable the test mode.
Bluetooth low energy
The test mode is enabled with BTLLC_EnableBleTransmitterTest. At least one test mode must be supported i.e. channel = 0, length= 37 and packetPayload = 0. The function is preferable called after radio initialization has been done in obpINIT_init in obp_init.c.
Note that this command can not be used when the module is in the peripheral role. Make sure that the application sets the module in either Classic mode or Central role when the test mode is enabled. See obpINIT_init function in obp_init.c in the demo applications how this can be done.
The code example below shows how this can be done for both Classic Bluetooth and Bluetooth low energy in the obpINIT_init function. Two external IOs are being used to detect mode.
The cb_pio functionality should be included:
'enableBleTransmitterTestCallback' callback also need to be implemented, for example:
OLP425 X-axis accelerometer notifications example
The example in the sequence chart below shows how OLP425 X-axis accelerometer notifications are enabled from an OBP421 using GATT.
Note that the application in this example interrupts the cbGATT_discoverAllCharactersticsOfService and cbGATT_discoverAllCharacteristicDescriptors by returning FALSE in the corresponding callbacks.