Merge pull request #13 from ARMmbed/add_docs

Adding documentation and making items configurable through json

Author: Hasnain Virk

README.md

@@ -1,3 +1,106 @@
-# mbed-os-example-cellular
+# Example cellulaur application for mbed OS
 
+This is a simple example based upon mbed-os celular APIs that demonstrates a simple TCP or UDP echo transaction with a public echo server. 
+
+## Getting started
+
+This particular Cellular application uses a Cellular network and network-socket APIs that are provided as a part of [mbed-os](github.com/armmbed/mbed-os). 
+
+The program uses a [generic celular modem driver](https://github.com/ARMmbed/mbed-os/tree/master/features/netsocket/cellular/generic_modem_driver) utilizing an external IP stack (LWIP) standard 3GPP AT 27.007 AT commands to setup the cellular modem and registers to the network.
+ After registration, the driver opens up a PPP (point-to-point protocol) pipe using LWIP with the cellular modem and connects to internet. This driver currently supports UART data connection type only between your cellular modem and MCU. 
+
+For more information on ARM mbed-os cellular APIs and porting guide, please visit [mbed-os Cellular Docs](https://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/communication/cellular/).
+
+### Download the application
+
+```sh
+$ mbed import mbed-os-example-cellular
+$ cd mbed-os-example-cellular
+
+#OR
+
+$ git clone [email protected]:ARMmbed/mbed-os-example-cellular.git
+$ cd mbed-os-example-cellular
+```
+
+### Change the network and SIM credentials
+
+See the file `mbed_app.json` in te root directory of your application. This file contains all the user specific configurations needed by your application.
+Provide the pin code for your SIM crad as well as any APN settings if needed, e.g., 
+
+```json
+        "sim-pin-code": {
+            "help": "SIM PIN code",
+            "value": "\"1234\""
+        },
+        "apn": {
+            "help": "The APN string to use for this SIM/network, set to 0 if none",
+            "value": "\"internet\""
+        },
+        "username": {
+            "help": "The user name string to use for this APN, set to zero if none",
+            "value": 0
+        },
+        "password": {
+            "help": "The password string to use for this APN, set to 0 if none",
+            "value": 0
+        }
+```  
+
+### Selecting socket type (TCP or UDP)
+
+You can choose which socket type the application should use, e.g.,
+
+```json
+
+     "sock-type": "TCP",
+
+```
+
+### Turning Modem AT echo trace on
+
+If you like details and wish to know about all the AT interactions between the modem and your driver, turn on the modem AT echo trace. 
+Set `modem_trace` field value to be true. 
+
+```json
+        "modem_trace": {
+            "help": "Turns AT command trace on/off from the cellular modem, defaults to off",
+            "value": true
+        },
+```
+
+### Board support
+
+The [generic celular modem driver](https://github.com/ARMmbed/mbed-os/tree/master/features/netsocket/cellular/generic_modem_driver) used by this application is written using only a standard AT command set and the uses PPP with a full fledge mbed-supported  external IP stack. These abilities make the driver essentially generic, i.e., non-vendor specific. However, this particular driver is written for onboard-modem types, i.e., the modem exists on the mbed-enabled target as oppose to plugin-modules (shields). For more details, please check documentation  [mbed-os Cellular Docs](https://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/communication/cellular/).    
+
+Examples of mbed-enabled boards with onboard modem chips can be, [u-blox C027](https://developer.mbed.org/platforms/u-blox-C027/) and [MultiTech MTS Dragonfly](https://developer.mbed.org/platforms/MTS-Dragonfly/).
+
+## Compiling the application
+
+Use mbed-cli commands to generate a binary for the application, e.g., in case of GCC use the following command:
+
+```sh
+$ mbed compile -m YOUR_TARGET_WITH_MODEM -t GCC_ARM
+```
+
+## Running the application
+
+Drag and drop the application binary from `BUILD/YOUR_TARGET_WITH_MODEM/GCC_ARM/mbed-os-example-cellular.bin` to your mbed-enabled target hardware which appears as a USB device on your host machine.
+
+Attatch a serial console emulator of your choice (e.g., putty, minicom, screen etc) to your USB device, set the baudrate to be 115200 and reset your board by pressing reset button.
+
+You should see an output similar to this:
+
+```
+mbed-os-example-cellular, Connecting...
+                                                                             
+                                                                            
+Connection Established.
+UDP: Sent 4 Bytes to echo.u-blox.com
+Received from echo server 4 Bytes
+                                                            
+                                                            
+Success. Exiting
+
+```   
 

main.cpp

@@ -7,22 +7,30 @@
 #define TCP 1
 
 // SIM pin code goes here
-#define PIN_CODE    "1234"
+#ifndef MBED_CONF_APP_SIM_PIN_CODE
+# define MBED_CONF_APP_SIM_PIN_CODE    "1234"
+#endif
 
-// Network credentials like APN go here, e.g.,
-// "apn, username, password"
-#define CREDENTIALS "internet"
+#ifndef MBED_CONF_APP_APN
+# define MBED_CONF_APP_APN         "internet"
+#endif
+#ifndef MBED_CONF_APP_USERNAME
+# define MBED_CONF_APP_USERNAME    NULL
+#endif
+#ifndef MBED_CONF_APP_PASSWORD
+# define MBED_CONF_APP_PASSWORD    NULL
+#endif
 
 // Number of retries /
 #define RETRY_COUNT 3
 
 // CellularInterface object
 OnboardCellularInterface iface;
 
-// NIST ntp hostname
+// Echo server hostname
 const char *host_name = "echo.u-blox.com";
 
-// NIST ntp port
+// Echo server port (same for TCP and UDP)
 const int port = 7;
 
 /**
@@ -135,10 +143,10 @@ int main()
 {
     iface.modem_debug_on(MBED_CONF_APP_MODEM_TRACE);
     /* Set Pin code for SIM card */
-    iface.set_sim_pin(PIN_CODE);
+    iface.set_sim_pin(MBED_CONF_APP_SIM_PIN_CODE);
 
     /* Set network credentials here, e.g., APN*/
-    iface.set_credentials(CREDENTIALS);
+    iface.set_credentials(MBED_CONF_APP_APN, MBED_CONF_APP_USERNAME, MBED_CONF_APP_PASSWORD);
 
     printf("\n\nmbed-os-example-cellular, Connecting...\n");
 

mbed_app.json

@@ -1,7 +1,26 @@
 {
-	"config": {
-		"sock-type": "UDP",
-		"modem_trace": false
+    "config": {
+        "sock-type": "UDP",
+        "modem_trace": {
+            "help": "Turns AT command trace on/off from the cellular modem, defaults to off",
+            "value": false
+        },
+        "sim-pin-code": {
+            "help": "SIM PIN code",
+            "value": "\"1234\""
+        },
+        "apn": {
+            "help": "The APN string to use for this SIM/network, set to 0 if none",
+            "value": "\"internet\""
+        },
+        "username": {
+            "help": "The user name string to use for this APN, set to zero if none",
+            "value": 0
+        },
+        "password": {
+            "help": "The password string to use for this APN, set to 0 if none",
+            "value": 0
+        }
 	},
     "target_overrides": {
         "*": {