YCCaster

# Configuration

The caster is managed through configuration files. All files should be in YAML format (opens new window) and should be located in the same folder as the executable file.

  • caster.yml - The main configuration file
caster:
  host: yccaster.com
  port: 2101
  identifier: Demo caster
  operator: Hedgehack OU
  nmea: 0
  country: EST
  latitude: 59.44
  longitude: 24.74
  fallback_host: 0.0.0.0
  fallback_port: 0
  misc: ""
  • networks.yml - List of NTRIP network that should be displayed in the SOURCE TABLE
- identifier: SAPOS
  operator: SAPOS
  authentication: B
  fee: 'Y'
  web-net: 'http://igs.ifag.de/'
  web-str: 'http://igs.ifag.de/'
  web-reg: euref-ip@ifag.de
  misc: ''

# Authorization

By default, YCCaster accepts any valid NTRIP connections. There are several strategies that you may employ to protect your caster.

# File

File strategie depends on 2 files that contain a list of mount points and a list of clients that are allowed to connect to the caster.

To enable it, you should specifile these files in caster.yml

caster:
  host: caster.de
  port: 2101
  identifier: YCCaster v1
  operator: MYNET
  nmea: 0
  country: JPN
  latitude: 10.12
  longitude: 10.12
  fallback_host: 0.0.0.0
  fallback_port: 0
  misc: ''
configuration:
  auth:
  - type: file
    options:
      mount-points: mountpoints.yml
      clients: clients.yml

And create respected files

mountpoints.yml

- mount-point: BCEP00BKG0
  password: 12345
  description:
    identifier: Barcelona
    format: RTCM 3.2
    format-details: 1006(15),1008(15),1013(60),1019,1020,1033(15),1075(1),1085(1),1095(1),1230(15)
    carrier: 2
    nav-system: GPS+GLO+GAL
    network: EUREF
    country: ESP
    latitude: 41.41
    longitude: 2.00
    nmea: 0
    solution: 0
    generator: LEICA GR10
    compr-encryp: none
    authentication: B
    fee: N
    bitrate: 6200
    misc: RGP, Ville de Cannes

clients.yml

- username: myrover
  password: 12345

Now, only NTRIP server and client that are listed will be allowed. You may restrict only server or only client connections, by specifying only one of the files in config.

caster.yml

configuration:
  auth:
  - type: file
    options:
      mount-points: mountpoints.yml

# Http

If you are building something bigger, local files may limit your flexibility. Http starategie will allow implement complex authorization logic. Caster will send http requests to an API and will allow or reject NTRIP connections depending on server responses.

To enable this strategie, specify url of your server endpoint and secret that will confirm that request came from your caster.

caster.yml

configuration:
  auth:
  - type: http
    options:
      url: http://api.mycompany.com/ntrip_auth
      secret: super_secret

When the caster receives a request from the NTRIP server or client, it in turn will send a request API.

Server connection authorization request example:

POST / HTTP/1.1
Host: 127.0.0.1:3000
Content-Length: 170
Accept: application/json
Content-Type: application/json
X-Api-Key: super_secret
Accept-Encoding: gzip

{
   "method":"SOURCE",
   "password":"test",
   "uri":"/Test",
   "http_version":"HTTP/1.0",
   "headers":[
      {
         "name":"User-Agent",
         "value":"NTRIP YCServer"
      }
   ],
   "type":"server",
   "ntrip_version":1
}

Client connection authorization request example:

POST / HTTP/1.1
Host: 127.0.0.1:3000
Content-Length: 203
Accept: application/json
Content-Type: application/json
X-Api-Key: super_secret
Accept-Encoding: gzip

{
   "method":"GET",
   "uri":"/Test",
   "http_version":"HTTP/1.0",
   "headers":[
      {
         "name":"User-Agent",
         "value":"NTRIP YCServer"
      },
      {
         "name":"Authorization",
         "value":"Basic cGFrOjEyMzQ1"
      }
   ],
   "type":"client",
   "ntrip_version":1

Caster will authorize NTRIP connection if it gets 2XX http response code and rejects with any other. In case of server connection, the caster will also expect to receive mount point description in the response body.

{
  "identifier": "Barcelona",
  "format": "RTCM 3.2",
  "format-details": "1006(15),1008(15),1013(60),1019,1020,1033(15),1075(1),1085(1),1095(1),1230(15)",
  "carrier": 2,
  "nav-system": "GPS+GLO+GAL",
  "network": "EUREF",
  "country": "ESP",
  "latitude": 41.41,
  "longitude": 2,
  "nmea": 0,
  "solution": 0,
  "generator": "LEICA GR10",
  "compr-encryp": "none",
  "authentication": "B",
  "fee": "N",
  "bitrate": 6200,
  "misc": "RGP, Ville de Cannes"
}

# Mixed

It's possible to use a mixed authorization strategy. For example, you can list some mount points and clients in text files, and use http for the rest of them.

caster.yml

configuration:
  auth:
  - type: file
    options:
      mount-points: mountpoints.yml
      clients: clients.yml
  - type: http
    options:
      url: http://api.mycompany.com/ntrip_auth
      secret: super_secret

YCCaster will check files first, and if it does not find a match in files, it will send http request.

# Nearest group

The Nearest group feature allows NTRIP clients to connect to the geographically closest base station within a defined group, instead of selecting a specific mount point manually. This is especially useful for mobile clients that change location frequently.

# 🔧 How It Works

  1. Mount Point Grouping
    Base stations are grouped into Nearest Groups, which are named collections of mount points. Each group has a unique name (e.g., FloridaRTCM3), and each base can be assigned to a group either:

    • In the mountpoints.yml config file
    • Or dynamically via HTTP authentication response

  2. Client Connection
    Clients can connect to the group by requesting the group name instead of a mount point:

    GET /FloridaRTCM3 HTTP/1.1
Host: ntrip.example.com
Ntrip-Version: Ntrip/2.0
User-Agent: NTRIP ExampleClient/2.0
Authorization: Basic base64credentials

  3. Sending Location
    Clients must send their current GPS position using an NMEA GGA sentence. This can be provided:

    • In the Ntrip-GGA header during connection, or
    • As a plain line within the first 30 seconds after connecting

    Example:

    $GNGGA,123610.00,0405.1171,N,07323.2386,E,4,49,0.4,-91.6814,M,0.0000,M,5.0,1024*7D

  4. Automatic Base Selection
    YCCaster reads the GGA message, determines the client's location, and selects the closest available base station within the group. The connection is then redirected to that base.

  5. Live Position Updates
    If the client sends new GGA messages (e.g., it moved), YCCaster will:

    • Check if the currently selected base is still the closest
    • If not, it will switch to a closer base and send:
      • ntrip-session-ended
      • ntrip-session-started

# 🗂 Configuring Nearest Groups

In your mountpoints.yml, you can define the group using the nearest-group field:

- mount-point: BCEP00BKG0
  password: 12345
  nearest-group: FloridaRTCM3
  description:
    identifier: Barcelona
    format: RTCM 3.2
    latitude: 41.41
    longitude: 2.00
    ...

Or provide it dynamically in your authentication response:

{
   "nearest-group":"FloridaRTCM3",
   "description":{
      "latitude":41.41,
      "longitude":2.00,
      ...
   }
}

# Group Name Rules:

  • May include letters, numbers, dashes (-), and underscores (_)
  • Must be unique

# ❗️Error Handling

If the client connects to a Nearest Group but fails to provide a GGA message within 30 seconds, it will be disconnected with the message:

NMEA position not provided

# Events

Things happen. And YCCaster can report about such events.

Event name Description
caster-ready Emits when caster is ready to accept incoming connections.
caster-terminate Emits when caster get termination signal.
connection-accepted Emits when incoming TCP connection received.
connection-terminated Emits when incoming TCP connection terminated.
ntrip-request-accepted Emits when NTRIP request was authorized.
ntrip-request-rejected Emits when NTRIP request was rejected.
ntrip-session-started Emits when NTRIP session was started.
ntrip-session-ended Emits when NTRIP session was was ended.
ntrip-session-server-data Emits when data from NTRIP server connection received. Data is encoded in base64.
ntrip-session-client-data Emits when data from NTRIP client connection received. Data is encoded in base64.
caster-status-10 Emits when every 10 seconds. Valid interval is between 1 and 3600.
ntrip-session-status-25 Emits when every 50 seconds. Valid interval is between 1 and 3600.

Caster events example:

            "headers":[
               {
                  "name":"User-Agent",
                  "value":"NTRIP YCServer"
               }
            ],
            "type":"server",
            "ntrip_version":1
         }
      }
   },
   {
      "name":"ntrip-session-started",
      "timestamp":1621776197,
      "data":{
         "address":"31.153.88.250:48114",
         "started_at":1621776197
      }
   },
   {
      "name":"ntrip-session-ended",
      "timestamp":1621776204,
      "data":{
         "address":"31.153.88.250:48114",
         "started_at":1621776197,
         "ended_at":1621776204,
         "type":"server",
         "name":"Test",
         "bytes_transferred":66560
      }
   },
   {
      "name":"connection-terminated",
      "timestamp":1621776204,
      "data":{
         "address":"31.153.88.250:48114",
         "reason":"session_finished"
      }
   }
]

# File

Events can be saved to local file.

caster.yml

configuration:
  events:
  - type: file
    options:
      path: /var/caster/session.log
      types:
        - caster-ready
        - caster-terminate
        - connection-accepted
        - connection-terminated
        - ntrip-request-accepted
        - ntrip-request-rejected
        - ntrip-session-started
        - ntrip-session-ended

# Http

Or they can be send to remote server via http.

caster.yml

configuration:
  - type: http
    options:
      url: api.youcors.com/v1/session
      secret: super_secret
      interval: 1000
      limit: 100
      types: 
        - caster-ready
        - caster-terminate
        - connection-accepted
        - connection-terminated
        - ntrip-request-accepted
        - ntrip-request-rejected
        - ntrip-session-started
        - ntrip-session-ended

Events are sent in batches when number of events reaches the limit or when the interval has passed. The interval is sets in miliseconds.

# API

YCCaster has a built-in http server that provides several endpoints to monitor NTRIP caster status. By default the server will start on an 8080 port, but you may specify a different port and address. Some of endepoints are protected by X-API-Key header others are open to every request.

caster.yml

configuration:
  api:
    address: 0.0.0.0
    port: 8081
    api-keys:
      - secret

# Endpoints

GET /health

Health endpoint return response code 200 with empty body if caster is up and running and is ready to accept incoming NTRIP connections.

Request example:

GET /health HTTP/1.1
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:34:17 GMT
Content-Length: 0

GET /status

Status endpoint responds with current caster status.

Request example:

GET /status HTTP/1.1
X-API-Key: secret
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:39:48 GMT
Content-Type: application/json
Content-Length: 144

{
   "data":{
      "address":"[::]:2101",
      "version":"0.0.14",
      "server_connections":1,
      "client_connections":0,
      "started_at":"2021-05-26T17:33:51.831462217Z"
   }
}

GET /mountpoints

Mount points endpoint return list of active server sessions.

Request example:

GET /mountpoints HTTP/1.1
X-API-Key: secret
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:43:33 GMT
Content-Type: application/json
Content-Length: 131

{
   "data":[
      {
         "name":"Test",
         "address":"62.228.76.148:49220",
         "bytes_transferred":43008,
         "started_at":"2021-05-26T17:43:29.915470675Z"
      }
   ]
}

GET /clients

Clients endpoint return list of active client sessions.

Request example:

GET /clients HTTP/1.1
X-API-Key: secret
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:55:25 GMT
Content-Type: application/json
Content-Length: 117

{
   "data":[
      {
         "address":"62.228.76.148:43952",
         "bytes_transferred":53248,
         "started_at":"2021-05-26T17:55:20.798783908Z"
      }
   ]
}

# License key

To run YCCaster in commercial mode, you need to specify a license key. Multiple YCCaster instances may be launched with the same key caster.yml

licence-key: K5UMY-73LLH-BSWFB-55V52

←