search

Fraunhofer-IIS / ogrp

OGRP - The Open Gnss Receiver Protocol
10 stars 8 forks source link
gnss json-schema

readme

OGRP

The Open Gnss Receiver Protocol (http://fraunhofer-iis.github.io/ogrp/).

Build Status

Introduction

Previous attempts to define an exchange protocol for GNSS related data have been proposed only by manufacturers for their own products with proprietary wire protocols or for limited applications, e.g. RTCM, RINEX, NMEA.

OGRP (Open GNSS Receiver Protocol) tries to be a protocol for many different use cases in the domain of GNSS may it be output of raw measurements from receivers over a physical wire connection but also supporting RPC (remote procedure call) like JSON-RPC.

OGRP is a protocol based on JSON [RFC4627].

For the use in RPC, zerorpc (http://zerorpc.dotcloud.com/) is recommended as a transport mechanism. Protocols that already provide message framing should use one JSON object per message. Stream oriented protocols, e.g. a plain TCP socket, a file, a serial line, should use the media type "application/json-seq". See [RFC7464]. Files containing OGRP should have the filename extension .ogrp.

OGRP is meant to be extendable and future-proof rather than optimized regarding performance for a specific case. Many messages are not defined but it should be easy to define one on your own fitting into the common scheme. OGRP should also support complete wrapping of other message protocols in itself, e.g. any message used in proprietary protocols should be expressable by OGRP or embeddable in OGRP messages.

Conventions used

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

The underlying format used for OGRP is JSON. Consequently, terms and types are to be interpreted as described in section 1 of [RFC4627].

The OGRP protocol definition uses the ABNF syntax [RFC5234]. where appropriate but mixes with examples in JSON syntax.

License information

Creative Commons License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Reasoning: Licenses for Protocols

OGRP Trademark Policy

Fraunhofer owns the registered EU trademark „OGRP“ (No 015314545). This chapter outlines the policy of Fraunhofer regarding the use of the trademark „OGRP“. Any use of the trademark „OGRP“ must be in accordance with this policy. Fraunhofer encourages the use of the trademark „OGRP“ if you are implementing the Open Gnss Receiver Protocol in your products. However, any use of the trademark „OGRP“ must comply with all of the conditions set forth in this Trademark Policy as follows:

  1. Any use of the trademark „OGRP“ depends on your compliance with the CC-BY-SA 4.0 license for the specification of the Open Gnss Receiver Protocol. If you do not comply with the CC-BY-SA 4.0 license for the use of the specification of the Open Gnss Receiver Protocol you are not permitted to use the trademark „OGRP“ for your products and your right to use the trademark terminates automatically. For the avoidance of doubt, implementations of the Open Gnss Receiver Protocol are not covered by the CC-BY-SA 4.0 license. This license is limited to the specification of the protocol as published at https://github.com/Fraunhofer-IIS/ogrp in the „master“ branch and Adapted Material thereof (as defined in the CC-BY-SA 4.0 license). Any use of the trademark „OGRP“ that is permitted by statutory law shall not be restricted by this trademark policy.

  2. You may distribute products implementing the OGRP specification as published at https://github.com/Fraunhofer-IIS/ogrp in the „master“ branch or any other repository Fraunhofer may use in the future for the specification of OGRP. In this case no specific requirements need to be met for the use of the trademark „OGRP“.

  3. You may distribute products implementing the OGRP specification in a modified version than the one published at https://github.com/Fraunhofer-IIS/ogrp in the „master“ branch, or any other repository Fraunhofer may use in the future for the specification of OGRP. In this case you have to commit your modifications at https://github.com/Fraunhofer-IIS/ogrp under the CC-BY-SA 4.0 license to allow any third party the use of the modified specification.

  4. You may publish modified versions of the OGRP specification than the one published at https://github.com/Fraunhofer-IIS/ogrp in the „master“ branch under the CC-BY-SA 4.0 license. You are encouraged to inform Fraunhofer about such publications at https://github.com/Fraunhofer-IIS/ogrp.

Maturity

Maturity indicator: Is this an experimental, draft, stable, legacy, or retired specification?

A: OGRP is considered in draft state.

Extending the protocol / specification

Consider the following:

Message specification

An OGRP message is composed of one JSON object. Two mandatory fields exist

msg = {
    "protocol": protocol,
    "id": id,
    ...
}

protocol = "OGRP1"
id = string ; lower-case, underscore separated id, e.g. "measurement", ...

The additional content in the message is dependant on the message id. Optional fields are allowed and must be ignored by parsers if unknown (according to JSON).

Example definitions

A message of id 'measurement' for raw measurements of a GNSS receiver, e.g. including pseudorange and carrier phase measurements for multiple satellites on different channels, can look like this:

measurement = {
    "protocol": protocol,
    "id": "measurement",
    "sw_version": int / hex,
    "timestamp": float / string, ; (see Representing time and date)
    "time_status": time_status,
    "channel_measurement": [*channel_measurement]
}

time_status = string, ; "FREE_RUNNING" / "COARSE" / "GPS_SYNCED" / ...

channel_measurement = {
    "gnss": string, ; "GPS" / "GALILEO" / "GLONASS" / "SBAS" / ...
    "satellite_id": int, ; starting at 1
    "signal_type": string, ; "L1CA" / "L5I" / "E5aI" / ...
    "channel_state": channel_state,
    "doppler": float, ; (Hz)
    "carrier_phase": float, ; (cycles)
    "signal_to_noise_ratio": float, ; (dB)
    "locktime": float, ; (seconds)
    "pseudorange": float, ; (meters)
    "code_phase": float, ; (chips)
    "sw_channel_number": int ; starting at 0
    "hw_channel_number": int ; starting at 0
}

channel_state = string, ; "IDLE" / "SEARCHING" / "PULL_IN" / "LOCKED" / "SYNCED"

Key naming

Names of keys should be explicit and unambiguous.

If desired, abbreviations can be used but should be properly defined using a title element in the schema.

Usage

Applications using OGRP for input or output should define the supported messages as JSON Schema [json-schema].

An example how to extend the OGRP core schema:

{
    "$id": "http://example.org/pvt-input-schema#",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "Minimum schema for a PVT application",
    "type": "object",
    "properties": {
        "protocol": { "type": "string" },
        "id": { "type": "string" },
        "timestamp": { "$ref": "http://ogrp.org/definitions/timestamp" },
        "channel_measurements": {
            "type": "object",
            "properties": {
                "satellite_id": {
                    "type": "integer",
                    "minimum": 1
                },
                "pseudorange": {
                    "type": "number"
                }
            }
        },
        "satellites": {
            "type": "object",
            "properties": {
                "satellite_id": {
                    "type": "integer",
                    "minimum": 1
                },
                "position": {
                    "type": "object",
                    "properties": {
                        "x": { "type": "number" },
                        "y": { "type": "number" },
                        "z": { "type": "number" }
                    }
                }
            }
        }
    }
}

Security considerations

See JSON considerations on this topic in [RFC4627].

No further security mechanisms are designed into OGRP.

References