Merge pull request #1 from ARMmbed/development

rebase 28.2

Author: KariHaapalehto

check_tools/config-update.py

@@ -0,0 +1,65 @@
+import sys, os
+import re
+import subprocess
+
+def split_into_pairs(l):
+    for i in range(0, len(l), 2):
+        yield l[i:i + 2]
+
+def main(file):
+    file_h = open(file, 'r+')
+    file   = file_h.read()
+    snippet_indices = [m.start() for m in re.finditer('```', file)]
+
+    blocks = {}
+    for i in range(0, int(len(snippet_indices) / 2)):
+        # Need to rerun on every loop as the indices change each iteration
+        snippet_indices = [m.start() for m in re.finditer('```', file)]
+        ranges = list(split_into_pairs(snippet_indices))
+        start  = ranges[i][0]
+        end    = ranges[i][1]
+
+        try:
+            blocks[i] = file[start : end + 3]
+            if ('Name: ' in blocks[i]):
+                lib = blocks[i].split('Name: ')[1].split('.')[0]
+                print("=================   %s   =================" % lib)
+                out = str(subprocess.check_output(["mbed", "compile", "--config", "-v", "--prefix", lib]))
+                file = file[:start+4] + out[:out.index("Macros") - 1] + file[end:]
+
+        # Originally added for debugging purposes, catch and display exceptions before
+        # continuing without exiting to provide a complete list of errors found
+        except Exception as e:
+            print("Error")
+            print(e)
+            print("____________________")
+            exc_type, exc_obj, exc_tb = sys.exc_info()
+            fname = os.path.split(exc_tb.tb_frame.f_code.co_filename)[1]
+            print(exc_type, fname, exc_tb.tb_lineno)
+            pass
+
+    file_h.truncate(0)
+    file_h.seek(0)
+    file_h.write(file)
+    file_h.close()
+
+if __name__ == '__main__':
+    if (len(sys.argv) < 2):
+        path = '../docs/reference/configuration'
+    else:
+        path = sys.argv[1]
+
+    if (path == '-h' or path == '--help'):
+        print("By default the script runs out of the docs tools directory and iterates through reference/configuration.\n"
+              "You may pass in a directory path that will run on all files contained within, or a single file path optionally.")
+        exit(0)
+
+    if (os.path.isfile(path)):
+        main(path)
+    elif (os.path.isdir(path)):
+        for doc in os.listdir(path):
+            if (doc != 'configuration.md'):
+                print('_____ %s _____' % os.path.join(path, doc))
+                main(os.path.join(path, doc))
+    else:
+        print("Please provide a valid file or directory path")

docs.json

@@ -8,36 +8,39 @@
 <tbody>
 <tr>
 <td><a href="wait.html">Wait</a></td>
-<td><a href="rtc.html">RTC</a></td>
-<td><a href="shared-pointer.html">Shared pointer</a></td>
-<td><a href="mpu-management.html">MPU management</a></td>
+<td><a href="time.html">Time</a></td>
+<td><a href="noncopyable.html">NonCopyable</a></td>
+<td><a href="circularbuffer.html">CircularBuffer</a></td>
 </tr>
 <tr>
 <td><a href="callback.html">Callback</a></td>
-<td><a href="debug.html">Debug</a></td>
-<td><a href="span.html">Span</a></td>
-<td><a href="scopedramexecutionlock.html">ScopedRamExecutionLock</a></td>
+<td><a href="rtc.html">RTC</a></td>
+<td><a href="shared-pointer.html">Shared pointer</a></td>
+<td><a href="atcmdparser.html">ATCmdParser</a></td>
 </tr>
 <tr>
 <td><a href="deepsleeplock.html">DeepSleepLock</a></td>
-<td><a href="memory-tracing.html">Memory tracing</a></td>
-<td><a href="platformmutex.html">PlatformMutex</a></td>
-<td><a href="scopedromwritelock.html">ScopedRomWriteLock</a></td>
+<td><a href="debug.html">Debug</a></td>
+<td><a href="span.html">Span</a></td>
+<td><a href="mbed-statistics.html">Mbed statistics</a></td>
 </tr>
 <tr>
 <td><a href="power-management.html">Power management</a></td>
-<td><a href="error-handling.html">Error handling</a></td>
-<td><a href="circularbuffer.html">CircularBuffer</a></td>
+<td><a href="memory-tracing.html">Memory tracing</a></td>
+<td><a href="filehandle.html">FileHandle</a></td>
+<td><a href="mpu-management.html">MPU management</a></td>
 </tr>
 <tr>
 <td><a href="idle-loop.html">Idle loop</a></td>
-<td><a href="assert.html">Assert</a></td>
-<td><a href="atcmdparser.html">ATCmdParser</a></td>
+<td><a href="error-handling.html">Error handling</a></td>
+<td><a href="poll.html">Poll</a></td>
+<td><a href="scopedramexecutionlock.html">ScopedRamExecutionLock</a></td>
 </tr>
 <tr>
 <td><a href="criticalsectionlock.html">CriticalSectionLock</a></td>
-<td><a href="noncopyable.html">NonCopyable</a></td>
-<td><a href="mbed-statistics.html">Mbed statistics</a></td>
+<td><a href="assert.html">Assert</a></td>
+<td><a href="platformmutex.html">PlatformMutex</a></td>
+<td><a href="scopedromwritelock.html">ScopedRomWriteLock</a></td>
 </tr>
 </tbody>
 </table>
@@ -123,6 +126,30 @@ The [Mbed OS RTOS](rtos.html) capabilities include managing objects such as thre
 </tbody>
 </table>
 
+### USB APIs
+
+The Mbed OS classes providing USB peripheral functionality, also known as [USB components](../apis/usb.html), inherit from USBDevice and provide specific USB peripherial functionality.
+
+<table>
+<tbody>
+<tr>
+<td><a href="usbserial.html">USBSerial</a></td>
+<td><a href="usbcdc.html">USBCDC</a></td>
+<td><a href="usbmouse.html">USBMouse</a></td>
+</tr>
+<tr>
+<td><a href="usbaudio.html">USBAudio</a></td>
+<td><a href="usbmsd.html">USBMSD</a></td>
+<td><a href="usbkeyboard.html">USBKeyboard</a></td>
+</tr>
+<tr>
+<td><a href="usbhid.html">USBHID</a></td>
+<td><a href="usbmidi.html">USBMIDI</a></td>
+<td><a href="usbmousekeyboard.html">USBMouseKeyboard</a></td>
+</tr>
+</tbody>
+</table>
+
 ### Network socket APIs
 
 [Network socket APIs](network-socket.html) include the application programming interface for IP networking. In Mbed OS, this API supports both TCP and UDP protocols.
@@ -132,15 +159,16 @@ The [Mbed OS RTOS](rtos.html) capabilities include managing objects such as thre
 <tr>
 <td><a href="socket.html">Socket</a></td>
 <td><a href="socketaddress.html">SocketAddress</a></td>
-<td><a href="dtlssocket.html">DTLSSocket</a></td>
+<td><a href="tlssocket.html">TLSSocket</a></td>
 </tr>
 <tr>
 <td><a href="udpsocket.html">UDPSocket</a></td>
-<td><a href="dns-resolver.html">DNS Resolver</a></td>
-<td><a href="socketstats.html">SocketStats</a></td>
+<td><a href="non-ip-cellular-socket.html">Non-IP cellular socket</a></td>
+<td><a href="dtlssocket.html">DTLSSocket</a></td>
 <tr>
 <td><a href="tcpsocket.html">TCPSocket</a></td>
-<td><a href="tlssocket.html">TLS Socket</a></td>
+<td><a href="dns-resolver.html">DNS resolver</a></td>
+<td><a href="socketstats.html">SocketStats</a></td>
 </tr>
 </tbody>
 </table>
@@ -153,7 +181,7 @@ The [Mbed OS RTOS](rtos.html) capabilities include managing objects such as thre
 <tbody>
 <tr>
 <td><a href="ethernet.html">Ethernet</a></td>
-<td><a href="mesh-api.html">6LoWPAN Mesh</a></td>
+<td><a href="mesh-api.html">Mesh</a></td>
 </tr>
 <tr>
 <td><a href="wi-fi.html">Wi-Fi</a></td>

docs/api/api.md

@@ -52,6 +52,16 @@ You may set preferred PHYs (separately for RX and TX) using `setPreferredPhys()`
 
 You may query the currently used PHY using `readPhy()`, which returns the result through a call to the registered event handler. You may register the handler with `setEventHandler()`. The events inform about the currently used PHY and of any changes to PHYs, which the controller or the peer may trigger autonomously.
 
+#### Data length (over-the-air MTU)
+
+In addition to modulation schemes, Maximum Transmission Unit (MTU) size also strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs. Because each packet contains overhead, bigger packets maximize throughput.
+
+There are two separate MTUs to consider: the `ATT_MTU` (maximum attribute size) and data length. `GattServer` and `GattClient` affect `ATT_MTU`. `Gap` only deals with data length, which is the maximum size of the packet that carries attributes that are fragmented across many such packets.
+
+The default value of data length supported by all controllers is 23 octets. If both controllers support data length extension and a higher value is negotiated, the BLE stack will call `onDataLengthChange` in the `Gap::EventHandler` registered by the user.
+
+`ATT_MTU` and data length are independent of each other. 
+
 ### GAP class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gap.html)

docs/api/bluetooth/Gap.md

@@ -1,6 +1,6 @@
 ## GattClient
 
-GattClient defines procedures required for interacting with a remote GattServer.
+You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction. `GattClient` defines procedures required for interacting with a remote `GattServer`.
 
 #### Discovery procedures
 
@@ -16,6 +16,16 @@ As a result of the discovery process, the client can start interacting with the
 
 Mbed BLE abstracts read and write operations to offer a single API that can be used to read or write characteristic values. The application code does not have to handle the necessary fragmentation or reassembly process if the attribute value to be transported can't fit in a single data packet.
 
+#### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+
+`ATT_MTU` is the maximum size of the attribute protocol packet. Operation on attributes too large to fit into a single packet are split across multiple operations.
+
+This is independent of the data length, which controls the over-the-air packet payload size (which the GAP handles). An L2CAP packet containing the attribute protocol packet is fragmented over many packets if required.
+
+Only `GattClient` can trigger the exchange of `ATT_MTU` between client and server. Depending on the implementation of the bluetooth stack, the client may trigger the exchange upon connection. You may also manually request the exchange using `negotiateAttMtu`. If an exchange happens, the biggest value possible across both devices will be used. Negotiation is only a best-effort process and does not guarantee a higher value being set.
+
+`ATT_MTU` is at least 23 octets by default. If a larger size is negotiated, the user application will be informed through the `onAttMtuChange` function called in the `GattClient::EventHandler`. (`GattServer::EventHandler` is also informed.)
+
 #### Server initiated events
 
 When a server updates a characteristic value, it can forward the new value to any registered clients. Clients may register for these updates on a per-characteristic basis. The server sends the updates by using notifications (no confirmation from client) or indications (client confirms receipt). This mechanism minimizes the number of transactions between a client and a server by avoiding polling.

docs/api/bluetooth/GattClient.md

@@ -1,6 +1,8 @@
 ## GattServer
 
-A GattServer is a collection of GattServices. These services contain characteristics that a peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
+You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction.
+
+`GattServer` is a collection of GattServices. These services contain characteristics that a `GattClient` on the peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
 
 #### Server layout
 
@@ -14,6 +16,10 @@ You must access values of the characteristic and the characteristic descriptor p
 
 You can query the server by invoking the function `areUpdatesEnabled()` to find out if a client has subscribed to a given characteristic's value update.
 
+#### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+
+The Attribute Protocol Maximum Transmission Unit (`ATT_MTU`) is the maximum size of the attribute protocol packet. For details, please see the [GattClient Documentation](../apis/gattclient.html).
+
 #### Events
 
 You can register several event handlers with the GattServer that it will call to notify you of client (remote application connected to the server) and server activities:

docs/api/bluetooth/GattServer.md

@@ -10,10 +10,10 @@ Use the AnalogOut interface to set the output voltage of an analog output pin sp
 
 ### AnalogOut hello, world
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/AnalogOut_HelloWorld/)](https://os.mbed.com/teams/mbed_example/code/DigitalIn_HelloWorld/file/9377dcb1cef3/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/AnalogOut_HelloWorld/)](https://os.mbed.com/teams/mbed_example/code/AnalogOut_HelloWorld/file/f2c29bab3feb/main.cpp)
 
 ### AnalogOut example
 
 Create a sine wave.
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/AnalogOut_ex_1/)](https://os.mbed.com/teams/mbed_example/code/DigitalIn_ex_1/file/ad8683db322a/main.cpp)
+[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/AnalogOut_ex_1/)](https://os.mbed.com/teams/mbed_example/code/AnalogOut_ex_1/file/e758daa05e53/main.cpp)

docs/api/drivers/AnalogOut.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/d6cbcdb04ada/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

@@ -15,6 +15,10 @@ Try this example to see how an I2C responder works.
 ```c++ TODO
 #include <mbed.h>
 
+#if !DEVICE_I2CSLAVE
+  #error [NOT_SUPPORTED] I2C Slave is not supported
+#endif
+
 I2CSlave slave(p9, p10);
 
 int main() {

docs/api/drivers/I2CSlave.md

@@ -1,10 +1,8 @@
-<h2 id="cellular-api">Cellular</h2>
+<h2 id="cellular-api">Cellular API</h2>
 
-<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.png)<span>CellularBase class hierarchy</span></span>
+<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.png)<span>CellularInterface class hierarchy</span></span>
 
-The [CellularBase](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_base_8h_source.html) provides a C++ API for connecting to the internet over a Cellular device.
-
-Arm Mbed OS provides a [reference implementation of CellularBase](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h_source.html), which has more information.
+The [CellularInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.html) class provides a C++ API for connecting to the internet over a Cellular device.
 
 ##### Getting started
 
@@ -48,15 +46,15 @@ You can use and extend a cellular interface in various different ways. For examp
 - The easy cellular connection uses standard 3GPP AT 27.007 AT commands to set up the cellular modem and to register to the network.
 - After registration, the driver opens a PPP pipe using LWIP with the cellular modem and connects to the internet. If AT only mode is in use, then modem-specific AT commands are used for socket data control.
 
-### CellularBase class reference
+### CellularInterface class reference
 
-[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.html)
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.html)
 
 ### Usage
 
 To bring up the network interface:
 
-1. Instantiate an implementation of the CellularBase class.
+1. Instantiate an implementation of the CellularInterface class.
 1. Call the `connect(pincode, apn)` function with a PIN code for your SIM card and an APN for your network.
 1. Once connected, you can use Mbed OS [network sockets](network-socket.html) as usual.
 
@@ -69,6 +67,6 @@ This example establishes connection with the cellular network using Mbed OS Cell
 ### Related content
 
 - [Network socket](network-socket.html) API reference overview.
-- [Cellular architecture](../reference/cellular.html).
+- [Cellular overview](../reference/cellular.html) describes cellular architecture and its usage in more detail.
 - [Cellular TCP sockets example](../tutorials/cellular-tcp-sockets.html).
 - [Cellular configuration documentation](../reference/configuration-connectivity.html).

docs/api/networkinterfaces/CellularInterface.md

@@ -1,4 +1,4 @@
-<h2 id="mesh-api">6LoWPAN Mesh</h2>
+<h2 id="mesh-api">Mesh</h2>
 
 <span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_mesh_interface.png)<span>MeshInterface class hierarchy</span></span>
 
@@ -41,11 +41,10 @@ See the example application [mbed-os-example-mesh-minimal](https://github.com/AR
 
 ### Mesh example
 
-The application below demonstrates a simple light control application, where devices can control the LED status of all devices in the network. You can build the application for the unsecure 6LoWPAN-ND or Thread network.
-
-[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-mesh-minimal)](https://github.com/ARMmbed/mbed-os-example-mesh-minimal/blob/mbed-os-5.10.0/main.cpp)
+To learn how to use mesh, please see our [light control tutorial](../tutorials/light-control.html), which demonstrates a light control application, where devices can control the LED status of all devices in the network. You can build the application for the unsecure 6LoWPAN-ND or Thread network.
 
 ### Related content
 
 - [Nanostack](../reference/mesh-tech.html#nanostack) technology reference material.
 - [6LoWPAN and Thread Mesh configuration documentation](../reference/configuration-mesh.html).
+- [Light control tutorial](../tutorials/light-control.html).