From aa55283cc8ca2ff6bf17b3e67da03737ead795fb Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Fri, 26 Apr 2019 11:42:15 +0300 Subject: [PATCH 01/20] first batch of review changes and comments --- docs/reference/technology/connectivity/NFC.md | 6 ++-- .../technology/connectivity/connectivity.md | 29 ++++++++++--------- .../technology/connectivity/ethernet.md | 18 ++++++------ .../technology/connectivity/lora-tech.md | 6 ++-- .../technology/connectivity/networking.md | 2 +- .../technology/connectivity/securesocket.md | 8 ++--- docs/reference/technology/technology.md | 2 ++ 7 files changed, 38 insertions(+), 33 deletions(-) diff --git a/docs/reference/technology/connectivity/NFC.md b/docs/reference/technology/connectivity/NFC.md index 2d2343636f..13358db631 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 @@ -42,11 +42,11 @@ NFC EEPROMs behave like NFC tags whose memory can either be addressed through a NFC examples are available on [GitHub](https://github.com/ARMmbed/mbed-os/tree/master/docs/design-documents/nfc) and demonstrate how to create NFC tags that you can be read from and write to using a phone. -![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/explorenfc_nucleo.jpg)An Explore-NFC board attached to a Nucleo board +![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/explorenfc_nucleo.jpg)An Explore-NFC board attached to a NUCLEO board ## 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 a9b3a48b61..b545723cff 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -13,14 +13,17 @@ For IP devices: - NB-IoT. - Bluetooth Low Energy (BLE). -Non-IP devices: + +Non-IP devices require a gateway: - LoRaWAN. - Cellular. + ## Choosing your connectivity method -There is a wide variety of possibilities for connected devices, and there is no globally correct connectivity method. Choose a method that fits your application needs, then choose a device that can support that method. If you're already committed to a device type, you may need to adjust your application to work within that device's connectivity constraints. + +There is a wide variety of possibilities for connected devices, and no globally correct connectivity method. Choose a method that fits your application needs, then choose a device that can support that method. If you're already committed to a device type, you may need to adjust your application to work within that device's connectivity constraints. ## Internet protocol (IP) networking @@ -32,11 +35,11 @@ Our Socket API standardizes all of our connectivity options. It supports both IP Mbed OS provides network drivers, such as Ethernet, Wi-Fi and cellular. -You can find descriptions of supported interfaces and protocols in the [IP networking](ip-networking.html) section. +You can find descriptions of supported interfaces and protocols in the [IP networking](#ip-networking.html) section. ### 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. @@ -44,7 +47,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 a wide variety of 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-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 a wide variety of 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 usage and cost. @@ -52,13 +55,13 @@ The new cellular technologies, NB-IoT and CAT-M1, are designed for IoT devices. **Narrow-band-IoT** (NB-IoT) relies on a simple waveform and therefore requires the lowest power consumption of all the cellular methods. It also has fewer components and offers better signal penetration through walls (thanks to lower bitrates and better link budgets). It needs a country-specific chip, because each country uses its own spectrum, which complicates production. It also experiences problems with large transfers, because of its reduced bandwidth. -**CAT-M1** has a higher data rate than NB-IoT (closer to existing cellular behaviour), but is not proven to be more power efficient. Any efficiency gains can be lost because of operator configurations. +**CAT-M1** has a higher data rate than NB-IoT (closer to existing cellular behavior), but is not proven to be more power efficient. Any efficiency gains can be lost because of operator configurations. It can be deployed on a single spectrum, reducing antenna configuration complexity, but isn't deployed world-wide, and can take years to be deployed in countries using 3G. ### Bluetooth Low Energy (BLE) -BLE is optimised for cheap, battery-based devices, and has a low memory footprint. It is widely adopted for connected spaces, but requires setting up an infrastructure. Its range is up to 100 meters, with 1 mbps bandwidth. You need an edge gateway so devices in your network can connect to the internet. +BLE is optimized for cheap, battery-based devices, and has a low memory footprint. It is widely adopted for connected spaces, but requires setting up an infrastructure. Its range is up to 100 meters, with 1 Mbps bandwidth. You need an edge gateway so devices in your network can connect to the internet. Typical applications of BLE are health care, fitness trackers, beacons, smart homes, security, entertainment, proximity sensors, industrial applications, and automotives. @@ -66,7 +69,7 @@ To learn how to use BLE on Mbed OS, please refer to the [Bluetooth overview](../ ### IP-based mesh (Thread, Wi-SUN and 6LoWPAN-ND) -As a technology designed with large-scale deployment in mind, mesh is optimized for long battery life and low cost. +Originally designed with large-scale deployment in mind, mesh is optimized for long battery life and low cost. **Thread** is designed for indoor use, with a range of only a few meters. **Wi-SUN** and **6LoWPAN-ND** have a range of up to one kilometer and are therefore better suited for external use. Throughput of Mesh technologies is up to 200 kbps. @@ -88,7 +91,7 @@ For descriptions of different mesh networks, please see the [Thread](../referenc ### LoRaWAN -LoRaWAN is optimized for low power consumption and a low memory footprint (allowing low-cost devices). The downside is a low throughput of no more than 50 kbps, as well as delays. It is a non-IP-based technology. +LoRaWAN is optimized for low power consumption and memory footprint, reducing device cost. The downside is low throughput of no more than 50 kbps, as well as delays. It is a non-IP-based technology. Because of its long range (up to 20 km) and low power, it is suitable for low data rate, outdoors solutions. @@ -98,21 +101,21 @@ The [LoRa](lora-tech.html) section and [LoRa tutorial](../tutorials/LoRa-tutoria ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/n_mark.png)NFC -Near-field communication (NFC) is a short range (few centimeters) wireless technology standard for personal area networks. Typical uses of NFC are commissioning, easy sharing of small content and Bluetooth connection initiation/out-of-band pairing. +Near-field communication (NFC) is a short range (few centimeters) wireless technology standard for personal area networks. Typical uses of NFC are commissioning, easy sharing of small content, and Bluetooth connection initiation/out-of-band pairing. To learn how to use NFC with Mbed OS, please refer to the [Mbed OS NFC overview](../apis/nfc.html). ### NB-IoT cellular -Non-IP Data Delivery (NIDD) is a new feature for communication over NB-IoT. It is enabled by Control Plane cellular IoT EPS optimization and meant to provide improved support of small data transfer. It does this by transporting user data over the control channel, thus reducing the total number of control plane messages when handling a short data transaction. +Non-IP Data Delivery (NIDD) is a new feature for communication over NB-IoT. It is enabled by Control Plane cellular IoT EPS optimization, to provide improved support for small data transfer. It does this by transporting user data over the control channel, thus reducing the total number of control plane messages when handling a short data transaction. To learn how to use this feature with Mbed OS, please refer to [CellularNonIPSocket](../apis/non-ip-cellular-socket.html). ### Memory needs for Pelion-connected devices -Mbed OS's baseline memory footprint, without Pelion connectivity, is 2.8kb of RAM and 8.2kb of flash. When you add connectivity and full functionality, the footprint grows: +Mbed OS's baseline memory footprint, without Pelion connectivity, is 2.8 KB RAM and 8.2 KB flash. When you add connectivity and full functionality, the footprint grows: - For **Device Management Client Lite**, the smaller of the two connectivity libraries: A total of 20 KB RAM, 210 KB flash. This includes not just Ethernet connectivity, but also startup and runtime demands, the size of Client Lite itself and additional drivers. Client Lite is currently available only to certain customer account types. - For **Device Management Client**: A total of 137 KB RAM, 330 KB flash. This adds FileSystem and the full Client to the functionality. -These two connectivity libraries give you the choice of a range of devices. Mbed OS with Client Lite can work on devices with only 64kb RAM and 256kb flash. Mbed OS with the full Client fits comfortably on devices with 128 KB RAM and 1024 KB flash. +These two connectivity libraries give you the choice of a range of devices. Mbed OS with Client Lite can work on devices with only 64 KB RAM and 256 KB flash. Mbed OS with the full Client fits comfortably on devices with 128 KB RAM and 1024 KB flash. diff --git a/docs/reference/technology/connectivity/ethernet.md b/docs/reference/technology/connectivity/ethernet.md index 9dc4f7e2ed..58baee9512 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, but optical fiber and coaxials exist, as well. 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 to first 10 Mbps and later 100 Mbps and 1 Gbps. The latter two remain 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. @@ -14,13 +14,13 @@ Since introducing the initial standard, IEEE has improved Ethernet by making it | 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. Uses 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 the speed to 1 Gbps by using CAT-5e cable. Together with 100BASE-TX remain the most popular standards 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 @@ -37,7 +37,7 @@ 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. 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 diff --git a/docs/reference/technology/connectivity/lora-tech.md b/docs/reference/technology/connectivity/lora-tech.md index 9d35b47cb9..654490a545 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 ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-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 7fce249255..d1fbe6c3c0 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 e94ea3cd07..0c5e9c3ade 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. +Please note that internal TLS structures require over 1 KB of RAM, so you need to 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 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 successfully 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/technology.md b/docs/reference/technology/technology.md index 57d1d6336d..8bc8d12976 100644 --- a/docs/reference/technology/technology.md +++ b/docs/reference/technology/technology.md @@ -1,3 +1,5 @@ # Technology This section of the book talks about technologies that Mbed OS implements or supports. The content in this section details the architecture and protocols, design decisions and historical context of these technologies. + + From ce7f2f50a78e86dabcdf543541831894a70b5436 Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Fri, 26 Apr 2019 14:41:26 +0300 Subject: [PATCH 02/20] second batch of changes --- docs/reference/runtime/Memory.md | 6 ++--- .../technology/connectivity/connectivity.md | 20 +++++++++-------- .../technology/connectivity/ethernet.md | 22 +++++++++---------- .../reference/technology/connectivity/wifi.md | 6 ++--- 4 files changed, 28 insertions(+), 26 deletions(-) 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/technology/connectivity/connectivity.md b/docs/reference/technology/connectivity/connectivity.md index b545723cff..3abe7bb14f 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -20,8 +20,9 @@ Non-IP devices require a gateway: - Cellular. -## Choosing your connectivity method + +## Choosing your connectivity method There is a wide variety of possibilities for connected devices, and no globally correct connectivity method. Choose a method that fits your application needs, then choose a device that can support that method. If you're already committed to a device type, you may need to adjust your application to work within that device's connectivity constraints. @@ -31,6 +32,7 @@ Mbed OS supports various IP-based connectivity options and IP stacks. ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/ip-networking-simple.png) + Our Socket API standardizes all of our connectivity options. It supports both IPv4 and IPv6. Applications are portable regardless of final connectivity option. Mbed OS provides network drivers, such as Ethernet, Wi-Fi and cellular. @@ -47,7 +49,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 a wide variety of 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 a wide variety of 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 usage and cost. @@ -57,7 +59,7 @@ The new cellular technologies, NB-IoT and CAT-M1, are designed for IoT devices. **CAT-M1** has a higher data rate than NB-IoT (closer to existing cellular behavior), but is not proven to be more power efficient. Any efficiency gains can be lost because of operator configurations. -It can be deployed on a single spectrum, reducing antenna configuration complexity, but isn't deployed world-wide, and can take years to be deployed in countries using 3G. +It can be deployed on a single spectrum, reducing antenna configuration complexity, but isn't deployed world-wide, and can take years to deploy in countries using 3G. ### Bluetooth Low Energy (BLE) @@ -69,13 +71,13 @@ To learn how to use BLE on Mbed OS, please refer to the [Bluetooth overview](../ ### IP-based mesh (Thread, Wi-SUN and 6LoWPAN-ND) -Originally designed with large-scale deployment in mind, mesh is optimized for long battery life and low cost. +Designed with large-scale deployment in mind, mesh is optimized for long battery life and low cost. -**Thread** is designed for indoor use, with a range of only a few meters. **Wi-SUN** and **6LoWPAN-ND** have a range of up to one kilometer and are therefore better suited for external use. Throughput of Mesh technologies is up to 200 kbps. +**Thread** is designed for indoor use, with a range of only a few meters. **Wi-SUN** and **6LoWPAN-ND** have a range of up to one kilometer and are therefore better suited for external use. Throughput of Mesh technologies is up to 200 Kbps. Mesh networks are self-healing, with no single point of failure. They are more suitable for limited spaces because of the expense in infrastructure setup and maintenance. -Additionally, Mbed OS Thread stack is certified using pre-defined test sets for stability, reliability, and performance to ensure high quality, production-ready delivery for application and product creation. +Additionally, Mbed OS Thread stack is certified using predefined test sets for stability, reliability, and performance to ensure high quality, production-ready delivery for application and product creation. ### 6LoWPAN Mesh networking @@ -91,7 +93,7 @@ For descriptions of different mesh networks, please see the [Thread](../referenc ### LoRaWAN -LoRaWAN is optimized for low power consumption and memory footprint, reducing device cost. The downside is low throughput of no more than 50 kbps, as well as delays. It is a non-IP-based technology. +LoRaWAN is optimized for low power consumption and memory footprint, reducing device cost. The downside is low throughput of no more than 50 Kbps, as well as delays. It is a non-IP-based technology. Because of its long range (up to 20 km) and low power, it is suitable for low data rate, outdoors solutions. @@ -107,7 +109,7 @@ To learn how to use NFC with Mbed OS, please refer to the [Mbed OS NFC overview] ### NB-IoT cellular -Non-IP Data Delivery (NIDD) is a new feature for communication over NB-IoT. It is enabled by Control Plane cellular IoT EPS optimization, to provide improved support for small data transfer. It does this by transporting user data over the control channel, thus reducing the total number of control plane messages when handling a short data transaction. +Non-IP Data Delivery (NIDD) is a new feature for communication over NB-IoT. It is enabled by Control Plane cellular IoT EPS optimization, to provide improved support for small data transfer. It transports user data over the control channel, thus reducing the total number of control plane messages when handling a short data transaction. To learn how to use this feature with Mbed OS, please refer to [CellularNonIPSocket](../apis/non-ip-cellular-socket.html). @@ -115,7 +117,7 @@ To learn how to use this feature with Mbed OS, please refer to [CellularNonIPSoc Mbed OS's baseline memory footprint, without Pelion connectivity, is 2.8 KB RAM and 8.2 KB flash. When you add connectivity and full functionality, the footprint grows: -- For **Device Management Client Lite**, the smaller of the two connectivity libraries: A total of 20 KB RAM, 210 KB flash. This includes not just Ethernet connectivity, but also startup and runtime demands, the size of Client Lite itself and additional drivers. Client Lite is currently available only to certain customer account types. +- For **Device Management Client Lite**, the smaller of the two connectivity libraries: A total of 20 KB RAM, 210 KB flash. This includes not just Ethernet connectivity, but also startup and runtime demands, the size of Client Lite itself, and additional drivers. Client Lite is currently available only to certain customer account types. - For **Device Management Client**: A total of 137 KB RAM, 330 KB flash. This adds FileSystem and the full Client to the functionality. These two connectivity libraries give you the choice of a range of devices. Mbed OS with Client Lite can work on devices with only 64 KB RAM and 256 KB flash. Mbed OS with the full Client fits comfortably on devices with 128 KB RAM and 1024 KB flash. diff --git a/docs/reference/technology/connectivity/ethernet.md b/docs/reference/technology/connectivity/ethernet.md index 58baee9512..cf6024e46d 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 fiber and coaxials exist, as well. However, coaxial has largely become obsolete. - -Initially, the speed from the standard was 1 Mbps but later standards increased it to first 10 Mbps and later 100 Mbps and 1 Gbps. The latter two remain the most popular connection speeds today. +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 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 Mbps | 10BASE-5 | IEEE 802.3 | 1983 | First Ethernet standard, used thick coaxial cable. | +| 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. Uses 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 the speed to 1 Gbps by using CAT-5e cable. Together with 100BASE-TX remain the most popular standards today. | +| 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 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. ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-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. -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/wifi.md b/docs/reference/technology/connectivity/wifi.md index e25db94cda..2274b6d6bb 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. ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-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 user configuration.git check ## Wi-Fi in Mbed OS @@ -33,6 +33,6 @@ As with Ethernet, Wi-Fi networks are only used for carrying IP traffic in Mbed O For more information, please see the following sections: - [IP networking](ip-networking.html). -- [Ethernet](ethernet-technology.html). +- [Ethernet](ethernet-technology.html). - [Socket API](../apis/socket.html). - [WifiInterface API](../apis/wi-fi.html). From e255d93ebe61584618cb01ae99c41ddace266af3 Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Fri, 26 Apr 2019 15:32:24 +0300 Subject: [PATCH 03/20] firmware update review --- docs/reference/technology/firmware_update.md | 28 ++++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/reference/technology/firmware_update.md b/docs/reference/technology/firmware_update.md index 4e02be9bf5..d71886509f 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 need to 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,14 +47,14 @@ 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). - + ### Security Note two things about the Mbed OS bootloader's design: @@ -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,14 +82,14 @@ 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's API key to call the 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). **Note**: The tools currently support the update flow for Device Management Client, not Device Management Client Lite. - + **Tutorials**: - Try the firmware [update flow on the Online Compiler](https://cloud.mbed.com/guides/pelion-firmware-update). Note: you first need to [use the connecting quick guide to set up the original application](https://cloud.mbed.com/guides/connect-device-to-pelion). From 849afb8f9ac782b7a362a8d55ef9472ad60da520 Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Fri, 26 Apr 2019 16:42:23 +0300 Subject: [PATCH 04/20] memory optimization review --- docs/reference/runtime/static_memory_optimization.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/runtime/static_memory_optimization.md b/docs/reference/runtime/static_memory_optimization.md index 1a90f36442..3911ad23ae 100644 --- a/docs/reference/runtime/static_memory_optimization.md +++ b/docs/reference/runtime/static_memory_optimization.md @@ -18,12 +18,12 @@ For a simple program like [Blinky](https://github.com/ARMmbed/mbed-os-example-bl | Subtotals | 53932 | 2312 | 10520 | +---------------------+-------+-------+-------+ ``` - + The `features/frameworks` module includes the Mbed OS test tools, even if you are no longer testing your program. Because of this, you are building one of our test harnesses into every binary. [Removing this module](https://github.com/ARMmbed/mbed-os/pull/2559) saves a significant amount of RAM and flash memory. #### `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 in 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,8 +40,8 @@ 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 results. Compiling with one compiler yields different memory usage savings than compiling with another. + #### Embedded targets You can also take advantage of the fact that these programs only run on embedded targets. When you run a C++ application on a desktop computer, the operating system constructs every global C++ object before calling `main`. It also registers a handle to destroy these objects when the program ends. The code the compiler injects has some implications for the application: @@ -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. 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. **Note:** Mbed OS 5.2.0+ enables removing destructor registration by default. From 5f2510f4148f26c3b00836bf97bb999b2869ceca Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Fri, 26 Apr 2019 17:43:17 +0300 Subject: [PATCH 05/20] USB and storage --- docs/reference/technology/USB.md | 22 +++++++++++----------- docs/reference/technology/storage.md | 10 +++++----- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/reference/technology/USB.md b/docs/reference/technology/USB.md index 3b879ac84f..dd60ac62c4 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 of three parts: 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. ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-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 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 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. - +The USB device can enter a state with less functionality at any time. This could be due to a loss of power or surprise disconnect. 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 that 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/storage.md b/docs/reference/technology/storage.md index d7a1631d82..0933e280ad 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. @@ -8,9 +8,9 @@ We designed the architecture of the Mbed OS storage solution with the following ## Architectural design -![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/storagearch.png)Mbed OS storage C++ class names (Blue indicates implementation and yellow indicates interfaces) +![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/storagearch.png)Mbed OS storage C++ class names (Blue indicates implementation; 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. @@ -39,7 +39,7 @@ An example of implementations of the interfaces are: - FileHandle. - File - Class that provides read and write access to files on a file system. - BlockDeviceFile - Class that provides read and write access to raw block device storage in the form of a FileHandle. - - UARTSerial - The UARTSerial class provides read and write access to a device's serial hardware. It is an example of a nonstorage device that you can access as a file. + - UARTSerial - The UARTSerial class provides read and write access to a device's serial hardware. It is an example of a non-storage device that you can access as a file. - KVStore. - TDBStore - Default implementation of the KVStore API. It provides static wear-leveling and quick access for when you have a small number of KV pairs. - FileSystemStore - Class that provides a key-value store API on top of a POSIX-like file system API. From 237a10fa44584f87994bb030156a4e8ab2da4913 Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Mon, 29 Apr 2019 11:45:47 +0300 Subject: [PATCH 06/20] Update docs/reference/technology/connectivity/wifi.md --- docs/reference/technology/connectivity/wifi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/technology/connectivity/wifi.md b/docs/reference/technology/connectivity/wifi.md index 2274b6d6bb..cdf2f2beaf 100644 --- a/docs/reference/technology/connectivity/wifi.md +++ b/docs/reference/technology/connectivity/wifi.md @@ -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.git check +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 From a5ef84b2193817a5e3478f8e27235e55696d9f79 Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Mon, 29 Apr 2019 14:43:29 +0300 Subject: [PATCH 07/20] linkfix --- docs/reference/technology/connectivity/connectivity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/technology/connectivity/connectivity.md b/docs/reference/technology/connectivity/connectivity.md index 3abe7bb14f..1741603f1d 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -37,7 +37,7 @@ Our Socket API standardizes all of our connectivity options. It supports both IP Mbed OS provides network drivers, such as Ethernet, Wi-Fi and cellular. -You can find descriptions of supported interfaces and protocols in the [IP networking](#ip-networking.html) section. +You can find descriptions of supported interfaces and protocols in the [IP networking](../reference/ip-networking.html) section. ### Wi-Fi From eba8a4fbc45d5c3f63c20cf92f431ccb4365c192 Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Tue, 30 Apr 2019 11:28:56 -0500 Subject: [PATCH 08/20] Update docs/reference/runtime/static_memory_optimization.md Co-Authored-By: AnotherButler --- docs/reference/runtime/static_memory_optimization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/runtime/static_memory_optimization.md b/docs/reference/runtime/static_memory_optimization.md index 3911ad23ae..776eea427f 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. This forces the `printf` and UART drivers to compile in and requires 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: From 3bd4a3103c370a7644eb5e30c1bff215e48bb18c Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 1 May 2019 16:18:55 -0500 Subject: [PATCH 09/20] Update static_memory_optimization.md Update with note in comments. --- docs/reference/runtime/static_memory_optimization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/runtime/static_memory_optimization.md b/docs/reference/runtime/static_memory_optimization.md index 776eea427f..cc7d76424d 100644 --- a/docs/reference/runtime/static_memory_optimization.md +++ b/docs/reference/runtime/static_memory_optimization.md @@ -18,7 +18,7 @@ For a simple program like [Blinky](https://github.com/ARMmbed/mbed-os-example-bl | Subtotals | 53932 | 2312 | 10520 | +---------------------+-------+-------+-------+ ``` - + The `features/frameworks` module includes the Mbed OS test tools, even if you are no longer testing your program. Because of this, you are building one of our test harnesses into every binary. [Removing this module](https://github.com/ARMmbed/mbed-os/pull/2559) saves a significant amount of RAM and flash memory. #### `Printf` and UART @@ -40,8 +40,8 @@ To disable error logging to serial output, set the `NDEBUG` macro and the follow } ``` -**Note:** Different compilers yield different results. Compiling with one compiler yields different memory usage savings than compiling with another. - +**Note:** Different compilers yield different memory savings. + #### Embedded targets You can also take advantage of the fact that these programs only run on embedded targets. When you run a C++ application on a desktop computer, the operating system constructs every global C++ object before calling `main`. It also registers a handle to destroy these objects when the program ends. The code the compiler injects has some implications for the application: From 7cb41f8ac91d0341d69c50cc623a4b2389d983b5 Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Mon, 6 May 2019 15:29:20 +0300 Subject: [PATCH 10/20] changing pre-list sentence structure --- docs/reference/technology/USB.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/technology/USB.md b/docs/reference/technology/USB.md index dd60ac62c4..bc44d18c8f 100644 --- a/docs/reference/technology/USB.md +++ b/docs/reference/technology/USB.md @@ -2,7 +2,7 @@ ## 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 is the core of Mbed OS's USB stack and is responsible for state management and synchronization. From a06827eb727a2a276dcca30bd150e716e5e6e49b Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Mon, 6 May 2019 15:46:51 +0300 Subject: [PATCH 11/20] Apply suggestions from code review --- docs/reference/technology/USB.md | 4 ++-- docs/reference/technology/connectivity/connectivity.md | 4 ++-- docs/reference/technology/connectivity/securesocket.md | 2 +- docs/reference/technology/firmware_update.md | 4 ++-- docs/reference/technology/storage.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/technology/USB.md b/docs/reference/technology/USB.md index bc44d18c8f..b2a6c6e7dd 100644 --- a/docs/reference/technology/USB.md +++ b/docs/reference/technology/USB.md @@ -16,7 +16,7 @@ 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 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. @@ -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, 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/connectivity.md b/docs/reference/technology/connectivity/connectivity.md index 1741603f1d..7ee736ea90 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -37,7 +37,7 @@ Our Socket API standardizes all of our connectivity options. It supports both IP Mbed OS provides network drivers, such as Ethernet, Wi-Fi and cellular. -You can find descriptions of supported interfaces and protocols in the [IP networking](../reference/ip-networking.html) section. +Descriptions of supported interfaces and protocols are in [IP networking](../reference/ip-networking.html). ### Wi-Fi @@ -63,7 +63,7 @@ It can be deployed on a single spectrum, reducing antenna configuration complexi ### Bluetooth Low Energy (BLE) -BLE is optimized for cheap, battery-based devices, and has a low memory footprint. It is widely adopted for connected spaces, but requires setting up an infrastructure. Its range is up to 100 meters, with 1 Mbps bandwidth. You need an edge gateway so devices in your network can connect to the internet. +BLE is optimized for cheap, battery-based devices, and has a low memory footprint. It is widely adopted for connected spaces, but requires setting up an infrastructure. Its range is up to 100 meters, with 1 Mbps bandwidth. You need an Edge gateway so devices in your network can connect to the internet. Typical applications of BLE are health care, fitness trackers, beacons, smart homes, security, entertainment, proximity sensors, industrial applications, and automotives. diff --git a/docs/reference/technology/connectivity/securesocket.md b/docs/reference/technology/connectivity/securesocket.md index 0c5e9c3ade..0aaf40a0fb 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 TLS Socket 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 diff --git a/docs/reference/technology/firmware_update.md b/docs/reference/technology/firmware_update.md index d71886509f..b4555a4c79 100644 --- a/docs/reference/technology/firmware_update.md +++ b/docs/reference/technology/firmware_update.md @@ -14,7 +14,7 @@ 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 to verify the firmware's source and validity. @@ -86,7 +86,7 @@ Mbed CLI and the Online Compiler implement the Pelion Device Management Update s **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 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 0933e280ad..8ef1f791c6 100644 --- a/docs/reference/technology/storage.md +++ b/docs/reference/technology/storage.md @@ -39,7 +39,7 @@ An example of implementations of the interfaces are: - FileHandle. - File - Class that provides read and write access to files on a file system. - BlockDeviceFile - Class that provides read and write access to raw block device storage in the form of a FileHandle. - - UARTSerial - The UARTSerial class provides read and write access to a device's serial hardware. It is an example of a non-storage device that you can access as a file. + - UARTSerial - The UARTSerial class provides read and write access to a device's serial hardware. It is an example of a nonstorage device that you can access as a file. - KVStore. - TDBStore - Default implementation of the KVStore API. It provides static wear-leveling and quick access for when you have a small number of KV pairs. - FileSystemStore - Class that provides a key-value store API on top of a POSIX-like file system API. From b8bdfce0453b55aeb4be2c7d503132ac872bca4d Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Mon, 6 May 2019 15:47:24 +0300 Subject: [PATCH 12/20] Apply suggestions from code review --- docs/reference/runtime/static_memory_optimization.md | 2 +- docs/reference/technology/connectivity/securesocket.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/runtime/static_memory_optimization.md b/docs/reference/runtime/static_memory_optimization.md index cc7d76424d..7bb65e2236 100644 --- a/docs/reference/runtime/static_memory_optimization.md +++ b/docs/reference/runtime/static_memory_optimization.md @@ -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/connectivity/securesocket.md b/docs/reference/technology/connectivity/securesocket.md index 0aaf40a0fb..84ce3fb151 100644 --- a/docs/reference/technology/connectivity/securesocket.md +++ b/docs/reference/technology/connectivity/securesocket.md @@ -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 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 successfully 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); From 500a40f258ffa5da7db9a351b858e8c424547bd4 Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Mon, 6 May 2019 15:49:33 +0300 Subject: [PATCH 13/20] -that --- docs/reference/technology/USB.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/technology/USB.md b/docs/reference/technology/USB.md index b2a6c6e7dd..439feb0921 100644 --- a/docs/reference/technology/USB.md +++ b/docs/reference/technology/USB.md @@ -60,7 +60,7 @@ The USB device can enter a state with less functionality at any time. This could ## USB component callbacks -All callbacks that 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 From 325ba1225a5423dc7801c2a637fa85d451b6be0c Mon Sep 17 00:00:00 2001 From: Mel Weed Date: Fri, 17 May 2019 12:05:17 +0300 Subject: [PATCH 14/20] Update docs/reference/technology/USB.md --- docs/reference/technology/USB.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/technology/USB.md b/docs/reference/technology/USB.md index 439feb0921..e24dcf0f3c 100644 --- a/docs/reference/technology/USB.md +++ b/docs/reference/technology/USB.md @@ -56,7 +56,7 @@ USB defines five separate states of a device: **Attached**, **Powered**, **Defau | Address | No new functionality | | Configured | All enabled endpoints are functional | -The USB device can enter a state with less functionality at any time. This could be due to a loss of power or surprise 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 or disconnect 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 From be1405f4368a06e3163be447a59c4b263c69a6bf Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 20 Jun 2019 14:00:32 -0500 Subject: [PATCH 15/20] Fix conflicts and comments in connectivity.md Resolve merge conflicts, and address comments. --- .../reference/technology/connectivity/connectivity.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/reference/technology/connectivity/connectivity.md b/docs/reference/technology/connectivity/connectivity.md index 3952b665b3..17e31886d8 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -6,22 +6,18 @@ 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 require a gateway: - LoRaWAN. - Cellular. - - - ## Choosing your connectivity method There is a wide variety of possibilities for connected devices, and there is no globally correct connectivity method. Choose a method that fits your application needs, and then choose a device that can support that method. If you're already committed to a device type, you may need to adjust your application to work within that device's connectivity constraints. @@ -30,9 +26,8 @@ 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. Mbed OS provides network drivers, such as Ethernet, Wi-Fi and cellular. From a849867c34c2179b9663f61e7a695ed646bda790 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 20 Jun 2019 14:02:01 -0500 Subject: [PATCH 16/20] Remove comment in wifi.md Remove answered comment. --- docs/reference/technology/connectivity/wifi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/technology/connectivity/wifi.md b/docs/reference/technology/connectivity/wifi.md index 7e1051878d..bc41650944 100644 --- a/docs/reference/technology/connectivity/wifi.md +++ b/docs/reference/technology/connectivity/wifi.md @@ -33,6 +33,6 @@ As with Ethernet, Wi-Fi networks are only used for carrying IP traffic in Mbed O For more information, please see the following sections: - [IP networking](ip-networking.html). -- [Ethernet](ethernet-technology.html). +- [Ethernet](ethernet-technology.html). - [Socket API](../apis/socket.html). - [WifiInterface API](../apis/wi-fi.html). From dab2d8f5a5b4e2a3bf56af330f5eb839a534e91f Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 20 Jun 2019 15:08:49 -0500 Subject: [PATCH 17/20] Address comments in firmware_update.md Address issues raised in comments. --- docs/reference/technology/firmware_update.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/technology/firmware_update.md b/docs/reference/technology/firmware_update.md index b4555a4c79..308b4a7343 100644 --- a/docs/reference/technology/firmware_update.md +++ b/docs/reference/technology/firmware_update.md @@ -53,8 +53,8 @@ For more information about [managed and unmanaged bootloaders, and how to create ### 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 Note two things about the Mbed OS bootloader's design: @@ -89,7 +89,7 @@ Mbed CLI and the Online Compiler implement the Pelion Device Management Update s 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. - + **Tutorials**: - Try the firmware [update flow on the Online Compiler](https://cloud.mbed.com/guides/pelion-firmware-update). Note: you first need to [use the connecting quick guide to set up the original application](https://cloud.mbed.com/guides/connect-device-to-pelion). From 2608b7e16360f8e6cfad122d157781a3f710c431 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 20 Jun 2019 15:24:35 -0500 Subject: [PATCH 18/20] Remove comment from technology.md Remove comment. --- docs/reference/technology/technology.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/reference/technology/technology.md b/docs/reference/technology/technology.md index 8bc8d12976..57d1d6336d 100644 --- a/docs/reference/technology/technology.md +++ b/docs/reference/technology/technology.md @@ -1,5 +1,3 @@ # Technology This section of the book talks about technologies that Mbed OS implements or supports. The content in this section details the architecture and protocols, design decisions and historical context of these technologies. - - From 8894177940dc9e54cab6e1443eb9ab208d84414b Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 20 Jun 2019 15:25:56 -0500 Subject: [PATCH 19/20] Remove comment from ethernet.md Remove comment. --- docs/reference/technology/connectivity/ethernet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/technology/connectivity/ethernet.md b/docs/reference/technology/connectivity/ethernet.md index 76106395f6..6328eda647 100644 --- a/docs/reference/technology/connectivity/ethernet.md +++ b/docs/reference/technology/connectivity/ethernet.md @@ -1,7 +1,7 @@

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, or optical fiber and coaxials. However, coaxial has largely become obsolete. - + 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. From 8e5c7c6bc8067297a6640f628ad5bf5fc42c9ade Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 20 Jun 2019 15:26:50 -0500 Subject: [PATCH 20/20] Fix phrasing in USB.md Fix phrasing to resolve comment. --- docs/reference/technology/USB.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/technology/USB.md b/docs/reference/technology/USB.md index a6b9a816c2..37a564077b 100644 --- a/docs/reference/technology/USB.md +++ b/docs/reference/technology/USB.md @@ -56,8 +56,8 @@ USB defines five separate states of a device: **Attached**, **Powered**, **Defau | Address | No new functionality | | Configured | All enabled endpoints are functional | -Random power loss or disconnect 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. - +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.