CodeZoo co., ltd / Mbed OS mbed-os-example-cellular-Type1SC

Cellular example for CodeZoo Type1SC Shield

README.md@0:04fa3499a11e, 2021-07-27 (annotated)

Committer:
pimco01
Date:
Tue Jul 27 05:42:30 2021 +0000
Revision:
0:04fa3499a11e
CodeZoo Type1SC Shield Initial commit.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
pimco01 0:04fa3499a11e 1 ![](./resources/official_armmbed_example_badge.png)
pimco01 0:04fa3499a11e 2 # Cellular Example
pimco01 0:04fa3499a11e 3
pimco01 0:04fa3499a11e 4 This is an example based on `mbed-os` cellular APIs that demonstrates a TCP or UDP echo transaction with a public echo server.
pimco01 0:04fa3499a11e 5
pimco01 0:04fa3499a11e 6 (Note: To see this example in a rendered form you can import into the Arm Mbed Online Compiler, please see
pimco01 0:04fa3499a11e 7 [the documentation](https://os.mbed.com/docs/mbed-os/latest/apis/cellular-api.html#cellular-example-connection-establishment).)
pimco01 0:04fa3499a11e 8
pimco01 0:04fa3499a11e 9 ## Getting started
pimco01 0:04fa3499a11e 10
pimco01 0:04fa3499a11e 11 This particular cellular application uses a cellular network and network-socket APIs that are part of [`mbed-os`](https://github.com/ARMmbed/mbed-os).
pimco01 0:04fa3499a11e 12
pimco01 0:04fa3499a11e 13 The program uses a [cellular modem driver](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/cellular/include/cellular/framework/API)
pimco01 0:04fa3499a11e 14 using an external IP stack standard 3GPP AT 27.007 AT commands to setup the cellular modem and registers to the network.
pimco01 0:04fa3499a11e 15
pimco01 0:04fa3499a11e 16 After registration, the driver opens a point-to-point protocol (PPP) pipe with the cellular modem and connects
pimco01 0:04fa3499a11e 17 to internet. This driver currently supports UART data connection type only between your cellular modem and MCU.
pimco01 0:04fa3499a11e 18
pimco01 0:04fa3499a11e 19 For more information on Arm Mbed OS cellular APIs and porting guide, please visit the
pimco01 0:04fa3499a11e 20 [Mbed OS cellular API](https://os.mbed.com/docs/mbed-os/latest/apis/cellular-networking.html) and
pimco01 0:04fa3499a11e 21 [Mbed OS cellular porting guide](https://os.mbed.com/docs/mbed-os/latest/porting/cellular-device-porting.html).
pimco01 0:04fa3499a11e 22
pimco01 0:04fa3499a11e 23 ### Board support
pimco01 0:04fa3499a11e 24
pimco01 0:04fa3499a11e 25 Currently supported boards with onboard modem chips can be found under Mbed OS
pimco01 0:04fa3499a11e 26 [/targets folder](https://github.com/ARMmbed/mbed-os/tree/master/targets).
pimco01 0:04fa3499a11e 27 You can find all cellular specific onboard modems by searching an overridden function
pimco01 0:04fa3499a11e 28 `CellularDevice::get_target_default_instance()`.
pimco01 0:04fa3499a11e 29
pimco01 0:04fa3499a11e 30 Currently supported modem drivers can be found under cellular
pimco01 0:04fa3499a11e 31 [/drivers folder](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/drivers/cellular).
pimco01 0:04fa3499a11e 32
pimco01 0:04fa3499a11e 33 For a cellular shield, you need to define which shield to use with `provide-default`, and also how the shield is connected
pimco01 0:04fa3499a11e 34 to the Mbed OS board. For example, a generic AT/PPP modem would add from the `GENERIC_AT3GPP/mbed_lib.json` file to your
pimco01 0:04fa3499a11e 35 `mbed_app.json`:
pimco01 0:04fa3499a11e 36
pimco01 0:04fa3499a11e 37 ```
pimco01 0:04fa3499a11e 38 "target_overrides": {
pimco01 0:04fa3499a11e 39 "GENERIC_AT3GPP.provide-default": true,
pimco01 0:04fa3499a11e 40 "GENERIC_AT3GPP.tx": "<tx-pinmap>",
pimco01 0:04fa3499a11e 41 "GENERIC_AT3GPP.rx": "<rx-pinmap>"
pimco01 0:04fa3499a11e 42 }
pimco01 0:04fa3499a11e 43 ```
pimco01 0:04fa3499a11e 44
pimco01 0:04fa3499a11e 45 ## Building and flashing the example
pimco01 0:04fa3499a11e 46
pimco01 0:04fa3499a11e 47 ### To build the example
pimco01 0:04fa3499a11e 48
pimco01 0:04fa3499a11e 49 Clone the repository containing example:
pimco01 0:04fa3499a11e 50
pimco01 0:04fa3499a11e 51 ```
pimco01 0:04fa3499a11e 52 git clone https://github.com/ARMmbed/mbed-os-example-cellular.git
pimco01 0:04fa3499a11e 53 ```
pimco01 0:04fa3499a11e 54
pimco01 0:04fa3499a11e 55 **Tip:** If you don't have git installed, you can
pimco01 0:04fa3499a11e 56 [download a zip file](https://github.com/ARMmbed/mbed-os-example-cellular/archive/master.zip) of the repository.
pimco01 0:04fa3499a11e 57
pimco01 0:04fa3499a11e 58 Update the source tree:
pimco01 0:04fa3499a11e 59
pimco01 0:04fa3499a11e 60 ```
pimco01 0:04fa3499a11e 61 cd mbed-os-example-cellular
pimco01 0:04fa3499a11e 62 mbed deploy
pimco01 0:04fa3499a11e 63 ```
pimco01 0:04fa3499a11e 64
pimco01 0:04fa3499a11e 65 Run the build:
pimco01 0:04fa3499a11e 66
pimco01 0:04fa3499a11e 67 ```mbed compile -t <ARM | GCC_ARM> -m <YOUR_TARGET>```
pimco01 0:04fa3499a11e 68
pimco01 0:04fa3499a11e 69 ### To flash the example onto your board
pimco01 0:04fa3499a11e 70
pimco01 0:04fa3499a11e 71 Connect your mbed board to your computer over USB. It appears as removable storage.
pimco01 0:04fa3499a11e 72
pimco01 0:04fa3499a11e 73 When you run the `mbed compile` command above, mbed cli creates a .bin or a .hex file (depending on your target) in
pimco01 0:04fa3499a11e 74 ```BUILD/<target-name>/<toolchain>``` under the example's directory. Drag and drop the file to the removable storage.
pimco01 0:04fa3499a11e 75
pimco01 0:04fa3499a11e 76 Alternatively you may launch compilation with `-f` flag to have mbed tools attempt to flash your board.
pimco01 0:04fa3499a11e 77 The tools will flash the binary to all targets that match the board specified by '-m' parameter.
pimco01 0:04fa3499a11e 78
pimco01 0:04fa3499a11e 79 ### Change the network and SIM credentials
pimco01 0:04fa3499a11e 80
pimco01 0:04fa3499a11e 81 See the file `mbed_app.json` in the root directory of your application. This file contains all the user specific
pimco01 0:04fa3499a11e 82 configurations your application needs. Provide the pin code for your SIM card, as well as any other cellular settings,
pimco01 0:04fa3499a11e 83 or `null` if not used. For example:
pimco01 0:04fa3499a11e 84
pimco01 0:04fa3499a11e 85 ```json
pimco01 0:04fa3499a11e 86 "target_overrides": {
pimco01 0:04fa3499a11e 87 "*": {
pimco01 0:04fa3499a11e 88 "nsapi.default-cellular-sim-pin": "\"1234\"",
pimco01 0:04fa3499a11e 89 ```
pimco01 0:04fa3499a11e 90
pimco01 0:04fa3499a11e 91 ### Selecting socket type (TCP, UDP or NONIP)
pimco01 0:04fa3499a11e 92
pimco01 0:04fa3499a11e 93 You can choose which socket type the application should use; however, please note that TCP is a more reliable
pimco01 0:04fa3499a11e 94 transmission protocol. For example:
pimco01 0:04fa3499a11e 95
pimco01 0:04fa3499a11e 96 ```json
pimco01 0:04fa3499a11e 97
pimco01 0:04fa3499a11e 98 "sock-type": "TCP",
pimco01 0:04fa3499a11e 99
pimco01 0:04fa3499a11e 100 ```
pimco01 0:04fa3499a11e 101
pimco01 0:04fa3499a11e 102 ### Turning modem AT echo trace on
pimco01 0:04fa3499a11e 103
pimco01 0:04fa3499a11e 104 If you like details and wish to know about all the AT interactions between the modem and your driver, turn on the modem
pimco01 0:04fa3499a11e 105 AT echo trace:
pimco01 0:04fa3499a11e 106
pimco01 0:04fa3499a11e 107 ```json
pimco01 0:04fa3499a11e 108 "cellular.debug-at": true
pimco01 0:04fa3499a11e 109 ```
pimco01 0:04fa3499a11e 110
pimco01 0:04fa3499a11e 111 ### Turning on the tracing and trace level
pimco01 0:04fa3499a11e 112
pimco01 0:04fa3499a11e 113 If you like to add more traces or follow the current ones you can turn traces on by changing `mbed-trace.enable` in
pimco01 0:04fa3499a11e 114 mbed_app.json:
pimco01 0:04fa3499a11e 115
pimco01 0:04fa3499a11e 116 ```"target_overrides": {
pimco01 0:04fa3499a11e 117 "*": {
pimco01 0:04fa3499a11e 118 "mbed-trace.enable": true,
pimco01 0:04fa3499a11e 119 ```
pimco01 0:04fa3499a11e 120
pimco01 0:04fa3499a11e 121 After you have defined `mbed-trace.enable: true`, you can set trace levels by changing value in `trace-level`:
pimco01 0:04fa3499a11e 122
pimco01 0:04fa3499a11e 123 ```"trace-level": {
pimco01 0:04fa3499a11e 124 "help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG",
pimco01 0:04fa3499a11e 125 "macro_name": "MBED_TRACE_MAX_LEVEL",
pimco01 0:04fa3499a11e 126 "value": "TRACE_LEVEL_INFO"
pimco01 0:04fa3499a11e 127 }
pimco01 0:04fa3499a11e 128 ```
pimco01 0:04fa3499a11e 129
pimco01 0:04fa3499a11e 130 ## Running the example
pimco01 0:04fa3499a11e 131
pimco01 0:04fa3499a11e 132 When example application is running information about activity is printed over the serial connection.
pimco01 0:04fa3499a11e 133
pimco01 0:04fa3499a11e 134 **Note:** The default serial baudrate has been set to 9600.
pimco01 0:04fa3499a11e 135
pimco01 0:04fa3499a11e 136 Please have a client open and connected to the board. You may use:
pimco01 0:04fa3499a11e 137
pimco01 0:04fa3499a11e 138 - [Tera Term](https://ttssh2.osdn.jp/index.html.en) for windows
pimco01 0:04fa3499a11e 139
pimco01 0:04fa3499a11e 140 - screen or minicom for Linux (example usage: `screen /dev/serial/<your board> 9600`)
pimco01 0:04fa3499a11e 141
pimco01 0:04fa3499a11e 142 - mbed tools has a terminal command `mbed term -b 9600`
pimco01 0:04fa3499a11e 143
pimco01 0:04fa3499a11e 144 ### Expected output
pimco01 0:04fa3499a11e 145
pimco01 0:04fa3499a11e 146 You should see an output similar to this:
pimco01 0:04fa3499a11e 147
pimco01 0:04fa3499a11e 148 ```
pimco01 0:04fa3499a11e 149 mbed-os-example-cellular
pimco01 0:04fa3499a11e 150 Establishing connection
pimco01 0:04fa3499a11e 151 Connection Established.
pimco01 0:04fa3499a11e 152 TCP: connected with echo.mbedcloudtesting.com server
pimco01 0:04fa3499a11e 153 TCP: Sent 4 Bytes to echo.mbedcloudtesting.com
pimco01 0:04fa3499a11e 154 Received from echo server 4 Bytes
pimco01 0:04fa3499a11e 155 Success. Exiting
pimco01 0:04fa3499a11e 156 ```
pimco01 0:04fa3499a11e 157
pimco01 0:04fa3499a11e 158 ### Troubleshooting
pimco01 0:04fa3499a11e 159
pimco01 0:04fa3499a11e 160 * Make sure the fields `nsapi.default-cellular-sim-pin`, `nsapi.default-cellular-plmn`, `nsapi.default-cellular-apn`,
pimco01 0:04fa3499a11e 161 `nsapi.default-cellular-username` and `nsapi.default-cellular-password` from the `mbed_app.json` file are filled in
pimco01 0:04fa3499a11e 162 correctly. The correct values should appear in the user manual of the board if using eSIM or in the details of the
pimco01 0:04fa3499a11e 163 SIM card if using normal SIM.
pimco01 0:04fa3499a11e 164 * Enable trace flag to have access to debug information `"mbed-trace.enable": true` and `"cellular.debug-at": true`.
pimco01 0:04fa3499a11e 165 * Error Message: Assertion failed: iface usually means that a default modem is not defined, e.g.
pimco01 0:04fa3499a11e 166 `"GENERIC_AT3GPP.provide-default": true`
pimco01 0:04fa3499a11e 167 * If the modem does not respond to (AT) queries, check that UART pins (tx, rx, rts, cts) are connected and defined,
pimco01 0:04fa3499a11e 168 e.g. `"GENERIC_AT3GPP.tx": "<tx-pinmap>"`, ...
pimco01 0:04fa3499a11e 169 * It is a common case that a modem seems to connect fine with just USB power, but actually it needs to have an external
pimco01 0:04fa3499a11e 170 power supply for a data connection.
pimco01 0:04fa3499a11e 171 * Try both `TCP` and `UDP` socket types.
pimco01 0:04fa3499a11e 172 * Try both `"lwip.ppp-enabled": true` and `"lwip.ppp-enabled": false`.
pimco01 0:04fa3499a11e 173 * The modem may support only a fixed baud-rate, such as `"platform.default-serial-baud-rate": 9600`.
pimco01 0:04fa3499a11e 174 * The modem and network may only support IPv6 in which case `"lwip.ipv6-enabled": true` shall be defined.
pimco01 0:04fa3499a11e 175 * The SIM and modem must have compatible cellular technology (3G, 4G, NB-IoT, ...) supported and cellular network available.
pimco01 0:04fa3499a11e 176 * Enable CIoT optimization for NONIP socket `control-plane-opt: true`.
pimco01 0:04fa3499a11e 177
pimco01 0:04fa3499a11e 178 If you have problems to get started with debugging, you can review the
pimco01 0:04fa3499a11e 179 [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html) for suggestions on what could be wrong and how to fix it.
pimco01 0:04fa3499a11e 180
pimco01 0:04fa3499a11e 181 ## License and contributions
pimco01 0:04fa3499a11e 182
pimco01 0:04fa3499a11e 183 The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license.
pimco01 0:04fa3499a11e 184 Please see [contributing.md](CONTRIBUTING.md) for more info.
pimco01 0:04fa3499a11e 185
pimco01 0:04fa3499a11e 186 This project contains code from other projects. The original license text is included in those source files.
pimco01 0:04fa3499a11e 187 They must comply with our license guide