Soracom Air for Cellular
Troubleshooting
When troubleshooting cellular connectivity issues, the most effective way to check for potential problems is typically to test the device directly. In many cases, running a series of simple tests can help you understand or narrow down what sort of problem is occurring.
In other situations, interacting directly with the modem can also help you understand how it is configured and verify its connection status. This is typically done by accessing the modem's serial interface and sending commands directly to the modem to check how it behaves.
Not all devices will provide access to the modem's serial interface. If you are using a third party device that does not allow you to access the modem's serial interface directly, you may need to check the device's instruction manual for other ways to perform similar troubleshooting steps. Alternatively, you may need to contact the manufacturer for further assistance.
Basic Troubleshooting
In some cases, a connectivity issue may simply be related to the device set up or configuration, such as a loose antenna or a missing setting. Refer to the Basic Connectivity documentation for general tips on how to check if your device is set up correctly.
If you are using a Soracom reference device or starter kit, you can also find dedicated tutorials and guides for how to set up your device:
If you have finished setting up your device but are still having connectivity issues, you can also use the connectivity diagnostics tool to check for basic network problems that might be related to the issue. Refer to the Diagnostics documentation for more information.
Device Troubleshooting
In addition to using the connectivity diagnostics tool to check for basic network problems, you can also perform the following steps to troubleshoot from your device:
- Reboot the device - If the device resumes normal operation after rebooting, this may indicate that there was a temporary issue, such as software error.
- Move the device to a new location - If the device resumes normal operation after moving it, this may indicate that the signal strength was poor.
- Try the SIM in a different device - If the new device successfully connects using the same SIM, this may indicate a problem with the previous device, such as configuration error or hardware failure.
- Try a different Soracom SIM in the same device - If the device resumes normal operation after switching to a different Soracom SIM, this may indicate a problem with the previous SIM, such as damage.
- Factory-reset the device - If the device resumes normal operation after performing a factory reset and reconfiguration, this may indicate that there was an issue with the previous configuration.
- Manually start a network scan (if applicable) - If the device provides a function to scan for available networks and resumes normal operation after successfully completing a network scan, this may indicate that the device encountered a scenario where it could not complete a network scan by itself.
- Manually select a network to connect to (if applicable) - If the device provides a way to choose a specific network to connect to and resumes normal operation after selecting a particular network, this may indicate that the device is unable to select and connect to a network automatically.
Soracom Troubleshooting
If you are using any of the following Soracom features, you can also try temporarily disabling these options as they may affect your device's ability to connect:
- Disable IMEI Lock - If you have enabled IMEI Lock for your SIM and your device resumes normal operation after disabling IMEI Lock, this may indicate that IMEI Lock was configured for a different device, or the local network operator did not report the IMEI of your device, causing Soracom to block the connection. For more information, refer to the IMEI Lock documentation.
- Disable Expiration - If you have enabled Expiration for your SIM and your device resumes normal operation after disabling Expiration, this may indicate that Expiration was configured in a way to disable the SIM, causing Soracom to block the connection. For more information, refer to the Expiration documentation.
- Disable CHAP Authentication - If you have enabled CHAP Authentication for your SIM and your device resumes normal operation after disabling CHAP Authentication, this may indicate that your device was not properly configured to use your CHAP Authentication settings, causing Soracom to block the connection. For more information, refer to the CHAP Authentication documentation.
- Disable Virtual Private Gateway - If you have a Virtual Private Gateway (VPG) and have configured your SIM to connect using the VPG, and your device resumes normal operation after disabling the VPG, this may indicate that your VPG has a configuration or routing issue which prevents your device from successfully communicating with servers or cloud endpoints.
Soracom Status Dashboard
In some cases, a connectivity issue may be related to a temporary service issue, such as network maintenance by the local network operator or Soracom platform. In these situations, normal connectivity should be resumed once the issue has been addressed. You can refer to Soracom's Status Dashboard page for known service issues, as well as the local network operator's website for local outage reports.
Advanced Troubleshooting
If you are able to directly access your modem's serial interface, you can use AT commands to check the modem configuration and connection status.
While every modem will have a serial interface, not every device provides a way to access this interface. If you are unsure of whether or not your device allows you to access the modem's serial interface directly, please contact the device manufacturer for more information.
The process for connecting to a modem's serial interface is different for every device. In some cases you may be able to connect directly using a terminal application and, if necessary, an appropriate hardware serial interface adapter. In other cases, you may need to compile a program, prepare a debugging environment, or use custom wiring in order to enable or access the modem's serial interface. The manufacturer of your device can typically provide additional information.
No matter the process for connecting to your modem's serial interface, you will also need to have its AT command manual available. This is typically a PDF file, published by the manufacturer of the modem, and will correspond to the model number of the modem in your device.
While many AT commands are common across all modems, there may be slight variations in the syntax or response. Additionally, newer modems provide additional functionality through the use of extended or vendor-specific AT commands, which will vary from one modem to another.
Make sure to find the AT command manual that corresponds to your modem's manufacturer and model number. You may also want to verify that the AT command manual also corresponds to your modem's firmware version.
Below are the common steps for checking a modem's configuration and connection status.
Modem and SIM Status
Once you are connected to your modem's serial interface, the first step is to check that the modem is responsive:
-
Send command:
ATIThe modem should respond with some information about itself, followed by
OK.
Next, check that the modem is able to read the SIM:
-
Send command:
AT+CIMIor
AT+CCIDThe modem should respond with the IMSI or ICCID of the SIM, which should match the respective values of your Soracom SIM, followed by
OK.
Finally, make sure the modem is fully enabled:
-
Send command:
AT+CFUN=1The modem should respond with
OK.
In addition to the AT+CFUN=1 command to enable full modem functionality, some modems may have advanced features such as Power Saving Mode (PSM) which may automatically disable the modem at specific intervals in order to reduce power consumption. When troubleshooting, you may want to temporarily disable these features as they may interfere with your ability to interact with the modem.
Radio Technology and Frequency Band
Make sure that the radio technology you are trying to use (such as 2G, 3G, 4G/LTE, or LTE-M) is enabled. This is especially true for Cat-M1/NB-IoT modems, where one of the radio technologies may be disabled by default, depending on what radio technologies are typically available in your region.
Similarly, you may want to check if the corresponding frequency bands used by the local network operator are also enabled in the modem.
The AT commands for enabling radio technologies and frequency bands are typically different for each modem manufacturer and model. Refer to your AT command manual for specific instructions.
Operator Selection
Next is to select a local network operator that the modem will connect to. Typically, this is done by first performing a network search:
-
Send command:
AT+COPS=?The modem will perform a network search. The duration of the search will depend on many factors (such as how many radio technologies and frequency bands are enabled), but will typically take 2-3 minutes. Once complete, the modem will respond with a list of network operators it was able to find, followed by
OK.
Once the network search has finished, most modems will automatically select one of the available networks. You can check which network operator the modem has selected:
-
Send command:
AT+COPS?The modem will respond with
+COPS:and some details of the network operator it has selected, such as the name of the network operator and connection type, followed byOK.
If the modem was able to find one or more available network operators but did not automatically select one, or if you prefer to override the automatic selection in order to connect to a different network operator, you can manually select a network operator instead:
-
Send command:
AT+COPS=1,2,"<PLMN>"where
<PLMN>is a 5- or 6-digit code that corresponds to a particular network operator (for example:AT+COPS=1,2,"310410"to manually select the AT&T network in the United States).The modem should respond with
OK.
You will want to verify that the manual network operator selection was effective by using the AT+COPS? command described above.
If you manually selected a network operator but want to revert to automatic selection, you can do so using AT+COPS=0.
Your AT command manual will have more information on how to read the list of available network operators response from the modem, as well as additional options for manually selecting a network operator.
For more information on what network operators you can use with your Soracom SIM, refer to the Supported Carriers documentation.
Network Registration
Once a network operator has been selected (either automatically by the modem or manually by custom input), the modem should attempt to register to the network. To confirm that the modem is registered to the selected network operator:
-
Send command:
AT+CREG?When using a plan01s SIM, or a planP1, planX1, planX2, planX3, plan-US-max, or plan-US-NA Subscription Container, the modem should respond with
+CREG: 0,5where the5indicates that the modem is registered to the network in a roaming status, followed byOK.When using a plan-US, plan-D, plan-DU, plan-K, or plan-KM1 SIM, the modem should respond with
+CREG: 0,1where the1indicates that the modem is registered to its home network, followed byOK.
At this stage, if your SIM status is Ready or Standby, Soracom will automatically activate or reactivate your SIM and change its status to Active. You should be able to see this change in the User Console.
Signal Quality
Although a modem may be registered to a network, the signal quality may affect its ability to reliably send or receive data. To check the signal quality:
-
Send command:
AT+CSQThe modem will respond with
+CSQ:, followed by a pair of numbers indicating the signal quality, followed byOK.
Refer to your modem's AT command manual for more information on what values are acceptable.
Newer modems also provide additional AT commands for checking additional signal strength values.
If the signal quality appears to be too low, try reorienting your modem's antenna or moving your device to a new location, and repeating the command, until you have found a suitable location that provides good signal quality.
PDP Context Configuration
With the modem successfully registered to a network operator and within an area with good signal quality, the next step is to establish a data connection. This is done by configuring a Packet Data Protocol (PDP) Context, where you specify Soracom's Access Point Name (APN):
-
Send command:
AT+CGDCONT=1,"IP","soracom.io"This command will save the APN information and connection type (IPv4) into PDP Context profile
1. The modem will respond withOK.Some modems will not allow you to modify the PDP Context while the modem functionality is enabled. If you encounter an error, you can temporarily disable the modem functionality using
AT+CFUN=0, then setting the PDP Context, and then re-enabling modem functionality usingAT+CFUN=1.
Then to check that your PDP Context configuration is stored correctly:
-
Send command:
AT+CGDCONT?The modem will respond with
+CGDCONT:, followed by a list of PDP Contexts stored in the modem, followed byOK.
Some modems may have additional AT commands for configuring username and password authentication. As Soracom verifies cellular connectivity based on SIM authentication, there is generally no need to manually configure additional authentication settings. However, if your modem's AT command manual recommends configuring username and password authentication, you can use the following parameters:
- Username -
sora - Password -
sora - Authentication Type -
PAP,CHAP, orAutomatic
PDP Context Activation
Next, the modem will check which PDP Context it should use in order to establish a data connection. This can be controlled by activating (or deactivating) a PDP Context, using its PDP Context profile number.
When creating a PDP Context, most modems will automatically activate the PDP Context at the same time. To check that the PDP Context is activated:
-
Send command:
AT+CGACT?The modem should respond with
+CGACT:, followed by a list of PDP Contexts and their activation status, followed byOK. For example, if the modem responds with+CGACT: 1,1, this indicates that PDP Context profile1is currently activated1.
If the PDP Context containing the Soracom APN is not activated, you can activate it using:
-
Send command:
AT+CGACT=1,1where the first
1indicates that you want to activate a PDP Context profile, and the second1indicates which PDP Context profile you want to activate.The modem should respond with
OK.
Once you have activated a PDP Context profile, you can repeat the AT+CGACT? command to check the activation status.
Packet Domain Attachment
Finally, with a PDP Context configured and activated, the modem is now ready to create a data session. This is done by attaching to the network operator's packet domain service.
Similar to PDP Context activation, most modems will automatically attach to the packet domain at the same time. To check that the modem has attached:
-
Send command:
AT+CGATT?The modem will respond with
1if it is attached, and0if it is not attached, followed byOK.
If the modem is not attached to the network operator's packet domain, you can attach it using:
-
Send command:
AT+CGATT=1The modem should respond with
OK.
Once the modem has attached to the packet domain, you can repeat the AT+CGATT? command to check the attach status.
At this point, your SIM should appear as Online in the User Console.
Additional Commands
You can also perform some additional AT commands to further confirm that your modem has successfully connected to a network and established a data connection.
If your device supports 2G or 3G connectivity:
-
Send command:
AT+CGREG?This command will check the 2G (GPRS) or 3G (UMTS) network registration status of your modem. Similar to the
AT+CREG?command above, the modem will respond with+CGREG: 0,5when registered and roaming, or+CGREG: 0,1when registered to the home network, followed byOK, depending on which SIM you are using.If you are using an LTE modem which also supports 3G or 2G fallback, the modem and local network operator will typically configure this network registration even if the modem only connects using LTE.
If your device supports LTE connectivity (including LTE-M):
-
Send command:
AT+CEREG?This command will check the 4G/LTE network registration status of your modem. Similar to the
AT+CREG?command above, the modem will respond with+CGREG: 0,5when registered and roaming, or+CGREG: 0,1when registered to the home network, followed byOK, depending on which SIM you are using.
Last, you can also verify that your modem has received an IP address from Soracom, indicating that IP connectivity was successfully set up:
-
Send command:
AT+CGPADDRThe modem should respond with
+CGPADDR:followed by the IP address assigned to your modem by Soracom, followed byOK. You can verify this IP address from the User Console.Some modems may use the command
AT+CGPADDR?instead. Check with your AT command manual for the correct syntax for your modem.