diff --git a/docs.json b/docs.json index 2b7f63f86..18143b565 100644 --- a/docs.json +++ b/docs.json @@ -834,7 +834,7 @@ "path": "docs/api/connectivity/bluetooth/GattClient.md" }, { - "path": "docs/api/connectivity/bluetooth/Optimising_for_performance.md" + "path": "docs/api/connectivity/bluetooth/Optimizing_for_performance.md" } ] }, diff --git a/docs/api/api.md b/docs/api/api.md index b2dd5d2e7..39733e0a1 100644 --- a/docs/api/api.md +++ b/docs/api/api.md @@ -240,12 +240,10 @@ Connectivity APIs include: | API | Full profile | Bare metal profile | | - | - | - | -| [BatteryService](../apis/bluetooth-apis.html) | ✔ | ✔ (can be manually enabled) | -| [BLE](../apis/ble.html) | ✔ | ✔ (can be manually enabled) | +| [BLE](../apis/bluetooth-apis.html) | ✔ | ✔ (can be manually enabled) | | [GAP](../apis/gap.html) | ✔ | ✔ (can be manually enabled) | | [GattClient](../apis/gattclient.html) | ✔ | ✔ (can be manually enabled) | | [GattServer](../apis/gattserver.html) | ✔ | ✔ (can be manually enabled) | -| [HeartRateService](../apis/heartrateservice.html) | ✔ | ✔ (can be manually enabled) | | [SecurityManager](../apis/securitymanager.html) | ✔ | ✔ (can be manually enabled) | ### NFC diff --git a/docs/api/connectivity/bluetooth/BLE_services.md b/docs/api/connectivity/bluetooth/BLE_services.md index 0080e9747..e9776e5f2 100644 --- a/docs/api/connectivity/bluetooth/BLE_services.md +++ b/docs/api/connectivity/bluetooth/BLE_services.md @@ -1,9 +1,9 @@ # BLE Services -Mbed OS BLE implementation isn't bundled with any BLE services. Services are in an external repository. Please go to: -- [ble-services](https://github.com/ARMmbed/mbed-os-experimental-ble-services) +Mbed OS BLE implementation isn't bundled with any BLE services. Services are however provided in this external repository: -This is a community led effort to provide implementations of services both from the official BLE spec and user defined -ones. It contains libraries which you can import into your project to use the services. Please refer to documentation -inside the repository: -- [README.md](https://github.com/ARMmbed/mbed-os-experimental-ble-services/blob/main/README.md) \ No newline at end of file +- [Experimental services for Mbed OS BLE](https://github.com/ARMmbed/mbed-os-experimental-ble-services) + +This is a community led effort to provide implementations of services both from the official BLE specification and user defined ones. It contains libraries which you can import into your project to use the services. For details see the documentation in the repository: + +- [README.md](https://github.com/ARMmbed/mbed-os-experimental-ble-services/blob/main/README.md) diff --git a/docs/api/connectivity/bluetooth/Optimising_for_performance.md b/docs/api/connectivity/bluetooth/Optimizing_for_performance.md similarity index 93% rename from docs/api/connectivity/bluetooth/Optimising_for_performance.md rename to docs/api/connectivity/bluetooth/Optimizing_for_performance.md index b68f1ccb5..3810c13ef 100644 --- a/docs/api/connectivity/bluetooth/Optimising_for_performance.md +++ b/docs/api/connectivity/bluetooth/Optimizing_for_performance.md @@ -1,8 +1,8 @@ -# Optimising application for throughput and power consumption +# Optimizing applications for throughput and power consumption BLE (Bluetooth Low Energy) devices are usually battery powered so performance might mean different things in different -applications. You will need to decide what is more important in your application - minimising power consumption on one -or both sides of the communication or maximising throughput and/or latency. Some optimisation steps can in fact achieve +applications. You will need to decide what is more important in your application - minimizing power consumption on one +or both sides of the communication or maximizing throughput and/or latency. Some optimization steps can in fact achieve both. This guide will discuss some trade-offs that should be considered and best practices that improve performance on all @@ -118,16 +118,18 @@ will only have to turn on the radio when the expected packet is due. ## Increasing throughput +The following approaches can help to increase throughput, but you might need to consider whether power consumption will be adversely affected in your application. + ### Modulation schemes Depending on controller support different modulation schemes are available in BLE through `setPreferredPhys()` and `setPhy()`. While the coded PHY will increase reliability in noisy environments and increase range at the cost of -power consumption, 2M PHY will increase the throughput saving power ber bit. If both devices support it and the signal -quality is good then this is recommended to be enabled. +power consumption, 2M PHY will increase the throughput saving power per bit. If both devices support it and the signal +quality is good then this is recommended to be enabled. ### Data length and ATT_MTU -Packet overhead strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs thus decreasing the +Packet overhead strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs thus decreasing the fragmentation overhead. There are two separate MTUs to consider: the `ATT_MTU` (which affects ATT protocol operations) and data length extension @@ -149,7 +151,7 @@ retransmissions (this is only related to data length, ATT_MTU does not affect th ### ATT protocol GATT client writes and GATT server updates come in two versions - with and without confirmation. Requiring confirmations -limits the throughput severely so to maximise throughput you can move reliability up from the stack to your application. +limits the throughput severely so to maximize throughput you can move reliability up from the stack to your application. Without confirmations more than a single Peripheral <=> Central data exchange can be made per connection event. With confirmations, the connection event ends when the peripheral replies as it needs to prepare the acknowledgement which will be sent possibly in the next event. @@ -158,18 +160,18 @@ will be sent possibly in the next event. If you're not constrained by battery power it might be tempting to use maximum/minimum values where possible. Advertising at maximum frequency and scanning continuously will speed up connecting. Setting intervals on connections -will minimise latency and maximise number of connection events. +will minimize latency and maximize number of connection events. One key thing to consider when setting the connection interval low is that you are creating a boundary between which a sequence of packets must fit. This means that the last transfer must end before the next connection event starts (plus 150us of inter packet space). This dead time may become significant if the connection interval is short and packet -length is long. +length is long. The connection interval shouldn't be shorter than what your data requires in terms of latency. # Test and measure -Due to complexity of the stack the only reliable way to truly maximise performance is to test your application with +Due to complexity of the stack the only reliable way to truly maximize performance is to test your application with representative data and measure the throughput and power usage. It's important to keep in mind that tweaking parameters by trial and error and fine-tuning them will only be reliable for sequential operations on known stacks. diff --git a/docs/api/connectivity/connectivity-arch.md b/docs/api/connectivity/connectivity-arch.md index 9fa6b9698..453ca74ec 100644 --- a/docs/api/connectivity/connectivity-arch.md +++ b/docs/api/connectivity/connectivity-arch.md @@ -57,7 +57,7 @@ BLE is optimized for cheap, battery-based devices and has a low memory footprint Typical applications of BLE are health care, fitness trackers, beacons, smart homes, security, entertainment, proximity sensors, industrial applications and automotives. -To learn how to use BLE on Mbed OS, please refer to the [Bluetooth overview](../apis/ble.html). +To learn how to use BLE on Mbed OS, please refer to the [Bluetooth overview](../apis/bluetooth-apis.html). ### 6LoWPAN Mesh diff --git a/docs/api/connectivity/connectivity_list.md b/docs/api/connectivity/connectivity_list.md index 32ac4f5b8..71004027d 100644 --- a/docs/api/connectivity/connectivity_list.md +++ b/docs/api/connectivity/connectivity_list.md @@ -28,12 +28,10 @@ ## Bluetooth (BLE) -- [BatteryService](../apis/bluetooth-apis.html): Report battery charge levels to the user. -- [BLE](../apis/ble.html): Interface with the BLE controller on the board. +- [BLE](../apis/bluetooth-apis.html): Interface with the BLE controller on the board. - [GAP](../apis/gap.html): Handle connectivity tasks. - [GattClient](../apis/gattclient.html): Initiate interactions with a GattServer to discover services, characteristics and descriptors and perform operations on them. - [GattServer](../apis/gattserver.html): Respond to a GattClient. -- [HeartRateService](../apis/heartrateservice.html): Expose heart rate sensor data in a Bluetooth standard compliant way. - [SecurityManager](../apis/securitymanager.html): Use pairing and optional bonding processes to authenticate and encrypt BLE links. ## NFC diff --git a/docs/api/connectivity/networksocket/CellularNonIPSocket.md b/docs/api/connectivity/networksocket/CellularNonIPSocket.md index d3c80faa5..457376b9e 100644 --- a/docs/api/connectivity/networksocket/CellularNonIPSocket.md +++ b/docs/api/connectivity/networksocket/CellularNonIPSocket.md @@ -19,7 +19,7 @@ You can request Control Plane optimization mode either with CellularDevice's [`c "name": "cellular", "config": { "control-plane-opt": { - "help": "Enables control plane CIoT EPS optimisation", + "help": "Enables control plane CIoT EPS optimization", "value": true } } diff --git a/docs/bare_metal/mbed2_porting.md b/docs/bare_metal/mbed2_porting.md index 781df3be1..2d70b0ea5 100644 --- a/docs/bare_metal/mbed2_porting.md +++ b/docs/bare_metal/mbed2_porting.md @@ -146,7 +146,7 @@ If you haven't used Greentea before, [you can learn more in our documentation](. Please ignore tests with similar errors. -Further optimisations for targets with small flash memories: +Further optimizations for targets with small flash memories: - Append `--profile release` to the command above. Use of the release profile helps keep some tests within the size limit. - Save additional memory by using a [minimal console](https://github.com/ARMmbed/mbed-os-example-blinky-baremetal#using-a-minimal-console) to remove file handling functionality from the system I/O retarget code. diff --git a/docs/bare_metal/using_bare_metal.md b/docs/bare_metal/using_bare_metal.md index f717fca85..fdc2e4cb3 100644 --- a/docs/bare_metal/using_bare_metal.md +++ b/docs/bare_metal/using_bare_metal.md @@ -42,7 +42,7 @@ To create the application using Mbed CLI: The `mbed_app.json` file specifies which **profile** to use (`"requires": ["bare-metal"]`) and which **C library** to use (`"target.c_lib": "small"`). - This example uses `"target.c_lib": "small"` (small C library). This means your application will use an optimised version of the C library with lower memory footprint. For more details, see [Using small C libraries in Mbed OS bare metal](../bare-metal/using-small-c-libraries.html). + This example uses `"target.c_lib": "small"` (small C library). This means your application will use an optimized version of the C library with lower memory footprint. For more details, see [Using small C libraries in Mbed OS bare metal](../bare-metal/using-small-c-libraries.html). ## 2. Adding APIs diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md index 779ce26d1..4c0e6cd2e 100644 --- a/docs/introduction/introduction.md +++ b/docs/introduction/introduction.md @@ -8,7 +8,7 @@ The Mbed OS source code is available on [GitHub](https://github.com/ARMmbed/mbed The **full profile** of Mbed OS is an RTOS (it includes [Keil RTX](https://www2.keil.com/mdk5/cmsis/rtx) and all RTOS APIs), so it supports deterministic, multithreaded, real-time software execution. The RTOS primitives are always available, allowing drivers and applications to rely on threads, semaphores, mutexes and other RTOS features. It also includes all APIs by default, although you can remove unused ones at build time. -The **bare metal profile** doesn't include Keil RTX and is therefore not an RTOS - it is designed for applications that do not require complex thread management. It is also designed for constrained devices, and therefore focuses on minimising the size of the final application: by default, it includes only the smallest possible set of APIs, to which you can manually add APIs that your application requires. The bare metal profile can use the small C libraries (which are not thread safe) to further minimise the size of the application. Mbed 2 users who want to move to Mbed OS 6 should use the bare metal profile. +The **bare metal profile** doesn't include Keil RTX and is therefore not an RTOS - it is designed for applications that do not require complex thread management. It is also designed for constrained devices, and therefore focuses on minimizing the size of the final application: by default, it includes only the smallest possible set of APIs, to which you can manually add APIs that your application requires. The bare metal profile can use the small C libraries (which are not thread safe) to further minimize the size of the application. Mbed 2 users who want to move to Mbed OS 6 should use the bare metal profile. ## Licensing @@ -24,6 +24,7 @@ Our [quick start](../quick-start/index.html) guides show how to build an example ## Recently updated documentation +- A new section about [optimizing for throughput and power consumption](../apis/optimizing-applications-for-throughput-and-power-consumption.html) with Bluetooth Low Energy (BLE). We've also removed old material relating to services which are no longer supported and instead provided links to the [Experimental services for Mbed OS BLE](../apis/ble-services.html) repository. - We've updated the [unit testing](../debug-test/unit-testing.html) information to reflect changes to the version of CMake used. You will need to update to CMake version 3.19 or above and alter your test code structure. - A new [Mbed CLI1 to CLI2 migration guide](../build-tools/migration-guide.html). - A new [tutorial about link time optimization](../apis/link-time-optimization.html). diff --git a/docs/introduction/terms.md b/docs/introduction/terms.md index 8792add5f..38125013a 100644 --- a/docs/introduction/terms.md +++ b/docs/introduction/terms.md @@ -22,7 +22,7 @@ **Bit** - A basic unit of digital information that can be one of two values: `0` (`false`) or `1` (`true`). -**BLE** - [Bluetooth Low Energy](../apis/ble.html). +**BLE** - [Bluetooth Low Energy](../apis/bluetooth-apis.html). **Blinky** - An [example application](../quick-start/index.html) that you can use to get to know Arm Mbed OS and the development tools. It’s one of the simplest examples of Mbed OS. @@ -170,3 +170,10 @@ ## U **utest** - A [test harness](../debug-test/utest-asynchronous-c-test-harness.html) you can use to execute a specified series of (asynchronous) C++ test cases. + + +## Inclusive terminology commitment + +Arm values inclusive communities. Arm recognizes that we and our industry have used terms that can be offensive. Arm strives to lead the industry and create change. + +This document includes terms that can be offensive. We will replace these terms in a future issue of this document. If you find offensive terms in this document, please contact [terms@arm.com](mailto:terms@arm.com). diff --git a/docs/reference/configuration/rtos-config.md b/docs/reference/configuration/rtos-config.md index 85e218c42..9edef303c 100644 --- a/docs/reference/configuration/rtos-config.md +++ b/docs/reference/configuration/rtos-config.md @@ -30,7 +30,7 @@ Name: rtos.idle-thread-stack-size Macro name: MBED_CONF_RTOS_IDLE_THREAD_STACK_SIZE Value: 512 (set by library:rtos) Name: rtos.idle-thread-stack-size-debug-extra - Description: Additional size to add to the idle thread when code compilation optimisation is disabled + Description: Additional size to add to the idle thread when code compilation optimization is disabled Defined by: library:rtos Macro name: MBED_CONF_RTOS_IDLE_THREAD_STACK_SIZE_DEBUG_EXTRA Value: 128 (set by library:rtos[STM]) diff --git a/readme.md b/readme.md index 27486c4fb..1120e97a8 100644 --- a/readme.md +++ b/readme.md @@ -7,6 +7,6 @@ If you want to contribute, please read our [contribution guide](https://os.mbed. Please open pull requests against either: - `development` - this is our development branch. -- `6.2` - this is the latest live version. +- `6.12` - this is the latest live version. Older version branches probably don't require fixes; please open an issue if you think we're wrong.