diff --git a/docs/reference/runtime/Memory.md b/docs/reference/runtime/Memory.md index ad97fec17d..1a40841d9a 100644 --- a/docs/reference/runtime/Memory.md +++ b/docs/reference/runtime/Memory.md @@ -61,7 +61,7 @@ There are at least two kinds of memory in the system: flash and RAM. ## RAM -Inside RAM, you can distinguish two logical types: static and dynamic memory. Static memory is allocated at compile time and, consequently, does not change size during runtime. Dynamic memory is allocated at runtime. For example, the program memory use grows and shrinks as you fork and join threads and construct and destruct objects. The system uses each of them in different ways: +Inside RAM, you can distinguish two logical types: **static** and **dynamic** memory. Static memory is allocated at compile time and, consequently, does not change size during runtime. Dynamic memory is allocated at runtime. For example, program memory use grows and shrinks as you fork and join threads, and construct and destruct objects. The system uses each of them in different ways: - Static: - Vector table (read and write). @@ -71,13 +71,13 @@ Inside RAM, you can distinguish two logical types: static and dynamic memory. St - Stacks for default threads (main, timer, idle and scheduler/ISR). - Dynamic: - Heap (dynamic data). - - Stacks for user threads. Mbed OS dynamically allocates memory on heap for user thread's stacks. + - Stacks for user threads. Mbed OS dynamically allocates memory on heap for user thread stacks. Stack checking is turned on for all threads, and the kernel errors if it detects an overflow condition. ## Flash -Flash is a read only memory (ROM) that contains: +Flash is a read-only memory (ROM) that contains: - Vector table (read only). - Application code. diff --git a/docs/reference/runtime/static_memory_optimization.md b/docs/reference/runtime/static_memory_optimization.md index 1a90f36442..7bb65e2236 100644 --- a/docs/reference/runtime/static_memory_optimization.md +++ b/docs/reference/runtime/static_memory_optimization.md @@ -23,7 +23,7 @@ The `features/frameworks` module includes the Mbed OS test tools, even if you ar #### `Printf` and UART -The linker can also remove other modules that your program does not use. For example, [Blinky's](https://github.com/ARMmbed/mbed-os-example-blinky) `main` program doesn't use `printf` or UART drivers. However, every Mbed OS module handles traces and assertions by redirecting their error messages to `printf` on serial output - forcing the `printf` and UART drivers to be compiled in and requiring a large amount of flash memory. +The linker can also remove other modules that your program does not use. For example, [Blinky's](https://github.com/ARMmbed/mbed-os-example-blinky) `main` program doesn't use `printf` or UART drivers. However, every Mbed OS module handles traces and assertions by redirecting their error messages to `printf` on serial output. This forces the `printf` and UART drivers to compile and requires a large amount of flash memory. To disable error logging to serial output, set the `NDEBUG` macro and the following configuration parameter in your program's `mbed_app.json` file: @@ -40,7 +40,7 @@ To disable error logging to serial output, set the `NDEBUG` macro and the follow } ``` -**Note:** Different compilers, different results; compiling with one compiler yields different memory usage savings than compiling with another. +**Note:** Different compilers yield different memory savings. #### Embedded targets @@ -49,6 +49,6 @@ You can also take advantage of the fact that these programs only run on embedded - The code that the compiler injects consumes memory. - It implies dynamic memory allocation and thus requires the binary to include `malloc`, even when the application does not use it. -When you run an application on an embedded device, you don't need handlers to destroy objects when the program exits, because the application will never end. You can save more RAM and flash memory usage by [removing destructor registration](https://github.com/ARMmbed/mbed-os/pull/2745) on application startup and by eliminating the code to destruct objects when the operating system calls `exit()` at runtime. +When you run an application on an embedded device, you don't need handlers to destroy objects when the program exits, because the application will never end. To save more RAM and flash memory, [remove destructor registration](https://github.com/ARMmbed/mbed-os/pull/2745) on application startup and eliminate the code to destruct objects when the operating system calls `exit()` at runtime. **Note:** Mbed OS 5.2.0+ enables removing destructor registration by default. diff --git a/docs/reference/technology/USB.md b/docs/reference/technology/USB.md index 890804c804..37a564077b 100644 --- a/docs/reference/technology/USB.md +++ b/docs/reference/technology/USB.md @@ -2,11 +2,11 @@ ## Introduction -A functional Mbed OS USB device consists of three parts - an implementation of USBPhy, the USBDevice stack and a USB component code: +A functional Mbed OS USB device consists an implementation of USBPhy, the USBDevice stack and a USB component code: -- USBPhy - provides raw access to USB in the role of a USB Device. -- USBDevice - the core of Mbed OS's USB stack and is responsible for state management and synchronization. -- USB component - code that inherits from USBDevice and provides the desired USB interfaces. +- USBPhy provides raw access to USB in the role of a USB Device. +- USBDevice is the core of Mbed OS's USB stack and is responsible for state management and synchronization. +- USB component is code that inherits from USBDevice and provides the desired USB interfaces. ![](../../images/usb_inheritance_diagram.png) @@ -16,9 +16,9 @@ You can see the interaction of these three components in this diagram: ## Synchronization -The class USBDevice is an interrupt-safe class. It uses a critical section to provide thread- and interrupt-safe locking. USB components inheriting from USBDevice can use this lock, but it is not required. +The class **USBDevice** is interrupt-safe. It uses a critical section to provide thread- and interrupt-safe locking. USB components inheriting from USBDevice can use this lock, but it is not required. -The recommended model for synchronizing a USB component is to wrap code requiring synchronization in a call to `USBDevice::lock` and `USBDevice::unlock`. Functions or callbacks that a caller at a higher level has already synchronized should document this locking requirement by calling `USBDevice::assert_locked` in the first line of the function or callback. +The recommended model for synchronizing a USB component is to wrap code requiring synchronization in a call to `USBDevice::lock` and `USBDevice::unlock`. Functions or callbacks already synchronized by a caller at a higher level should document this locking requirement by calling `USBDevice::assert_locked` in the first line of the function or callback. Code requiring locking: @@ -46,7 +46,7 @@ void USBComponent::do_something_internal() ## USB device state -USB defines 5 separate states a device can be in - Attached, Powered, Default, Address and Configured. Each state adds functionality. The Attached state has the least functionality, and the Configured state has the most functionality. +USB defines five separate states of a device: **Attached**, **Powered**, **Default**, **Address** and **Configured**. Each state adds functionality. The **Attached** state has the least functionality, and the **Configured** state has the most functionality. | State | Functionality | |:----------:|:----------------------------------------:| @@ -56,11 +56,11 @@ USB defines 5 separate states a device can be in - Attached, Powered, Default, A | Address | No new functionality | | Configured | All enabled endpoints are functional | -At any time, the USB device can enter a state with less functionality. This could be due to a loss of power event or a surprise USB disconnect. When leaving or outside of the Configured state, USBDevice ignores writes to and reads from all endpoints other than endpoint 0. +Random power loss can cause the USB device to lose functionality. When leaving or outside of the Configured state, USBDevice ignores writes to and reads from all endpoints other than endpoint 0. ## USB component callbacks -All callbacks USBDevice sends to its children are prefixed with callback_*. USBDevice calls these callbacks with the USB lock held. One notable callback is `callback_state_change`, which USB components can use generically to handle leaving the Configured state. The USB stack automatically exits the Configured state on disconnect, power loss or USB reset. +All callbacks USBDevice sends to its children are prefixed with `callback_*`. USBDevice calls these callbacks with the USB lock held. One notable callback is `callback_state_change`, which USB components can use generically to handle leaving the Configured state. The USB stack automatically exits the Configured state on disconnect, power loss or USB reset. ### Control request state machine @@ -93,7 +93,7 @@ Below is a diagram showing the typical state machine for read (OUT) and write (I To ensure a USB component runs on all supported devices, the USB component must select the configuration descriptor's endpoints based on the current device. This is because endpoint number and endpoint functionality can differ by device. A USB component can determine the features of USBPhy by examining its endpoint table. -To simplify the process of selecting endpoints, we recommend you use the EndpointResolver class. A USB component constructs the class with an endpoint table. The USB component can then call the class to find an endpoint of the given type and size. After the component finds all required endpoints, it can call the function `EndpointResolver::valid()` to determine whether this device supports this configuration. Below is an example of this: +To simplify the process of selecting endpoints, use the **EndpointResolver** class. A USB component constructs the class with an endpoint table. The USB component can then call the class to find an endpoint of the given type and size. After the component finds all required endpoints, it can call the function `EndpointResolver::valid()` to determine whether this device supports this configuration. Below is an example of this: ```c++ TODO EndpointResolver resolver(endpoint_table()); diff --git a/docs/reference/technology/connectivity/NFC.md b/docs/reference/technology/connectivity/NFC.md index f53aa2b15c..87acf520dc 100644 --- a/docs/reference/technology/connectivity/NFC.md +++ b/docs/reference/technology/connectivity/NFC.md @@ -26,7 +26,7 @@ An NFC EEPROM can read from and write to a NDEF message. A NFC initiator can acc The NFC Forum defines 5 Tag specifications, which define how to transmit and receive NDEF messages on top of various NFC technologies. -When using a controller, the Mbed OS NFC Framework can implement the [Type 4 Tag platform](https://nfc-forum.org/our-work/specifications-and-application-documents/specifications/tag-type-technical-specifications/). This means that the initiator can gnerate NDEF messages dynamically before each read and parse it after each write. +When using a controller, the Mbed OS NFC Framework can implement the [Type 4 Tag platform](https://nfc-forum.org/our-work/specifications-and-application-documents/specifications/tag-type-technical-specifications/). This means that the initiator can generate NDEF messages dynamically before each read and parse it after each write. ## NFC controllers and NFC EEPROMs @@ -46,7 +46,7 @@ NFC examples are available on [GitHub](https://github.com/ARMmbed/mbed-os/tree/m ## API -There are two entrypoints for the API, depending on whether you are using a NFC Controller or EEPROM. +There are two entry points for the API, depending on whether you are using a NFC Controller or EEPROM. You must initiate either entry point with a driver instance, an event queue and a scratch buffer for NDEF messages. diff --git a/docs/reference/technology/connectivity/connectivity.md b/docs/reference/technology/connectivity/connectivity.md index d61662066d..17e31886d8 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -6,14 +6,14 @@ Mbed OS offers a strong, integrated stack of standards-based technologies: For IP devices: +- Cellular. +- NB-IoT. - Thread. - Wi-SUN. - 6LoWPAN-ND. -- Cellular. -- NB-IoT. - Bluetooth Low Energy (BLE). -Non-IP devices: +Non-IP devices require a gateway: - LoRaWAN. - Cellular. @@ -26,7 +26,7 @@ There is a wide variety of possibilities for connected devices, and there is no Mbed OS supports various IP-based connectivity options and IP stacks. -![](../../../images/ip-networking-simple.png) +![](../../../images/ip-networking-simple.png)Connectivity stack architecture in Mbed OS Our Socket API standardizes all of our connectivity options. It supports both IPv4 and IPv6. Applications are portable regardless of final connectivity option. @@ -34,7 +34,7 @@ Mbed OS provides network drivers, such as Ethernet, Wi-Fi and cellular. ### Wi-Fi -Wi-Fi has a relatively high throughput of up to 1 gbps, which is suitable for data-heavy applications. The cost of this throughput is high power consumption. Wi-Fi is not ideal for long-term deployments of battery-powered devices. It can also prove problematic where other devices compete for the same bandwidth. +Wi-Fi has a relatively high throughput of up to 1 Gbps, which is suitable for data-heavy applications. The cost of this throughput is high power consumption. Wi-Fi is not ideal for long-term deployments of battery-powered devices. It can also prove problematic where other devices compete for the same bandwidth. It works for proof-of-concept devices because the infrastructure is in place in most offices, and its WPA2 security is familiar to developers. @@ -42,7 +42,7 @@ End devices for Wi-Fi are complicated due to hardware requirements and limitatio ### Cellular -Cellular has a variable throughput, reaching 10 mbps. Its coverage is extensive, and its range is 25-100km, so it is commonly used in transportation and logistics. It is also well-suited for proof of concept because, like Wi-Fi, it relies on an existing infrastructure. It's suitable for many use cases, from monitoring temperature sensors to streaming video. +Cellular has a variable throughput, reaching 10 Mbps. Its coverage is extensive, and its range is 25-100 km, so it is commonly used in transportation and logistics. It is also well suited for proof of concept, because, like Wi-Fi, it relies on an existing infrastructure. It's suitable for many use cases, from monitoring temperature sensors to streaming video. Cellular coverage, load balancing and reliability are the responsibility of the providers, not the application. However, network access is subscription based, so there is a direct correlation between use and cost. diff --git a/docs/reference/technology/connectivity/ethernet.md b/docs/reference/technology/connectivity/ethernet.md index 78082cc81a..6328eda647 100644 --- a/docs/reference/technology/connectivity/ethernet.md +++ b/docs/reference/technology/connectivity/ethernet.md @@ -1,8 +1,8 @@

Ethernet

-The term "Ethernet" refers to technologies first introduced in 1980 and standardized in 1983 as IEEE 802.3. Ethernet is a wired network, usually implemented by twisted pair wiring, but optical fibre and coaxials exist, as well. However, coaxial has been superseded, and no one uses it anymore. +The term **Ethernet** refers to technologies first introduced in 1980 and standardized in 1983 as **IEEE 802.3**. Ethernet is a wired network, usually implemented by twisted pair wiring, or optical fiber and coaxials. However, coaxial has largely become obsolete. -Initially, the speed from the standard was 1 Mb/s but later standards increased it to first 10 Mb/s and later 100 Mb/s and 1 Gb/s. The latter two remain the most popular connection speeds today. +Initially, the speed from the standard was 1 Mbps, but later standards increased it first to 10 Mbps, and later 100 Mbps and 1 Gbps. The latter two are the most popular connection speeds today. Ethernet works with cable lengths of up to 100 meters. When connected to a switch, Ethernet allows the maximum segment length to span 200 meters. @@ -10,21 +10,21 @@ Ethernet works with cable lengths of up to 100 meters. When connected to a switc ## Ethernet connection speeds -Since introducing the initial standard, IEEE has improved Ethernet by making it faster and cheaper and has released subsequent standards covering these improvements. +Since introducing the initial standard, IEEE has improved Ethernet, making it faster and cheaper, and has released subsequent standards covering these improvements. | Speed | Name | Standard | Year | Description | |-----------|------------|--------------|------|-------------| -| 10 Mb/s | 10BASE-5 | IEEE 802.3 | 1983 | First Ethernet standard, used thick coaxial cable. | -| 10 Mb/s | 10BASE-2 | IEEE 802.3a | 1985 | Superseded the first coaxial by using thinner and cheaper cable. Newer versions of IEEE 802.3 make both obsolete now. | -| 10 Mb/s | 10BASE-T | IEEE 802.3i | 1990 | Became most popular Ethernet by replacing problematic coaxial cables. Uses CAT-3 twisted pair cable. | -| 100 Mb/s | 100BASE-TX | IEEE 802.3u | 1995 | Standard called "Fast Ethernet", uses CAT-5 twisted pair cable. | -| 1000 Mb/s | 1000BASE-T | IEEE 802.3ab | 1999 | Increased the speed to 1 Gb/s by using CAT-5e cable. Together with 100BASE-TX remain the most popular standards today. | +| 10 Mbps | 10BASE-5 | IEEE 802.3 | 1983 | First Ethernet standard; used thick coaxial cable. | +| 10 Mbps | 10BASE-2 | IEEE 802.3a | 1985 | Superseded the first coaxial by using thinner and cheaper cable. Newer versions of IEEE 802.3 make both obsolete now. | +| 10 Mbps | 10BASE-T | IEEE 802.3i | 1990 | Became most popular Ethernet by replacing problematic coaxial cables with CAT-3 twisted pair cable. | +| 100 Mbps | 100BASE-TX | IEEE 802.3u | 1995 | Standard called **Fast Ethernet**; uses CAT-5 twisted pair cable. | +| 1000 Mbps | 1000BASE-T | IEEE 802.3ab | 1999 | Increased speed to 1 Gbps using CAT-5e cable. With 100BASE-TX, the most popular standard today. | -Today, most Ethernet devices are capable of automatically negotiating connection speeds of 10/100/1000 Mbit/s with the switch. However, embedded devices rarely support 1 Gb/s connection speed. +Today, most Ethernet devices are capable of automatically negotiating connection speeds of 10/100/1000 Mbit/s with the switch. However, embedded devices rarely support 1 Gbps connection speed. ## Ethernet frames -Ethernet framing has remained nearly untouched after its initial introduction, making it possible to connect devices with various speeds to the same Ethernet segment. Mbed OS only uses Ethernet for carrying IP frames. +Ethernet framing has remained nearly untouched after its initial introduction, making it possible to connect devices with various speeds to the same Ethernet segment. Mbed OS uses Ethernet only to carry IP frames. ![](../../../images/ethernet-frame.png)Ethernet frame @@ -34,12 +34,12 @@ DST: 48 bit destination MAC address SRC: 48 bit source MAC address -Type: Originally this was length field, but later used as specifying the content type of payload. Also known as EtherType. +Type: Originally length field, but later used to specify content type of payload. Also known as EtherType. Values higher than 1536 are registered type specifiers. Most common is 0x0800 for IPv4 and 0x86DD for IPv6. -Q-Tag: Optional virtual lan ID. +Q-Tag: Optional virtual LAN ID. -FCS: Frame Check Sequence is used for integrity check. Implemented as CRC-32 +FCS: Frame Check Sequence used for integrity check. Implemented as CRC-32. ## Follow-up information diff --git a/docs/reference/technology/connectivity/lora-tech.md b/docs/reference/technology/connectivity/lora-tech.md index fad20cf268..fe88202b99 100644 --- a/docs/reference/technology/connectivity/lora-tech.md +++ b/docs/reference/technology/connectivity/lora-tech.md @@ -51,7 +51,7 @@ The base stations transmit a beacon every 128 seconds, and all Class B nodes are ![](../../../images/class_b_timing.png)Figure 3: Class B timing diagram -Beacon guard time precedes each beacon, and no ping slot can be placed in that time period. A ping slot is a 30ms unit that you can assign to a Class B device. Beacon reserved is a time period when the actual beacon is sent. Beacon window is the time period when you can open and assign ping slots. +Beacon guard time precedes each beacon, and no ping slot can be placed in that time period. A ping slot is a 30 ms unit that you can assign to a Class B device. Beacon reserved is a time period when the actual beacon is sent. Beacon window is the time period when you can open and assign ping slots. - Beacon period = 128 seconds. - Beacon reserved = 2.120 seconds. @@ -157,7 +157,7 @@ radio.unlock(); ``` ##### Example: radio generating interrupt -The radio driver uses the callbacks it received in the form `radio_events_t` to notify the the upper layers to postprocess an interrupt. +The radio driver uses the callbacks it received in the form `radio_events_t` to notify the upper layers to postprocess an interrupt: ```C NOCI if (signal & GENERATE_TX_DONE) { @@ -276,7 +276,7 @@ The flow for reception looks like this: By default, the stack handles the case automatically if any data is pending on the network server side waiting to be delivered to the device or if there are any MAC command responses that require an immediate uplink. - When there is pending data indicated by fPending bit set in the previous downlink message sent by Network Server, the stack will automatically generate an empty outgoing message, if not configured otherwise. Application will not receive a `TX_DONE` in this case. The application may receive subsequent `RX_DONE` events as per reception of the pending data. -- If a MAC command requires an immediate response, the stack generates an empty uplink automatically if not configured otherwise. The `TX_DONE` event is supressed because it was an automatic uplink. +- If a MAC command requires an immediate response, the stack generates an empty uplink automatically if not configured otherwise. The `TX_DONE` event is suppressed because it was an automatic uplink. While the automatic uplink transaction is taking place, you receive a `LORAWAN_STATUS_WOULD_BLOCK` error message if you attempt to do a data uplink. diff --git a/docs/reference/technology/connectivity/networking.md b/docs/reference/technology/connectivity/networking.md index 9427a22afe..5b10d8c8b0 100644 --- a/docs/reference/technology/connectivity/networking.md +++ b/docs/reference/technology/connectivity/networking.md @@ -53,7 +53,7 @@ Please note that the interface API is not the same as the network driver. The in Mbed OS implements the following network interface APIs: - Ethernet. -- WiFi. +- Wi-Fi. - Cellular (PPP). - 6LoWPAN-ND mesh networking. - Thread mesh networking. diff --git a/docs/reference/technology/connectivity/securesocket.md b/docs/reference/technology/connectivity/securesocket.md index 4209c9ad9b..420498b5db 100644 --- a/docs/reference/technology/connectivity/securesocket.md +++ b/docs/reference/technology/connectivity/securesocket.md @@ -20,7 +20,7 @@ socket->connect(HOST_NAME, PORT) socket->send(data, size); ``` -Please note that internal TLS structures require over 1 kB of RAM, so you need to allocate each TLSSocket from the heap by using the `new` command, instead of using stack or statically allocating it. +**Note:** Internal TLS structures require over 1 KB of RAM. Allocate each TLS Socket from the heap by using the `new` command, instead of using stack or statically allocating it. ## Design @@ -102,7 +102,7 @@ This destroys the memory the TLS library allocates. It also closes the transport virtual nsapi_error_t connect(const SocketAddress &address); ``` -The code above initiates the TCP connection and continues to TLS hanshake. If [transport mode](#transport-modes) is either `TRANSPORT_KEEP` or `TRANSPORT_CLOSE`, TCP is assumed to be open and state directly goes into TLS handshake. This is currently forced to blocking mode. After succesfully connecting, you can set it to nonblocking mode: +The code above initiates the TCP connection and continues to the TLS handshake. If [transport mode](#transport-modes) is either `TRANSPORT_KEEP` or `TRANSPORT_CLOSE`, TCP is assumed to be open and state directly goes into TLS handshake. This is currently forced to blocking mode. After connecting, you can set it to nonblocking mode: ``` virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size); @@ -139,8 +139,8 @@ These are returning `NSAPI_ERROR_UNSUPPORTED` as you can't set TLS socket to lis `TLSSocketWrapper` has four modes that are given in the constructor and affect how the transport Socket is used in connection and closing phases: -|Mode|Behavior on trasport socket| -|----|----------------------------| +| Mode | Behavior on transport socket | +|------|------------------------------| |TRANSPORT_KEEP | Keep the transport as it is. Does not call `connect()` or `close()` methods. | |TRANSPORT_CONNECT_AND_CLOSE | Both `connect()` and `close()` are called. (default) | |TRANSPORT_CONNECT | Call `connect()`, but do not close the connection when finished. | diff --git a/docs/reference/technology/connectivity/wifi.md b/docs/reference/technology/connectivity/wifi.md index 28c836cca4..bc41650944 100644 --- a/docs/reference/technology/connectivity/wifi.md +++ b/docs/reference/technology/connectivity/wifi.md @@ -6,7 +6,7 @@ To users, these networks behave exactly as Ethernet but without cables. ![](../../../images/wlan-segment.png)WLAN networks -A WLAN network typically consists of an access point (AP) connected to an Ethernet backbone and multiple stations (STA) connecting the same access point. You can identify networks by their name, which the standard refers to as *service set identifier* (SSID). Multiple access points can serve the same network, and you can identify each AP by its *basic service set identifier* (BSSID). +A WLAN network typically consists of an access point (AP) connected to an Ethernet backbone and multiple stations (STA) connecting the same access point. You can identify networks by their name, which the standard refers to as **service set identifier** (SSID). Multiple access points can serve the same network, and you can identify each AP by its **basic service set identifier** (BSSID). ## Standards @@ -20,7 +20,7 @@ The original version of the standard IEEE 802.11 was released in 1997. Updates a | 802.11n | 2009 | 6.5 - 600 | Both 2.4 Ghz and 5 Ghz | | 802.11ac | 2013 | 6.5 - 1000 | 5 Ghz | -Today, new access points and computers support all a/b/g/n/ac standards, and most embedded devices offer only a/b/g/n capability. The device and the access point negotiate speed and standard automatically without requiring user configuration. +Today, new access points and computers support all a/b/g/n/ac standards, and most embedded devices offer only a/b/g/n capability. The device and the access point negotiate speed and standard automatically without requiring a user configuration.git check. ## Wi-Fi in Mbed OS diff --git a/docs/reference/technology/firmware_update.md b/docs/reference/technology/firmware_update.md index 4e02be9bf5..308b4a7343 100644 --- a/docs/reference/technology/firmware_update.md +++ b/docs/reference/technology/firmware_update.md @@ -1,11 +1,11 @@ # Firmware update in Mbed OS -Mbed OS integrates the Pelion Device Management firmware update services, so if you have a Device Management account, you can send binaries to your remote device. You can update the bootloader independently of the application. +Mbed OS integrates Pelion Device Management firmware update services, so if you have a Device Management account, you can send binaries to your remote device. You can update the bootloader independently of the application. Update support in Mbed OS relies on two features: - Mbed OS now includes the bootloader that manages update verification and installation. -- Mbed CLI and the Mbed Online Compiler now support update actions, by using the Update Service APIs and the Manifest Tool. We have a quick start [for updating through the Online Compiler](https://cloud.mbed.com/guides/pelion-firmware-update), and a review [of the Mbed CLI flow and commands]../tools/cli-update.html). +- Mbed CLI and the Mbed Online Compiler now support update actions using the Update Service API and manifest tool. We have a quick start guide [for updating through the Online Compiler](https://cloud.mbed.com/guides/pelion-firmware-update), and a review [of the Mbed CLI flow and commands](../tools/cli-update.html). ## Updatable binaries @@ -14,9 +14,9 @@ The active firmware, made up of Mbed OS and an application, can be updated only 1. A bootloader, as [reviewed below](#the-mbed-os-bootloader). The bootloader can load a new version of the firmware. If for some reason, the update fails, the bootloader falls back to the firmware version last known to work. As a security feature, the default behavior of the bootloader is to refuse to roll back to old firmware versions once an update succeeds. 1. Mbed OS with the Device Management Client (which includes the Update client). The clients allow your device to communicate with the Device Management Update service, receive update manifests and firmware, and verify the binary's validity. They are [reviewed in details in our Pelion Device Management documentation](https://cloud.mbed.com/docs/latest/updating-firmware/index.html). - Note: Because some embedded devices don't require remote update capabilities, Mbed OS does not include the Device Management Client by default; you need to explicitly import the client to your application. + **Note:** Because some embedded devices don't require remote update capabilities, Mbed OS does not include the Device Management Client by default. You must explicitly import the client to your application. -1. Permission to access your Device Management account, as well as keys and certificates used to verify the firmware's source and validity. +1. Permission to access your Device Management account, as well as keys and certificates to verify the firmware's source and validity. ## The Mbed OS bootloader @@ -24,7 +24,7 @@ During system startup, a bootloader is responsible for selecting and forwarding ### Background: boot sequences and fault tolerance -A boot sequence can have several stages of bootloaders, leading to an application. The different stages (including the application) may need to evolve over time, to add features or bug-fixes. Upgrades are possible for boot sequences with two or more stages: any active stage can replace the next stage in the sequence; when the system restarts, it executs the updated components. Typically, however, the very first stage isn't replaced; because it takes control on startup, a faulty upgrade of this stage can make recovery impossible. This is known as stage 0 bootloader. +A boot sequence can have several stages of bootloaders, leading to an application. The different stages (including the application) may need to evolve over time, to add features or bug-fixes. Upgrades are possible for boot sequences with two or more stages: any active stage can replace the next stage in the sequence; when the system restarts, it executes the updated components. Typically, however, the very first stage isn't replaced; because it takes control on startup, a faulty upgrade of this stage can make recovery impossible. This is known as stage 0 bootloader. To protect against faults in the newly updated components, we store multiple versions (up to a certain maximum number of versions). Each stag is responsible for detecting faults in the following component and rolling it back if it discovers faults. For example, if stage 3 is unstable, needs additional functionality or is otherwise behaving incorrectly, stage 2 (during the *next* startup sequence) can roll stage 3 back to an earlier version before handing over control. This results in a boot-sequence tree that is traversed in a depth-first order as the system recovers from successive faults. @@ -38,7 +38,7 @@ Fault tolerance ultimately rests on the sanity of the first-stage bootloader. Th The Mbed OS bootloader is a hybrid of the boot selector and a bootloader, but it fulfills the requirements of the boot selector: It is small enough to minimize the chance of bugs, but it is advanced enough to install new images. -### Managed and unamanaged bootloader tool integration +### Managed and unmanaged bootloader tool integration The Mbed tools (Mbed CLI, Online Compiler) can manage bootloaders where: @@ -47,13 +47,13 @@ The Mbed tools (Mbed CLI, Online Compiler) can manage bootloaders where: If the Mbed tool finds a manageable bootloader, the image build process automatically merges the bootloader image with the application image. -If your bootloader does not meet the two requirements of a manageable bootloader, you will need an unmanaged bootloader. The Mbed tools will not automatically combine this bootloader with the application image; you will need to write your own scripts to build your full image. +If your bootloader does not meet the two requirements of a manageable bootloader, you will need an unmanaged bootloader. The Mbed tools do not automatically combine this bootloader with the application image; you need to write your own scripts to build your full image. For more information about [managed and unmanaged bootloaders, and how to create bootloaders, see the tutorial](../tutorials/bootloader.html). ### Porting a bootloader -If you're interested in porting the Update client and bootloader to new hardware, please [review the porting section](../porting/bootloader.html). +If you're interested in porting the Update client and bootloader to new hardware, please [review the porting section](https://www.pelion.com/docs/device-management/current/porting/porting-the-device-management-update-client.html). ### Security @@ -66,14 +66,14 @@ This means that the default bootloader does not implement secure boot; for high- ## Managing updates with the bootloader -When a device downloads new firmware, it stores it locally (in the storage area) and reboots; the device's bootloader then: +When a device downloads new firmware, it stores it locally (in the storage area) and reboots; the device bootloader then: 1. Checks the integrity of the active firmware by calculating the hash of the active image and comparing it to the one in the metadata header (the bootloader metadata header is explained below). 1. Looks for available firmware on the system. There may be more than one image, depending on image sizes. 1. Chooses the firmware with the latest timestamp. 1. Checks the integrity of the image in the storage area by checking its hash against its internal metadata header. 1. Copies the image in the storage area to the active application region if it is applicable. -1. Forwards control to the start of the active firmware, which contains the Update client (part of Device Management client). The Update client runs the Pelion Device Management update process: +1. Forwards control to the start of the active firmware, which contains the Update client (part of Device Management Client). The Update client runs the Pelion Device Management update process: 1. Receives a notification from one of its update sources. 1. Downloads the new manifest and parses it to obtain the firmware URI. 1. Fetches the firmware from one of its update sources. Either the manifest or a cost-ranking algorithm specifies the update source to use. @@ -82,11 +82,11 @@ When a device downloads new firmware, it stores it locally (in the storage area) ## Development tool integration with Pelion Device Management Update -Mbed CLI and the Online Compiler implement the Pelion Device Management Update service by directly using the service's APIs and the manifest tool. For a device running an updatable application, using Mbed CLI and the Online Compiler's built in update features can reduce the steps needed to run an update campaign. +Mbed CLI and the Online Compiler implement the Pelion Device Management Update service by directly using the service APIs and the manifest tool. For a device running an updatable application, using Mbed CLI and the Online Compiler's built-in update features can reduce the steps needed to run an update campaign. -**Note**: The default workflow of the development tools is intended only for development and testing purposes. It is not considered secure for production. +**Note**: The default workflow of the development tools is intended only for development and testing purposes. It is not secure for production. -Your development tool needs to use your Device Management account's API key to call the Pelion Device Management APIs. Once it has access to the APIs, it can generate a manifest and upload the manifest and binary to the server, and deliver the manifest to a device or group of devices. For more information, see [the update API documentation](https://cloud.mbed.com/docs/latest/service-api-references/update-service.html). +Your development tool needs to use your Device Management account API key to call the APIs. Once it has access to the APIs, it can generate a manifest, upload the manifest and binary to the server, and deliver the manifest to a device or group of devices. For more information, see [the update API documentation](https://cloud.mbed.com/docs/latest/service-api-references/update-service.html). **Note**: The tools currently support the update flow for Device Management Client, not Device Management Client Lite. diff --git a/docs/reference/technology/storage.md b/docs/reference/technology/storage.md index 6921a0ca68..23296fe943 100644 --- a/docs/reference/technology/storage.md +++ b/docs/reference/technology/storage.md @@ -1,6 +1,6 @@

Storage

-We designed the architecture of the Mbed OS storage solution with the following properties: +The architecture of the Mbed OS storage solution has the following properties: - Wear-leveling of internal and external flash storage. - No wear-leveling for firmware, both active and future updates. @@ -10,7 +10,7 @@ We designed the architecture of the Mbed OS storage solution with the following ![](../../images/storagearch.png)Mbed OS storage C++ class names (Blue indicates implementation and yellow indicates interfaces) -Storage in Mbed OS is composed of multiple layers that stack. With these stackable layers, you can configure the storage system that is most appropriate for your needs. For example, if you only need to store small, fixed-size data, you can use TDBStore. If you need a POSIX-like API for random access of larger files, such as logs or databases, then LittleFS is a good choice. +Storage in Mbed OS is composed of multiple layers that stack. With these stackable layers, you can configure the storage system that is most appropriate for your needs. For example, if you only need to store small, fixed-size data, you can use TDBStore. If you need a POSIX-like API for random access of larger files, such as logs or databases, then LittleFS is a good choice. ## Class hierarchy @@ -26,7 +26,7 @@ Interfaces from low-level to high-level: An example of implementations of the interfaces are: - BlockDevice. - - QSPIBlockDevice - Block device driver for NOR-based QSPI Flash devices that support the SFDP standard. + - QSPIBlockDevice - Block device driver for NOR-based QSPI Flash devices that support the SFDP standard. - SPIFBlockDevice - Block device driver for NOR-based SPI flash devices that support SFDP. NOR-based SPI flash supports byte-sized read and writes, with an erase size of around 4 kbytes. An erase sets a block to all 1s, with successive writes clearing set bits. - SDBlockDevice - The SD driver uses the SDCard SPI mode of operation, which is a subset of possible SDCard functionality. - FlashIAPBlockDevice - Block device driver bound to the FlashIAP driver in Mbed OS for reading and writing to internal flash. Only use this driver on platforms where the FlashIAP implementation is using external flash or in conjunction with a file system with wear leveling, that can operate on a page size granularity.