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";
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;
}
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;
}
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;
}
}