CodeZoo co., ltd
/
mbed-os-example-cellular-Type1SC
Cellular example for CodeZoo Type1SC Shield
Diff: README.md
- Revision:
- 0:04fa3499a11e
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.md Tue Jul 27 05:42:30 2021 +0000 @@ -0,0 +1,187 @@ +![](./resources/official_armmbed_example_badge.png) +# Cellular Example + +This is an example based on `mbed-os` cellular APIs that demonstrates a TCP or UDP echo transaction with a public echo server. + +(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).) + +## Getting started + +This particular cellular application uses a cellular network and network-socket APIs that are part of [`mbed-os`](https://github.com/ARMmbed/mbed-os). + +The program uses a [cellular modem driver](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/cellular/include/cellular/framework/API) +using an external IP stack standard 3GPP AT 27.007 AT commands to setup the cellular modem and registers to the network. + +After registration, the driver opens a point-to-point protocol (PPP) pipe 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 the +[Mbed OS cellular API](https://os.mbed.com/docs/mbed-os/latest/apis/cellular-networking.html) and +[Mbed OS cellular porting guide](https://os.mbed.com/docs/mbed-os/latest/porting/cellular-device-porting.html). + +### Board support + +Currently supported boards with onboard modem chips can be found under Mbed OS +[/targets folder](https://github.com/ARMmbed/mbed-os/tree/master/targets). +You can find all cellular specific onboard modems by searching an overridden function +`CellularDevice::get_target_default_instance()`. + +Currently supported modem drivers can be found under cellular +[/drivers folder](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/drivers/cellular). + +For a cellular shield, you need to define which shield to use with `provide-default`, and also how the shield is connected +to the Mbed OS board. For example, a generic AT/PPP modem would add from the `GENERIC_AT3GPP/mbed_lib.json` file to your +`mbed_app.json`: + +``` + "target_overrides": { + "GENERIC_AT3GPP.provide-default": true, + "GENERIC_AT3GPP.tx": "<tx-pinmap>", + "GENERIC_AT3GPP.rx": "<rx-pinmap>" + } +``` + +## Building and flashing the example + +### To build the example + +Clone the repository containing example: + +``` +git clone https://github.com/ARMmbed/mbed-os-example-cellular.git +``` + +**Tip:** If you don't have git installed, you can +[download a zip file](https://github.com/ARMmbed/mbed-os-example-cellular/archive/master.zip) of the repository. + +Update the source tree: + +``` +cd mbed-os-example-cellular +mbed deploy +``` + +Run the build: + +```mbed compile -t <ARM | GCC_ARM> -m <YOUR_TARGET>``` + +### To flash the example onto your board + +Connect your mbed board to your computer over USB. It appears as removable storage. + +When you run the `mbed compile` command above, mbed cli creates a .bin or a .hex file (depending on your target) in +```BUILD/<target-name>/<toolchain>``` under the example's directory. Drag and drop the file to the removable storage. + +Alternatively you may launch compilation with `-f` flag to have mbed tools attempt to flash your board. +The tools will flash the binary to all targets that match the board specified by '-m' parameter. + +### Change the network and SIM credentials + +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 other cellular settings, +or `null` if not used. For example: + +```json + "target_overrides": { + "*": { + "nsapi.default-cellular-sim-pin": "\"1234\"", +``` + +### Selecting socket type (TCP, UDP or NONIP) + +You can choose which socket type the application should use; however, please note that TCP is a more reliable +transmission protocol. For example: + +```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: + +```json + "cellular.debug-at": true +``` + +### Turning on the tracing and trace level + +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: + +```"target_overrides": { + "*": { + "mbed-trace.enable": true, +``` + +After you have defined `mbed-trace.enable: true`, you can set trace levels by changing value in `trace-level`: + + ```"trace-level": { + "help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG", + "macro_name": "MBED_TRACE_MAX_LEVEL", + "value": "TRACE_LEVEL_INFO" + } +``` + +## Running the example + +When example application is running information about activity is printed over the serial connection. + +**Note:** The default serial baudrate has been set to 9600. + +Please have a client open and connected to the board. You may use: + +- [Tera Term](https://ttssh2.osdn.jp/index.html.en) for windows + +- screen or minicom for Linux (example usage: `screen /dev/serial/<your board> 9600`) + +- mbed tools has a terminal command `mbed term -b 9600` + +### Expected output + +You should see an output similar to this: + +``` +mbed-os-example-cellular +Establishing connection +Connection Established. +TCP: connected with echo.mbedcloudtesting.com server +TCP: Sent 4 Bytes to echo.mbedcloudtesting.com +Received from echo server 4 Bytes +Success. Exiting +``` + +### Troubleshooting + +* Make sure the fields `nsapi.default-cellular-sim-pin`, `nsapi.default-cellular-plmn`, `nsapi.default-cellular-apn`, + `nsapi.default-cellular-username` and `nsapi.default-cellular-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. +* Enable trace flag to have access to debug information `"mbed-trace.enable": true` and `"cellular.debug-at": true`. +* Error Message: Assertion failed: iface usually means that a default modem is not defined, e.g. + `"GENERIC_AT3GPP.provide-default": true` +* If the modem does not respond to (AT) queries, check that UART pins (tx, rx, rts, cts) are connected and defined, + e.g. `"GENERIC_AT3GPP.tx": "<tx-pinmap>"`, ... +* It is a common case that a modem seems to connect fine with just USB power, but actually it needs to have an external + power supply for a data connection. +* Try both `TCP` and `UDP` socket types. +* Try both `"lwip.ppp-enabled": true` and `"lwip.ppp-enabled": false`. +* The modem may support only a fixed baud-rate, such as `"platform.default-serial-baud-rate": 9600`. +* The modem and network may only support IPv6 in which case `"lwip.ipv6-enabled": true` shall be defined. +* The SIM and modem must have compatible cellular technology (3G, 4G, NB-IoT, ...) supported and cellular network available. +* Enable CIoT optimization for NONIP socket `control-plane-opt: true`. + +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. + +## License and contributions + +The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. +Please see [contributing.md](CONTRIBUTING.md) for more info. + +This project contains code from other projects. The original license text is included in those source files. +They must comply with our license guide