MQTT API Reference¶
The RTK Base uses MQTT for real-time communication, configuration, and data streaming.
Connection Details¶
- Broker:
mqtt.yamabikorobots.net(production) - Port:
8883(MQTT over TLS) - Client ID:
<serial_number> - Authentication: TLS client certificates
Topic Structure¶
All topics use the format: base/<SN>/<action>
Where <SN> is the RTK Base serial number (e.g., BRRB000021)
DRTK Publication¶
base/{SN}/drtk¶
Type: Publish
Raw RTCM data stream. Published as soon as RTCM data is available from the ZED module.
Behavior:
- Payload is raw bytes (binary RTCM data)
- Published continuously when operational
- If
transfer/mqtt/rtcm/optimizationis enabled, requires keep-alive messages
Keep-Alive Mechanism:
When optimization is enabled, robots must publish to base/keepAlive/<NAME>/<SN> periodically to maintain the RTCM stream.
REST-like API over MQTT¶
The RTK Base emulates its REST API over MQTT for environments where HTTP is not available.
Info Request¶
Request:
- Topic:
base/{SN}/info/get - Payload: optional;
;- or,-separatedkey=valueoptions:- (empty) — plain JSON response
gzip— gzip-compress the response (zlib default level)gzip=<level>— gzip-compress at zlib level0–9(0= no compression)
Response:
- Topic:
base/{SN}/info - Payload: JSON info object (same as HTTP
/get-info), or a raw gzip stream whengzipwas requested - QoS: 0 (best effort, not retained)
A gzip-compressed response starts with the magic bytes 1f 8b, which is how a
subscriber can tell it apart from the plain JSON payload.
Examples:
| Request payload | Response payload |
|---|---|
| (empty) | plain JSON |
gzip |
gzip stream, default compression |
gzip=9 |
gzip stream, maximum compression |
gzip=0 |
plain JSON (level 0 = no compression) |
See Automatic Publication of Status and Config for the full trigger model, payload schema, bitmask flags, and failure-mode semantics.
Change Configuration¶
Request:
- Topic: base/{SN}/change/post
- Payload: JSON configuration object
Response:
- Topic:
base/{SN}/change/resp - Payload: Response JSON with result and leftover fields
See REST API for available configuration fields.
System Commands¶
Request:
- Topic: base/{SN}/system/post
- Payload: Parameter string (the part after ? in HTTP URI)
Response:
- Topic:
base/{SN}/notice - Payload: Text output from command
The payload is exactly the query string that would follow ? on the HTTP
endpoint, so parameterised commands are sent verbatim, for example
router-rms=1,rms.example.com,1883,30 to configure the router's RMS
connection (see Router RMS Configuration).
Generic Command¶
Request:
- Topic: base/{SN}/cmd
- Payload: JSON or system command string
See command formats below.
Router RPC¶
Send a raw RPC (ubus) call directly to the Teltonika RUT router. This mirrors
the HTTP POST /rut endpoint: the base forwards the
call to the router's ubus HTTP endpoint and authenticates automatically using
the stored router credentials.
Request:
- Topic:
base/{SN}/rut/post - Payload: the RPC call arguments, as they would appear in the JSON-RPC
paramsarray after the session id — a comma-separated list of the quoted object name, the quoted method name, and a JSON arguments object:
Response:
- Topic:
base/{SN}/rut/return - Payload: numeric return code (
0on success, non-zero on error) -
QoS: 1, not retained
-
Topic:
base/{SN}/rut/resp - Payload: raw JSON-RPC response returned by the router (empty on failure)
- QoS: 1, not retained
Examples:
# Read system information from the router
aws_pub -t "base/BRRB000021/rut/post" -m "'system', 'info', {}"
# Return code on: base/BRRB000021/rut/return
# Response JSON on: base/BRRB000021/rut/resp
The higher-level system commands (including router-rms=...) can also be
issued over MQTT via base/{SN}/system/post; see the
REST API for the available commands.
Debug Logs¶
Log Retrieval¶
Request:
- Topic: debug/log/get
- Payload: unused
Response:
- Topic:
debug/log/lines/{IDX} - Payload: One log line per message
- QoS: 1 (at least once delivery)
- Index:
{IDX}is the line index
Value Storage (NVS)¶
Get Value¶
Request:
- Topic: base/{SN}/val/get
- Payload: ID (value identifier)
Response:
- Topic:
base/{SN}/val - Payload:
ID HEXVALUE
Set Value¶
Request:
- Topic:
base/{SN}/val/set - Payload:
ID HEXVALUE
Response:
- Topic:
base/{SN}/val/ack - Payload: Acknowledgment
Delete Value¶
Request:
- Topic:
base/{SN}/val/del - Payload:
ID
Response:
- Topic:
base/{SN}/val/ack - Payload: Acknowledgment
UBX Protocol¶
UBX Forwarding¶
Request:
- Topic: base/{SN}/ubx/post
- Payload: Binary UBX packet or hex string
Behavior: - Upon receiving this command, the RTK Base forwards all UBX packets to MQTT for 30 seconds - Forwarding format follows the format of the last received packet (binary or hex)
Response:
- Topic:
base/{SN}/ubx - Payload: UBX packets
Spectrum Analyzer¶
Get Spectrum Data¶
Request:
- Topic: base/{SN}/span/get
- Payload: unused
Response:
- Topic:
base/{SN}/span - Payload: JSON spectrum data
Example Response:
{
"bands": [
{
"center": 1583461250,
"span": 128000000,
"res": 500000,
"pga": 57,
"buck": [67, 68, 67, 66, ...]
},
{
"center": 1224006250,
"span": 128000000,
"res": 500000,
"pga": 57,
"buck": [67, 69, 69, 70, ...]
}
]
}
Satellite Information¶
Get Satellite Data¶
Request:
- Topic: base/{SN}/sat/get
- Payload: unused
Response:
- Topic: base/{SN}/sat
- Payload: JSON array of satellite objects
Example Response:
[
{
"gnss": "gps",
"svid": 5,
"pr": 2,
"q": 7,
"cno": 43,
"elev": 48,
"azim": 212,
"flags": ["used", "healthy", "diffcorr"],
"orbit": "ano",
"corr": ["sbas", "pr", "doppler"]
},
{
"gnss": "gal",
"svid": 24,
"pr": 3,
"q": 7,
"cno": 38,
"elev": 27,
"azim": 46,
"flags": ["used", "healthy"],
"orbit": "ano",
"corr": []
}
]
Fields:
gnss: GNSS system (gps, glonass, gal, bds, sbas, navic)svid: Space Vehicle IDpr: Pseudorangeq: Quality indicatorcno: Carrier-to-Noise ratio (dB-Hz)elev: Elevation angle (degrees)azim: Azimuth angle (degrees)flags: Status flags (used, healthy, diffcorr)orbit: Orbit source (ano, eph, alm)corr: Applied corrections
Fast SVIN Query¶
Request RTCM Source¶
See Fast SVIN technical documentation.
Query:
- Topic:
base/{SN}/query/rtcm/req - Payload:
lat=LAT,lon=LON
Response:
- Topic:
base/{SN}/query/rtcm/resp - Payload:
topic=RTCM_TOPIC,keepalive=KA_TOPIC,dist=DISTANCE,prio=PRIO
Production Mode¶
Note: These interfaces are only available when the RTK Base is in production test mode.
UI Display¶
Topics:
production/base/{SN}/UI/USER-TITLE: Display title (string)production/base/{SN}/UI/USER-TEXT: Display text (string)production/base/{SN}/UI/INTERACT: Interaction command
Interaction Types:
- Button:
OK,CANCEL,PASS - Text Input:
TEXT;name(name = default text) - List:
LIST;a;b;c;d;e
Test Report¶
Topic: production/base/{SN}/UI/test-report
Payload: JSON test results
UI Interaction Response¶
Topic: production/base/{SN}/UI/INTERACT/resp
Payload: User response (button name, list item, or text input)
Device Command¶
Topic: production/base/{HW_ID}/cmd
Commands:
whereAreYou: Start 10-second Christmas blinking animation (for locating device)- Any other payload: Treated as standard command
Device Ready¶
Topic: production/base/{SN}/ready
Payload: 1 (published when base is ready for production test)
Who Is Alive¶
Topic: production/whoIsAlive
Response: production/base/{SN}/ready with payload 1
Keep-Alive¶
Keep-alive messages are used to maintain RTCM data streams. The base supports keep-alive over both MQTT and UDP, using the same payload format.
MQTT Keep-Alive¶
Topic: base/keepAlive/{NAME}/{SN}
Type: Subscribe (base listens)
Parameters:
{NAME}: Identifier of the robot or entity requesting data{SN}: RTK Base serial number
Payload:
- Format: Semicolon-separated
key=valuepairs (optional) - Supported Keys:
| Key | Value | Description |
|---|---|---|
rtcm-interval |
Integer | Requested RTCM message interval (seconds) |
msm |
Integer | Requested MSM (Multiple Signal Messages) type |
gnss |
Comma-separated list | Requested GNSS systems (see table below) |
GNSS System Identifiers:
| ID | System | Description |
|---|---|---|
gp |
GPS | Global Positioning System (USA) |
gl |
GLONASS | Russian GNSS system |
ga |
Galileo | European GNSS system |
bd |
BeiDou | Chinese GNSS system (BDS) |
- Examples:
- Empty payload:
"" - RTCM interval:
"rtcm-interval=1" - MSM and GNSS:
"msm=7;gnss=gp,gl,ga" - Full config:
"rtcm-interval=1;msm=7;gnss=gp,gl,ga,bd"
Behavior:
| Parameter | Value | Description |
|---|---|---|
| Interval | 20 seconds | Recommended publish frequency |
| Timeout | 5 minutes | RTCM stream stops if no keep-alive received |
| QoS | 0 | Fire and forget delivery |
| Retain | 0 | Do not retain messages |
UDP Keep-Alive¶
Port: 5003 (configurable)
Type: UDP Datagram
Format: name;payload
| Field | Description |
|---|---|
name |
Robot identifier (optional, use "keepalive" for anonymous) |
payload |
Semicolon-separated key=value pairs (same as MQTT) |
- Examples:
- Anonymous:
"keepalive" - Named robot:
"robot1" - With config:
"robot1;rtcm-interval=1" - Full config:
"robot1;rtcm-interval=1;msm=7;gnss=gp,gl,ga,bd"
Behavior:
| Parameter | Value | Description |
|---|---|---|
| Interval | 30 seconds | Recommended send frequency |
| Timeout | 5 minutes | RTCM stream stops if no keep-alive received |
Aggregation Behavior¶
When multiple robots send keep-alives with different settings:
- Interval: Minimum of all requested intervals is used
- MSM: Maximum of all requested MSM types is used
- GNSS: Union (OR) of all requested GNSS systems is used
Robots must publish periodically to maintain the RTCM stream. Prevents unnecessary bandwidth usage when no robots are actively listening.
MSM Filtering¶
The RTCM stream carries MSM (Multiple Signal Message) frames of several
types, for example MSM4 (1074, 1084, ...) and MSM7 (1077, 1087, ...).
For each output transport the base forwards only the MSM type that its
subscribers selected:
- A keep-alive without an
msmkey is treated as requesting MSM7, the default. - When no subscriber requests a specific MSM type, the transport also falls back to MSM7. Only MSM7 frames are forwarded and MSM4 frames are dropped.
- Over UDP the MSM type is fixed to MSM7 unless variable MSM over UDP
(
udp-var-msm) is enabled, in which case the UDP MSM type follows the keep-alive requests just like MQTT.
This keeps the MSM type consistent while subscribers come and go, and avoids mixing MSM4 and MSM7 frames in the same stream.
JSON Command Format¶
Firmware Update¶
{
"cmd_type": "updateBase",
"cmd_param": {
"url": "http://myStaticFileServer.com/RTK_BASE_4.0.2.bin"
}
}
ZED Configuration Update¶
{
"cmd_type": "updateZedConfig",
"cmd_param": {
"url": "http://myStaticFileServer.com/Zed_Config_file_1.3.txt"
}
}
QoS Levels¶
| Topic Pattern | QoS | Description |
|---|---|---|
base/{SN}/drtk |
0 | RTCM data (best effort) |
base/{SN}/info |
0 | Info responses (best effort, not retained) |
base/{SN}/online |
0 | Online status & last will (always retained; see Automatic Publication) |
base/{SN}/rut/return, base/{SN}/rut/resp |
1 | Router RPC responses (not retained) |
debug/log/lines/{IDX} |
1 | Log lines |
production/base/{SN}/ready |
1 | Production status |
Security¶
- All production MQTT traffic uses TLS encryption
- Client certificates are used for authentication
- Certificate lifecycle managed automatically
- Production test mode uses separate topic namespace