Skip to content

Commit dab0faa

Browse files
Merge branch 'development' into ble-rewrite
2 parents 83dd837 + e8f9ac8 commit dab0faa

File tree

17 files changed

+574
-319
lines changed

17 files changed

+574
-319
lines changed

docs.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -832,6 +832,9 @@
832832
},
833833
{
834834
"path": "docs/api/connectivity/bluetooth/GattClient.md"
835+
},
836+
{
837+
"path": "docs/api/connectivity/bluetooth/Optimising_for_performance.md"
835838
}
836839
]
837840
},

docs/api/api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@ With Arm Mbed TLS, a comprehensive SSL/TLS solution, you can include cryptograph
279279

280280
<h2 id="deprecated-apis">Deprecated APIs: moving from Mbed OS 5 to 6</h2>
281281

282-
If you're moving your program from Mbed OS 5 to 6, you will need to replace deprecated APIs. The table lists classes that have been completely removed. Functions and methods that have been removed from other classes are listed in each class's Doxgen, and [summarised here](../mbed-os-api-doxy/deprecated.html).
282+
If you're moving your program from Mbed OS 5 to 6, you will need to replace deprecated APIs. The table lists classes that have been completely removed. Functions and methods that have been removed from other classes are listed in each class's Doxygen ouput, and [summarised here](../mbed-os-api-doxy/deprecated.html).
283283

284284
| Deprecated API | Replaced by |
285285
| - | - |
Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Optimising application for throughput and power consumption
2+
3+
BLE (Bluetooth Low Energy) devices are usually battery powered so performance might mean different things in different
4+
applications. You will need to decide what is more important in your application - minimising power consumption on one
5+
or both sides of the communication or maximising throughput and/or latency. Some optimisation steps can in fact achieve
6+
both.
7+
8+
This guide will discuss some trade-offs that should be considered and best practices that improve performance on all
9+
fronts.
10+
11+
## Power consumption
12+
13+
Any radio activity will consume power. Depending on what the stack is doing you have to power the radio even when no
14+
data is being sent. It is important to understand when radio is active.
15+
16+
### Connections
17+
18+
The most intuitive power consumption rate to understand is when using connections. Each device will take turns sending
19+
and receiving at set interval.
20+
21+
```
22+
CENTRAL
23+
┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐
24+
│send│ │recv│ │send│ │recv│ │send│ │recv│ │send│ │recv│
25+
└────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘
26+
connection interval
27+
◄─────────────────────►
28+
29+
PERIPHERAL
30+
┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐
31+
│recv│ │send│ │recv│ │send│ │recv│ │send│
32+
└────┘ └────┘ └────┘ └────┘ └────┘ └────┘
33+
slave latency
34+
◄───────────────────────────────────────────►
35+
36+
▲ ▲ ▲
37+
connection event connection event connection event
38+
```
39+
40+
To maintain a connection, regardless if there is data transfer to be transferred, the central needs to transmit and
41+
receive once every connection interval.
42+
43+
The peripheral needs to acknowledge connection events to the central. Data ready to be transmitted is sent in the
44+
acknowledgement. To save power, if the peripheral has no data to transmit it may skip up to `slaveLatency` connection
45+
events.
46+
47+
More power is consumed if there is data to be exchanged. The exchange can continue until the next connection event would
48+
take place.
49+
50+
It's worth considering if keeping the connection active is worth it. Connection in BLE has little overhead and there are
51+
some cases when it is better to connect and disconnect each time you want to send a burst of data if for example you
52+
want to conserve power on one of the devices. This way only one side will have to run advertising/scanning all the time
53+
while the power limited device can turn the transmitter on only when it needs to.
54+
55+
The cost of the connection is proportionate to the negotiable connection interval. This can be set during `connect` or
56+
later through `updateConnectionParameters`. The lower the interval the more often radio is active. This is especially
57+
important for the peripheral which needs to enable the radio to receive packets.
58+
59+
This can be further helped by setting a high `slaveLatency` parameter. This allows the peripheral to skip
60+
connection events and save power not just by not sending any packets but by not even listening. This is not free for
61+
central as it increases latency of data transmission from central to peripheral. Central may have to attempt sending
62+
data multiple times before the peripheral accepts the transmission. The peripheral may send data at any connection event
63+
as the central must listen after every transmission.
64+
65+
### Advertising and scanning
66+
67+
Power draw during advertising affected by:
68+
- the advertising interval - lower interval uses more power,
69+
- use of Coded PHY which uses more power for extended effective range,
70+
- amount of data sent,
71+
- number of channels used - each advertising event is sent by default to three channels which you can limit to 2 or 1,
72+
- whether extended advertising is used - this will send additional packets on regular channels,
73+
- whether the type is connectable or scannable - it means the advertiser needs to listen on the radio after each
74+
advertisement for potential connection of scan requests.
75+
76+
```
77+
PERIPHERAL
78+
┌────┐ advertising interval ┌────┐
79+
channel 37 │adv │◄───────────────────────────────────────────►│adv │
80+
└────┘ └────┘
81+
┌────┐ ┌────┐
82+
channel 38 │adv │ │adv │
83+
└────┘ └────┘
84+
┌────┐ ┌────┐
85+
channel 39 │adv │ │adv │
86+
└────┘ └────┘
87+
88+
non-advertising ┌────────────────────┐
89+
channel │extended advertising│
90+
(indicated in regular └────────────────────┘
91+
advertising payload)
92+
```
93+
94+
Scanning power draw is proportional to time spent scanning. Additional power will be used if you run active scanning
95+
which will send a scan request and listen for the reply.
96+
97+
The interaction between scanning an advertising means that the less power the advertiser spends advertising, the more
98+
power the scanner will have to spend to see the advertising packets. The decision on balance will be dictated by your
99+
design of your devices (which one is more constrained).
100+
101+
### Connection vs advertising
102+
103+
Instead of connecting to the device you can consider transferring data in advertising packets. This depends on the
104+
nature of the data.
105+
106+
A transfer over a connection will allow you to use the ATT protocol, this can handle acknowledgement for you. This might
107+
be a good choice if you're sending data that must get through reliably.
108+
109+
If your data is non-critical then advertising might be cheaper. You might have to accept less reliability and no built
110+
in acknowledgment. Additional benefit is that multiple devices may receive the data and each scanner may make their own
111+
decisions about power consumption.
112+
113+
### Periodic advertising
114+
115+
Periodic advertising allows you to get best of both worlds by having the power characteristics of advertising for the
116+
peripheral but also saving power for the scanner. After finding periodic advertising through `createSync` the scanner
117+
will only have to turn on the radio when the expected packet is due.
118+
119+
## Increasing throughput
120+
121+
### Modulation schemes
122+
123+
Depending on controller support different modulation schemes are available in BLE through `setPreferredPhys()` and
124+
`setPhy()`. While the coded PHY will increase reliability in noisy environments and increase range at the cost of
125+
power consumption, 2M PHY will increase the throughput saving power ber bit. If both devices support it and the signal
126+
quality is good then this is recommended to be enabled.
127+
128+
### Data length and ATT_MTU
129+
130+
Packet overhead strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs thus decreasing the
131+
fragmentation overhead.
132+
133+
There are two separate MTUs to consider: the `ATT_MTU` (which affects ATT protocol operations) and data length extension
134+
(which affects transport packets). Increasing the sizes will increase memory usage but greatly increase throughput.
135+
`ATT_MTU` and data length are independent of each other.
136+
137+
The size of ATT_MTU doesn't have any other overhead than memory and should only be limited by your biggest attribute
138+
and available memory.
139+
140+
The default value of data length supported by all controllers is 23 octets. If both controllers support data length
141+
extension and a higher value is negotiated, the BLE stack will call `onDataLengthChange` in the `Gap::EventHandler`
142+
registered by the user. The supported length is set in the link layer with a maximum of 251. For Cordio Link Layer it
143+
is derived from the config option `cordio_ll.max-acl-size`.
144+
145+
Larger data length greatly increases throughput (although diminishing returns quickly set in above 80). The only
146+
potential drawback is in noisy environments where longer packets may cause slower effective transfer due to
147+
retransmissions (this is only related to data length, ATT_MTU does not affect this).
148+
149+
### ATT protocol
150+
151+
GATT client writes and GATT server updates come in two versions - with and without confirmation. Requiring confirmations
152+
limits the throughput severely so to maximise throughput you can move reliability up from the stack to your application.
153+
Without confirmations more than a single Peripheral <=> Central data exchange can be made per connection event. With
154+
confirmations, the connection event ends when the peripheral replies as it needs to prepare the acknowledgement which
155+
will be sent possibly in the next event.
156+
157+
### Packet timings
158+
159+
If you're not constrained by battery power it might be tempting to use maximum/minimum values where possible.
160+
Advertising at maximum frequency and scanning continuously will speed up connecting. Setting intervals on connections
161+
will minimise latency and maximise number of connection events.
162+
163+
One key thing to consider when setting the connection interval low is that you are creating a boundary between which a
164+
sequence of packets must fit. This means that the last transfer must end before the next connection event starts
165+
(plus 150us of inter packet space). This dead time may become significant if the connection interval is short and packet
166+
length is long.
167+
168+
The connection interval shouldn't be shorter than what your data requires in terms of latency.
169+
170+
# Test and measure
171+
172+
Due to complexity of the stack the only reliable way to truly maximise performance is to test your application with
173+
representative data and measure the throughput and power usage. It's important to keep in mind that tweaking
174+
parameters by trial and error and fine-tuning them will only be reliable for sequential operations on known stacks.
175+
176+
Many behaviours are implementation dependant and many operations are best effort and not guaranteed to succeed. The
177+
stack has a lot of latitude to change its behaviour in accordance with resource constrains and other commitments. For
178+
example your advertising may be severely affected by other operations that take precedence like keeping up a connection.
179+
180+
If your device needs to communicate with an unknown device or you run a non-trivial combination of concurrent
181+
operations your fine-tuning should give way to sound principles since stack behaviours vary and you cannot test against
182+
all stacks and sequences of operations.

docs/api/connectivity/networksocket/socket.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,5 +38,5 @@ Here is a client example of HTTP transaction over TCPSocket or TLSSocket:
3838

3939
- [TCPSocket](tcpsocket.html) API reference.
4040
- [UDPSocket](udpsocket.html) API reference.
41-
- [TLSSocket](../secure-socket/tlssocket.html) API reference.
41+
- [TLSSocket](tlssocket.html) API reference.
4242
- [Socket](../apis/connectivity-architecture.html#socket-api) architecture.

docs/api/drivers/usb/USBCDC_ECM.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ One application in which you can use this class is a USB to Ethernet adapter. If
1010

1111
[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/v6.7/mbed-os-api-doxy/class_u_s_b_c_d_c___e_c_m.html)
1212

13-
<span class="notes">**Note:** Because Windows doesn’t provide native support for the USB CDC-ECM model, you must use third party drivers to use this class on Windows.</span>
13+
<span class="notes">**Note:** Because Windows does not provide native support for the USB CDC-ECM model, you must use third party drivers to use this class on Windows.</span>
1414

1515
## USBCDC_ECM example
1616

docs/api/platform/FileHandle.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,11 +82,11 @@ namespace mbed
8282

8383
Then any program using `printf` on that target sends its output over the SWO, rather than serial.
8484

85-
Because targets can redirect the console in this way, portable applications should not use constructs such as `Serial(USBTX, USBRX)`, assuming that this will access the console. Instead they should use `stdin`/`stdout`/`stderr` or `STDIN_FILENO`/`STDOUT_FILENO`/`STDERR_FILENO`.
85+
Because targets can redirect the console in this way, portable applications should not use constructs such as `Serial(CONSOLE_TX, CONSOLE_RX)`, assuming that this will access the console. Instead they should use `stdin`/`stdout`/`stderr` or `STDIN_FILENO`/`STDOUT_FILENO`/`STDERR_FILENO`.
8686

8787
```
8888
// Don't do:
89-
Serial serial(USBTX, USBRX);
89+
Serial serial(CONSOLE_TX, CONSOLE_RX);
9090
serial.printf("Hello!\r\n");
9191
9292
// Do do:

docs/api/scheduling/rtos.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The code of the Mbed RTOS can be found in the [`mbed-os`](https://github.com/ARM
88

99
Memory for the RTOS primitives is allocated as part of the C++ objects on the stack unless you explicitly use dynamic allocation, in which case it is placed on the heap. Exceptions to this rule are user's thread stacks, which by default are allocated on the heap. You can provide your own memory in the construction if you'd rather not use dynamic memory in your system. For details, please see the [Thread](thread.html) class documentation.
1010

11-
<span class="notes">**Note:** Mbed OS overrides the RTX default memory pool approach.</span>
11+
<span class="notes">**Note:** Mbed OS overrides the Keil RTX default memory pool approach.</span>
1212

1313
## RTOS Ticker
1414

docs/bare_metal/bare_metal.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Bare metal is a profile of Mbed OS for ultraconstrained hardware: compact and without an RTOS. It represents a different way of working with Mbed OS: the bare metal profile builds only the smallest set of APIs that applications require - driver APIs, platform APIs and a subset of the RTOS APIs. This gives you better control of the application's final size than the full profile, which relies on the build time linker to remove classes that are not used and are not a dependency.
44

5-
The bare metal profile implements a subset of Mbed OS's RTOS APIs that are useful in non-threaded applications, such as semaphores (calling the release API from interrupts) and tickers (to set up a recurring interrupt). It does not include an RTX, and is therefore suitable for applications that do not require complex thread management. Instead of the RTOS's scheduler, all activities are polled or interrupt-driven. This simplifies application code and allows using APIs that are not thread safe. Just as important, you can use the code-optimized versions of the C standard libraries, `microlib` and `newlib-nano`, which are much smaller than the thread safe equivalents the full profile requires.
5+
The bare metal profile implements a subset of Mbed OS's RTOS APIs that are useful in non-threaded applications, such as semaphores (calling the release API from interrupts) and tickers (to set up a recurring interrupt). It does not include [Keil RTX](https://www2.keil.com/mdk5/cmsis/rtx), and is therefore suitable for applications that do not require complex thread management. Instead of the RTOS's scheduler, all activities are polled or interrupt-driven. This simplifies application code and allows using APIs that are not thread safe. Just as important, you can use the code-optimized versions of the C standard libraries, `microlib` and `newlib-nano`, which are much smaller than the thread safe equivalents the full profile requires.
66

77
The Mbed OS build tools - Mbed CLI, Mbed Online Compiler and Mbed Studio - all support working with the bare metal profile.
88

docs/contributing/contributing.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Contributing overview
22

3-
The Arm Mbed OS porting guide describes how to a add development board Mbed OS and configure it. It includes porting information about related features, such as cellular, exporters and Mbed TLS. It also contains information about CMSIS, RTX and Thread safety.
3+
The Arm Mbed OS porting guide describes how to a add development board Mbed OS and configure it. It includes porting information about related features, such as cellular, exporters and Mbed TLS. It also contains information about CMSIS, Keil RTX and Thread safety.
44

55
Please see the contributing guide's section on [contributing code](../contributing/style.html) for style and ABI requirements.

docs/debugging-testing/debug/common_issues.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ When you start using Mbed OS, you may find small challenges in a few cases. This
66

77
### Mbed Studio
88

9-
Mbed Studio comes with a built-in debugger. For instructions on using the debugger mode and debugger tools, please see the [Mbed Studio debugging documentation](https://os.mbed.com/docs/mbed-studio/latest/using-mbed-studio/debugging.html).
9+
Mbed Studio comes with a built-in debugger. For instructions on using the debugger mode and debugger tools, please see the [Mbed Studio debugging documentation](https://os.mbed.com/docs/mbed-studio/current/monitor-debug/debugging-with-mbed-studio.html).
1010

1111
### Mbed CLI
1212

0 commit comments

Comments
 (0)