Skip to main content

NB-IoT Troubleshooting

Most of the difficulty in getting an NB-IoT device reporting is between the device and the mobile network, before Yggio is involved at all. That is cold comfort when a device will not connect, so this page covers the whole chain, in the order faults actually occur.

The single most useful habit: change one setting at a time, and confirm the effect before changing the next. Configuration problems here compound, and a device with three speculative changes applied is much harder to reason about than one.

For the procedure itself, see Connecting NB-IoT Devices.

Two things to keep in mind while reading. Everything about the SIM, the console and attaching to the mobile network applies to any NB-IoT device, whatever protocol it eventually speaks. Everything about topics and credentials assumes MQTT, which is the worked example here; a device reporting over CoAP or HTTP addresses and authenticates itself differently.

Work out which half the fault is in​

Before anything else, establish whether the device has reached the mobile network. Most modules report signal strength continuously on the console, with one particular value meaning "searching, not attached". Find that value in your device's manual, because it differs between manufacturers, and then:

  • If the reading never leaves that value, the fault is between the device and the operator. Continue with attaching to the network.
  • If it shows anything else, the device is on the network and the fault is further along. Continue with reaching Yggio.

Your SIM provider's portal answers the same question from the other end, and does it without you being on site: it shows whether the SIM has attached and how much data it has sent.

Between them, these two checks save more time than anything else on this page.

On a Dragino D20S-NB or D23-NB, the value is 99. See device-specific behaviour for the rest of what we have confirmed on particular hardware.

The device never attaches​

Check the SIM provider's portal first​

Before changing anything on the device, look at the SIM in your provider's web portal. It tells you, independently of the device, whether the SIM is activated, whether it has attached to a network, which network it attached to, and how much data it has sent.

That answers several questions at once:

  • No activation means nothing on the device will help until the subscription is sorted out.
  • Activated but never attached points at the SIM type, the APN, or coverage where the device sits.
  • Attached, with data counted, means the device is on the network and reporting. The fault is further along, so continue with reaching Yggio.
  • Attached but with no data means it reached the network and then failed to publish, which is a configuration problem rather than a network one.

The data counter is also the quickest way to confirm a device is still alive after you leave site.

Is it the right kind of SIM?​

An NB-IoT device needs an NB-IoT SIM. A normal mobile broadband SIM will not attach, and the symptom is indistinguishable from every other attach failure. Confirm with the supplier rather than assuming, especially if the SIM came from a general-purpose subscription.

Is the APN right?​

The APN is the access point the SIM connects through, and it is specific to the SIM supplier, not to the device. Get it from whoever supplied the SIM. On many networks setting it correctly is all that is needed.

Is the modem searching too widely?​

Left alone, a modem scans every band and every operator it can, which is slow and sometimes fails outright where coverage is marginal. Constraining the search often turns a device that never attaches into one that attaches in a minute.

  • Restrict it to the bands your operator actually uses locally. In Europe, bands 8 and 20 are the common NB-IoT bands.
  • Increase the time the modem is allowed to keep trying before giving up. The default is often optimistic for a device sitting in a basement or a cabinet.
  • Select the operator explicitly by network code rather than letting the modem choose. On a roaming SIM this matters, because the modem may otherwise keep retrying a network with poor local coverage.

Your operator publishes its network code, and the SIM supplier can tell you which networks the SIM is entitled to roam onto.

Is it a coverage problem rather than a configuration problem?​

If the settings are right and it still will not attach, move the device. A metre or two, or temporarily outdoors, is enough to tell you whether you are debugging configuration or physics. NB-IoT penetrates buildings well but not infinitely, and a cabinet, a basement or a metal enclosure all cost signal.

The device attaches but nothing arrives in Yggio​

At this point the device is on the network, so the question is whether it is publishing at all, and if so whether it is publishing where you think.

Prove the device can publish, independently of Yggio​

This is the most valuable technique on this page, and it separates two problems that otherwise look identical. It is written for a device reporting over MQTT; the equivalent for another protocol is any endpoint you control and can watch.

Point the device temporarily at a public test MQTT broker, then subscribe to the same topic from your computer with a tool such as MQTT Explorer. You will see each message land, the moment it lands.

A test broker needs no credentials and nothing on the Yggio side. If messages appear there, the device and its payload are fine and the fault is in the Yggio configuration. If they do not, the fault is still on the device.

Keep the topics exactly as they are for Yggio. They work unchanged on a public broker, and leaving them alone means the only thing you change is the server address, so the test proves what you think it proves and switching back is one command.

Make sure the device is set to MQTT with a JSON payload first, and restart it so the protocol setting takes effect.

On a Dragino D20S-NB or D23-NB the whole diversion is four commands:

AT+PRO=3,5
ATZ
AT+SERVADDR=<public test broker>,1883

Subscribe to yggio/generic/v2/<your device id> from MQTT Explorer and watch. Restore the Yggio server address with AT+SERVADDR when you are done.

Do not send anything confidential to a public broker. Anyone can subscribe to it.

Does the publish topic match the reserved topic exactly?​

A mismatch fails silently. The device reports a successful publish, and Yggio never sees it, because it is publishing to a topic nobody reserved. Compare the two character by character rather than reading them; this is the single most common cause once the device is on the network.

Do the credentials match the credential set?​

The username and password on the device must be the ones on the credential set, and the client identifier is normally the credential set's _id. Getting the username right but the identifier wrong produces a login failure that is easy to misread as a network problem.

Is the reserved topic linked to the credential set?​

Creating both but not linking them leaves a topic nobody can publish to. Check that the reserved topic carries the credential set's id in basicCredentialsSetId.

The device stops responding after configuration​

Some devices require a subscribe topic to be set even when nothing is ever sent back to them, and will stop responding if it is empty or if it duplicates the publish topic exactly. The manufacturer's convention is often the publish topic with a suffix appended.

If a device becomes unresponsive immediately after the topics were set, this is the first thing to check. Recovering usually means a power cycle and re-entering the console. On a Dragino D20S-NB or D23-NB the required form is the publish topic with /subtopic appended.

Data arrives but does not look right​

The payload contains arrays​

Yggio expects a flat JSON object. Devices that wrap readings in arrays need their log or payload format changed, which is usually a separate setting from the protocol and easy to overlook. The symptom is a device that appears in Yggio with fewer fields than expected, or none.

Values are impossible​

Many sensors report a fixed out-of-range number when a probe is missing or disconnected, rather than omitting the field. Left alone, these values flow into charts, averages and alarms as though they were real. On a Dragino D20S-NB or D23-NB the value is -409.5, which is below absolute zero and therefore a sentinel rather than a reading.

Handle them in a translator: validate against a plausible range, and where the value fails, leave the field unset and record a status instead. A range check also catches readings that are numerically fine but physically implausible, which is what you get when a sensor is moved, tampered with, or left in the sun.

Field names are not what Yggio expects​

Manufacturers name their fields to suit themselves, and Yggio recognizes its own names. A device with several inputs may number them rather than using the name Yggio looks for. Copy the one actually in use to the expected field in a translator, and it behaves like any other device in previews, views and charts. On a Dragino D20S-NB or D23-NB the three inputs are temperature1, temperature2 and temperature3, none of which Yggio reads as a temperature.

Security questions​

Is my data encrypted?​

Only if you configured it to be. Port 1883 is clear text. Yggio also accepts TLS, but installing a certificate on a constrained device is significantly more work than the rest of the setup, and support varies by model.

Treat this as a decision rather than a default. For an open environmental measurement it may be an acceptable trade. For anything personal, commercial or operationally sensitive it is not, and the device should be chosen partly on how well it handles certificates.

What is the risk of a weak device password?​

The credential set password lives on the device and, on port 1883, crosses the network in clear text. Use a distinct credential set per site or per device group rather than one shared everywhere, so that a compromise is contained.

Device-specific behaviour​

Everything above is written to apply to NB-IoT devices generally. The details below are from one widely used NB-IoT device, included as a worked example of the kind of thing to look for. Other manufacturers do the same things differently, so check these against your own manual rather than copying the values.

  • Dragino D20S-NB and D23-NB
    • Console signal strength 99 means the modem has not attached. Any other value means it has.
    • The subscribe topic must be the publish topic with /subtopic appended. Leaving it empty, or setting it equal to the publish topic, makes the device stop responding.
    • An input with no probe connected reports -409.5, a sentinel rather than a reading.
    • The three inputs are named temperature1, temperature2 and temperature3.
    • The payload format must be set to flat JSON separately from the protocol, and the device needs a restart before a protocol change takes effect.
    • The console is reached over Bluetooth using the manufacturer's app, with a PIN printed on the packaging. The device advertises under its IMEI.

The AT commands for this sequence are listed in Connecting NB-IoT Devices, and the manufacturer documents the full command set in the Dragino NB-IoT configuration wiki.

Practical notes​

It takes longer the first time​

Expect the first device to take a working session, and the rest to take minutes. Almost all of the difficulty is discovering the right APN, band and operator settings for your SIM and location, and those are the same for every subsequent device on the same network.

Configure devices from a file where you can​

Most devices that accept AT commands can also load a saved configuration, so a fleet does not have to be typed in one command at a time. Once the first device works, capture its configuration and reuse it, changing only the topic and credentials.

Choose the reporting interval deliberately​

Defaults are often every two hours. Reporting more often costs battery disproportionately, since the radio dominates consumption. Decide from how quickly the value actually needs to be acted on, not from what feels responsive.

Before contacting support​

There is one check that decides whether we can help you at all, and it takes a couple of minutes.

Connect MQTT Explorer to the Yggio MQTT broker, authenticate with the same credential set the device uses, and subscribe to your topic. Then trigger an upload from the device.

If the message does not appear there, the data never reached us. Nothing in Yggio can be misconfigured in a way that would explain it, because the message is not arriving at the broker in the first place. The fault is somewhere between the device and the broker, and this page is the faster route: the SIM provider's portal, the attach checks, the topic and the credentials.

If the message does appear there but no device shows up in Yggio, the chain is complete up to our side and something past the broker is wrong. That is ours to investigate, and it is the point at which a support request is worth raising. Contact Sensative support, and include the topic, the timestamp of a message you saw arrive, and what MQTT Explorer showed.

For faults before that point, the people who can resolve them fastest are the SIM supplier for the APN and roaming entitlements, the operator for local band and coverage, and the device manufacturer for the command set.