Skip to content

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/optimization is 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 ,-separated key=value options:
    • (empty) — plain JSON response
    • gzip — gzip-compress the response (zlib default level)
    • gzip=<level> — gzip-compress at zlib level 0–9 (0 = no compression)

Response:

  • Topic: base/{SN}/info
  • Payload: JSON info object (same as HTTP /get-info), or a raw gzip stream when gzip was 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 params array after the session id — a comma-separated list of the quoted object name, the quoted method name, and a JSON arguments object:
'<object>', '<method>', <arguments>

Response:

  • Topic: base/{SN}/rut/return
  • Payload: numeric return code (0 on 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 ID
  • pr: Pseudorange
  • q: Quality indicator
  • cno: 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=value pairs (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 msm key 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