package pylongps

Get desktop application:
View/edit binary Protocol Buffers messages

This message is sent in response to a add/remove proxy request and indicates the success or failure of the request. If there is a failure reason, the request was unsuccessful

• optional proxy_request_failure_reason reason = 10

  Why the request failed (success if not there)

This message is used to request an that the caster add a new proxy or remove an old one. If a new caster is to be added, the three connection strings must be given This message can be used to remove a caster from proxying by specifying the caster to remove. In this case, the caster_id_to_remove field is expected.

• optional bytes client_request_connection_string = 10

  The ZMQ connection string to connect to the client query interface of the caster to proxy

• optional bytes connect_disconnect_notification_connection_string = 20

  The ZMQ connection string to connect to the caster's connect/disconnect notification interface

• optional bytes base_station_publishing_connection_string = 30

  The ZMQ connection string to connect to the base station's correction publishing interface

• optional bytes client_request_connection_string_for_caster_to_remove = 40

  The same connection string used to add the caster to the proxy list

This message defines the permissions granted to the owner of the public key by those that sign a serialized version of this message.

• required bytes public_key = 1

  The public key of the entity the permissions are granted to

• optional int64 valid_until = 2

  These permissions are granted until revoked by blacklist or the timepointed defined by valid_until which is defined as the 64 bit unix timestamp given by the Poco Timestamp function (microseconds since Unix Epoc).

• optional uint32 number_of_permitted_base_stations = 3

  The granted permissions

  The number of simultaneous base station streams the owner of the key may open with a PylonGPS on behalf of the signers

Classes of base stations (official, community, etc)

Used in: base_station_stream_information, client_subquery

• OFFICIAL = 1

  Base stations that are run by trusted entities (such as governments) and use authentication so that injecting bad data is difficult

• REGISTERED_COMMUNITY = 2

  Base stations run by private individuals or organizations that have registered and gotten a signing key for their organization

• COMMUNITY = 3

  Base stations run by anonymous individuals

Used in: client_subquery

• required double latitude = 1

  Latitude of the center of the circle

• required double longitude = 2

  Longitude of the center of the circle

• required double radius = 3

  Radius in meters of the circle

Used in: stream_status_update

• BASE_STATION_TIMED_OUT = 1

  The base station hasn't sent updates for an unacceptable amount of time

• BASE_STATION_TERMINATED_CONNECTION = 2

  The base station indicated it wished to stop sending updates

This message contains all of the details related to a basestation stream (including public key/organization, if there is one and lat/long, expected update rate, basestation tech? and message protocol).

Used in: basestation_data_receiver_configuration, client_query_reply, database_request, stream_status_update, transmitter_registration_request

• optional int64 base_station_id = 10

  Stick first so database interface selects it as primary key

  The 64 bit id assigned by the caster for this stream

• optional double latitude = 20

  Fields that are expected in registration

  The latitude of the information source (degrees)

• optional double longitude = 30

  The longitude of the information source (degrees)

• optional double expected_update_rate = 40

  Expected number of complete protocol messages (RTCM/etc) per second

• optional corrections_message_format message_format = 50

  The base station stream's message protocol/format

• optional bytes informal_name = 60

  The name the basestation suggests be used for it in graphical displays/user interfaces.

• optional base_station_class station_class = 70

  Fields potentially filled in by the caster

  The type of the basestation (OFFICIAL, COMMUNITY, etc)

• optional bytes source_public_key = 80

  The public key (in binary) associated with a source (if it has one), this is left blank in registration requests and filled internally via credentials

• repeated bytes signing_keys = 90

  Any keys that have signed the public key associated with this source (if any) in binary format

• optional double real_update_rate = 100

  How many messages/second received on average from the basestation (updated every 30 seconds or so to prevent needing too many database accesses)

• optional double uptime = 110

  How long a basestation has been connected

• optional int64 start_time = 120

  The POCO datetime when the basestation was registered (microseconds since unix epoch)

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Key to allow senders to find this receiver on loading, required to be unique across all receivers stored

• required int64 caster_id = 20

  ID of caster to retrieve from

• required int64 stream_id = 30

  ID of stream to retrieve from

• optional base_station_stream_information basestation_details = 40

  Used with GUI

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Data receiver this sender forwards from

• required bytes caster_ip_address = 20

• required int64 caster_registration_port = 30

• required double latitude = 40

• required double longitude = 50

• required corrections_message_format message_format = 60

• required bytes informal_basestation_name = 70

• required double expected_update_rate = 80

  messages/sec

• optional bytes secret_key = 90

• optional credentials registration_credentials = 100

This message represents the timepoint at which the certficate associated with the given blacklisted key has expired

• required bytes blacklist_key = 10

  The blacklist key which timed out

This message is used to store the parameters to configure a Pylon GPS 2.0 caster with. It can be configured and passed to the caster constructor.

• optional int64 caster_id = 10

  The 64 bit ID associated with this caster (make sure it does not collide with caster IDs the clients are likely to run into) (required)

• optional uint64 transmitter_registration_and_streaming_port_number = 20

  The port number to register the ZMQ router socket used for receiving PylonGPS transmitter registrations/streams (required)

• optional uint64 client_request_port_number = 30

  The port to open to receive client requests (including requests from proxies for the list of sources) (required)

• optional uint64 client_stream_publishing_port_number = 40

  The port to open for the interface to publish stream data to clients (required)

• optional uint64 proxy_stream_publishing_port_number = 50

  The port to open for the interface to publish stream data to proxies (potentially higher priority) (required)

• optional uint64 stream_status_notification_port_number = 60

  The port for the interface that is used to to publish stream status changes (required)

• optional uint64 key_registration_and_removal_port_number = 70

  The port for the interface that is used to add/remove (required)

• optional bytes caster_public_key = 80

  The public key for this caster to use for encryption/authentation (binary format). Caster will generate a new one if this is missing

• optional bytes caster_secret_key = 90

  The secret key for this caster to use for encryption/authentation (binary format). Caster will generate a new one if this is missing

• optional bytes signing_keys_management_key = 100

  The signing key that has permission to add/remove allowed signing keys from the caster (binary format) (required)

• repeated bytes official_signing_keys = 110

  A list of the initial set of approved keys for official basestations (binary format)

• repeated bytes registered_community_signing_keys = 120

  A list of the initial set of approved keys for registered community basestations (binary format)

• repeated bytes blacklisted_keys = 130

  A list of signing keys not to trust (binary format)

• optional bytes caster_sqlite_connection_string = 140

  The connection string used to connect to or create the SQLITE database used for stream source entry management and query resolution. If an empty string is given or it is left out (by default), it will connect/create an in-memory database.

This message contains all the details regarding a pylonGPS caster instance, including version.

• required bytes version = 1

  A string indicating the version of the caster ("x.x.x" format)

This message contains either an error message indicating the request was invalid, a list (sometimes sorted) of base station information structures or a message containing the details about the caster.

• optional int64 caster_id = 10

  The (currently required) caster ID associated with the answering caster

• repeated base_station_stream_information base_stations = 20

  A list of base_stations that meet the required criteria

• optional client_query_request_failure_reason failure_reason = 30

  The reason the request failed (the request failed if this has a value)

This message is used by a PylonGPS client to request a list of available sources from a caster. It allows filtering based on lat/long (entries within a certain distance of a point, sorted by distance or in a grid), limiting the number of entries returned to a certain number, uptime (> certain amount), update rate (> certain amount), expected update rate (> certain amount) and protocol (in a list of different types).

Used in: pylongps_protobuf_sql_converter.protobuf_sql_converter_test_message

• optional uint32 max_number_of_results = 10

  The maximum number of base station entries that should be returned

• repeated client_subquery subqueries = 20

  Zero or more subqueries, with the results from each subquery "ORed" together

Used in: client_query_reply

• CLIENT_QUERY_REQUEST_DESERIALIZATION_FAILED = 1

  Couldn't read the request

• CLIENT_QUERY_REQUEST_PARAMETERS_INVALID = 2

  One or more required parameters were not found

• CLIENT_QUERY_REQUEST_TOO_COMPLEX = 3

  The request had too many things to check for (would take a really long time to process)

This message defines several "AND" clauses together to form a complex set of conditions. Multiple messages of this type can be "ORed" placed in a client_query_request message to enable complex queries.

Used in: client_query_request

• repeated base_station_class acceptable_classes = 10

  One or more acceptable types of base station classes

• repeated corrections_message_format acceptable_formats = 20

  One or more acceptable message types. If zero types are defined, it is assumed any type is acceptable.

• repeated sql_double_condition latitude_condition = 30

  Conditions on the value of the latitude

• repeated sql_double_condition longitude_condition = 40

  Conditions on the value of the longitude

• repeated sql_double_condition uptime_condition = 50

  Conditions on how long base stations have been active in seconds (potentially allowing only long running basestations to be used)

• repeated sql_double_condition real_update_rate_condition = 60

  Conditions on the real update rate (ZMQ messages per second)

• repeated sql_double_condition expected_update_rate_condition = 70

  A condition on the expected update rate (GPS format messages/second), defined at registration

• optional sql_string_condition informal_name_condition = 80

  A condition on the informal name to search for

• repeated sql_integer_condition base_station_id_condition = 90

  Conditions on the assigned base station ID

• repeated bytes source_public_keys = 100

  Acceptable signing public keys

• optional base_station_radius_subquery circular_search_region = 110

  A central point and radius to search for base stations around

This message represents the timepoint at which the certficate associated with the given key has expired

• required bytes connection_key = 10

  The connection key which timed out

Types of message formats

Used in: base_station_stream_information, basestation_data_sender_configuration, client_subquery

• RTCM_V1 = 1

  RTCM version 1.0

• RTCM_V2 = 2

  RTCM version 2.0

• RTCM_V2_1 = 3

  RTCM version 2.1

• RTCM_V2_2 = 4

  RTCM version 2.2

• RTCM_V2_3 = 5

  RTCM version 2.3

• RTCM_V3 = 6

  RTCM version 3.0

• RTCM_V3_1 = 7

  RTCM version 3.1

• RTCM_PP = 100

  RTCM++

• RTCM_ADV = 101

  RTCM-AdV

• RTCM_ADV_FKP = 102

  RTCM-AdV FKP

• RINEX = 200

  RINEX

• PIKSI_V1 = 300

  Piksi's format version 1

• CMR = 400

  Compact Measurement Record (CMR)

• RAW = 500

  Raw data from a receiver

This message contains all of the information required to show that a given public key has been granted permissions from one or more entities via their private key

Used in: basestation_data_sender_configuration, transmitter_registration_request

• required bytes permissions = 10

  A serialized authorized_permissions message that details what permissions have been granted and to whom they have been granted to

• repeated signature signatures = 20

  One or more signatures authorizing the permission (who grants the permissions and associated proof)

This message is used to notify listeners to a data receiver if something has happened (such as an unrecoverable error).

• optional bool unrecoverable_error_has_occurred = 10

  The receiver has gone offline

This message is sent in response to a database request and indicates the success or failure of the request.

• optional bytes registration_connection_id = 10

  The connection ID associated with the base_station_to_register in the registration thread

• optional database_request_failure_reason reason = 20

  Why the request failed (success if not there)

This message is used to request an operation on the database be completed. So far this includes adding or removing a base station entry or updating the reported update rate.

• optional bytes registration_connection_id = 10

  The connection ID associated with the base_station_to_register in the registration thread

• optional base_station_stream_information base_station_to_register = 20

  The information about a basestation to register

• repeated int64 delete_base_station_ids = 30

  The IDs of a basestations to remove

• optional int64 base_station_to_update_id = 40

  The ID of a basestation to update

• optional double real_update_rate = 50

  The real update rate to update in the table

Used in: database_reply

• DATABASE_REQUEST_DESERIALIZATION_FAILED = 10

• DATABASE_CONSTRAINTS_VIOLATED = 20

• DATABASE_REQUEST_FORMAT_INVALID = 30

  Missing "optional" fields required for a valid transaction

This message contains no fields but has a large extension option range so that any new "event" messages can add its definition to it as an optional or repeated message member. It is meant to be used with a std::tuple<std::chrono::timepoint, event_message> to allow easy construction of an event queue. Which messages the event_message has embedded can be checked with the has_ member functions.

(message has no fields)

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Key to allow senders to find this receiver on loading, required to be unique across all receivers stored

• required bytes file_path = 20

  File path to get data from

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Data receiver this sender forwards from

• required bytes file_path_to_write_to = 20

This message used used by a caster to reply to a transmitter_registration_request. It indicates if the registration succeeded and if not, then why it failed.

• required bool request_succeeded = 10

  True if the registration request succeeded

• optional key_management_request_failure_reason failure_reason = 20

  The reason for the request being rejected

This message is used to send a request to add or blacklist a set of keys from the lists of acceptable signing keys for different applications

For now, both fields are required

• optional bytes serialized_key_status_changes = 10

  A serialized key_status_changes message which details the changes to make to the different keys lists

• optional signature signature = 20

  The signature from the owner of the caster authorizing the change

Used in: key_management_reply

• KEY_MESSAGE_FORMAT_INVALID = 1

  Deserialization failed

• KEY_STATUS_CHANGE_DESERIALIZATION_FAILED = 2

  Unable to read desired change

• KEY_INSUFFICIENT_PERMISSIONS = 3

  Credentials not signed by recognized authorities or otherwise are not enough.

• KEY_MISSING_REQUIRED_FIELD = 4

  One or more needed fields are missing

This message defines the permissions granted to the owner of the public key by those that sign a serialized version of this message.

• repeated bytes official_signing_keys_to_add = 10

  Signing keys to add to the list of accepted signing keys for official basestations

• repeated int64 official_signing_keys_to_add_valid_until = 20

  The date at which each of the official_signing_key_to_add become invalid (required, one for each key)

• repeated bytes registered_community_signing_keys_to_add = 30

  Signing keys to add to the list of accepted signing keys for registered community basestations

• repeated int64 registered_community_signing_keys_to_add_valid_until = 40

  The dates at which each of the registered_community_signing_keys_to_add become invalid (required, one for each key)

• repeated bytes keys_to_add_to_blacklist = 50

  Signing keys to add to the list of accepted signing keys for registered community basestations

• repeated int64 keys_to_add_to_blacklist_valid_until = 60

  The dates at which each of the keys should be removed from the blacklist (their certificates have expired by then) (required, one for each key)

This message is used to inform the caster that one of its proxy requests may have timed out. If the socket this message refers to is still around, it is deleted and the source of the add proxy request is informed of the failure. If it is not, then nothing happens.

• required bytes ephemeral_socket_pointer = 1

  The binary value (local machine format) of the address for the query socket

• required bytes connection_id = 1

  The connection id associated with the base station

• required bool is_authenticated = 2

  This refers to an authenticated basestation if true

This message represents the timepoint at which a proxy stream may have expired (the check occurs)

• required int64 caster_id = 10

  The foreign caster ID

• required int64 stream_id = 20

  The foreign stream ID

Used in: add_remove_proxy_reply

• PROXY_REQUEST_DESERIALIZATION_FAILED = 10

• PROXY_REQUEST_FORMAT_INVALID = 20

  Missing "optional" fields required for a valid transaction

• CASTER_QUERY_REQUEST_FAILED = 30

  Unable to retrieve basestation information from the caster

Used in: transmitter_registration_reply

• MESSAGE_FORMAT_INVALID = 1

  Deserialization failed

• CREDENTIALS_DESERIALIZATION_FAILED = 2

  Unable to read credentials

• INSUFFICIENT_PERMISSIONS = 3

  Credentials not signed by recognized authorities or otherwise are not enough.

• MISSING_REQUIRED_FIELD = 4

This message carries the public key of a key pair used to sign a given message and the resulting signed hash for associated with the particular message that was signed

Used in: credentials, key_management_request

• required bytes public_key = 1

  The public key associated with the private key that was used to sign the key

• required bytes cryptographic_signature = 2

  The signature generated from the key pair/message

This message represents the timepoint at which the certficate associated with the given key has expired

• required bytes key = 10

  The official key which timed out

• required bool is_official = 20

  True if it is an "official" signing key and false if it is a "registered community" signing key

This message is used as part of a subquery message to specify conditions on one or more parts of stream base station results that are returned. It specifies a constraint on the value of a particular field of the stream base station entry.

Used in: client_subquery

• required double value = 10

  The value the condition is in relation to

• required sql_relational_operator relation = 20

  The relation to the value (<,<=, ==, >=, >)

This message is used as part of a subquery message to specify conditions on one or more parts of stream base station results that are returned. It specifies a constraint on the value of a particular field of the stream base station entry.

Used in: client_subquery

• required int64 value = 10

  The value the condition is in relation to

• required sql_relational_operator relation = 20

  The relation to the value (<,<=, ==, >=, >)

Relational operators for SQL operations

Used in: sql_double_condition, sql_integer_condition

• LESS_THAN = 10

• LESS_THAN_EQUAL_TO = 20

• EQUAL_TO = 30

• NOT_EQUAL_TO = 40

• GREATER_THAN = 50

• GREATER_THAN_EQUAL_TO = 60

This message is used as part of a subquery message to specify conditions on one or more parts of stream base station results that are returned. It specifies a constraint on the value of a particular field of the stream base station entry.

Used in: client_subquery

• required bytes value = 10

  The value the condition is in relation to

• required sql_string_relational_operator relation = 20

  The relation to the value (==, LIKE (permits wildcards))

Used in: sql_string_condition

• IDENTICAL = 10

• LIKE = 20

This message is published by a caster to inform proxies or interested clients if a stream has been added or has been removed from the caster's list of information sources. This allows clients and proxies to be aware of when their subscribed source disconnects and allow for waiting until a source comes online. The registrations notifications include a base_station_stream_information message with all of the details associated with the new source.

• optional base_station_stream_information new_base_station_info = 10

  Non-empty if there is a new base station available

• optional int64 base_station_removed = 20

  The 64 bit ID of the base station that is being removed from the caster

• optional base_station_removal_reason removal_reason = 30

  The reason the base station was removed from the caster

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Key to allow senders to find this receiver on loading, required to be unique across all receivers stored

• required bytes server_ip_address = 20

• required int64 server_port = 30

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Data receiver this sender forwards from

• required int64 server_port = 20

This message is used to store the current state of a PylonGPS 2.0 transceiver so that it can be restarted in the same state.

• repeated basestation_data_receiver_configuration basestation_receivers = 10

• repeated file_data_receiver_configuration file_receivers = 20

• repeated tcp_data_receiver_configuration tcp_receivers = 30

• repeated zmq_data_receiver_configuration zmq_receivers = 40

• repeated basestation_data_sender_configuration basestation_senders = 50

• repeated file_data_sender_configuration file_senders = 60

• repeated tcp_data_sender_configuration tcp_senders = 70

• repeated zmq_data_sender_configuration zmq_senders = 80

This message used used by a caster to reply to a transmitter_registration_request. It indicates if the registration succeeded and if not, then why it failed.

• required bool request_succeeded = 10

  True if the registration request succeeded

• optional request_failure_reason failure_reason = 20

  The reason for the request being rejected

This message is used by a PylonGPS transmitter to submit any required credentials and give the required metadata for the stream to the caster (lat/long, expected update rate, basestation tech, message protocol). The caster should reply with a transmitter_registration_reply.

• optional base_station_stream_information stream_info = 10

  The metadata associated with the stream we are attempting to register

• optional credentials transmitter_credentials = 20

  This is any credentials (such as signatures of its key via an organization key) used to authenticate this transmitter's key (if it is attempting to authenticate) as a representative of a particular organization.

This message represents the timepoint at which the the next wave of real_update_rate entries should be updated

(message has no fields)

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Key to allow senders to find this receiver on loading, required to be unique across all receivers stored

• required bytes server_ip_address = 20

• required int64 server_port = 30

Used in: transceiver_configuration

• required int64 receiver_id = 10

  Data receiver this sender forwards from

• required int64 server_port = 20