gateway.proto

syntax = "proto3";

package api;

option go_package = "github.com/brocaar/chirpstack-api/go/v3/as/external/api";
option java_package = "io.chirpstack.api.as.external.api";
option java_multiple_files = true;
option java_outer_classname = "GatewayProto";

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "common/common.proto";
import "as/external/api/frameLog.proto";


// GatewayService is the service managing the gateways.
service GatewayService {
	// Create creates the given gateway.
	rpc Create(CreateGatewayRequest) returns (google.protobuf.Empty) {
		option(google.api.http) = {
			post: "/api/gateways"
			body: "*"
		};
	}

	// Get returns the gateway for the requested mac address.
	rpc Get(GetGatewayRequest) returns (GetGatewayResponse) {
		option (google.api.http) = {
			get: "/api/gateways/{id}"
		};
	}

	// Update updates the gateway matching the given mac address.
	rpc Update(UpdateGatewayRequest) returns (google.protobuf.Empty) {
		option (google.api.http) = {
			put: "/api/gateways/{gateway.id}"
			body: "*"
		};
	}

	// Delete deletes the gateway matching the given mac address.
	rpc Delete(DeleteGatewayRequest) returns (google.protobuf.Empty) {
		option (google.api.http) = {
			delete: "/api/gateways/{id}"
		};
	}

	// List lists the gateways.
	rpc List(ListGatewayRequest) returns (ListGatewayResponse) {
		option (google.api.http) = {
			get: "/api/gateways"
		};
	}

	// GetStats lists the gateway stats given the query parameters.
	rpc GetStats(GetGatewayStatsRequest) returns (GetGatewayStatsResponse) {
		option (google.api.http) = {
			get: "/api/gateways/{gateway_id}/stats"
		};
	}

	// GetLastPing returns the last emitted ping and gateways receiving this ping.
	rpc GetLastPing(GetLastPingRequest) returns (GetLastPingResponse) {
		option (google.api.http) = {
			get: "/api/gateways/{gateway_id}/pings/last"
		};
	}

    // GenerateGatewayClientCertificate returns TLS certificate gateway authentication / authorization.
    // This endpoint can ony be used when ChirpStack Network Server is configured with a gateway
    // CA certificate and key, which is used for signing the TLS certificate. The returned TLS
    // certificate will have the Gateway ID as Common Name.
    rpc GenerateGatewayClientCertificate(GenerateGatewayClientCertificateRequest) returns (GenerateGatewayClientCertificateResponse) {
        option(google.api.http) = {
            post: "/api/gateways/{gateway_id}/generate-certificate"
        };
    }

    // StreamFrameLogs streams the uplink and downlink frame-logs for the given gateway ID.
	// Notes:
	//   * These are the raw LoRaWAN frames and this endpoint is intended for debugging only.
	//   * This endpoint does not work from a web-browser.
    rpc StreamFrameLogs(StreamGatewayFrameLogsRequest) returns (stream StreamGatewayFrameLogsResponse) {
        option (google.api.http) = {
            get: "/api/gateways/{gateway_id}/frames"
        };
	}
}

message Gateway {
	// Gateway ID (HEX encoded).
	string id = 1;

	// Gateway name.
	string name = 2;

	// Gateway description.
	string description = 3;

	// Gateway location.
	common.Location location = 4;

	// Organization ID to which the gateway belongs.
	// This can't be changed after creating the gateway.
	int64 organization_id = 5 [json_name = "organizationID"];

	// Set to true to enable gateway discovery.
	bool discovery_enabled = 6;

	// Network-server ID on which the gateway is provisioned.
	int64 network_server_id = 7 [json_name = "networkServerID"];

	// Gateway-profile ID (UUID string, optional).
	string gateway_profile_id = 8 [json_name = "gatewayProfileID"];

	// Gateway boards configuration (optional).
    // This is (currently) only needed when the gateway supports the fine-timestamp
    // and you you would like to add the FPGA ID to the gateway meta-data or would
	// like ChirpStack Network Server to decrypt the fine-timestamp.
	repeated GatewayBoard boards = 9;

    // Tags (user defined).
    map<string, string> tags = 10;

    // Metadata (provided by the gateway).
    map<string, string> metadata = 11;

    // Service-profile ID (UUID string, optional).
    string service_profile_id = 12 [json_name = "serviceProfileID"];
}

message GatewayBoard {
    // FPGA ID of the gateway (HEX encoded) (optional).
    string fpga_id = 1 [json_name = "fpgaID"];

    // Fine-timestamp AES decryption key (HEX encoded) (optional).
    string fine_timestamp_key = 2;
}

message CreateGatewayRequest {
	// Gateway object to create.
	Gateway gateway = 1;
}

message GetGatewayRequest {
	// Gateway ID (HEX encoded).
	string id = 1;
}

message GetGatewayResponse {
	// Gateway object.
	Gateway gateway = 1;

	// Created at timestamp.
	google.protobuf.Timestamp created_at = 2;

	// Last update timestamp.
	google.protobuf.Timestamp updated_at = 3;

	// First seen at timestamp.
	google.protobuf.Timestamp first_seen_at = 4;

	// Last seen at timestamp.
	google.protobuf.Timestamp last_seen_at = 5;
};

message DeleteGatewayRequest {
	// Gateway ID (HEX encoded).
	string id = 1;
}

message GenerateGatewayClientCertificateRequest {
    // Gateway ID (HEX encoded).
    string gateway_id = 1;
}

message GenerateGatewayClientCertificateResponse {
    // TLS certificate.
    string tls_cert = 1;

    // TLS key.
    string tls_key = 2;

    // CA certificate.
    string ca_cert = 3;

    // Expires at defines the expiration date of the certificate.
    google.protobuf.Timestamp expires_at = 4;
}


message ListGatewayRequest {
	// Max number of nodes to return in the result-set.
	int32 limit = 1;

	// Offset of the result-set (for pagination).
	int32 offset = 2;

	// ID of the organization for which to filter on, when left blank the
	// response will return all gateways to which the user has access to.
	int64 organization_id = 3 [json_name = "organizationID"];

	// Search on name or gateway MAC (optional).
	string search = 4;
}

message GatewayListItem {
	// Gateway ID (HEX encoded).
	string id = 1;

	// A name for the gateway
	string name = 2;

	// A description for the gateway
	string description = 3;

	// Create timestamp.
	google.protobuf.Timestamp created_at = 4;

	// Last update timestamp.
	google.protobuf.Timestamp updated_at = 5;

    // First seen timestamp.
    google.protobuf.Timestamp first_seen_at = 8;

    // Last seen timestamp.
    google.protobuf.Timestamp last_seen_at = 9;

	// Organization ID.
	int64 organization_id = 6 [json_name = "organizationID"];

	// Network-server ID.
	int64 network_server_id = 7 [json_name = "networkServerID"];

    // Location.
    common.Location location = 10;

    // Network-server name.
    string network_server_name = 11;
}

message ListGatewayResponse {
	// Total number of nodes available within the result-set.
	int64 total_count = 1;

	// Nodes within this result-set.
	repeated GatewayListItem result = 2;
}


message UpdateGatewayRequest {
	// Gateway object to update.
	Gateway gateway = 1;
}

message GatewayStats {
	// Timestamp of the (aggregated) measurement.
	google.protobuf.Timestamp timestamp = 1;

	// Packets received by the gateway.
	int32 rx_packets_received = 2;

	// Packets received by the gateway that passed the CRC check.
	int32 rx_packets_received_ok = 3 [json_name = "rxPacketsReceivedOK"];

	// Packets received by the gateway for transmission.
	int32 tx_packets_received = 4;

	// Packets transmitted by the gateway.
	int32 tx_packets_emitted = 5;

    // Tx packets per frequency.
    map<uint32, uint32> tx_packets_per_frequency = 6;

    // Rx packets per frequency.
    map<uint32, uint32> rx_packets_per_frequency = 7;

    // Tx packets per DR.
    map<uint32, uint32> tx_packets_per_dr = 8;

    // Rx packets per DR.
    map<uint32, uint32> rx_packets_per_dr = 9;

    // Tx packets per status.
    map<string, uint32> tx_packets_per_status = 10;
}

message GetGatewayStatsRequest {
	// Gateway ID (HEX encoded).
	string gateway_id = 1 [json_name = "gatewayID"];

	// Aggregation interval.  One of "second", "minute", "hour", "day", "week",
	// "month", "quarter", "year".  Case insensitive.
	string interval = 2;

	// Timestamp to start from.
	google.protobuf.Timestamp start_timestamp = 3;

	// Timestamp until to get from.
	google.protobuf.Timestamp end_timestamp = 4;
}

message GetGatewayStatsResponse {
	repeated GatewayStats result = 1;
}

message PingRX {
	// Gateway ID (HEX encoded).
	string gateway_id = 1 [json_name = "gatewayID"];

	// RSSI.
	int32 rssi = 2;

	// LoRa SNR.
	double lora_snr = 3 [json_name = "loRaSNR"];

	// Latitude of the gateway -90.0 to 90.0.
	double latitude = 4;

	// Longitude of the gateway -180.0 to 180.0.
	double longitude = 5;

	// Altitude of the gateway in meters.
	double altitude = 6;
}

message GetLastPingRequest {
	// Gateway ID (HEX encoded).
	string gateway_id = 1 [json_name = "gatewayID"];
}

message GetLastPingResponse {
	// Created at timestamp.
	google.protobuf.Timestamp created_at = 1;

	// Frequency (Hz).
	uint32 frequency = 2;

	// Data-rate.
	uint32 dr = 3;

	// Gateways and meta-data of reception.
	repeated PingRX ping_rx = 4 [json_name = "pingRX"];
}

message StreamGatewayFrameLogsRequest {
	// Gateway ID (HEX encoded).
	string gateway_id = 1 [json_name = "gatewayID"];
}

message StreamGatewayFrameLogsResponse {
    oneof frame {
        // Contains an uplink frame.
        UplinkFrameLog uplink_frame = 1;

        // Contains a downlink frame.
        DownlinkFrameLog downlink_frame = 2;
    }
}