1# 2 3As well as any other communication stack, BTstack is a collection of 4state machines that interact with each other. There is one or more state 5machines for each protocol and service that it implements. The rest of 6the architecture follows these fundamental design guidelines: 7 8- *Single threaded design* - BTstack does not use or require 9 multi-threading to handle data sources and timers. Instead, it uses 10 a single run loop. 11 12- *No blocking anywhere* - If Bluetooth processing is required, its 13 result will be delivered as an event via registered packet handlers. 14 15- *No artificially limited buffers/pools* - Incoming and outgoing data 16 packets are not queued. 17 18- *Statically bounded memory (optionally)* - The number of maximum 19 connections/channels/services can be configured. 20 21Figure {@fig:BTstackArchitecture} shows the general architecture of a 22BTstack-based single-threaded application that includes the BTstack run loop. 23The Main Application contains the application logic, e.g., reading a sensor value and 24providing it via the Communication Logic as a SPP Server. The 25Communication Logic is often modeled as a finite state machine with 26events and data coming from either the Main Application or from BTstack 27via registered packet handlers (PH). BTstack’s Run Loop is responsible 28for providing timers and processing incoming data. 29 30 {#fig:BTstackArchitecture} 31 32## Single threaded design 33 34BTstack does not use or require multi-threading. It uses a single run 35loop to handle data sources and timers. Data sources represent 36communication interfaces like an UART or an USB driver. Timers are used 37by BTstack to implement various Bluetooth-related timeouts. For example, 38to disconnect a Bluetooth baseband channel without an active L2CAP 39channel after 20 seconds. They can also be used to handle periodic 40events. During a run loop cycle, the callback functions of all 41registered data sources are called. Then, the callback functions of 42timers that are ready are executed. 43 44For adapting BTstack to multi-threaded environments check [here](../integration/#sec:multithreadingIntegration). 45 46## No blocking anywhere 47 48Bluetooth logic is event-driven. Therefore, all BTstack functions are 49non-blocking, i.e., all functions that cannot return immediately 50implement an asynchronous pattern. If the arguments of a function are 51valid, the necessary commands are sent to the Bluetooth chipset and the 52function returns with a success value. The actual result is delivered 53later as an asynchronous event via registered packet handlers. 54 55If a Bluetooth event triggers longer processing by the application, the 56processing should be split into smaller chunks. The packet handler could 57then schedule a timer that manages the sequential execution of the 58chunks. 59 60## No artificially limited buffers/pools 61 62Incoming and outgoing data packets are not queued. BTstack delivers an 63incoming data packet to the application before it receives the next one 64from the Bluetooth chipset. Therefore, it relies on the link layer of 65the Bluetooth chipset to slow down the remote sender when needed. 66 67Similarly, the application has to adapt its packet generation to the 68remote receiver for outgoing data. L2CAP relies on ACL flow control 69between sender and receiver. If there are no free ACL buffers in the 70Bluetooth module, the application cannot send. For RFCOMM, the mandatory 71credit-based flow-control limits the data sending rate additionally. The 72application can only send an RFCOMM packet if it has RFCOMM credits. 73 74## Statically bounded memory 75 76BTstack has to keep track of services and active connections on the 77various protocol layers. The number of maximum 78connections/channels/services can be configured. In addition, the 79non-persistent database for remote device names and link keys needs 80memory and can be be configured, too. These numbers determine the amount 81of static memory allocation. 82
