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: unused (empty)

Response:

• Topic: base/{SN}/info
• Payload: JSON info object (same as HTTP /get-info)

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

Generic Command¶

Request: - Topic: base/{SN}/cmd - Payload: JSON or system command string

See command formats below.

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:

GNSS System Identifiers:

• 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:

UDP Keep-Alive¶

Port: 5003 (configurable)

Type: UDP Datagram

Format: name;payload

• 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:

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.

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¶

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