Nuvoton / Mbed OS NuMaker-mbed-Cellular-example

NuMaker Cellular(NB-IoT/4G)

README.md@0:25c616c85d69, 2019-09-24 (annotated)

Committer:
cyliang
Date:
Tue Sep 24 02:53:23 2019 +0000
Revision:
0:25c616c85d69
Child:
3:6f804b5237be
First commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
cyliang 0:25c616c85d69 1 This example is modified from mbed-os-example-cellular.
cyliang 0:25c616c85d69 2
cyliang 0:25c616c85d69 3 Before build the example, please notice
cyliang 0:25c616c85d69 4
cyliang 0:25c616c85d69 5 1. For NB-IoT and Cat M1, please contact your service provider to get band information and use AT command to setup it.
cyliang 0:25c616c85d69 6
cyliang 0:25c616c85d69 7 For Taiwan example, it uses the band 1, 3, 8 and 28, you can refer the AT command document to do it.
cyliang 0:25c616c85d69 8 1a. In BG96 case, you need to type below AT command to set band.
cyliang 0:25c616c85d69 9 AT+QCFG="band",0,8000085,8000085,1
cyliang 0:25c616c85d69 10 And after first time to register network, you still need type below AT command to save information.
cyliang 0:25c616c85d69 11 AT+CFUN=0
cyliang 0:25c616c85d69 12 1b. In SIM7020 case, you need to type below AT command to set band.
cyliang 0:25c616c85d69 13 AT+CBAND=1,3,8,28
cyliang 0:25c616c85d69 14
cyliang 0:25c616c85d69 15 For Taiwan's CHT ISP example, it uses the Band 8, you can only set band 8 active.
cyliang 0:25c616c85d69 16
cyliang 0:25c616c85d69 17 2. If run SIM7020, please use Mbed-OS 5.13.1 and later.
cyliang 0:25c616c85d69 18
cyliang 0:25c616c85d69 19 3. Add the cellular device support in mbed_app.json as below.
cyliang 0:25c616c85d69 20
cyliang 0:25c616c85d69 21 For SIMCOM SIM7020, please add the first two configurations. The drivers.uart-serial-rxbuf-size should be MAX_PACKET_SIZE*2+100.
cyliang 0:25c616c85d69 22 "target_overrides": {
cyliang 0:25c616c85d69 23 "*": {
cyliang 0:25c616c85d69 24 "target.extra_labels_add": ["SIM7020"],
cyliang 0:25c616c85d69 25 "drivers.uart-serial-rxbuf-size": 4196,
cyliang 0:25c616c85d69 26 "target.network-default-interface-type": "CELLULAR",
cyliang 0:25c616c85d69 27
cyliang 0:25c616c85d69 28 For QUECTEL BG96, please add the first three configurations.
cyliang 0:25c616c85d69 29 "target_overrides": {
cyliang 0:25c616c85d69 30 "*": {
cyliang 0:25c616c85d69 31 "QUECTEL_BG96.provide-default": true,
cyliang 0:25c616c85d69 32 "QUECTEL_BG96.tx": "D1",
cyliang 0:25c616c85d69 33 "QUECTEL_BG96.rx": "D0",
cyliang 0:25c616c85d69 34 "target.network-default-interface-type": "CELLULAR",
cyliang 0:25c616c85d69 35
cyliang 0:25c616c85d69 36 For QUECTEL EC2x, please add the first three configurations.
cyliang 0:25c616c85d69 37 "target_overrides": {
cyliang 0:25c616c85d69 38 "*": {
cyliang 0:25c616c85d69 39 "GENERIC_AT3GPP.provide-default": true,
cyliang 0:25c616c85d69 40 "GENERIC_AT3GPP.tx": "D1",
cyliang 0:25c616c85d69 41 "GENERIC_AT3GPP.rx": "D0",
cyliang 0:25c616c85d69 42 "target.network-default-interface-type": "CELLULAR",
cyliang 0:25c616c85d69 43 ...
cyliang 0:25c616c85d69 44 "lwip.ppp-enabled": true,
cyliang 0:25c616c85d69 45 "lwip.tcp-enabled": true,
cyliang 0:25c616c85d69 46
cyliang 0:25c616c85d69 47 4. Add the cellular network APN support in mbed_app.json.
cyliang 0:25c616c85d69 48
cyliang 0:25c616c85d69 49 For other configurations, you can refer the original README content as below.
cyliang 0:25c616c85d69 50
cyliang 0:25c616c85d69 51
cyliang 0:25c616c85d69 52 ====================================================================================================
cyliang 0:25c616c85d69 53
cyliang 0:25c616c85d69 54
cyliang 0:25c616c85d69 55 # Example cellular application for Mbed OS
cyliang 0:25c616c85d69 56
cyliang 0:25c616c85d69 57 This is an example based on `mbed-os` cellular APIs that demonstrates a TCP or UDP echo transaction with a public echo server.
cyliang 0:25c616c85d69 58
cyliang 0:25c616c85d69 59 (Note: To see this example in a rendered form you can import into the Arm Mbed Online Compiler, please see [the documentation](https://os.mbed.com/docs/mbed-os/latest/apis/cellular-api.html#cellular-example-connection-establishment).)
cyliang 0:25c616c85d69 60
cyliang 0:25c616c85d69 61 ## Getting started
cyliang 0:25c616c85d69 62
cyliang 0:25c616c85d69 63 This particular cellular application uses a cellular network and network-socket APIs that are part of [`mbed-os`](https://github.com/ARMmbed/mbed-os).
cyliang 0:25c616c85d69 64
cyliang 0:25c616c85d69 65 The program uses a [cellular modem driver](https://github.com/ARMmbed/mbed-os/tree/master/features/cellular/framework/API) using an external IP stack (LWIP) standard 3GPP AT 27.007 AT commands to setup the cellular modem and registers to the network.
cyliang 0:25c616c85d69 66
cyliang 0:25c616c85d69 67 After registration, the driver opens a point-to-point protocol (PPP) 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.
cyliang 0:25c616c85d69 68
cyliang 0:25c616c85d69 69 For more information on Arm Mbed OS cellular APIs and porting guide, please visit the [Mbed OS cellular API](https://os.mbed.com/docs/latest/reference/cellular.html) and [contributing documentation](https://os.mbed.com/docs/mbed-os/latest/contributing/index.html).
cyliang 0:25c616c85d69 70
cyliang 0:25c616c85d69 71 ### Download the application
cyliang 0:25c616c85d69 72
cyliang 0:25c616c85d69 73 ```sh
cyliang 0:25c616c85d69 74 $ mbed import mbed-os-example-cellular
cyliang 0:25c616c85d69 75 $ cd mbed-os-example-cellular
cyliang 0:25c616c85d69 76
cyliang 0:25c616c85d69 77 #OR
cyliang 0:25c616c85d69 78
cyliang 0:25c616c85d69 79 $ git clone git@github.com:ARMmbed/mbed-os-example-cellular.git
cyliang 0:25c616c85d69 80 $ cd mbed-os-example-cellular
cyliang 0:25c616c85d69 81 ```
cyliang 0:25c616c85d69 82
cyliang 0:25c616c85d69 83 ### Change the network and SIM credentials
cyliang 0:25c616c85d69 84
cyliang 0:25c616c85d69 85 See the file `mbed_app.json` in the root directory of your application. This file contains all the user specific configurations your application needs. Provide the pin code for your SIM card, as well as any APN settings if needed. For example:
cyliang 0:25c616c85d69 86
cyliang 0:25c616c85d69 87 ```json
cyliang 0:25c616c85d69 88 "nsapi.default-cellular-plmn": 0,
cyliang 0:25c616c85d69 89 "nsapi.default-cellular-sim-pin": "\"1234\"",
cyliang 0:25c616c85d69 90 "nsapi.default-cellular-apn": 0,
cyliang 0:25c616c85d69 91 "nsapi.default-cellular-username": 0,
cyliang 0:25c616c85d69 92 "nsapi.default-cellular-password": 0
cyliang 0:25c616c85d69 93 ```
cyliang 0:25c616c85d69 94
cyliang 0:25c616c85d69 95 ### Selecting socket type (TCP or UDP)
cyliang 0:25c616c85d69 96
cyliang 0:25c616c85d69 97
cyliang 0:25c616c85d69 98 You can choose which socket type the application should use; however, please note that TCP is a more reliable transmission protocol. For example:
cyliang 0:25c616c85d69 99
cyliang 0:25c616c85d69 100
cyliang 0:25c616c85d69 101 ```json
cyliang 0:25c616c85d69 102
cyliang 0:25c616c85d69 103 "sock-type": "TCP",
cyliang 0:25c616c85d69 104
cyliang 0:25c616c85d69 105 ```
cyliang 0:25c616c85d69 106
cyliang 0:25c616c85d69 107 ### Turning modem AT echo trace on
cyliang 0:25c616c85d69 108
cyliang 0:25c616c85d69 109 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.
cyliang 0:25c616c85d69 110
cyliang 0:25c616c85d69 111 ```json
cyliang 0:25c616c85d69 112 "cellular.debug-at": true
cyliang 0:25c616c85d69 113 ```
cyliang 0:25c616c85d69 114
cyliang 0:25c616c85d69 115 ### Turning on the tracing and trace level
cyliang 0:25c616c85d69 116
cyliang 0:25c616c85d69 117 If you like to add more traces or follow the current ones you can turn traces on by changing `mbed-trace.enable` in mbed_app.json
cyliang 0:25c616c85d69 118
cyliang 0:25c616c85d69 119 ```"target_overrides": {
cyliang 0:25c616c85d69 120 "*": {
cyliang 0:25c616c85d69 121 "mbed-trace.enable": true,
cyliang 0:25c616c85d69 122 ```
cyliang 0:25c616c85d69 123
cyliang 0:25c616c85d69 124 After you have defined `mbed-trace.enable: true`, you can set trace levels by changing value in `trace-level`
cyliang 0:25c616c85d69 125
cyliang 0:25c616c85d69 126 ```"trace-level": {
cyliang 0:25c616c85d69 127 "help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG",
cyliang 0:25c616c85d69 128 "macro_name": "MBED_TRACE_MAX_LEVEL",
cyliang 0:25c616c85d69 129 "value": "TRACE_LEVEL_INFO"
cyliang 0:25c616c85d69 130 }
cyliang 0:25c616c85d69 131 ```
cyliang 0:25c616c85d69 132
cyliang 0:25c616c85d69 133 ### Board support
cyliang 0:25c616c85d69 134
cyliang 0:25c616c85d69 135 The [cellular modem driver](https://github.com/ARMmbed/mbed-os/tree/master/features/cellular/framework/API) in this example uses PPP with an Mbed-supported external IP stack. It supports targets when modem exists on the Mbed Enabled target as opposed to plug-in modules (shields). For more details, please see our [Mbed OS cellular documentation](https://os.mbed.com/docs/mbed-os/latest/apis/cellular-api.html).
cyliang 0:25c616c85d69 136
cyliang 0:25c616c85d69 137 Currently supported boards with onboard modem chips are:
cyliang 0:25c616c85d69 138
cyliang 0:25c616c85d69 139 [u-blox C027](https://os.mbed.com/platforms/u-blox-C027/)
cyliang 0:25c616c85d69 140 [MultiTech MTS Dragonfly](https://os.mbed.com/platforms/MTS-Dragonfly/)
cyliang 0:25c616c85d69 141
cyliang 0:25c616c85d69 142
cyliang 0:25c616c85d69 143 ## Compiling the application
cyliang 0:25c616c85d69 144
cyliang 0:25c616c85d69 145 The master branch is for daily development and it uses the latest mbed-os/master release.
cyliang 0:25c616c85d69 146
cyliang 0:25c616c85d69 147 To use older versions update Mbed OS release tag, for example:
cyliang 0:25c616c85d69 148
cyliang 0:25c616c85d69 149 ```
cyliang 0:25c616c85d69 150 mbed releases
cyliang 0:25c616c85d69 151 * mbed-os-5.10.4
cyliang 0:25c616c85d69 152 ...
cyliang 0:25c616c85d69 153 mbed update mbed-os-5.10.4
cyliang 0:25c616c85d69 154 ```
cyliang 0:25c616c85d69 155
cyliang 0:25c616c85d69 156 You may need to use `--clean` option to discard your local changes (use with caution).
cyliang 0:25c616c85d69 157
cyliang 0:25c616c85d69 158 Use Mbed CLI commands to generate a binary for the application. For example, in the case of GCC, use the following command:
cyliang 0:25c616c85d69 159
cyliang 0:25c616c85d69 160 ```sh
cyliang 0:25c616c85d69 161 $ mbed compile -m YOUR_TARGET_WITH_MODEM -t GCC_ARM
cyliang 0:25c616c85d69 162 ```
cyliang 0:25c616c85d69 163
cyliang 0:25c616c85d69 164 ## Running the application
cyliang 0:25c616c85d69 165
cyliang 0:25c616c85d69 166 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.
cyliang 0:25c616c85d69 167
cyliang 0:25c616c85d69 168 Attach a serial console emulator of your choice (for example, PuTTY, Minicom or screen) to your USB device. Set the baudrate to 115200 bit/s, and reset your board by pressing the reset button.
cyliang 0:25c616c85d69 169
cyliang 0:25c616c85d69 170 You should see an output similar to this:
cyliang 0:25c616c85d69 171
cyliang 0:25c616c85d69 172 ```
cyliang 0:25c616c85d69 173 mbed-os-example-cellular
cyliang 0:25c616c85d69 174 Establishing connection ......
cyliang 0:25c616c85d69 175
cyliang 0:25c616c85d69 176 Connection Established.
cyliang 0:25c616c85d69 177 TCP: connected with echo.mbedcloudtesting.com server
cyliang 0:25c616c85d69 178 TCP: Sent 4 Bytes to echo.mbedcloudtesting.com
cyliang 0:25c616c85d69 179 Received from echo server 4 Bytes
cyliang 0:25c616c85d69 180
cyliang 0:25c616c85d69 181
cyliang 0:25c616c85d69 182 Success. Exiting
cyliang 0:25c616c85d69 183 ```
cyliang 0:25c616c85d69 184
cyliang 0:25c616c85d69 185 ## Troubleshooting
cyliang 0:25c616c85d69 186
cyliang 0:25c616c85d69 187 * Make sure the fields `sim-pin-code`, `apn`, `username` and `password` from the `mbed_app.json` file are filled in correctly. The correct values should appear in the user manual of the board if using eSIM or in the details of the SIM card if using normal SIM.
cyliang 0:25c616c85d69 188 * Enable trace flag to have access to debug information `"mbed-trace.enable": true`.
cyliang 0:25c616c85d69 189 * Try both `TCP` and `UDP` socket types.
cyliang 0:25c616c85d69 190 * Try both `"lwip.ppp-enabled": true` and `"lwip.ppp-enabled": false`.
cyliang 0:25c616c85d69 191 * The modem may support only a fixed baud-rate, such as `"platform.default-serial-baud-rate": 9600`.
cyliang 0:25c616c85d69 192 * The modem and network may only support IPv6 in which case `"lwip.ipv6-enabled": true` shall be defined.
cyliang 0:25c616c85d69 193 * The SIM and modem must have compatible cellular technology (3G, 4G, NB-IoT, ...) supported and cellular network available.
cyliang 0:25c616c85d69 194
cyliang 0:25c616c85d69 195 If you have problems to get started with debugging, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html) for suggestions on what could be wrong and how to fix it.