Merge branch 'development' into ci

Author: Amanda Butler

docs.json

@@ -76,7 +76,6 @@
 <td><a href="busin.html">BusIn</a></td>
 <td><a href="ticker.html">Ticker</a></td>
 <td><a href="serial.html">Serial</a></td>
-<td><a href="devicekey.html">DeviceKey</a></td>
 </tr>
 <tr>
 <td><a href="busout.html">BusOut</a></td>
@@ -201,9 +200,14 @@ You can use [Near-Field Communication (NFC)](nfc.html), a short-range radio tech
 <tbody>
 <tr>
 <td><a href="nfccontroller.html">NFCController</a></td>
+<td><a href="simplemessageparser.html">SimpleMessageParser</a></td>
 </tr>
 <tr>
 <td><a href="nfc-eeprom.html">NFC EEPROM</a></td>
+<td><a href="messagebuilder.html">MessageBuilder</a></td>
+</tr>
+<tr>
+<td><a href="messageparser.html">MessageParser</a></td>
 </tr>
 </tbody>
 </table>
@@ -217,6 +221,9 @@ With [Arm Mbed TLS](security.html), a comprehensive SSL/TLS solution, you can in
 <tr>
 <td><a href="tls.html">TLS</a></td>
 </tr>
+<tr>
+<td><a href="Devicekey.html">DeviceKey</a></td>
+</tr>
 </tbody>
 </table>
 
@@ -238,13 +245,14 @@ The [storage APIs](storage.html) include file system APIs, for file system opera
 <td><a href="blockdevice.html">BlockDevice</a></td>
 <td><a href="slicingblockdevice.html">SlicingBlockDevice</a></td>
 <td><a href="dataflash-block-device.html">DataFlashBlockDevice</a></td>
-<td><a href="nvstore.html">NVStore</a></td>
+<td><a href="qspifblockdevice.html">QSPIFBlockDevice</a></td>
 </tr>
 <tr>
 <td><a href="file.html">File</a></td>
 <td><a href="heapblockdevice.html">HeapBlockDevice</a></td>
 <td><a href="profilingblockdevice.html">ProfilingBlockDevice</a></td>
 <td><a href="flashiapblockdevice.html">FlashIAPBlockDevice</a></td>
+<td><a href="nvstore.html">NVStore</a></td>
 </tr>
 <tr>
 <td><a href="littlefilesystem.html">LittleFileSystem</a></td>

docs/api/api.md

@@ -12,7 +12,7 @@ The BatteryService class implements the Bluetooth Battery Service as defined by
 
 ### BatteryService example
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-BatteryLevel/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-BatteryLevel/file/5cf292205001/source/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-BatteryLevel/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-BatteryLevel/file/15a6111a679e/source/main.cpp)
 
 ### Related content
 

docs/api/bluetooth/BatteryService.md

@@ -48,4 +48,4 @@ You may query the currently used PHY using `readPhy()`, which returns the result
 
 Here is an example demonstrating how to use the GAP API to advertise, scan, connect and disconnect and how parameters influence efficiency of these actions.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GAP/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GAP/file/37872bf83624/source/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GAP/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GAP/file/3993e2608615/source/main.cpp)

docs/api/bluetooth/Gap.md

@@ -33,4 +33,4 @@ The term characteristic value update represents Characteristic Value Notificatio
 
 ### GattServer example
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/file/a17a79f0d8af/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/file/6aa9b4b024d7/main.cpp)

docs/api/bluetooth/GattServer.md

@@ -14,7 +14,7 @@ The HeartRateService class implements the Bluetooth Heart Rate service as define
 
 ### HeartRateService example
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-HeartRate/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-HeartRate/file/55c859f4efe0/source/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-HeartRate/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-HeartRate/file/f5279652302f/source/main.cpp)
 
 ### Related content
 

docs/api/bluetooth/HeartRateService.md

@@ -52,4 +52,4 @@ The simplest example is a pairing of a device with no IO capabilities and no OOB
 
 The SecurityManager example demonstrates both a central and a peripheral connecting, performing basic pairing and setting up link security.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-SM/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-SM/file/547e88d95052/source/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-SM/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-SM/file/d849f18bb4dd/source/main.cpp)

docs/api/bluetooth/SecurityManager.md

@@ -12,6 +12,6 @@ The iBeacon class builds an advertising payload mimicking an iBeacon and assigns
 
 ### iBeacon example
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-Beacon/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-Beacon/file/5575d1bee775/source/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-Beacon/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-Beacon/file/ec76013cdcab/source/main.cpp)
 
 <span class="notes">**Note:** You can find more information at the [Apple iBeacon page](https://developer.apple.com/ibeacon/).</span>

docs/api/bluetooth/iBeacon.md

@@ -2,7 +2,7 @@
 
 <span class="images">![](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_bus_in.png)<span>BusIn class hierarchy</span></span>
 
-With the BusIn API, you can create a number of DigitalIn pins that you can read as one value. This abstraction is useful for checking multiple inputs at once. You can use this API to write clearer code faster.
+With the BusIn API, you can combine number of DigitalIn pins to read them at once. This abstraction is useful for checking multiple inputs together as single interface instead of individual pins.
 
 You can use any of the numbered Arm Mbed pins as a DigitalIn in the BusIn.
 

docs/api/drivers/BusIn.md

@@ -2,7 +2,7 @@
 
 <span class="images">![](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_bus_out.png)<span>BusOut class hierarchy</span></span>
 
-Use the BusOut interface to create a number of [DigitalOut](digitalout.html) pins that you can write as one value. This API is useful for writing multiple outputs at once. You can use this API to write clearer code faster.
+Use the BusOut interface to combine a number of [DigitalOut](digitalout.html) pins to write them at once. This API is useful for writing to multiple pins together as single interface instead of individual pins.
 
 You can use any of the numbered Arm Mbed pins as a DigitalOut in the BusOut.
 

docs/api/drivers/BusOut.md

@@ -14,4 +14,4 @@ Controller-Area Network (CAN) is a bus standard that allows microcontrollers and
 
 This example sends a counter from one CAN bus (can1) and listens for a packet on the other CAN bus (can2). Each bus controller should be connected to a CAN bus transceiver. These should be connected together at a CAN bus.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/CAN_ex_1/)](https://os.mbed.com/teams/mbed_example/code/CAN_ex_1/file/5791101761f9/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/CAN_ex_1/)](https://os.mbed.com/teams/mbed_example/code/CAN_ex_1/file/d6cbcdb04ada/main.cpp)

docs/api/drivers/CAN.md

@@ -24,13 +24,13 @@ Below is a CRC example to compute 32-bit CRC.
 
 Below is a 32-bit CRC example using `compute_partial` APIs.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/CRC_partial_example/)](https://os.mbed.com/teams/mbed_example/code/CRC_partial_example/file/834c44916a38/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/CRC_partial_example/)](https://os.mbed.com/teams/mbed_example/code/CRC_partial_example/file/d4c48b62da22/main.cpp)
 
 #### Example 3
 
 Below is a CRC example for the SD driver.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/CRC_eample_sd/)](https://os.mbed.com/teams/mbed_example/code/CRC_eample_sd/file/ee110889fa99/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/CRC_eample_sd/)](https://os.mbed.com/teams/mbed_example/code/CRC_eample_sd/file/97e3e51ca5d5/main.cpp)
 
 ### Related content
 

docs/api/drivers/MbedCRC.md

@@ -1,8 +1,12 @@
 ## PortIn
 
-Use the PortIn interface to read an underlying GPIO port as one value. This is much faster than [BusIn](busin.html) because you can read a port in one go, but it is much less flexible because you are constrained by the port and bit layout of the underlying GPIO ports.
+Use the PortIn interface to define which pins of a hardware GPIO port are set as an input and to read the value of those pins. The port name is device specific and defined in the device's `PortNames.h` file in the `mbed-os/targets` folder.  
 
-A mask can be supplied so only certain bits of a port are used, allowing other bits to be used for other interfaces.
+A bit mask defines which pins of the GPIO port are set as an input (`1b` = include, `0b` = ignore). The default mask value is `0xFFFFFFFF`, which sets all pins as an input.
+
+The device-specific `PinNames.h` and the respective datasheet or reference manual define the pins associated with a GPIO port.   
+
+<span class="notes">**Note:** You can combine pins from different GPIO ports using the [BusIn](busin.html) interface. Use [PortOut](portout.html) to define which GPIO pins are to be used as digital output.</span>
 
 ### PortIn class reference
 
@@ -15,3 +19,4 @@ A mask can be supplied so only certain bits of a port are used, allowing other b
 ### Related content
 
 - [BusIn](busin.html) API reference.
+- [PortOut](portout.html) API reference.

docs/api/drivers/PortIn.md

@@ -1,8 +1,12 @@
 ## PortOut
 
-Use the PortOut interface to write to an underlying GPIO port as one value. This is much faster than [BusOut](busout.html) because you can write a port in one go, but it is much less flexible because you are constrained by the port and bit layout of the underlying GPIO ports.
+Use the PortOut interface to define which pins of a hardware GPIO port are set as an output and to write those pins. The port name is device specific and defined in the device's `PortNames.h` file in the `mbed-os/targets` folder.
 
-A mask can be supplied so only certain bits of a port are used, allowing other bits to be used for other interfaces.
+A bit mask defines which pins of the GPIO port are set as an output (`1b` = include, `0b` = ignore). The default mask value is `0xFFFFFFFF` which sets all pins as an output.
+
+The device-specific `PinNames.h` and the respective datasheet or reference manual define the pins associated with a GPIO port.
+
+<span class="notes">**Note:** You can combine pins from different GPIO ports using the [BusOut](busout.html) interface. Use [PortIn](portin.html) to define which GPIO pins are to be used as digital input.</span>
 
 ### PortOut class reference
 
@@ -15,3 +19,4 @@ A mask can be supplied so only certain bits of a port are used, allowing other b
 ### Related content
 
 - [BusOut](busout.html) API reference.
+- [PortIn](portin.html) API reference.

docs/api/drivers/PortOut.md

@@ -9,7 +9,7 @@ Use the PwmOut interface to control the frequency and duty cycle of a PWM signal
 
 ### PwmOut class reference
 
-[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_pwm_out.html)
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_pwm_out_8h_source.html)
 
 
 ### PwmOut hello, world

docs/api/drivers/PwmOut.md

@@ -8,12 +8,12 @@ You can create any number of Timeout objects, allowing multiple outstanding inte
 
 ### Warnings and notes
 
-* Timers are based on 32-bit int microsecond counters, so they can only time up to a maximum of 2^31-1 microseconds (30 minutes). They are designed for times between microseconds and seconds. For longer times, you should consider the time() real time clock.
-
 * No blocking code in ISR: avoid any call to wait, infinite while loop or blocking calls in general.
 
 * No printf, malloc or new in ISR: Avoid any call to bulky library functions. In particular, certain library functions (such as printf, malloc and new) are not re-entrant, and their behavior could be corrupted when called from an ISR.
 
+* While a Timeout is running, deep sleep is blocked to maintain accurate timing. If you don't need microsecond precision, consider using the LowPowerTimeout class instead because this does not block deep sleep mode.
+
 ### Timeout class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_timeout.html)

docs/api/drivers/TimeOut.md

@@ -1,10 +1,15 @@
 ## Timer
 
-Use the Timer interface to create, start, stop and read a timer for measuring small times (between microseconds and seconds).
+<span class="images">![](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_timer.png)<span>Timer class hierarchy</span></span>
+
+Use the Timer interface to create, start, stop and read a timer for measuring precise times (better than millisecond precision).
 
 You can independently create, start and stop any number of Timer objects.
 
-<span class="notes">**Note:** Timers are based on 32-bit int microsecond counters, so they can only time up to a maximum of 2^31-1 microseconds (30 minutes). They are designed for times between microseconds and seconds. For longer times, use the `time()` real time clock.</span>
+### Warnings and notes
+
+- Timers are based on 64-bit unsigned microsecond counters, but for backward compatibility, the `read_ms()` and `read_us()` methods only return 32-bit signed integers. This limits their range before wrapping to 49 days and 35 minutes respectively. Use `read_high_resolution_us()` to access the full range of over 500,000 years.
+- While a Timer is running, deep sleep is blocked to maintain accurate timing. If you don't need microsecond precision, consider using the LowPowerTimer class instead because this does not block deep sleep mode.
 
 ### Timer class reference
 

docs/api/drivers/Timer.md

@@ -1,3 +1,23 @@
 ## Drivers overview
 
-Driver APIs include analog and digital inputs and outputs on development boards, as well as digital interfaces, which allow your board to interface with a computer or external devices. With these drivers, you can read or set the voltage of analog pins, control digital pins individually or as a grouped value and trigger an event when a digital input pin changes value. You can also control the frequency and mark to space ratio of a digital pulse wave (or train).
+Drivers provide access to general purpose microcontroller hardware. Drivers typically access a microcontroller's hardware peripherals directly, and may form the lowest lever of a protocol or network stack.
+
+The Mbed OS driver APIs include analog and digital inputs and outputs on development boards, as well as digital interfaces, which allow your board to interface with a computer or external devices. With these drivers, you can read or set the voltage of analog pins, control digital pins individually or grouped into a bus and trigger an event when more data is available on the bus. You can also control the frequency and mark to space ratio, or duty cycle, of a Pulse Width Modulated (PWM) digital output.
+
+### Blocking nature
+
+By default, all Mbed OS driver APIs are blocking. In the drivers, blocking APIs cause the current thread to wait until the hardware operation completes. Blocking APIs simplify control flow, allow for linearly structured programs and make debugging intuitive. We suggest using blocking APIs as a starting point. You should only consider more complex APIs if the blocking APIs do not satisfy your requirements.
+
+Mbed OS is built around an RTOS, and to complement this, the drivers are thread safe. This means that if you use multiple drivers in a blocking manner, as long as the drivers are in separate threads, their operations can still be carried out in parallel. When a driver blocks a thread, the RTOS either switches to any nonblocked threads or sleeps. This means that in most cases, an application using blocking APIs has the same advantages as one using nonblocking APIs.
+
+In some cases, the drivers provide nonblocking APIs. These APIs configure hardware to run in the background of the processor, without blocking a thread. Nonblocking drivers signal through the attach function once the background operation is complete.
+
+### Attaching callbacks to drivers
+
+In Mbed OS, the standard API for asynchronous events is the attach function. You can use the attach function to attach a callback function. Drivers call the attached callback function during specific events. You can use this to learn when the state of a nonblocking operation changes or whether other asynchronous events occur.
+
+For example, you can attach a callback function on a [Serial](serial.html) object, which the Serial object calls when the serial line receives a packet on the RX line.
+
+One important thing to note is that when you attach callbacks with this function, the driver calls them in interrupt context. Interrupt context runs at a higher priority than any thread, which means that any code called from the attach callback must be interrupt safe. This excludes any blocking APIs such as blocking drivers, malloc, and mutexes. Or you risk preventing other high-priority interrupts from running, which may break other parts of the OS.
+
+When you need to call code that’s not interrupt safe from interrupt context, you must first defer from the interrupt context to a thread. The easiest way to defer to a thread is to signal a waiting thread through a [Semaphore](semaphore.html). In more complex use cases, you can use an [EventQueue](eventqueue.html) to manage multiple events at once.

docs/api/drivers/drivers.md

@@ -12,7 +12,7 @@ To configure this class, please see the [LoRa configuration documentation](/docs
 
 ### LoRaRadio example
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan/file/ceea78461fbd/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-lorawan)](https://github.com/ARMmbed/mbed-os-example-lorawan/blob/master/main.cpp)
 
 ### Related content
 

docs/api/lorawan/loraradio.md

@@ -14,7 +14,7 @@ To configure this class, please see the [LoRa configuration documentation](/docs
 
 Please visit our Arm Mbed Online Compiler example, and follow the instructions in the `README.md`.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan/file/ceea78461fbd/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-lorawan)](https://github.com/ARMmbed/mbed-os-example-lorawan/blob/master/main.cpp)
 
 ### Related content
 

docs/api/lorawan/lorawan.md

@@ -70,7 +70,7 @@ To bring up the network interface:
 
 This example establishes connection with the cellular network using Mbed OS CellularInterface.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/file/cf737b827270/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-cellular)](https://github.com/ARMmbed/mbed-os-example-cellular/blob/master/main.cpp)
 
 ### Related content