Configure the receiver and caster

Status: Draft

Purpose

Prepare a safe configuration for the receiver, caster, stream, logging, RTCM description, and monitor. Learn when to use survey-in and when fixed mode is permitted.

Learning objectives

After this lesson, you can:

1. Explain each configuration group.
2. Select survey-in or fixed mode safely.
3. Configure a mountpoint and placeholder client credentials.
4. Set stream, logging, RTCM, and monitoring controls.
5. Review a configuration without exposing secrets or coordinates.

Prerequisites

Complete Lesson 2. You need basic YAML editing skills. Use only a sanitised exercise template.

Key terms

• Serial path: The operating-system path used to open the receiver.
• Survey-in: A receiver process that estimates the base position over time.
• Fixed mode: A receiver mode that uses supplied antenna coordinates.
• Ellipsoid height: Height relative to the GNSS reference ellipsoid.
• Queue: A bounded holding area for data waiting for one client.
• Stale data: Stream data that has not been updated within the configured time.

Concept explanation

Configuration groups

The application requires serial, caster, stream, and logging. It applies defaults to many survey, rtcm, and web values.

Receiver mode decision

Fixed mode is selected only when all four values are present:

• latitude
• longitude
• height
• fixed_position_accuracy

If one value is blank or absent, the application uses survey-in. Do not insert guessed values to force fixed mode. A base-position error is also present in rover positions.

Latitude must be from -90 to 90. Longitude must be from -180 to 180. Accuracy, survey duration, survey accuracy limit, and command timeout must be greater than zero.

The receiver settings are applied to RAM after each serial connection. The caster waits for the receiver acknowledgement. It does not serve an unconfirmed base position.

Network and credential controls

Use a loopback or trusted-network listener during learning. Basic credentials are reusable secrets. Use placeholders in the lesson and submitted evidence. Do not enable debug request logging with real clients because the authorisation header can appear in logs.

The web monitor has no built-in authentication. Keep it on the trusted network or bind it to a safe local address.

Stream behaviour

Each client has a bounded queue. A slow client loses its oldest queued frame instead of blocking the receiver reader. The write timeout limits a stalled socket. The stale-data timeout detects a stream that stops producing data.

cast_hz and max_buffer_bytes are loaded for compatibility but are not used by the current broadcaster. Do not teach them as active controls.

Worked demonstration

Review this sanitised decision, not a production configuration:

serial:
  port: "<serial-device>"
  baudrate: <approved-baud-rate>
  timeout: <approved-read-timeout>
caster:
  host: "<trusted-listener>"
  port: 2100
  mountpoint: "<course-mountpoint>"
  users:
    - username: "<course-user>"
      password: "<course-password>"
  sourcetable_name: "<course-stream-name>"
survey:
  latitude: null
  longitude: null
  height: null
  fixed_position_accuracy: null
stream:
  client_queue_size: 200
  client_write_timeout: 5
  stale_data_timeout: 10
  serial_retry_seconds: 3

Expected result: the blank fixed-position set selects survey-in. It does not publish a guessed fixed position.

This fragment is an instructional example. It is not yet the approved complete project configuration template.

Guided practice

1. Start with the supplied sanitised template.
2. Select the hardware or test-data pathway.
3. Enter placeholder serial and listener values.
4. Select survey-in unless all fixed-position values are approved.
5. Add a course mountpoint and placeholder user.
6. Review stream timeouts and queue size.
7. Keep the monitor inside the trusted boundary.
8. Check the file for real secrets, hostnames, coordinates, and paths.

Expected result: the structure is complete and safe for instructor review.

Independent practice

Correct a configuration that has these faults:

• only latitude and longitude are supplied for fixed mode
• the monitor listens on an untrusted interface
• a real password appears in submitted evidence
• fixed_position_accuracy is zero
• debug logging is enabled with real credentials

Explain each correction.

Checks for understanding

1. Which four values enable fixed mode?
2. What happens when one fixed-position value is blank?
3. Why must the receiver acknowledge its mode before publication?
4. Why does each client need a separate bounded queue?
5. Which compatibility values are not active broadcaster controls?

Assessment and evidence

Correct a supplied unsafe configuration. Submit a sanitised copy and a decision record. The record must explain receiver mode, listener scope, authentication, stream controls, and monitor exposure.

Troubleshooting guidance

Summary

Configuration joins the software to one site. Use fixed mode only with a complete approved antenna position. Keep credentials and site details out of lesson evidence. Treat the caster and monitor as trusted-network services.

Source references

• SRC-PROJECT-OVERVIEW: configuration groups and safety guidance
• SRC-PROJECT-CODE: implemented fields, defaults, and validation
• SRC-RECEIVER-GUIDANCE: receiver-specific context; exact vendor revision remains unresolved