gateway.proto

// Copyright © 2017 The Things Network
// Use of this source code is governed by the MIT license that can be found in the LICENSE file.

syntax = "proto3";

import "github.com/gogo/protobuf/gogoproto/gogo.proto";

package gateway;

option csharp_namespace = "TheThingsNetwork.API.Gateway";
option go_package = "github.com/TheThingsNetwork/api/gateway";
option java_package = "org.thethingsnetwork.api.gateway";
option java_outer_classname = "GatewayProto";
option java_multiple_files = true;

message LocationMetadata {
  // Time (unix nanoseconds)
  int64   time       = 1;

  // the north–south position (degrees; -90 to +90), where 0 is the equator, north pole is positive, south pole is negative
  float   latitude   = 2;

  // the east-west position (degrees; -180 to +180), where 0 is the Prime Meridian (Greenwich), east is positive , west is negative
  float   longitude  = 3;

  // the altitude (meters), where 0 is the mean sea level
  int32   altitude   = 4;

  // the accuracy of the location (meters)
  int32   accuracy   = 5;

  LocationSource source = 6;

  enum LocationSource {
    // The source of the location is not known or not set
    UNKNOWN  = 0;
    // The location is determined by GPS
    GPS      = 1;
    // The location is fixed by configuration
    CONFIG   = 2;
    // The location is set in and updated from a registry
    REGISTRY = 3;
    // The location is estimated with IP Geolocation
    IP_GEOLOCATION = 4;
    // More estimation methods can be added
  }
}

message RxMetadata {
  string  gateway_id = 1 [(gogoproto.customname) = "GatewayID"];

  // Indicates whether the gateway is trusted. Components that are able to verify gateway trust MUST do so and set this value accordingly
  bool    gateway_trusted = 2;

  // Timestamp (uptime of LoRa module) in microseconds with rollover
  uint32  timestamp  = 11;
  // Time in Unix nanoseconds
  int64   time       = 12;

  // Encrypted time from the Gateway FPGA
  bytes   encrypted_time = 13;

  uint32  rf_chain   = 21;
  uint32  channel    = 22;

  repeated Antenna antennas = 30;

  // Frequency in Hz
  uint64  frequency  = 31;
  // Received signal strength in dBm
  float   rssi       = 32 [(gogoproto.customname) = "RSSI"];
  // Signal-to-noise-ratio in dB
  float   snr        = 33 [(gogoproto.customname) = "SNR"];

  message Antenna {
    uint32 antenna = 1;
    uint32 channel = 2;

    // Received signal power in dBm
    float  rssi         = 3 [(gogoproto.customname) = "RSSI"];

    // Received channel power in dBm
    float  channel_rssi = 5 [(gogoproto.customname) = "ChannelRSSI"];

    // Standard deviation of the RSSI
    float  rssi_standard_deviation = 6 [(gogoproto.customname) = "RSSIStandardDeviation"];

    // Frequency offset (Hz)
    int64 frequency_offset = 7;

    // Signal-to-noise-ratio in dB
    float  snr     = 4 [(gogoproto.customname) = "SNR"];

    // Encrypted fine timestamp from the Gateway FPGA
    bytes encrypted_time = 10;

    // Fine timestamp from the Gateway FPGA (decrypted)
    int64 fine_time = 11;
  }

  LocationMetadata location = 41;
}

message TxConfiguration {
  // Timestamp (uptime of LoRa module) in microseconds with rollover
  uint32 timestamp   = 11;

  uint32  rf_chain   = 21;

  // Frequency in Hz
  uint64  frequency  = 22;
  // Transmit power in dBm
  int32   power      = 23;

  // LoRa polarization inversion (basically always true for messages from gateway to node)
  bool polarization_inversion = 31;
  // FSK frequency deviation in Hz
  uint32 frequency_deviation = 32;
}

// message Status represents a status update from a Gateway.
message Status {
  // Timestamp (uptime of gateway) in microseconds with rollover
  uint32  timestamp      = 1;
  // Time in Unix nanoseconds
  int64   time           = 2;

  // Indicates whether the gateway is trusted. Components that are able to verify gateway trust MUST do so and set this value accordingly
  bool    gateway_trusted = 3;

  // Boot time in Unix nanoseconds
  int64   boot_time      = 4;

  // Configuration and relatively static stuff
  // These values may be left out if they don't change
  // Reset using "-"

  repeated string ip     = 11 [(gogoproto.customname) = "IP"];
  string  platform       = 12;
  string  contact_email  = 13;
  string  description    = 14;

  // The gateway's frequency plan: one of EU_863_870, US_902_928, CN_779_787, EU_433, AU_915_928, CN_470_510, AS_923, AS_920_923, AS_923_925, KR_920_923
  string  frequency_plan = 15;
  // The value of Bridge is set by the Bridge
  string  bridge         = 16;
  // The value of Router is set by the Router
  string  router         = 17;
  // Version of Gateway FPGA
  uint32  fpga           = 18 [(gogoproto.customname) = "FPGA"];
  // Version of Gateway DSP software
  uint32  dsp            = 19 [(gogoproto.customname) = "DSP"];
  // Version of gateway driver (in X.X.X format)
  string  hal            = 20 [(gogoproto.customname) = "HAL"];

  LocationMetadata location = 21;

  // Network (internet) stuff

  // Round-trip time to the server in milliseconds
  uint32  rtt            = 31 [(gogoproto.customname) = "RTT"];

  // Rx and Tx stuff

  // Total number of received uplink packets since boot
  uint32  rx_in          = 41;
  // Total number of successful (correct) uplink packets since boot
  uint32  rx_ok          = 42;
  // Total number of received downlink packets since boot
  uint32  tx_in          = 43;
  // Total number of successfully sent downlink packets since boot
  uint32  tx_ok          = 44;
  // Total number of packets received from link testing mote, with CRC OK
  uint32  lm_ok          = 45;
  // Sequence number of the first packet received from the link testing mote
  uint32  lm_st          = 46;
  // Sequence number of the last packet received from the link testing mote
  uint32  lm_nw          = 47;
  // Number of lost PPS pulses
  uint32  l_pps       = 48 [(gogoproto.customname) = "LPPS"];

  // Additional metrics from the operating system
  message OSMetrics {
    float   load_1            = 1;
    float   load_5            = 2;
    float   load_15           = 3;

    float   cpu_percentage    = 11 [(gogoproto.customname) = "CPUPercentage"];

    float   memory_percentage = 21;

    float   temperature       = 31;
  }

  OSMetrics os = 51 [(gogoproto.customname) = "OS"];

  // debug or warning messages from the gateway
  repeated string messages = 52;
}