nRF9160: Modem Shell
The Modem Shell (MoSh) sample application enables you to test various device connectivity features, including data throughput.
The sample supports the following development kits:
MoSh enables testing of different connectivity features such as LTE link handling, TCP/IP connections, data throughput (iperf3 and curl), SMS, GNSS, FOTA updates and PPP. Hence, this sample is not only code sample, which it also is in many aspects, but also a test application for aforementioned features. MoSh uses the LTE link control driver to establish an LTE connection and initializes the Zephyr shell to provide a shell command-line interface for users.
The subsections list the MoSh features and show shell command examples for their usage.
You can use the AT command module to send AT commands to the modem.
Send AT command to query network status:
Send AT command to query neighbor cells:
Enable AT command events:
Disable AT command events:
Ping is a tool for testing the reachability of a host on an IP network.
Ping a URL:
ping -d ping.server.url
Ping an IPv6 address with length of 500 bytes and 1 s intervals (the used PDN needs to support IPv6):
ping -d 1a2b:1a2b:1a2b:1a2b::1 -6 -l 500 -i 1000
Iperf3 is a tool for measuring data transfer performance both in uplink and downlink direction.
Some features, for example file operations and TCP option tuning, are not supported.
Download data over TCP for 30 seconds with a buffer size of 3540 bytes and use detailed output:
iperf3 --client 18.104.22.168 --port 10000 -l 3540 --time 30 -V -R
Upload data over TCP for 30 seconds with the payload size of 708 bytes using a PDN with ID #2 (use the
link statuscommand to see the active PDNs and their IDs):
iperf3 -c 22.214.171.124 -p 10000 -l 708 -t 30 --pdn_id 2
Upload data over UDP for 60 seconds with the payload size of 1240 bytes and use the detailed output as well as debug output:
iperf3 --client 126.96.36.199 --port 10000 -l 1240 --time 60 -u -V -d
Download data over TCP/IPv6 for 10 seconds (the used PDN needs to support IPv6, use the
link statuscommand to see PDP type support for active contexts):
iperf3 --client 1a2b:1a2b:1a2b:1a2b::1 --port 20000 --time 10 -R -6
Curl is a command-line tool for transferring data specified with URL syntax. It is a part of MoSh and enables you to test the data download with a “standard” tool.
File operations are not supported.
curl http://curl.server.url/small.txt curl http://curl.server.url/bigger_file.zip --output /dev/null
HTTP upload for given data:
curl http://curl.server.url/data -d "foo=bar"
HTTP upload for given number of bytes sent in a POST body:
curl http://curl.server.url/data -d #500000
HTTP upload for given number of bytes sent in a POST body using a PDN with ID #1 (use the
link statuscommand to see active PDNs and their IDs):
curl http://curl.server.url/data -d #500000 --pdn_id 1
You can use the socket tool to:
Create and manage socket connections.
Send and receive data.
Open and connect to an IP address and port (IPv4 TCP socket):
sock connect -a 188.8.131.52 -p 20000
Open and connect to hostname and port (IPv4 TCP socket):
sock connect -a google.com -p 20000
Open and connect an IPv6 TCP socket and bind to a port:
sock connect -a 1a2b:1a2b:1a2b:1a2b::1 -p 20000 -f inet6 -t stream -b 40000
Open an IPv6 UDP socket:
sock connect -a 1a2b:1a2b:1a2b:1a2b::1 -p 20000 -f inet6 -t dgram
Open a raw socket:
sock connect -f packet -t raw
Open a socket to a non-default PDP context:
link connect -a nondefault.context.com sock connect -f packet -t raw -I 1
Send a string through the socket:
sock send -i 0 -d testing
Send 100 kB of data and show throughput statistics:
sock send -i 0 -l 100000
Send data periodically with 10 s interval:
sock send -i 0 -e 10 -d test_periodic
Calculate the receive throughput:
<do whatever is needed to make device receive data after some time> sock recv -i 0 -r -l 1000000 sock recv -i 0 sock recv -i 0
Close a socket:
sock close -i 0
Use RAI settings:
link funmode -4 link rai -e link funmode -1 sock connect -a 184.108.40.206 -p 20000 sock rai -i 0 --rai_last sock send -i 0 -d testing
List open sockets:
You can use the SMS tool for sending and receiving SMS messages.
Register the SMS service so that messages can be received if SIM subscription supports it:
Send an SMS message (registration is done automatically if not already done):
sms send -n +987654321 -m testing
You can use the Location tool for retrieving device’s location with different methods. See Location library for information on the configuration of different location methods and services. Some default configurations are available to facilitate trials.
Retrieve location with default configuration:
Retrieve location with Wi-Fi positioning. You need to have a Wi-Fi-enabled device and build the sample with Wi-Fi support. If the location is not found, use cellular positioning:
location get --method wifi --wifi_timeout 60 --method cellular --cellular_service nrf
Retrieve location periodically every hour with GNSS and if not found, use cellular positioning:
location get --interval 3600 --method gnss --gnss_timeout 300 --method cellular
Cancel ongoing location request or periodic location request:
GNSS provides commands for searching the location of the device.
Start GNSS tracking and stop it:
gnss start gnss stop
Disable LTE, enable all GNSS output and start continuous tracking with power saving enabled:
link funmode --lteoff gnss output 2 1 1 gnss mode cont gnss config powersave perf gnss start
Enable LTE PSM, only NMEA output, automatic A-GPS data fetching and start periodic fixes with 5 minute interval and 120 second timeout:
link psm -e gnss output 0 1 0 gnss agps automatic enable gnss mode periodic 300 120 gnss start
You can use FOTA to perform software updates over-the-air for both modem and application side. However, to use this feature, you need to know which updates are available in the servers. This feature is intended to be used only by selected users and customers to whom available image names are communicated separately.
Perform a FOTA update:
fota download eu fw_update_package_filename.hex
You can use the PPP (Point-to-Point Protocol) to enable dial-up access to the Internet. The MoSh command is simple but you need to have a normal dial-up setup in your PC to be able to use the development kit’s PPP interface.
On Windows, dial-up connection is not functional when using Segger virtual UART ports. PPP has been used successfully with FTDI UART port though. Refer to nRF9160 Hardware Verification Guidelines - UART interface.
PPP has been successfully used running Ubuntu Linux in a virtualization environment hosted by Windows. In the hosted virtual Linux environment, using PPP is possible also with plain Segger UART ports.
PPP network interface is brought up/down automatically when LTE connection is up/down. Set the PPP network interface up manually:
Set the PPP network interface down manually:
Set the custom baudrate configuration for PPP UART (default: 115200):
ppp uartconf --baudrate 921600
rts_ctshardware flow control configuration for PPP UART (default: none):
ppp uartconf --flowctrl rts_cts
You can use the REST client for sending simple REST requests and receiving responses to them.
Sending a HEAD request with custom dummy headers:
rest -d example.com -l 1024 -m head -H "X-foo1: bar1\x0D\x0A" -H "X-foo2: bar2\x0D\x0A"
nRF Cloud is a platform for providing, among other things, various location services.
Modem Shell enables you to establish an MQTT connection to nRF Cloud using the nRF Cloud library.
cloud command is useful mostly when using the location services and MQTT is the desired transport protocol.
However, you can use any nRF Cloud services once the MQTT connection is established.
Establish the connection to nRF Cloud, request the cell-based location of the device, and disconnect when ready:
cloud connect location get --method cellular cloud disconnect
See Configuring your application for information about how to permanently or temporarily change the configuration.
Check and configure the following configuration options for the sample:
Enable ping feature in modem shell.
Enable iperf3 feature in modem shell.
Enable curl feature in modem shell.
Enable socket tool feature in modem shell.
Enable SMS feature in modem shell
Enable Location tool in modem shell.
Enable GNSS feature in modem shell
Enable FOTA feature in modem shell
Enable PPP feature in modem shell
Enable REST feature in modem shell
You may not be able to use all features at the same time due to memory restrictions. To see which features are enabled simultaneously, check the configuration files and overlays.
This sample can be found under
samples/nrf9160/modem_shell in the nRF Connect SDK folder structure.
The sample is built as a non-secure firmware image for the nrf9160dk_nrf9160_ns build target. Because of this, it automatically includes the Secure Partition Manager. You can also configure it to use TF-M instead of SPM.
See Building and programming an application for information about how to build and program the application.
See Providing CMake options for instructions on how to provide CMake options, for example to use a configuration overlay.
The LEDs have the following functions:
- LED 1:
Indicates the LTE registration status.
After programming the application and all prerequisites to your development kit, test it by performing the following steps:
Connect the development kit to the computer using a USB cable. The development kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.
Create a serial connection to the development kit (J-Link COM port) with a terminal using the following settings:
Hardware flow control: disabled
Baud rate: 115200
Parity bit: no
Reset the development kit.
Observe in the terminal window that the application starts. This is indicated by output similar to the following (there is also a lot of additional information about the LTE connection):
*** Booting Zephyr OS build v2.4.99-ncs1-3525-g4d068de3f50f *** MOSH version: v1.5.0-649-g7e657c2fab02 MOSH build id: 152 MOSH build variant: normal Initializing modemlib... Initialized modemlib Network registration status: searching Network registration status: Connected - home network mosh:~$
Type any of the commands listed in the Overview section to the terminal. When you type only the command, the terminal shows the usage, for example
To build the MoSh sample with ESP8266 Wi-Fi chip support, use the
west build -p -b nrf9160dk_nrf9160_ns -d build -- -DDTC_OVERLAY_FILE=esp_8266_nrf9160ns.overlay -DOVERLAY_CONFIG=overlay-esp-wifi.conf
See Providing CMake options for more instructions on how to add these options.
To build the MoSh sample with PPP/dial up support, use the
west build -p -b nrf9160dk_nrf9160_ns -- -DDTC_OVERLAY_FILE=ppp.overlay -DOVERLAY_CONFIG=overlay-ppp.conf
After programming the development kit, test it in the Linux environment by performing the following steps:
Connect the development kit to the computer using a USB cable. The development kit is assigned a ttyACM device (Linux).
Open a serial connection to the development kit (/dev/ttyACM2) with a terminal (for example PuTTY).
Reset the development kit.
Observe in the terminal window that the MoSh starts with the PPP support. This is indicated by output similar to the following (there is also a lot of additional information about the LTE connection):
Network registration status: searching Network registration status: Connected - home network Default PDN is active: starting PPP automatically PPP: started mosh:~$
Enter command``ppp uartconf`` that results in the following UART configuration:
mosh:~$ ppp uartconf -r PPP uart configuration: baudrate: 921600 flow control: RTS_CTS parity: none data bits: bits8 stop bits: bits1 mosh:~$
In a Linux terminal, enter the following command to start the PPP connection:
$ sudo pppd -detach /dev/ttyACM0 921600 noauth crtscts noccp novj nodeflate nobsdcomp local debug +ipv6 ipv6cp-use-ipaddr usepeerdns noipdefault defaultroute
In a MoSh terminal, observe that the PPP connection is created:
Dial up (IPv6) connection up Dial up (IPv4) connection up mosh:~$
Now, you are ready to browse Internet in Linux by using the MoSh PPP dial-up over LTE connection.
To build the MoSh sample with application FOTA support, use the
west build -p -b nrf9160dk_nrf9160_ns -d build -- -DOVERLAY_CONFIG=overlay-app_fota.conf
To build the MoSh sample with LwM2M carrier library support, use the
west build -p -b nrf9160dk_nrf9160_ns -d build -- -DOVERLAY_CONFIG=overlay-lwm2m_carrier.conf
To build the MoSh sample with P-GPS support, use the
west build -p -b nrf9160dk_nrf9160_ns -d build -- -DOVERLAY_CONFIG=overlay-pgps.conf