MQTT streaming

The MQTT stream destination publishes survey records live to an MQTT broker as JSON messages. You save one or more brokers on the phone and pick the one to use; the survey streams to it whenever MQTT stream is on.

Open the MQTT stream page

Tap the MQTT stream row on the Survey tab, or go to More > MQTT stream.

The page has three parts:

• Brokers: the brokers saved on this phone, with the one in use selected.
• This phone: the client ID and the device status switch, which apply to every broker.
• What is sent: “Everything the survey records, except call records.”

In the second screenshot the broker’s host is localhost, which is only an example from a test setup. Yours is the address of your broker.

Brokers

You can save as many brokers as you like. One is selected, shown by the filled radio button. “The selected broker is used when the survey sends to MQTT. Switch any time.” Tap another broker to switch; if MQTT is streaming, it moves to the new broker.

If brokers are saved but none is selected (for example after you remove the selected one), the page says “Choose a broker to use.” and the MQTT stream row on the Survey tab says Choose a broker.

To edit a broker, tap the pencil next to it. The editor also has Remove this broker, which deletes its saved password from the phone. Removing the broker a survey is streaming to stops MQTT for that survey; other destinations keep going. If MQTT is the survey’s only destination, the survey stops too.

Add a broker

Tap Add a broker and fill in:

Field	Default	Notes
Name	The host	How the broker is listed on this phone
Host		The broker’s host name or address (required)
Port	8883	1 to 65535. Brokers commonly use 8883 for TLS and 1883 without it
Use TLS	On	Encrypts the connection. Turn it off only if the broker doesn’t use TLS
Username		If the broker needs a login
Password		When editing, leave it blank to keep the saved password

Under More options:

Field	Default	Notes
Topic prefix	Empty	Added in front of every topic. It can’t contain # or +. “Leave blank unless the broker expects the data under a different topic.”
Delivery guarantee (QoS)	At least once (1)	Also At most once (0) and Exactly once (2)

Tap Save and select. The new broker is saved and selected. If it is your first broker and no survey is running, MQTT is turned on for your next survey; streaming starts when you tap Start survey. Saving changes to the broker a survey is streaming to reconnects the stream without stopping the survey.

The username and password are stored encrypted on the phone.

Scan a QR code

Scan a QR code (“The fastest way; ask whoever runs the broker”) reads a broker from a QR code and saves it. If a saved broker has the same host, port and username, that broker is updated instead. Either way, it becomes the selected broker.

A broker QR code can set the host, port, TLS, username, password, topic prefix and QoS. If the code includes a client ID or a device status setting, those are applied to this phone. Per record type stream settings in a QR code are ignored: what MQTT streams always comes from the survey’s record types.

If you build a QR code yourself, encode JSON like this:

{
  "mqtt_host": "mqtt.example.com",
  "mqtt_port": 8883,
  "mqtt_tls": true,
  "mqtt_username": "auser",
  "mqtt_password": "apassword",
  "mqtt_topic_prefix": "my/custom/topic/path/",
  "mqtt_qos": 1,
  "device_status_stream_enabled": true
}

Add "mqtt_client": "a-unique-name" only if you make a separate code for each phone, since every phone needs its own client ID.

The scanner needs the camera. On a phone without a camera, the page explains that it can’t scan a code; add the broker by hand instead.

Share as QR code

To set up another phone with the same broker, open the broker’s editor and tap Share as QR code. The other phone scans it with Scan a QR code.

The code holds the host, port, TLS setting, username, password, topic prefix, QoS and this phone’s device status setting, plus per record type flags taken from your current setup for older app versions that still read them. It leaves out the client ID, so two phones set up from the same code don’t use the same one.

Caution

“This code includes the password. Show it only to people who should use this broker.” Don’t post it publicly.

This phone

• Client ID: how the broker tells this phone apart. It belongs to the phone, not to a broker, so every broker gets the same one. If none is set, the app makes one up (two words and a number, like BerlinDawn22). Tap it to change it. Give every phone a different client ID: when a second client connects with the same ID, the broker drops the first one.
• Send device status: “This phone’s location, battery and app version, sent regularly.” On by default. How often is set in scan rates.

What MQTT streams

Every record type the survey records, except Call records and an NS Scout’s Raw frames. Choose record types on the Survey tab; MQTT gets all of them. Device status is added when Send device status is on, and Wi-Fi watchlist events when More > Settings > Watchlist > Stream over MQTT is on (the default). See Wi-Fi watchlist.

MQTT topics

The topics are defined in the Network Survey Messaging API.

Messages	Topic	Message type
GSM	gsm_message	GsmRecord
CDMA	cdma_message	CdmaRecord
UMTS	umts_message	UmtsRecord
LTE	lte_message	LteRecord
NR (5G)	nr_message	NrRecord
Wi-Fi	80211_beacon_message	WifiBeaconRecord
Bluetooth	bluetooth_message	BluetoothRecord
GNSS	gnss_message	GnssRecord
Wi-Fi clients (NS Scout)	80211_client_message and 80211_probe_request_message	WifiClientRecord and WifiProbeRequestRecord
Device status and Phone state	device_status_message	DeviceStatus and PhoneState
Watchlist match	watchlist_match_message	WatchlistMatch
Watchlist entries	watchlist_entry_message	WatchlistEntryUpdate

Phone state messages share the device_status_message topic with device status; tell them apart by messageType.

Topic prefix

The topic prefix is put directly in front of each topic name. With the prefix surveys/device1/, LTE records go to surveys/device1/lte_message. End the prefix with / if you want a separate topic level.

Organization brokers

On a managed phone, your organization can provide the broker through MDM. It counts only when the configuration sets both the broker host and the client ID.

While the organization’s broker is in force:

• The Brokers section shows one row, Provided by your organization, with the host and Set by your organization. “Your organization provides this broker; it cannot be edited or removed.”
• Add a broker, Scan a QR code and the This phone section are hidden. Brokers you saved yourself are kept for when you use your own settings.
• If the organization removes its broker while a survey streams to it, MQTT disconnects. It does not switch to one of your own brokers.

Tap the organization’s broker to see why it is locked. From there, Use my own settings switches the phone to your own settings (Settings calls this Override organization settings). The organization’s broker is then saved as Copy of your organization’s broker and selected, so the stream keeps going. If the organization set the password, that copy can’t be shared as a QR code.

See MDM configuration for the MQTT keys.

Streams with no record types

From the Survey tab, a survey needs at least one record type. An MQTT stream that sends only device status (and watchlist events) can still run when it is set up outside the Survey tab: by your organization’s configuration, by the upgrade from 1.x for a phone that streamed only device status before, or by another app through the Intent API.

Troubleshooting

• Connection refused or can’t connect: check that the broker is running and reachable from the phone, and check the host, port and login.
• TLS errors: make sure Use TLS matches the broker; 8883 is the usual TLS port and 1883 the usual plain one.
• Sign-in failed: the broker refused the username or password. Edit the broker and enter them again.
• One phone keeps disconnecting another: two phones share a client ID. Change one under This phone > Client ID.
• No messages arrive: check that MQTT stream is on, that a survey is running, and that your subscriber uses the same topic prefix. Under Where it’s going on the Survey tab, the MQTT stream row shows whether it is live.
• Broker on your local network (Android 17 and later): allow access to devices on your local network when the app asks.

Related

• Data streaming overview: how streams combine with other destinations
• gRPC streaming: the other streaming destination
• Message formats: what each message contains
• Wi-Fi watchlist: watchlist events over MQTT