While troubleshooting a cellular connectivity issue might seem intimidating at first, the Particle Platform empowers users like you with a number of tools to help you get (and stay) connected. This guide will walk you through three of these tools: Device Vitals (an easy-to-access readout of connectivity metrics), SIM Management, and Cloud Debug (a powerful firmware application that prints out relevant connectivity data directly from your device). Let's get started!
It should be explicitly stated that this guide is relevant to cellular Particle devices that are blinking green. If your device is presenting some other LED state, please return to our Support Portal (link) and select the appropriate resource.
First things first, let's tackle the three easiest things you can do to rule out a cellular issue:
- Place your device in Safe Mode by pressing RESET and MODE simultaneously, releasing RESET, and releasing MODE once the status LED blinks magenta. Give the device ample opportunity to connect.
- Ensure your antenna's U.FL connector is firmly attached. If possible, try with another antenna.
- If you have a 2G/3G device, ensure your device's LiPo battery is attached.
The Particle Console provides you with current and historical Device Vitals that are helpful in debugging cellular connections.
To see Device Vitals, head to: https://console.particle.io/devices, and click on the device you are interested in. These values will not appear if the device has never connected in the past - if this is the case, please skip ahead to "Sim Management" below.
On the right-hand side you will see “Last Vitals”, and you can press the reset button to request the latest numbers from the device. (You can also do so by selecting "Run health check" on the bottom of the panel).
You will see the following:
- Cellular Signal, with the Operator, access technology (2G/3G/LTE depending on your device) and the Cell Global Identity number (the number used to identify the tower your device is connected to).
This is useful to ensure your device is connecting to the expected technology given acceptable local signal. Please note that for LTE RSSI is not a complete indicator of signal quality.
- Round trip time - basically a cellular ping time. Longer times here indicate a less than optimal signal.
- Amount of RAM used and total available.
High RAM usage can lead to device lock-up.
- Battery charge level.
- Number of recent disconnects from the Particle Cloud.
Frequent disconnects can point to issues with signal quality (Low RSSI/Quality values will correlate) and/or local interference.
- Number of rate-limited publish attempts.
If you see anything other than 0 here, you are attempting to publish to the cloud more than once a second. Implement code changes to avoid missing critical messages.
You can download a CSV file with your vitals history to dig into more details. In order to do so, click "Download History" on the underside of the Vitals panel.
This is a very information-dense document, but the key things to look out for are:
This value corresponds to signal “Strength”, with desirable values higher than -85dBm, with a steady decrease in stability as you approach -120dBm.
This value corresponds to signal “Quality”, lower values indicate the device has trouble talking to the tower (eg. potentially due to interference).
Seeing -1200 here indicates the response from the modem was not received in a timely manner and would indicate a bad signal. Please note that on DeviceOS 1.5.0, this key returns -1200 regardless of signal strength: a regression that will be fixed in DeviceOS 1.5.1.
Common errors here include 1 (ping timeout) and 17 (error establishing a session), both commonly associated with signal issues. See below for more information about error codes!
Useful to determine what is powering your device (VIN, battery, etc…). It’s worth explicitly stating that 2G/3G devices have specific current requirements (link) in order to connect.
Is your battery charging or not?
The amount of charge in your battery (percentage).
If your cellular device has trouble getting online, make a note of its ICCID (the identifier for your SIM Card). If this device has come online in the past and is visible in the Console, merely click on the Device in question to check the ICCID number. If the device has never come online, you can find this information by either checking the packaging for your Particle SIM and/or (especially in the case of embedded SIM devices), following the instructions here to ask the device to reveal this number for you.
Once you have your ICCID, be sure to check https://console.particle.io/sims to ensure the SIM is Active. If the SIM does not appear in https://console.particle.io/sims (or in the respective SIM Management page for a given Product), please activate your SIM by following the steps at https://setup.particle.io. If the SIM does appear in https://console.particle.io/sims but is marked as “Deactivated”, please Activate the SIM by pressing the “…” marking on the right-hand side of the SIM Management page. Should you have any issues with SIM Activation, please visit our Article on “Troubleshooting SIM Activation/Deactivations.”
If all of the above are correct, and your device is blinking green, Cloud Debug is the next step.
What is Cloud debug?
Cloud debug is a precompiled firmware binary that communicates with the modem and spits out the information over serial.
These logs are helpful in determining what the modem is sending to and hearing back from the tower.
This is a tool to debug cloud connection issues. It:
- Prints out cellular parameters (ICCID, etc.)
- Prints out your cellular carrier and frequency band information
- Pings your IP gateway
- Pings the Google DNS (188.8.131.52)
- Does a DNS server lookup of the device server (device.spark.io)
- Makes an actual cloud connection
- Acts like Tinker after connecting
- Can print out information about nearby cellular towers
You can download Cloud-debug here:
For the Electron: https://github.com/rickkas7/electron-clouddebug
For the Boron: https://github.com/rickkas7/boron-clouddebug
Gathering Debug Logs
The best way to produce these logs is with
particle serial monitor --follow in CLI. We recommend resetting the device after running this command so that you are able to source logs from the device from the very beginning of the application.
Once the device is connected to an active serial monitor, you will encounter the following menu:
- a - enter APN for 3rd-party SIM card
- k - set keep-alive value
- c - show carriers at this location
- t - run normal tests (occurs automatically after 10 seconds)
- or tap the MODE button once to show carriers
Unless explicitly asked by a support engineer, it's probably best to let the device run its normal tests. The carrier scan functionality (`c`) is another very useful function - it will print out what towers are available in your area along with their respective signal strength metrics.
Interpreting Cloud Debug
Once you have the logs, scan through it and look out for the following responses to the CREG AT command:
2,3 indicates your SIM card is being rejected by the local tower. Please ensure that your SIM card is active! If your SIM card is indeed active, this error could occur for various infrastructural reasons; it might resolve itself if you have a day or two to wait.
If not, please submit a ticket at https://particle.io/support so we can check with our MVNO what is going on.
2,2 indicates no compatible carrier is available on the local tower for the SIM card.
2,0 indicates a lack of available local towers.
Indicates a successful connection to the tower.
Once you have these logs in hand, reach out to our support team (https://particle.io/support) with about 10 minutes or so of those logs!
Uninstalling Cloud Debug
Put your device in DFU mode (blinking yellow) by pressing RESET and SETUP. Release RESET and continue to hold down SETUP while the LED blinks magenta until it blinks yellow, then release SETUP. Then run the following command in the CLI:
particle flash --usb tinker
Submitting a Ticket
In order to provide our Support Team the opportunity to address your request with optimal efficiency, please supplement any and all cellular connectivity tickets with the following information (to the extent possible):
- Confirmation that the antenna and (if using a 2G/3G device) LiPo battery connections satisfy a visual inspection.
- An attached Device Vitals History .pdf, downloadable in the Console per the instructions above (link). (Please note that this resource will not appear if the device has never connected in the past).
- Confirmation that the SIM associated with this device is indeed active within the Console. If you are using a 3rd Party SIM, please specify that you are doing so, taking care to note that we cannot help troubleshoot cellular connectivity for 3rd Party configurations.
- At least ten minutes of Cloud Debug logs documenting the connectivity incident. If possible, please further supplement these logs with a carrier scan, accomplished by resetting the device and using the `c` command to request a carrier scan (note: carrier scans not supported on LTE devices, so just Cloud Debug logs will suffice in this instance).
- The location of the device in question (e.g. GPS coordinates).
- A brief connectivity history, if possible including timestamps.