Docs fixes (#1467)

* update intro section to refer to new BLE optimiztion section, correct spelling (optimise/optimize etc.) in various places for consitency (including a filename change), and minor improvements to wording in new BLE topics.

* correct filepath

* correct link / link text

Author: ChrisGooch-Arm

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"
                                 }
                             ]
                         },

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)
+- [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)

docs/api/connectivity/bluetooth/Optimising_for_performance.md renamed to 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.
 

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
         }
     }

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.
 

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
 

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).

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])

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.