Nuvoton / Mbed OS NuMaker-mbed-Cellular-example

NuMaker Cellular(NB-IoT/4G)

README.md@4:9432d7355f2b, 2021-02-25 (annotated)

Committer:
SHLIU1@OANBE02333.nuvoton.com
Date:
Thu Feb 25 11:31:56 2021 +0800
Revision:
4:9432d7355f2b
Parent:
3:6f804b5237be 
Support the both V5.X and V6.X for mbed-os

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 3:6f804b5237be 17 2. If run SIM7020, please use Mbed-OS 5.15.0 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 3:6f804b5237be 35 ...
cyliang 3:6f804b5237be 36 "lwip.ppp-enabled": false,
cyliang 3:6f804b5237be 37 "lwip.tcp-enabled": false,
cyliang 0:25c616c85d69 38
cyliang 0:25c616c85d69 39 For QUECTEL EC2x, please add the first three configurations.
cyliang 0:25c616c85d69 40 "target_overrides": {
cyliang 0:25c616c85d69 41 "*": {
cyliang 0:25c616c85d69 42 "GENERIC_AT3GPP.provide-default": true,
cyliang 0:25c616c85d69 43 "GENERIC_AT3GPP.tx": "D1",
cyliang 0:25c616c85d69 44 "GENERIC_AT3GPP.rx": "D0",
cyliang 0:25c616c85d69 45 "target.network-default-interface-type": "CELLULAR",
cyliang 0:25c616c85d69 46 ...
cyliang 0:25c616c85d69 47 "lwip.ppp-enabled": true,
cyliang 0:25c616c85d69 48 "lwip.tcp-enabled": true,
cyliang 0:25c616c85d69 49
cyliang 0:25c616c85d69 50 4. Add the cellular network APN support in mbed_app.json.
cyliang 0:25c616c85d69 51
cyliang 0:25c616c85d69 52 For other configurations, you can refer the original README content as below.
cyliang 0:25c616c85d69 53
cyliang 0:25c616c85d69 54
cyliang 0:25c616c85d69 55 ====================================================================================================
cyliang 0:25c616c85d69 56
cyliang 0:25c616c85d69 57
cyliang 0:25c616c85d69 58 # Example cellular application for Mbed OS
cyliang 0:25c616c85d69 59
cyliang 0:25c616c85d69 60 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 61
cyliang 0:25c616c85d69 62 (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 63
cyliang 0:25c616c85d69 64 ## Getting started
cyliang 0:25c616c85d69 65
cyliang 0:25c616c85d69 66 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 67
cyliang 0:25c616c85d69 68 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 69
cyliang 0:25c616c85d69 70 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 71
cyliang 0:25c616c85d69 72 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 73
cyliang 0:25c616c85d69 74 ### Download the application
cyliang 0:25c616c85d69 75
cyliang 0:25c616c85d69 76 ```sh
cyliang 0:25c616c85d69 77 $ mbed import mbed-os-example-cellular
cyliang 0:25c616c85d69 78 $ cd mbed-os-example-cellular
cyliang 0:25c616c85d69 79
cyliang 0:25c616c85d69 80 #OR
cyliang 0:25c616c85d69 81
cyliang 0:25c616c85d69 82 $ git clone git@github.com:ARMmbed/mbed-os-example-cellular.git
cyliang 0:25c616c85d69 83 $ cd mbed-os-example-cellular
cyliang 0:25c616c85d69 84 ```
cyliang 0:25c616c85d69 85
cyliang 0:25c616c85d69 86 ### Change the network and SIM credentials
cyliang 0:25c616c85d69 87
cyliang 0:25c616c85d69 88 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 89
cyliang 0:25c616c85d69 90 ```json
cyliang 0:25c616c85d69 91 "nsapi.default-cellular-plmn": 0,
cyliang 0:25c616c85d69 92 "nsapi.default-cellular-sim-pin": "\"1234\"",
cyliang 0:25c616c85d69 93 "nsapi.default-cellular-apn": 0,
cyliang 0:25c616c85d69 94 "nsapi.default-cellular-username": 0,
cyliang 0:25c616c85d69 95 "nsapi.default-cellular-password": 0
cyliang 0:25c616c85d69 96 ```
cyliang 0:25c616c85d69 97
cyliang 0:25c616c85d69 98 ### Selecting socket type (TCP or UDP)
cyliang 0:25c616c85d69 99
cyliang 0:25c616c85d69 100
cyliang 0:25c616c85d69 101 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 102
cyliang 0:25c616c85d69 103
cyliang 0:25c616c85d69 104 ```json
cyliang 0:25c616c85d69 105
cyliang 0:25c616c85d69 106 "sock-type": "TCP",
cyliang 0:25c616c85d69 107
cyliang 0:25c616c85d69 108 ```
cyliang 0:25c616c85d69 109
cyliang 0:25c616c85d69 110 ### Turning modem AT echo trace on
cyliang 0:25c616c85d69 111
cyliang 0:25c616c85d69 112 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 113
cyliang 0:25c616c85d69 114 ```json
cyliang 0:25c616c85d69 115 "cellular.debug-at": true
cyliang 0:25c616c85d69 116 ```
cyliang 0:25c616c85d69 117
cyliang 0:25c616c85d69 118 ### Turning on the tracing and trace level
cyliang 0:25c616c85d69 119
cyliang 0:25c616c85d69 120 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 121
cyliang 0:25c616c85d69 122 ```"target_overrides": {
cyliang 0:25c616c85d69 123 "*": {
cyliang 0:25c616c85d69 124 "mbed-trace.enable": true,
cyliang 0:25c616c85d69 125 ```
cyliang 0:25c616c85d69 126
cyliang 0:25c616c85d69 127 After you have defined `mbed-trace.enable: true`, you can set trace levels by changing value in `trace-level`
cyliang 0:25c616c85d69 128
cyliang 0:25c616c85d69 129 ```"trace-level": {
cyliang 0:25c616c85d69 130 "help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG",
cyliang 0:25c616c85d69 131 "macro_name": "MBED_TRACE_MAX_LEVEL",
cyliang 0:25c616c85d69 132 "value": "TRACE_LEVEL_INFO"
cyliang 0:25c616c85d69 133 }
cyliang 0:25c616c85d69 134 ```
cyliang 0:25c616c85d69 135
cyliang 0:25c616c85d69 136 ### Board support
cyliang 0:25c616c85d69 137
cyliang 0:25c616c85d69 138 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 139
cyliang 0:25c616c85d69 140 Currently supported boards with onboard modem chips are:
cyliang 0:25c616c85d69 141
cyliang 0:25c616c85d69 142 [u-blox C027](https://os.mbed.com/platforms/u-blox-C027/)
cyliang 0:25c616c85d69 143 [MultiTech MTS Dragonfly](https://os.mbed.com/platforms/MTS-Dragonfly/)
cyliang 0:25c616c85d69 144
cyliang 0:25c616c85d69 145
cyliang 0:25c616c85d69 146 ## Compiling the application
cyliang 0:25c616c85d69 147
cyliang 0:25c616c85d69 148 The master branch is for daily development and it uses the latest mbed-os/master release.
cyliang 0:25c616c85d69 149
cyliang 0:25c616c85d69 150 To use older versions update Mbed OS release tag, for example:
cyliang 0:25c616c85d69 151
cyliang 0:25c616c85d69 152 ```
cyliang 0:25c616c85d69 153 mbed releases
cyliang 0:25c616c85d69 154 * mbed-os-5.10.4
cyliang 0:25c616c85d69 155 ...
cyliang 0:25c616c85d69 156 mbed update mbed-os-5.10.4
cyliang 0:25c616c85d69 157 ```
cyliang 0:25c616c85d69 158
cyliang 0:25c616c85d69 159 You may need to use `--clean` option to discard your local changes (use with caution).
cyliang 0:25c616c85d69 160
cyliang 0:25c616c85d69 161 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 162
cyliang 0:25c616c85d69 163 ```sh
cyliang 0:25c616c85d69 164 $ mbed compile -m YOUR_TARGET_WITH_MODEM -t GCC_ARM
cyliang 0:25c616c85d69 165 ```
cyliang 0:25c616c85d69 166
cyliang 0:25c616c85d69 167 ## Running the application
cyliang 0:25c616c85d69 168
cyliang 0:25c616c85d69 169 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 170
cyliang 0:25c616c85d69 171 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 172
cyliang 0:25c616c85d69 173 You should see an output similar to this:
cyliang 0:25c616c85d69 174
cyliang 0:25c616c85d69 175 ```
cyliang 0:25c616c85d69 176 mbed-os-example-cellular
cyliang 0:25c616c85d69 177 Establishing connection ......
cyliang 0:25c616c85d69 178
cyliang 0:25c616c85d69 179 Connection Established.
cyliang 0:25c616c85d69 180 TCP: connected with echo.mbedcloudtesting.com server
cyliang 0:25c616c85d69 181 TCP: Sent 4 Bytes to echo.mbedcloudtesting.com
cyliang 0:25c616c85d69 182 Received from echo server 4 Bytes
cyliang 0:25c616c85d69 183
cyliang 0:25c616c85d69 184
cyliang 0:25c616c85d69 185 Success. Exiting
cyliang 0:25c616c85d69 186 ```
cyliang 0:25c616c85d69 187
cyliang 0:25c616c85d69 188 ## Troubleshooting
cyliang 0:25c616c85d69 189
cyliang 0:25c616c85d69 190 * 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 191 * Enable trace flag to have access to debug information `"mbed-trace.enable": true`.
cyliang 0:25c616c85d69 192 * Try both `TCP` and `UDP` socket types.
cyliang 0:25c616c85d69 193 * Try both `"lwip.ppp-enabled": true` and `"lwip.ppp-enabled": false`.
cyliang 0:25c616c85d69 194 * The modem may support only a fixed baud-rate, such as `"platform.default-serial-baud-rate": 9600`.
cyliang 0:25c616c85d69 195 * The modem and network may only support IPv6 in which case `"lwip.ipv6-enabled": true` shall be defined.
cyliang 0:25c616c85d69 196 * The SIM and modem must have compatible cellular technology (3G, 4G, NB-IoT, ...) supported and cellular network available.
cyliang 0:25c616c85d69 197
cyliang 0:25c616c85d69 198 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.