Skip to content

Software Setup

ESP32 Firmware

We have intentionally kept the ESP32 firmware as simple as possible - supporting only two modes: Ethernet (mode 1) and WiFi (mode 2). The intention is that you can easily develop your own firmware for the RTK mosaic-X5 using the Espressif ESP IDF if the SparkFun firmware does not meet your needs.

You can of course modify the hardware too, should you want to. The design is completely open-source.

Limitations

The ESP32 firmware we provide is only compatible with basic SSID and Password WiFi authentication. The firmware is not compatible with networks that implement other provisioning methods such as a QR code or a captive portal.

Note

The mosaic-X5 module has numerous capabilities and a multitude of ways to configure and interface with them. Without regurgitating all the information that is documented in Septentrio's user manuals and videos, we have tried to highlight a good majority of the module's aspects.

With that said, please feel free to file an issue if you feel we have missed something that may benefit other users. (Don't forget to provide us with a link to the documentation and what section the information is located.)

Septentrio  mosaic-X5

RxTools Software Suite

Tip

Even if you aren't necessarily interested in it, we highly recommend that users install the RXTools software suite before plugging in their board. For Windows PCs, it also includes the USB driver for the module that enables the Ethernet-over-USB support and virtual COM ports.

Users should install the RXTools software suite on their computer to interact with the mosaic-X5 module through the USB interface. The software package includes the USB-IP driver1 necessary to recognize the board as an ethernet device on Windows PCs (1).

  1. On Linux, the standard Linux CDC-ACM driver is suitable.
System Requirements2
  • Windows 7
  • Windows 8
  • Windows 10
  • Fedora 23 (or later) using Qt technology.
    • The standalone tools (except bin2asc) will run on older distributions.

The minimal hardware requirements (1Hz update3):

  • CPU: 1 GHz processor
  • RAM: 1 GB RAM
  • Screen Resolution: 1024Ă—768 or higher resolution
Installation Instructions2

Users can install RxTools software suite by running the installation executable4(1), located in the RxTools\windows directory of the downloaded *.zip file5. During the installation process, users will be notified if a previous version of RxTools is already installed then the previous version will be uninstalled. Next, users will need to provide an installation directory for the RxTools software suite. Users will then select which of the following applications6 are installed:

  1. For RxTools v22.1.0, the installation filename is RxTools_22_1_0_Installer.exe for Windows PCs.
  • RxControl
  • SBF Converter
  • SBF Analyzer
  • RxLogger
  • RxUpgrade
  • RxDownload
  • RxPlanner
  • Data Link
  • RxAssistant
  • RxLauncher

Warning

It is recommended that users NOT install RxControl as root, for security reasons and to avoid installation overwrites of other system settings. To make RxTools available to more than one user, provide a shared installation directory.

Users can install RxTools software suite by running the installation binary4(1), located in the RxTools/linux-i386/ directory of the downloaded *.zip file5. During the installation, users will be prompted for an installation directory. If there are any previous installations of RxControl, please use a different directory to avoid conflicts.

  1. For RxTools v22.1.0, the installation filename is RxTools_22_1_0_Installer.bin for Linux.
Permission Settings

Once installed, users may need to reconfigure their permission settings:

  • RxTools will need rights to access the /dev/ttyS* serial ports.

    • To access the serial ports, users must be part of the uucp and lock groups (1). This can be configured by editing the /etc/group7 file and adding the username to the lines defining the uucp group and the lock group.

      For example, when adding the user jsmith to the uucp group, users would modify the /etc/group file as shown below:

      uucp:x:14:uucp # (2)!
uucp:x:14:uucp,jsmith # (3)!

    • On Linux machine administered centrally on a local network, ask your system administrator to be included in the uucp and lock groups.

  • RxTools also needs read/write (rw) access(4) to the /dev/ttyS* serial ports.

    • Users can change the permissions with the chmod8 command:

      chmod 660 /dev/ttyS<add port> # (5)!>
  1. On most Linux operating systems, the /dev/ttyS* devices are owned by root and belong to the uucp group with read/write (rw) access. Additionally, the devices are normally locked by writing a file in the /var/lock/ directory, with the same permissions.
  2. Remove
  3. Replace with this line
  4. By default, users will normally have read/write (rw) access to the /dev/ttyS* serial ports.
  5. where users must specify the port number
    e.g. /dev/ttyS0 might be port COM1

Note

In order for these changes to take effect, users must update their environment by logging out and back in.

Be aware that the X-session has to be restarted as well. On most systems, this can be done by pressing the key combination Ctrl + Alt + Backspace

64-bit OS

In order to run the RxTools on a 64-bit Linux operating system, users might have to install the 32-bit version of the C standard library.

  • For Fedora installations, this is the glibc.i686 package.
  • The equivalent for Debian(/Ubuntu) installations is the ia32-libs package.

USB Driver

If users haven't already installed the RxTools software suite on their Windows PC, they will need to install the USB driver1 necessary to recognize and interact with the mosaic-X5 module through the USB interface.

A Windows USB driver for the mosaic-X5 can be installed through two methods:

  • RxTools Software Suite (1)
  • mosaic-X5 GNSS Receiver Module (2)
  1. The driver is installed during the installation process.
  2. The installation file for the Windows USB driver will be available from the mass-storage device when the board is initially connected to the computer.

Once installed, the driver emulates two virtual serial ports, which can be accessed as standard COM ports to the receiver.

Terminal Emulators

Most terminal emulation programs will not make a distinction between virtual or native COM ports. However, for virtual serial ports, the port settings (i.e. baud rate, etc.) are not relevant and the default configuration is used in the terminal emulation program. However, the physical/native COM ports will have the following default setting:

  • Baudrate: 115200bps
  • Data Bits: 8
  • Parity: No
  • Stop Bits: 1
  • Flow Control: None
Having Trouble?

For users who are having trouble installing the USB driver, we have an archived version (v3.0.29) of the installation file. Users can download version 3.0.2 of the driver, by clicking on the button below.

On Linux, the standard Linux CDC-ACM driver is suitable for the mosaic-X5 module.

Web Interface

With the USB driver installed, the mosaic-X5 module supports Ethernet-over-USB. The default IP address allocated for the Ethernet-over-USB interface is 192.168.3.1. This IP can be entered in any browser to open a connection to the receiver's Web Interface as shown below.

navigation tabs in the web interface

All the drop-down navigation tabs in the web interface.

Info

The default IP address cannot be changed; this feature is only to be used when a single receiver is connected to your computer.

Invalid IP Address (WiFi Only)

One of the documentation pages on Septentrio's website, specifies a default IP address of 192.168.20.1 for the web interface. However, that address is for a WiFi enabled product and cannot be used with this product.

Espressif logo ESP32

USB Driver

Users will need to install a USB driver for the CH340 serial-to-USB chip, in order to communicate with the ESP32 module. The latest USB drivers for the CH340 are available from the manufacturer, on the WCH website:

Need Directions?

For users having trouble installing the CH340 USB driver, check out our video and hookup guide:

Terminal Emulator

In order to configure the WiFi settings on the ESP32, users will need to install a serial terminal emulator on their computer.

For Windows computers, we highly recommend TeraTerm.

Some Linux operating systems will already have the screen terminal emulator preinstalled.

Need Directions?

Check out our hookup guide to install your favorite terminal emulator:

WiFi Credentials for the Network Bridge

With the CH340 USB driver and a terminal emulator installed, users will now be able to configure the WiFi credentials on the ESP32. In order for the firmware to operate properly, users should have their RTK mosaic-X5 assembled with the network bridge in WiFi Mode.

WiFi Mode

WiFi Mode (PNG) for the RTK mosaic-X5.

1 - Open a Serial Terminal
Open the connection to the CH340 using a baud rate of 115200bps

2 - Put the ESP32 firmware into WiFi mode

Console Prompt

Console Prompt (PNG) for changing the RTK mosaic-X5 firmware mode.

  • Type help and hit enter to see the help.

    Console Help
    Console Help (PNG) for changing the RTK mosaic-X5 firmware mode.

  • Type show to see the current configuration.

    Console Show
    Console Show (PNG) for changing the RTK mosaic-X5 firmware mode.

  • By default the firmware will be in Mode: 1 (Ethernet). To change the mode to Mode: 2 (WiFi), we type:

    Terminal

    set -m 2

    Long Arguments

    The console supports both short and long args, so we could type:

    set --mode=2

  • To set the WiFi SSID, type one of:

    Terminal

    set -s YOUR_SSID
set --ssid=YOUR_SSID

    • Likewise, to set the WiFi password, type one of:

      Terminal

      set -p YOUR_PASSWORD
set --password=YOUR_PASSWORD

    • To save time, you can set all three together with one of:

      Terminal

      set -m 2 -s YOUR_SSID -p YOUR_PASSWORD
set --mode=2 --ssid=YOUR_SSID --password=YOUR_PASSWORD

  • Finally, type restart to restart the firmware with the new settings:

    Terminal

    restart
    NULL (empty) password

    To clear the password - making it NULL / empty - type one of:

    Terminal

    set -p %00
set --password=%00

Once the mosaic-X5 has acquired a satellite signal and is connected to the WiFi network, the OLED will display the antenna's position as Latitude (Lat), Longitude (Long) and Altitude (Alt); the WiFi IP (Internet Protocol) network address. The firmware mode, SSID and password are stored in flash (non-volatile) memory. After changing them, you can disconnect the computer and power the RTK mosaic-X5 using the supplied wall adapter.

WiFi Connections

WiFi Connections (PNG) for the RTK mosaic-X5.

Info

When powering the RTK mosaic-X5 on for the first time, you may see the firmware restart (reboot) several times while it waits for the mosaic-X5 to initialize. This is not an error or anything to be concerned about.

With the RTK mosaic-X5 operating with the configured WiFi network bridge, users should be able to open a web browser on any connected device and navigate to the IP address shown on the OLED display. The browser should be able to access the mosaic-X5's internal web page, where users can configure the mosaic-X5.

ESP32 Firmware - Update

The firmware running on the ESP32 is based heavily on the firmware for the Septentrio mowi. SparkFun added some bells and whistles, primarily to support the OLED display. The full firmware source code is available in the GitHub repo. It was developed and compiled with the Espressif ESP-IDF version 5.1.5.

The most recent version of the firmware is v1.0.5, released on April 22nd 2026. If you purchased your RTK mosaic-X5 before this date, you may enjoy the improvements in v1.0.5:

Changes added at v1.0.5:

  • The firmware now supports a username and password for the X5 itself
    • This is to support mosaic-X5 firmware versions >= 4.15.1 where a username and password are mandatory on IP interfaces (webUI, Ethernet-over-USB, CLI over TCP/IP)
    • The username and password are not mandatory on COM and USB (virtual COM) ports, unless you set the Default Access Level Per Interface (setDefaultAccessLevel / sdal) to none for COM and/or USB ports
    • The ESP32 firmware only needs to know the username and password if the default access levels have been changed
    • For more information about the X5 Log-in procedure, please read this Septentrio documentation
    • If you upgrade the X5 firmware to 4.15.1:
      • Enter your user-defined username and password, using the Factory credentials RxAdmin and S3pt3ntr10, as described in the Log-in procedure
      • You will need to enter the user-defined username and password whenever you connect over an IP interface
      • Logging in via the ESP32 on a COM port does not remove the need to log in on IP interfaces. You still need to log in on each IP interface individually and separately
      • Upgrade the ESP32 Firmware to v1.0.5, following the procedure described below
      • If the ESP32 needs to know the username and password: in the ESP32 Serial Terminal / console, use option set -u to set the X5 username and option set -x to set the X5 password
      • Turn the RTK mosaic-X5 off and back on again

Changes added at v1.0.4:

  • The firmware now includes an efficient SBF and NMEA parser
    • Previously the NMEA GPGGA and SBF IPStatus messages were polled, this resulted in the OLED being updated once every ~2 seconds
    • In v1.0.4: NMEA Stream10 carries the GPGGA message at 1Hz; SBF Stream10 carries the IPStatus message OnChange
    • The OLED is now updated on the arrival of the GPGGA message, at exactly 1Hz
  • The firmware now ensures that the SBF and NMEA protocols are enabled for output on X5 COM4
    • Previously, the firmware would stall if either SBF or NMEA were disabled
  • The firmware now supports the NMEA GN Talker ID, in addition to GP
    • Previously setting the Talker ID to GN would cause the firmware to stall
  • The OLED now displays the Latitude and Longitude in DD MM SS.SSSS format, to match the format of the X5's internal web page
    • Previously the format was DDMM.MMMMMM, copied directly from the GPGGA message
  • The firmware will perform a soft reset of the GNSS during startup - if needed
    • The X5 can go into a Ready for SUF download state if it is reset four times with no antenna connected
    • This can be cleared with a soft reset

To upgrade the ESP32 firmware, using a Windows PC:

  • Download the complete RTK mosaic-X5 repo as a Zip file:
  • Alternatively, download the latest or a previous release (Source code zip) from the repo releases page
  • Unzip the Zip file (Extract All)
  • Open a Command Prompt and navigate into the Firmware sub-folder
  • Connect the RTK mosaic-X5 “CONFIG ESP32” port to your PC using a USB-C cable
    • It should appear in Device Manager as a CH340 COM port
  • Run ESP32_FLASH_ERASE.bat to completely clear the ESP32 memory
    • The .bat file should find the COM port number for you
    • If you see the error 'wmic' is not recognized as an internal or external command, operable program or batch file, you will need to install WMIC or provide the COM port manually:
ESP32_FLASH_ERASE.bat COM1
  • If you need to run esptool manually, use the following replacing COM1 with your COM port:
esptool.exe --chip esp32 -p COM1 -b 460800 erase_flash
  • Then run ESP32_FLASHER.bat to upload the firmware
    • The .bat file should find the COM port number for you
    • If you see the error 'wmic' is not recognized as an internal or external command, operable program or batch file, you will need to install WMIC or provide the COM port manually:
ESP32_FLASHER.bat COM1
  • If you need to run esptool manually, use:
esptool.exe --chip esp32 -p COM1 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 4MB 0x1000 RTK_mosaic-X5_Firmware\build\bootloader\bootloader.bin 0x10000 RTK_mosaic-X5_Firmware\build\RTK_mosaic-X5_Firmware.bin 0x8000 RTK_mosaic-X5_Firmware\build\partition_table\partition-table.bin

On Linux / MacOS, you can pip install esptool and then run the above commnds, replacing esptool.exe with esptool

ESP32 Firmware - Compiling from source

This is information about how to compile the RTK mosaic-X5 firmware from source. This is for advanced users who would like to modify the functionality of this RTK product.

How SparkFun does it

At SparkFun, we use GitHub Actions and a Workflow to compile each release of the RTK mosaic-X5 firmware. We run the build-for-release workflow directly on GitHub. A virtual ubuntu machine installs the Espressif IDF and generates the firmware binary for the ESP32. The updated firmware, bootloader and partition-table .bin files are pushed to the repo. We then create the new release manually.

You are welcome to clone or fork this repo and do the exact same thing yourself. But you may need a paid GitHub Pro account to run the GitHub Actions, especially if you keep your clone / fork private.

The non-release-build workflow builds the firmware binaries and attaches them as an Artifact to the workflow run. Navigate to Actions Non-Release Build, select the latest run of Non-Release Build, the binary files are in the Artifact. This may be useful if you want to build the firmware on GitHub but don't want the changes pushed to your repo.

You can then use (e.g.) ESP32_FLASHER.bat to upload the binary onto the ESP32.

Using Docker

Here is a step-by-step guide for how to install Docker and compile the firmware locally from scratch:

Clone, fork or download the RTK mosaic-X5 repo

To build the RTK mosaic-X5 firmware, you obviously need a copy of the source code.

If you are familiar with Git and GitHub Desktop, you can clone the RTK mosaic-X5 repo directly into GitHub Desktop:

Clone RTK mosaic-X5 with GitHub Desktop

If you want to contribute to RTK Everywhere, and already have a GitHub account, you can Fork the repo:

Fork RTK Everywhere

Clone your fork to your local machine, make changes, and send us a Pull Request. This is exactly what the SparkFun Team do when developing the code. Please use the release_candidate branch for any such changes. We are very unlikely to merge anything directly into main, unless it is (e.g.) docs corrections or improvements.

If you don't want to do either of those, you can simply Download a Zip copy of the repo instead. You will receive a complete copy as a Zip file. You can do this from the green Code button, or click on the icon below to download a copy of the main (released) branch:

Download ZIP

For the real Wild West experience, you can also download a copy of the release_candidate code branch. This is where the team is actively changing and testing the code, before it becomes a full release. The code there will usually compile and will usually work, but we don't guarantee it! We may be part way through implementing some breaking changes at the time of your download...

Download ZIP - release candidate

Install Docker Desktop

  • (Optional) Head to Docker and create an account. A free "Personal" account will cover occasional compilations of the firmware
  • Download and install Docker Desktop - there are versions for Mac, Windows and Linux. You may need to restart to complete the installation.
  • Run the Desktop
    • You don't need to have an account and you don't need to be signed in
    • You only need to be signed in if you want to store or share your Container on Docker Hub
    • If you don't sign in, Docker Desktop will run in Personal mode - which will cover local compilations of the firmware
  • On Windows, you may see an error saying "WSL needs updating Your version of Windows Subsystem for Linux (WSL) is too old". If you do:
    • Open a command prompt
    • Type wsl --update to update WSL. At the time of writing, this installs Windows Subsystem for Linux 2.6.1
    • Restart the Docker Desktop
  • If you are using Docker for the first time, the "What is a container?" and "How do I run a container?" demos are useful - but not essential
    • On Windows, you may want to give Docker Desktop permission to access to your Network, so it can access (e.g.) HTML ports
    • You can Stop the container and Delete it when you are done
  • You may want to prevent Docker from running when your machine starts up
    • Uncheck "Start Docker Desktop when you sign in to your computer" in the Desktop settings

Using Docker to create the firmware binary

  • Make sure you have Docker Desktop running. You don't need to be signed in, but it needs to be running.
  • Open a Command Prompt and cd into the SparkFun_RTK_mosaic-X5 folder
  • Check you are in the right place. Type dir and hit enter. You should see the following files and folders:
    .gitattributes
    .gitignore
    CONTRIBUTING.md
    ISSUE_TEMPLATE.md
    LICENSE.md
    mkdocs.yml
    README.md
  • cd Firmware and then dir again. You should see:
    RTK_mosaic-X5_Firmware
    compile_run_terminal.bat
    compile_with_docker.bat
    Dockerfile
    ESP32_FLASH_ERASE.bat
    ESP32_FLASHER.bat
    esptool.exe

  • The file that does most of the work is the Dockerfile

  • Run compile_with_docker.bat. It does everything for you:

Output of the compile batch file

  • Hey presto! You have your newly compiled firmware binary!
  • The three new files are:
    • RTK_mosaic-X5_Firmware\build\RTK_mosaic-X5_Firmware.bin
    • RTK_mosaic-X5_Firmware\build\bootloader\bootloader.bin
    • RTK_mosaic-X5_Firmware\build\partition_table\partition-table.bin

You can then use (e.g.) ESP32_FLASHER.bat to upload the binary onto the ESP32.

  1. On Linux, the standard Linux CDC-ACM driver is suitable. ↩↩↩

  2. The system requirements and installation instructions are from the RxTools v22.1.0 user manual. This information may change in later iterations of the software suite. Please refer to the user manual (of the version you are utilizing) for the most accurate information. ↩↩

  3. Higher data rates will require higher CPU speed and more memory capacity. ↩

  4. Users will need administrative privileges to install the RxTools software. ↩↩

  5. Users may need to extract the RxTools installation files from the downloaded, compressed file. ↩↩

  6. Please see the release notes for the issues and limitations of the RxTools applications. ↩

  7. Requires c privileges. ↩

  8. Changing these permissions also requires root privileges. ↩

  9. For the latest USB driver from Septentrio, please install their driver through the RxTools software suite.
    This driver version was archived at the time that the mosaic-X5 hookup guide was written. Please do not request for the file to be updated. ↩