> For the complete documentation index, see [llms.txt](https://docs.rtkdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rtkdata.com/integration-hub/ntrip-clients-and-field-software/ros2-ntrip-client.md). # ROS 2 NTRIP Client Setup: RTK Corrections with ntrip\_client Set up the ROS 2 NTRIP client ntrip\_client (Humble, Jazzy) with RTKdata: port 2101, AUTO, GGA from your receiver on /nmea, RTCM on /rtcm to your GNSS driver. To stream RTKdata corrections to a ROS 2 robot, run the ROS 2 NTRIP client `ntrip_client` (`ros-humble-ntrip-client` or `ros-jazzy-ntrip-client`) with a parameter file that sets `host` to the RTKdata server for your region (`rtk.rtkdata.com` for North America, `eu.rtkdata.com` for Europe or `aus.rtkdata.com` for Australia) and `port` to `2101`. In the same file, set `mountpoint` to `AUTO`, `authenticate` to `true`, `username` and `password` to the values from [RTK Credentials](https://rtkdata.com/my-account/rtk-credentials/), and `rtcm_message_package` to `rtcm_msgs`. Connect it to a GNSS driver that publishes the receiver's NMEA sentences on `nmea` and writes the RTCM messages from the `rtcm` topic into the receiver. `ntrip_client` forwards the receiver's GGA sentences to RTKdata and publishes the corrections on a ROS topic; it never writes to the receiver itself. This guide was written for `ntrip_client` 1.4.1, the version in the ROS 2 Humble and Jazzy package repositories in September 2026. Parameter names, topics and log lines follow the source code of the open-source [ntrip\_client package](https://github.com/LORD-MicroStrain/ntrip_client/tree/ros2-1.4.1) (MIT license), branch `ros2`, tag `ros2-1.4.1`. The driver tabs refer to `ublox_gps` from the `ros2` branch of the KumarRobotics `ublox` repository (release 3.0.0), `ublox_dgnss` 0.7.5 (Humble) and 0.7.4 (Jazzy), `microstrain_inertial_driver` 4.9.0 and `septentrio_gnss_driver` 1.4.8. Older ROS 2 distributions ship older `ntrip_client` releases with other parameters, which this guide does not cover. ## Requirements * **ROS 2 Humble** (Ubuntu 22.04) or **ROS 2 Jazzy** (Ubuntu 24.04) on the robot computer * **`ntrip_client` 1.4.1**, from apt for amd64 and arm64, or built from source * A **GNSS receiver with a ROS 2 driver that takes RTCM from a topic** (see the driver table below), or a receiver with its own NTRIP client, such as the Septentrio mosaic-X5 * **Internet on the robot** with outbound TCP on port `2101` * **RTKdata account** with RTK credentials (the username starts with `rtk`) * **One data stream per robot** that is connected at the same time, see [Account & Credentials](/get-started/account-and-credentials.md#using-one-subscription-with-several-devices) * **RTKdata coverage** where the robot works: check the [coverage map](/get-started/coverage-map.md) {% hint style="info" %} Don't have an RTKdata.com account yet? [Start 30-day Free Trial](https://rtkdata.com/try-rtk-corrections-free-for-30-days/) or [View Pricing](https://rtkdata.com/pricing/) {% endhint %} ## How does the ROS 2 NTRIP client work with RTKdata? `ntrip_client` links ROS 2 topics to the RTKdata caster: it logs in, forwards the position messages it receives on `nmea` or `fix` to the caster, and publishes every RTCM message from the caster on `rtcm`, where a GNSS driver has to pick it up and write it into the receiver. | Step | What `ntrip_client` does | Topic and message type | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | 1. Connect | Opens a TCP connection to `host` on port `2101`, requests the mountpoint (`GET /AUTO`) with your credentials and, on success, logs `Connected to http://eu.rtkdata.com:2101/AUTO` | None | | 2. Subscribe | Subscribes to its two position topics, but only after the connection is up. NMEA that arrives while the client is not connected is discarded with `NMEA sent before client was connected, discarding NMEA` | `nmea` (`nmea_msgs/msg/Sentence`), `fix` (`sensor_msgs/msg/NavSatFix`) | | 3. Send the position | Sends every valid NMEA sentence from `nmea` to the caster unchanged (it only adds a missing line ending), whatever its type, and builds its own `$GPGGA` sentence from each `NavSatFix` on `fix` | `nmea`, `fix` | | 4. Publish corrections | Splits the caster stream into RTCM 3 frames and publishes each frame as a separate message | `rtcm` (`rtcm_msgs/msg/Message` with `rtcm_message_package: rtcm_msgs`) | | 5. Correct the receiver | Nothing: a GNSS driver subscribes to the RTCM topic and writes the bytes into the receiver, which computes the RTK solution | The driver's RTCM topic, see the next section | `ntrip_client` creates no position of its own and does not limit the rate: it sends what arrives on `nmea` and `fix`, at the rate of the publisher. Connect exactly one of the two topics to a position source. RTKdata streams RTCM 3.2 with MSM4 messages (1074, 1084, 1094, 1114, 1124, 1134) and 1005. `ntrip_client` passes every message on without filtering by type, and the receiver uses the ones it supports: the ZED-F9P lists 1005, 1074, 1084, 1094 and 1124 among its RTCM input messages (u-blox ZED-F9P Integration Manual R16, table 6). RTCM 1230 (GLONASS code-phase biases) comes from the base station, and most RTKdata base stations do not send it. The ZED-F9P needs 1230 or 1033 to fix GLONASS ambiguities and otherwise estimates them as float (Integration Manual R16, section 3.1.5.4), so GLONASS does not contribute to the RTK fix. GPS, Galileo and BeiDou are not affected, and you can leave GLONASS enabled. {% hint style="danger" %} **RTKdata needs your position (GGA).** The `AUTO` mountpoint selects the nearest reference station from the GGA position that `ntrip_client` forwards. RTKdata is not a virtual reference station (VRS) service, but without a position it sends no corrections: the log shows `Connected to ...`, and no messages arrive on `rtcm`. See [What Happens When GGA Is Not Sent](/integration-hub/ntrip-clients-and-field-software/ntrip-and-gga-essentials.md#what-happens-when-gga-is-not-sent). {% endhint %} ## Which ROS 2 GNSS drivers accept RTCM from ntrip\_client? To get RTKdata corrections into the receiver, `ntrip_client` needs a GNSS driver that subscribes to an RTCM topic: `ublox_gps` built from the `ros2` branch (3.0.0), `ublox_dgnss` and `microstrain_inertial_driver` (GQ7) do; `ublox_gps` 2.3.0 from apt and `nmea_navsat_driver` do not; `septentrio_gnss_driver` uses the NTRIP client inside the receiver instead. | Driver and version | Receivers | RTCM input | RTCM topic of the driver | GGA source for `ntrip_client` | | ----------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `ublox_gps`, `ros2` branch (3.0.0), built from source | u-blox ZED-F9P | Yes | `/rtcm` (`rtcm_msgs/msg/Message`) | Receiver NMEA on `nmea` (`publish.nmea: true`) | | `ublox_gps` from apt on Humble and Jazzy (2.3.0) | u-blox | No | None | Not usable for RTK | | `ublox_dgnss` (apt: 0.7.5 on Humble, 0.7.4 on Jazzy) | u-blox ZED-F9P and ZED-F9R over USB | Yes | `/ntrip_client/rtcm` (`rtcm_msgs/msg/Message`) | `/fix` only, published best effort, needs a QoS override | | `microstrain_inertial_driver` 4.9.0 | MicroStrain GQ7 | Yes, with `ntrip_interface_enable: True` | `/rtcm` (`rtcm_msgs/msg/Message`) | NMEA from the aux port on `/nmea` | | `septentrio_gnss_driver` 1.4.8 | Septentrio receivers with a built-in NTRIP client | No ROS topic input | None: the receiver's own NTRIP client, set with `rtk_settings.ntrip_1` | Sent by the receiver (`send_gga`) | | `nmea_navsat_driver` | Receivers that output NMEA | No | None: the driver only reads the serial port | `fix` reaches `ntrip_client`, but the corrections never reach the receiver | ## How do you install and configure ntrip\_client for RTKdata? Install `ntrip_client` 1.4.1 from apt or build the `ros2` branch, write a parameter file with the RTKdata values for your region, and start the node with `ros2 run ntrip_client ntrip_ros.py --ros-args --params-file`. {% stepper %} {% step %} ### Install ntrip\_client On ROS 2 Humble (Ubuntu 22.04): ```bash sudo apt install ros-humble-ntrip-client ``` On ROS 2 Jazzy (Ubuntu 24.04): ```bash sudo apt install ros-jazzy-ntrip-client ``` Both packages exist for amd64 and arm64 and install `rtcm_msgs` and `nmea_msgs` as dependencies. To build from source instead, clone the `ros2` branch into a workspace. The default branch of the repository, `ros`, contains the ROS 1 (catkin) version and does not build for ROS 2. If the computer has no ROS 2 build tools yet, run `sudo apt install ros-dev-tools`, `sudo rosdep init` and `rosdep update` once. On Jazzy, source `/opt/ros/jazzy/setup.bash` instead: ```bash source /opt/ros/humble/setup.bash mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src git clone --branch ros2 https://github.com/LORD-MicroStrain/ntrip_client.git cd ~/ros2_ws rosdep install --from-paths src --ignore-src -r -y colcon build source install/setup.bash ``` Run `source ~/ros2_ws/install/setup.bash` in every new terminal before you start a node from the workspace. {% endstep %} {% step %} ### Create the parameter file Save the parameter file for your region, for example as `~/rtkdata_ntrip.yaml`. Replace `` and `` with the values from [RTK Credentials](https://rtkdata.com/my-account/rtk-credentials/) and keep the quotes. {% tabs %} {% tab title="North America" %} ```yaml ntrip_client: ros__parameters: host: rtk.rtkdata.com port: 2101 mountpoint: AUTO authenticate: true username: '' password: '' rtcm_message_package: rtcm_msgs nmea_max_length: 128 rtcm_timeout_seconds: 15 ``` * **Host (domain):** `rtk.rtkdata.com` * **Host (IP fallback):** `13.56.117.10`, only if the hostname does not resolve on the robot * **Port:** `2101` * **Username / Password:** from *RTK Credentials* in your [account dashboard](https://rtkdata.com/my-account/rtk-credentials/), not your website login (the username starts with `rtk`) * **Mountpoint (ALL CAPS):** `AUTO` (recommended), or `AUTO_WGS84`, `AUTO_ITRF2020`, `AUTO_ITRF2014` {% endtab %} {% tab title="Europe" %} ```yaml ntrip_client: ros__parameters: host: eu.rtkdata.com port: 2101 mountpoint: AUTO authenticate: true username: '' password: '' rtcm_message_package: rtcm_msgs nmea_max_length: 128 rtcm_timeout_seconds: 15 ``` * **Host (domain):** `eu.rtkdata.com` * **Host (IP fallback):** `3.73.41.96`, only if the hostname does not resolve on the robot * **Port:** `2101` * **Username / Password:** from *RTK Credentials* in your [account dashboard](https://rtkdata.com/my-account/rtk-credentials/), not your website login (the username starts with `rtk`) * **Mountpoint (ALL CAPS):** `AUTO` (recommended), or `AUTO_WGS84`, `AUTO_ITRF2020`, `AUTO_ITRF2014` {% endtab %} {% tab title="Australia" %} ```yaml ntrip_client: ros__parameters: host: aus.rtkdata.com port: 2101 mountpoint: AUTO authenticate: true username: '' password: '' rtcm_message_package: rtcm_msgs nmea_max_length: 128 rtcm_timeout_seconds: 15 ``` * **Host (domain):** `aus.rtkdata.com` * **Host (IP fallback):** `54.206.56.130`, only if the hostname does not resolve on the robot * **Port:** `2101` * **Username / Password:** from *RTK Credentials* in your [account dashboard](https://rtkdata.com/my-account/rtk-credentials/), not your website login (the username starts with `rtk`) * **Mountpoint (ALL CAPS):** `AUTO` (recommended), or `AUTO_WGS84`, `AUTO_ITRF2020`, `AUTO_ITRF2014` {% endtab %} {% endtabs %} Write each value with the type the node expects. `rclpy` fixes the type of every parameter from its default in the code, and a value of another type stops the node at start with an `InvalidParameterTypeException`: * `port`, `nmea_max_length` and `rtcm_timeout_seconds` are whole numbers: write `15`, not `15.0` or `"15"`. * `authenticate` is `true` without quotes. * `username` and `password` are text, so keep them in single quotes, which keep characters such as `$`, `\` or `"` as they are. A password such as `123456` without quotes stops the node with `Trying to set parameter 'password' to '123456' of type 'INTEGER', expecting type 'STRING'`. * `host` takes the hostname only, without `http://` and without `:2101`. The log always prints the server as `http://host:port`, but the value you enter is the plain hostname. * The root key `ntrip_client:` matches only the node `ntrip_client` in the root namespace. If you start the node in a namespace, use `/**/ntrip_client:` as the root key. If you give the node another name, use that name instead, for example `/**/my_ntrip:`, or `/**:` to match every node. Otherwise the node starts with its code defaults. * The parameter is `rtcm_message_package`. The README of version 1.4.1 spells it `rtcm_message_packege`, and a parameter under that name has no effect. Four values in this file differ from the defaults in the code, and each default causes a failure with RTKdata: | Parameter | Default in 1.4.1 | Value for RTKdata | Why | | ---------------------- | --------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authenticate` | `false` (only the included launch file sets `True`) | `true` | Without it, the node sends no credentials, and RTKdata answers with its source table: `Received sourcetable response from the server` | | `rtcm_message_package` | `mavros_msgs` | `rtcm_msgs` | The apt package depends on `rtcm_msgs`, not on `mavros_msgs`. Without `mavros_msgs`, the node logs a fatal error and stops. `ublox_gps`, `ublox_dgnss` and `microstrain_inertial_driver` subscribe to `rtcm_msgs/msg/Message` | | `nmea_max_length` | `82`, counted including the line ending | `128` | A GGA sentence that carries a correction age and a reference station ID, as it does once corrections are in use, can be longer than 82 bytes and is then dropped | | `rtcm_timeout_seconds` | `4` | `15` | Each gap in the correction stream longer than this value makes the node disconnect and reconnect. That starts a new session, and the receiver can lose its RTK fix and have to solve it again. The examples on this page use `15` | Leave the other parameters at their defaults: `ssl` stays `false`, because port `2101` is a plain TCP connection, and `ntrip_version` stays unset, so the request carries no `Ntrip-Version` header. {% endstep %} {% step %} ### Start ntrip\_client In every terminal, source the ROS 2 environment: `source /opt/ros/humble/setup.bash` (on Jazzy, `/opt/ros/jazzy/setup.bash`), or `source ~/ros2_ws/install/setup.bash` if you built packages in a workspace. Start the GNSS driver first and wait until the receiver has a position, then start `ntrip_client` with the parameter file: ```bash ros2 run ntrip_client ntrip_ros.py --ros-args --params-file ~/rtkdata_ntrip.yaml ``` For a quick test without a parameter file, the included launch file takes the connection values as arguments. It has no remap arguments and sets `rtcm_timeout_seconds` to `4` and `nmea_max_length` to `128` with no argument to change them, so use it only for a first check with a driver that needs no remap. Always pass `host`, `mountpoint`, `username` and `password`, because its defaults are not RTKdata values. The launch file reads argument values as YAML, so keep the password in single quotes inside the double quotes. If your username or password contains `$`, `\`, `"` or a backtick, use the parameter file instead: ```bash ros2 launch ntrip_client ntrip_client_launch.py host:=eu.rtkdata.com port:=2101 mountpoint:=AUTO authenticate:=True "username:=" "password:=''" ``` Outside Europe, replace `eu.rtkdata.com` with `rtk.rtkdata.com` or `aus.rtkdata.com`. The next section shows the settings each driver needs. {% endstep %} {% endstepper %} ## How do you connect ntrip\_client to your GNSS driver? `ntrip_client` and the driver meet on two topics, `nmea` for the receiver's NMEA sentences and `rtcm` for the corrections: `ublox_gps` and the GQ7 match without a remap, `ublox_dgnss` needs one remap and a QoS override, and Septentrio receivers connect to RTKdata with their own NTRIP client instead. {% tabs %} {% tab title="u-blox ZED-F9P (ublox\_gps)" %} **Build `ublox_gps` from the `ros2` branch.** The apt packages `ros-humble-ublox-gps` and `ros-jazzy-ublox-gps` contain version 2.3.0, which has no RTCM input. The `ros2` branch (release 3.0.0) subscribes to `/rtcm` and writes the corrections into the receiver. If the computer has no ROS 2 build tools yet, install them and set up `rosdep` once: ```bash sudo apt install ros-dev-tools sudo rosdep init rosdep update ``` Then create the workspace and build the driver. On Jazzy, source `/opt/ros/jazzy/setup.bash` instead: ```bash source /opt/ros/humble/setup.bash mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src git clone --branch ros2 https://github.com/KumarRobotics/ublox.git cd ~/ros2_ws rosdep install --from-paths src --ignore-src -r -y colcon build source install/setup.bash ``` **Source the workspace in every new terminal.** Run `source ~/ros2_ws/install/setup.bash` before `ros2 run`, then check which driver the terminal starts with `ros2 pkg prefix ublox_gps`. It must print a path in `~/ros2_ws/install`. A path in `/opt/ros` means that the terminal starts the apt version 2.3.0, which has no RTCM input. **Write your own rover file.** Do not start the F9P with the included `zed_f9p.yaml`: it sets `tmode3: 1` (survey-in), which sets the receiver up as a base station. Save this file as `~/ublox_rover.yaml`: ```yaml ublox_gps_node: ros__parameters: device: /dev/ttyACM0 frame_id: gps config_on_startup: true tmode3: 0 rate: 1.0 nav_rate: 1 gnss: gps: true glonass: true galileo: true beidou: true qzss: true publish: nmea: true ``` * `tmode3: 0` runs the F9P as a rover. With `config_on_startup: true`, the driver requires this value for the F9P and stops with `Invalid settings: TMODE3 must be set` without it. * `gnss.*: true` enables all five constellations. With `config_on_startup: true`, the driver writes its constellation selection into the F9P, and with its defaults it keeps GPS on and switches GLONASS, Galileo, BeiDou and QZSS off. The F9P uses GPS, GLONASS, Galileo, BeiDou and QZSS at the factory (u-blox ZED-F9P Integration Manual R16, section 3.1.2). * `rate: 1.0` sets one measurement per second, so the receiver sends GGA at 1 Hz. The driver default is 4 Hz. * `publish.nmea: true` publishes the receiver's NMEA sentences on `nmea`. Over USB, the F9P outputs GGA, GLL, GSA, GSV, RMC, VTG and TXT at the factory (Integration Manual R16, section 3.1.3), so `/nmea` carries the receiver's own GGA. **Start the driver and `ntrip_client` in two terminals** with the workspace sourced. No remap is needed: `ublox_gps_node` publishes `nmea` and subscribes to the absolute topic `/rtcm`, and `ntrip_client` in the root namespace uses the same two topics. ```bash ros2 run ublox_gps ublox_gps_node --ros-args --params-file ~/ublox_rover.yaml ``` ```bash ros2 run ntrip_client ntrip_ros.py --ros-args --params-file ~/rtkdata_ntrip.yaml ``` Do not also remap `fix` to `/ublox_gps_node/fix`. `ntrip_client` would then send a second GGA, built from `NavSatFix`, next to the receiver's own sentences. **USB or UART.** Connect the F9P over USB (`/dev/ttyACM0`). The user that runs the driver needs read and write access to this device. If the driver stops with `U-Blox: Could not open serial port :/dev/ttyACM0`, check the device name with `ls /dev/ttyACM*` and add the user to the `dialout` group with `sudo usermod -a -G dialout $USER`, then log out and back in. On UART1, set `device` to the serial port of that connection and add three values to the rover file: `uart1.baudrate` with the receiver's baud rate (38400 at the factory), `uart1.in: 35` (UBX, NMEA and RTCM 3 input) and `uart1.out: 3` (UBX and NMEA output). With the driver defaults (9600 baud, RTCM 3 input off, UBX output only), the start stops with `Could not configure serial baud rate` when the receiver runs at another baud rate, and UART1 neither accepts RTCM 3 nor outputs NMEA. {% endtab %} {% tab title="u-blox (ublox\_dgnss)" %} This tab covers the ZED-F9P and ZED-F9R. For the ZED-X20P, the `ublox_dgnss` README describes another udev rule, launch files for the X20P and `/ubx_rxm_cor` in place of `/ubx_rxm_rtcm`; this guide does not cover it. **Install the driver and the udev rule.** The command is for Humble; on Jazzy, install `ros-jazzy-ublox-dgnss`. ```bash sudo apt install ros-humble-ublox-dgnss ``` `ublox_dgnss` talks to the receiver over USB. Its README gives this udev rule for the ZED-F9P and ZED-F9R in `/etc/udev/rules.d/99-ublox-gnss.rules`: ``` ATTRS{idVendor}=="1546", ATTRS{idProduct}=="01a9", MODE="0666", GROUP="plugdev", ENV{ID_MM_DEVICE_IGNORE}="1" ``` **Use `ntrip_client`, not the `ntrip_client_node` of `ublox_dgnss`.** The NTRIP node included with `ublox_dgnss` only downloads corrections and sends no GGA (it identifies itself as `NTRIP ros2/ublox_dgnss`), so `AUTO` sends it nothing. It also runs under the node name `ntrip_client`, so do not start both. **Remap the RTCM topic.** `ublox_dgnss_node` subscribes to `/ntrip_client/rtcm`: ```bash ros2 run ntrip_client ntrip_ros.py --ros-args --params-file ~/rtkdata_ntrip.yaml -r rtcm:=/ntrip_client/rtcm ``` **Make `/fix` reliable.** The rover launch file `ublox_rover_hpposllh_navsatfix.launch.py` switches the NMEA output over USB off (`CFG_USBOUTPROT_NMEA: False`), so `ntrip_client` builds the GGA itself from `/fix`. The node `ublox_nav_sat_fix_hp` publishes `/fix` with the sensor data profile (best effort), while `ntrip_client` subscribes as reliable. According to the ROS 2 QoS compatibility table, a best effort publisher and a reliable subscription do not connect. The included launch file passes no parameters to this node, so copy it: ```bash cp "$(ros2 pkg prefix --share ublox_dgnss)/launch/ublox_rover_hpposllh_navsatfix.launch.py" ~/ublox_rover_rtkdata.launch.py ``` In the copy, add the QoS override to the `ComposableNode` named `ublox_nav_sat_fix_hp`: ```python ComposableNode( package='ublox_nav_sat_fix_hp_node', plugin='ublox_nav_sat_fix_hp::UbloxNavSatHpFixNode', name='ublox_nav_sat_fix_hp', namespace=namespace, parameters=[{'qos_overrides./fix.publisher.reliability': 'reliable'}] ) ``` Start the copy, start `ntrip_client` with the remap shown above, and check the connection. The publisher on `/fix` must show `Reliability: RELIABLE`, and `ntrip_client` must appear as a subscription: ```bash ros2 launch ~/ublox_rover_rtkdata.launch.py ``` ```bash ros2 topic info /fix --verbose ``` **Check the RTK status.** `ros2 topic echo /ubx_nav_status` shows `carr_soln.status` `2` for fixed and `1` for float ambiguities. `ros2 topic echo /ubx_rxm_rtcm` shows `msg_used: 2` when the receiver used an RTCM message; the rover launch file turns this output on with `CFG_MSGOUT_UBX_RXM_RTCM_USB: 1`. {% endtab %} {% tab title="MicroStrain GQ7" %} **Install the driver.** The command is for Humble; on Jazzy, install `ros-jazzy-microstrain-inertial-driver`. ```bash sudo apt install ros-humble-microstrain-inertial-driver ``` **Enable the NTRIP interface.** Save a parameter file for the driver, for example as `~/gq7_ntrip.yaml`, with the root key `microstrain_inertial_driver`: ```yaml microstrain_inertial_driver: ros__parameters: ntrip_interface_enable: True aux_port: /dev/ttyACM1 aux_baudrate: 115200 ``` Set `aux_port` to the device of the GQ7 aux port: the driver needs a valid aux port for this interface. Start the driver with the file: ```bash ros2 launch microstrain_inertial_driver microstrain_launch.py params_file:=$HOME/gq7_ntrip.yaml ``` According to the MicroStrain parameter file, this setting allows the driver to "receive RTCM messages on the /rtcm topic and publish NMEA sentences from the aux port on /nmea", and MicroStrain suggests `ntrip_client` for this interface. In the root namespace, both topics match `ntrip_client` without a remap. **Check the GGA source first.** Run `ros2 topic echo /nmea` and confirm that GGA sentences arrive before you start `ntrip_client` with your parameter file: ```bash ros2 run ntrip_client ntrip_ros.py --ros-args --params-file ~/rtkdata_ntrip.yaml ``` {% endtab %} {% tab title="Septentrio (mosaic, AsteRx)" %} **No `ntrip_client` here.** `septentrio_gnss_driver` has no ROS topic input for RTCM. It writes NTRIP client settings into the receiver instead, and the receiver connects to RTKdata itself. This works with receivers that have a built-in NTRIP client, such as the mosaic-X5. The receiver needs its own internet connection: Ethernet, or USB with internet sharing from the computer as described in the driver README. **Copy the driver's rover file.** ```bash cp "$(ros2 pkg prefix --share septentrio_gnss_driver)/config/rover_node.yaml" ~/rtkdata_rover.yaml ``` In the copy, keep `configure_rx: true`, set `device` to your receiver connection (the example file uses `tcp://192.168.3.1:28784`, the receiver's address over USB), and fill in the `ntrip_1` block under `rtk_settings`. Enter the host for your region in `caster`: `rtk.rtkdata.com`, `eu.rtkdata.com` or `aus.rtkdata.com`. This excerpt shows the keys to set; leave the rest of the copied file in place: ```yaml septentrio_gnss_driver: ros__parameters: configure_rx: true rtk_settings: ntrip_1: id: "NTR1" caster: "eu.rtkdata.com" caster_port: 2101 username: '' password: '' mountpoint: "AUTO" version: "v2" tls: false fingerprint: "" rtk_standard: "RTCMv3" send_gga: "sec1" keep_open: true ``` * `id` must be `NTR1` (or `NTR2`, `NTR3`). With an empty `id`, the driver skips the block. * `send_gga: "sec1"` sends GGA every second. With `auto`, the receiver sends GGA only when the caster requests it. * The key is `password`, although the driver README spells it `pasword`. * With `configure_rx: true`, the driver writes these settings into the receiver. According to its README, it overwrites the previous values, even for keys left empty in the file. **Start the driver with the full path of your file.** The launch argument `file_name` only looks in the config folder of the package, so pass your copy with `path_to_config`: ```bash ros2 launch septentrio_gnss_driver rover_node.launch.py path_to_config:=$HOME/rtkdata_rover.yaml ``` For the NTRIP setup without ROS, see [Septentrio mosaic-X5](/integration-hub/gnss-rovers-and-receivers/septentrio-mosaic-x5.md) and [Septentrio RxTools](/integration-hub/ntrip-clients-and-field-software/septentrio-rxtools.md). {% endtab %} {% endtabs %} ## How do you check that corrections reach the receiver? Corrections reach the receiver when the driver reports an RTK solution, for example `status.status: 2` on `/ublox_gps_node/fix`; the log line `Connected to http://eu.rtkdata.com:2101/AUTO` only shows that the RTKdata login worked. 1. **Login:** the `ntrip_client` log shows `Connected to http://:2101/AUTO`. 2. **GGA source:** `ros2 topic echo /nmea` shows the receiver's GGA sentences. With `ublox_dgnss`, check `/fix` instead. 3. **RTCM subscription:** `ros2 topic info /rtcm --verbose` must list your GNSS driver with `Endpoint type: SUBSCRIPTION` and `Topic type: rtcm_msgs/msg/Message`. With `ublox_dgnss`, check `/ntrip_client/rtcm`. 4. **Data flow:** `ros2 topic hz /rtcm` shows that corrections arrive from the caster. The rate is not a target value and does not prove that the receiver uses the data. 5. **Receiver status:** only the RTK status the driver reports shows that the receiver uses the corrections. ```bash ros2 topic echo /nmea ros2 topic info /rtcm --verbose ros2 topic hz /rtcm ros2 topic echo /ublox_gps_node/fix ``` | Driver | Where to look | RTK Fixed | Other values | | ------------- | ---------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `ublox_gps` | `status.status` on `/ublox_gps_node/fix` | `2` (`STATUS_GBAS_FIX`), set only when the carrier phase is fixed | `0` (`STATUS_FIX`): a fix without fixed ambiguities, which includes RTK Float; `-1` (`STATUS_NO_FIX`): no fix | | `ublox_dgnss` | `carr_soln.status` on `/ubx_nav_status` | `2`: fixed ambiguities | `1`: float ambiguities; `0`: no carrier phase solution | | `ublox_dgnss` | `msg_used` on `/ubx_rxm_rtcm` | `2`: the receiver used the RTCM message | `1`: not used; `0`: unknown | If the log shows `Connected to ...` but nothing arrives on `rtcm`, usually no GGA reaches RTKdata: `AUTO` needs the position before it sends corrections. If the GGA source works, check the robot's location on the [Coverage Map](/get-started/coverage-map.md). ## How do you keep the NTRIP connection stable on a robot? Start `ntrip_client` from your own launch file with `respawn=True`, because the node exits on several errors, give it exactly one GGA source at 1 Hz, and set `rtcm_timeout_seconds` to `15` as in the parameter file above. `ntrip_client` 1.4.1 ends in these cases and does not start again by itself: * The first connection attempt fails, for example because the network is not up at boot. The log shows `Unable to connect`, and there is no retry. * After a lost connection, `reconnect_attempt_max` reconnect attempts (default `10`) fail. The node stops with `Reconnect was attempted 0 times, but never succeeded`. * An NMEA sentence on `nmea` contains a `*` but no valid hexadecimal checksum: `ValueError: invalid literal for int() with base 16`. * A `NavSatFix` on `fix` carries NaN as latitude or longitude. A launch file with `respawn` starts the node again after each of these exits: ```python from launch import LaunchDescription from launch_ros.actions import Node def generate_launch_description(): return LaunchDescription([ Node( package='ntrip_client', executable='ntrip_ros.py', name='ntrip_client', parameters=['/home//rtkdata_ntrip.yaml'], respawn=True, respawn_delay=5.0, ), ]) ``` Save it, for example as `~/rtkdata_ntrip_launch.py`, replace `/home//rtkdata_ntrip.yaml` with the absolute path of your parameter file and start it with `ros2 launch ~/rtkdata_ntrip_launch.py`. With `ublox_dgnss`, add `remappings=[('rtcm', '/ntrip_client/rtcm')],` to the `Node`. * **Absolute path:** give the parameter file in the launch file with its absolute path. * **Start order:** start `ntrip_client` only after the driver reports a position. * **GGA at 1 Hz:** set the rate at the driver, for example `rate: 1.0` for `ublox_gps` or `send_gga: "sec1"` for Septentrio, see [GGA Rate Recommendation](/integration-hub/ntrip-clients-and-field-software/ntrip-and-gga-essentials.md#gga-rate-recommendation). * **One GGA source:** `ntrip_client` sends everything that arrives on `nmea` and on `fix`. With the receiver's NMEA on `nmea`, do not remap `fix` to the driver's `NavSatFix` topic. * **Timeout:** keep `rtcm_timeout_seconds: 15` in the parameter file, and raise `reconnect_attempt_max` if the robot often loses its network for longer periods. ### Several robots on one account or one network Every robot that is connected at the same time needs its own RTKdata data stream, because one data stream allows one connection at a time, and two robots on the same stream disconnect each other. The [Robotics overview](/integration-hub/robotics.md#how-many-data-streams-does-a-robot-fleet-need) explains how many data streams a fleet needs, and [Account & Credentials](/get-started/account-and-credentials.md#using-one-subscription-with-several-devices) how extra streams are set up. On ROS 2, a connection that the caster closes shows up in the `ntrip_client` log as `Reconnecting because we received 0 bytes from the socket even though it said there was data available 5 times`, and the node connects again. Also check that a robot does not run a second `ntrip_client` process, for example one started at boot and one started in a terminal. Robots on the same network also see each other's topics, because all ROS 2 nodes use domain ID 0 by default. The ROS 2 documentation advises: "To avoid interference between different groups of computers running ROS 2 on the same network, a different domain ID should be set for each group." Give each robot its own `ROS_DOMAIN_ID` between 0 and 101 before you start its nodes: ```bash export ROS_DOMAIN_ID=11 ``` If you separate robots with namespaces instead, note that `ublox_gps` (`/rtcm`) and `ublox_dgnss` (`/ntrip_client/rtcm`) subscribe to absolute topics: remap them into the robot's namespace, and use `/**/ntrip_client:` as the root key of the parameter file. For volume licensing across many robots, see [Enterprise & Volume](/commercial/enterprise-and-volume.md). ## Which mountpoint should a ROS 2 robot use: AUTO or AUTO\_WGS84? Use the RTKdata mountpoint `AUTO` when the robot's maps, geofences and surveyed points are in your region's datum, and `AUTO_WGS84` or `AUTO_ITRF2020` when they are in WGS 84, because the receiver outputs its RTK position in the reference frame of the corrections. * `AUTO` delivers your region's datum, chosen from the GGA position: for example NAD83(2011), epoch 2010.0, in the USA; NAD83(CSRS)v7, epoch 2010.0, in Canada; ETRS89 (realization ETRF2000), epoch 2010.0, in Europe; and GDA2020, epoch 2020.0, in Australia. For regions not listed, `AUTO` falls back to WGS84(G2139) at the mid-year epoch. The datum for every region is listed in [Coordinate Systems & Datums](/get-started/coordinate-systems-and-datums.md). * `AUTO_ITRF2020` and `AUTO_ITRF2014` deliver ITRF2020 and ITRF2014 at the current epoch, and `AUTO_WGS84` delivers WGS84(G2139) at the mid-year epoch. * `sensor_msgs/msg/NavSatFix` is "Specified using the WGS 84 reference ellipsoid" and has no datum field. With `AUTO`, the latitude and longitude in the message are still in the regional datum: the receiver computes its RTK position in the frame of the correction source, and the u-blox ZED-F9P Integration Manual states that "the receiver coordinates will be expressed in the datum used by the RTCM correction provider". * For maps, geofences and waypoints from WGS 84 sources, such as web maps, use `AUTO_WGS84` or `AUTO_ITRF2020`. For points surveyed in your national datum, use `AUTO`. * Heights are ellipsoidal: `NavSatFix` defines `altitude` as the height above the ellipsoid. Apply a geoid model if you need heights above sea level, see [Understanding Heights](/get-started/understanding-heights.md). * When corrections stop, the F9P stops using RTCM corrections older than 60 seconds (default) and falls back to a standard solution, and the reference frame of its output switches from that of the corrections to that of the standard solution. * A constant offset of 50 cm to 1 m against local survey control usually means a datum mismatch, see [Why Your Coordinates May Be Offset](/get-started/coordinate-systems-and-datums.md#why-your-coordinates-may-be-offset). ## Troubleshooting | Log line or symptom | Cause | Fix | | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Received sourcetable response from the server. This probably means the mountpoint specified is not valid` | RTKdata answers a request without credentials with its source table, and `authenticate` is `false` in the node unless you set it | Set `authenticate: true` first. Then check that the mountpoint is `AUTO` in capitals and that the parameter file is applied | | `Received unauthorized response from the server. Check your username, password, and mountpoint to make sure they are correct.` | Wrong username or password, often the website login | Enter the username (starts with `rtk`) and the password from *RTK Credentials* | | `Unable to connect socket to server at http://:2101` | `host` contains `http://` or `:2101` (the log then shows `http://http://` or `:2101:2101`), the hostname does not resolve, or outbound TCP on port 2101 is blocked | Enter the hostname only, try the IP fallback for your region and allow outbound TCP on port `2101`. If the log shows `127.0.0.1`, the parameter file was not applied: check the root key against the node name and the namespace | | `Requested to authenticate, but param "username" was not set` | `authenticate: true`, but `username` is empty | Enter `username` in the parameter file. The same check exists for `password` | | `The requested RTCM package mavros_msgs is a valid option, but we were unable to import it. Please make sure you have it installed` | `rtcm_message_package` is missing, misspelled as `rtcm_message_packege`, or not applied, so the default `mavros_msgs` is used | Set `rtcm_message_package: rtcm_msgs`. If the line appears although the file sets it, check the root key, the namespace and the path of the parameter file | | `Received invalid NMEA sentence. Max length is 82, but sentence was bytes` | `nmea_max_length` is at its default `82` | Set `nmea_max_length: 128` | | `New publisher discovered on topic '/fix', offering incompatible QoS. No messages will be received from it. Last incompatible policy: RELIABILITY` | `ublox_nav_sat_fix_hp` (`ublox_dgnss`) publishes `/fix` best effort, and `ntrip_client` subscribes as reliable | Add the QoS override from the `ublox_dgnss` tab and check with `ros2 topic info /fix --verbose` | | `RTCM data not received for 4 seconds, reconnecting` | A gap in the correction stream longer than `rtcm_timeout_seconds` (default `4`) | Set `rtcm_timeout_seconds: 15` and check the robot's internet connection | | `Reconnecting because we received 0 bytes from the socket even though it said there was data available 5 times` | The caster closed the connection: a second device or process with the same credentials, or a dropped connection | One data stream per robot that is connected at the same time; stop duplicate `ntrip_client` processes | | `Reconnect was attempted 0 times, but never succeeded` | All reconnect attempts failed (`reconnect_attempt_max`, default `10`), and the node has stopped | Start the node from a launch file with `respawn=True` and check the network | | `ValueError: invalid literal for int() with base 16` | An NMEA sentence with a broken checksum reached `nmea`, and the node has stopped | Use `respawn=True` and check the NMEA source | | `Trying to set parameter '' to '' of type '', expecting type ''` | A value in the parameter file has the wrong type | Quote `username` and `password`, write whole numbers without a decimal point and `authenticate: true` without quotes | | `Invalid settings: TMODE3 must be set` (`ublox_gps`) | `config_on_startup: true` without `tmode3` | Add `tmode3: 0` to the rover file | | `Could not configure serial baud rate` (`ublox_gps`) | The receiver on UART1 runs at another baud rate than `uart1.baudrate` | Connect over USB, or set `uart1.baudrate` to the receiver's baud rate (38400 at the factory) | | `U-Blox: Could not open serial port :/dev/ttyACM0` (`ublox_gps`) | The device name is wrong, or the user that runs the driver has no read and write access to the device | Check the device name with `ls /dev/ttyACM*`, add the user to the `dialout` group with `sudo usermod -a -G dialout $USER` and log in again | | `ros2 pkg prefix ublox_gps` prints a path in `/opt/ros` | The workspace is not sourced or not built, so the terminal starts `ublox_gps` 2.3.0 from apt, which has no RTCM input | Run `source ~/ros2_ws/install/setup.bash` before `ros2 run`. If the path stays in `/opt/ros`, build the `ros2` branch as shown in the `ublox_gps` tab | | `Failed to write RTCM to aux port` (`microstrain_inertial_driver`) | The driver cannot write to the GQ7 aux port | Check `aux_port` and `aux_baudrate` | | Septentrio receiver makes no NTRIP connection | `id` is empty (the driver skips the block), `configure_rx` is not `true`, or the receiver has no internet | Set `id: "NTR1"` and `configure_rx: true`, and give the receiver internet | | `Found packet, but checksums didn't match`, now and then | Not a caster error: `ntrip_client` 1.4.1 can log this while it reassembles RTCM frames that arrive in parts | Check the RTK status of the receiver; act only if corrections do not arrive | | Log shows `Connected to ...`, but `/rtcm` stays empty | Usually no GGA reaches the caster: nothing is published on `nmea` or `fix`, or `/fix` is best effort | Check `ros2 topic echo /nmea` and `ros2 topic info /fix --verbose`, and remap to the driver's topic. If the GGA source works, check the robot's location on the [Coverage Map](/get-started/coverage-map.md) | | `/rtcm` has data, but the receiver never reaches RTK Fixed | No driver writes the corrections into the receiver (`ublox_gps` 2.3.0, `nmea_navsat_driver`, a driver in another namespace), or `ublox_gps` 3.0.0 runs with its default constellations (GLONASS, Galileo, BeiDou and QZSS off), which leaves the receiver fewer satellites for the fix | Check `ros2 topic info /rtcm --verbose`, use a driver with RTCM input and set all `gnss.*` values to `true` | | No corrections with a lowercase mountpoint | Mountpoint names are case sensitive | Use `AUTO` in capitals | For connection problems that are not specific to ROS 2, see [Common Connection Issues](/support/common-connection-issues.md) and [Troubleshooting & FAQ](/support/troubleshooting-and-faq.md). ## Tips * **Driver first, then `ntrip_client`:** start the GNSS driver, wait for a position, then connect. * **Source the workspace in every terminal** that starts a node built from source; `ros2 pkg prefix ublox_gps` shows which `ublox_gps` the terminal runs. * **One GGA source at 1 Hz** on `nmea` or `fix`, never both. * **`ssl: false`, `ntrip_version` unset, port `2101`, mountpoint `AUTO` in ALL CAPS.** * **More log output:** start the included launch file with `debug:=true`, or put `NTRIP_CLIENT_DEBUG=true` in front of `ros2 run`. * **IP fallback** (`13.56.117.10`, `3.73.41.96` or `54.206.56.130`) only if the hostname does not resolve on the robot. ## Frequently asked questions ### Why does ntrip\_client log "Received sourcetable response from the server"? Because the caster answered with its source table instead of corrections, which RTKdata does for a request without credentials, and `authenticate` is `false` in the node by default; only the included launch file sets it to `True`. Set `authenticate: true` together with the username and password from *RTK Credentials*. If the line stays, check that the mountpoint is `AUTO` in capitals and that the parameter file is applied. ### Does ntrip\_client send GGA to RTKdata on its own? No, `ntrip_client` only forwards to RTKdata what arrives on its `nmea` and `fix` topics. It sends NMEA sentences from `nmea` unchanged and builds a `$GPGGA` sentence from each `NavSatFix` on `fix`, but it creates no position of its own and has no rate limit. Connect exactly one GGA source, preferably the receiver's own NMEA, and set it to 1 Hz at the driver. ### Why does /rtcm show data while the receiver never reaches RTK Fixed? Because data on `/rtcm` only shows that RTKdata sends corrections, not that a driver writes them into the receiver. `ublox_gps` 2.3.0 from apt and `nmea_navsat_driver` have no RTCM input, and a driver in another namespace or on another topic name does not receive the messages. Check the subscription with `ros2 topic info /rtcm --verbose`, then the RTK status of the receiver. With `ublox_gps` 3.0.0, also set all `gnss.*` values to `true`: with its defaults, the driver switches GLONASS, Galileo, BeiDou and QZSS off, which leaves the receiver fewer satellites for the fix. ### Can I use ublox\_gps from apt (ros-humble-ublox-gps) with ntrip\_client? Not for RTK with RTKdata: the apt packages for Humble and Jazzy contain `ublox_gps` 2.3.0, which has no RTCM input, so the corrections never reach the receiver. Build the `ros2` branch (release 3.0.0) from source as shown in the `ublox_gps` tab, or use `ublox_dgnss` from apt. ### Can several robots share one set of RTKdata credentials? Only if your RTKdata account has one data stream for each robot that is connected at the same time: one data stream allows one connection, and two robots on the same stream disconnect each other. Depending on how the account is set up, extra streams come as separate credentials or as one set of credentials with several connections, see [Account & Credentials](/get-started/account-and-credentials.md#using-one-subscription-with-several-devices). Give robots on the same network their own `ROS_DOMAIN_ID` as well. ## Quick reference 1. Install `ros-humble-ntrip-client` or `ros-jazzy-ntrip-client` (1.4.1), or build the `ros2` branch. 2. Write the parameter file with the root key `ntrip_client:`: `host` `rtk.rtkdata.com`, `eu.rtkdata.com` or `aus.rtkdata.com` (IP fallback `13.56.117.10`, `3.73.41.96` or `54.206.56.130`), `port: 2101`, `mountpoint: AUTO`, `authenticate: true`, `username` and `password` in quotes, `rtcm_message_package: rtcm_msgs`, `nmea_max_length: 128`, `rtcm_timeout_seconds: 15`. 3. Use a driver with RTCM input: `ublox_gps` from the `ros2` branch (`tmode3: 0`, all `gnss.*` values `true`, `rate: 1.0`, `publish.nmea: true`), `ublox_dgnss` (`-r rtcm:=/ntrip_client/rtcm`, QoS override on `/fix`) or the GQ7 (`ntrip_interface_enable: True`). Septentrio: `rtk_settings.ntrip_1` in the receiver with `send_gga: "sec1"`, no `ntrip_client`. 4. In each terminal, source the ROS 2 environment, or `~/ros2_ws/install/setup.bash` for a driver built from source. Start the driver, wait for a position, then run `ros2 run ntrip_client ntrip_ros.py --ros-args --params-file ~/rtkdata_ntrip.yaml`. 5. Check the log line `Connected to http://:2101/AUTO`, GGA on `/nmea`, a driver subscription on `/rtcm` and the RTK status of the receiver. 6. For operation, use your own launch file with `respawn=True`, one GGA source at 1 Hz, and one data stream and one `ROS_DOMAIN_ID` per robot. ## Related Guides * [NTRIP & GGA Essentials](/integration-hub/ntrip-clients-and-field-software/ntrip-and-gga-essentials.md): why the caster needs your GGA position before it sends corrections * [NTRIP Server Settings](/get-started/network.md): the regional hosts, IP fallbacks, port 2101 and the `AUTO` mountpoints in one reference * [Account & Credentials](/get-started/account-and-credentials.md#using-one-subscription-with-several-devices): one connection per data stream, and what two devices on the same credentials look like * [Coordinate Systems & Datums](/get-started/coordinate-systems-and-datums.md): which datum `AUTO` and its variants deliver in each region * [Understanding Heights](/get-started/understanding-heights.md): ellipsoidal and orthometric heights, and how to apply a geoid * [u-center (u-blox F9)](/integration-hub/ntrip-clients-and-field-software/u-center-u-blox-f9.md): check and configure a ZED-F9P on a Windows computer before it goes on the robot * [ArduSimple simpleRTK2B / simpleRTK3B](/integration-hub/gnss-rovers-and-receivers/ardusimple-simplertk2b.md): RTKdata setup for the ArduSimple boards with the ZED-F9P * [Septentrio mosaic-X5](/integration-hub/gnss-rovers-and-receivers/septentrio-mosaic-x5.md): the receiver's own NTRIP client, set up without ROS * [Septentrio RxTools](/integration-hub/ntrip-clients-and-field-software/septentrio-rxtools.md): DataLink and the web interface for Septentrio receivers * [Mission Planner (ArduPilot)](/integration-hub/ntrip-clients-and-field-software/mission-planner.md): corrections for ArduPilot vehicles through the ground station * [QGroundControl (PX4)](/integration-hub/ntrip-clients-and-field-software/qgroundcontrol.md): corrections for PX4 vehicles through the ground station * [Unitree Go2 EDU](/integration-hub/robotics/unitree-go2-rtk.md): an external RTK receiver on the Go2 EDU with this ROS 2 setup * [Robotics](/integration-hub/robotics.md): all robot guides and how corrections reach a robot * [Common Connection Issues](/support/common-connection-issues.md): what to check when you connect but no corrections arrive * [NTRIP Clients & Field Software](/integration-hub/ntrip-clients-and-field-software.md): all NTRIP client and field software guides ## Related Industry Solutions * [Robotics](https://rtkdata.com/robotics/) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.rtkdata.com/integration-hub/ntrip-clients-and-field-software/ros2-ntrip-client.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.