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";
// DeviceService is the service managing the devices.
service DeviceService {
// Create creates the given device.
rpc Create(CreateDeviceRequest) returns (google.protobuf.Empty) {
option(google.api.http) = {
post: "/api/devices"
body: "*"
};
}
// Get returns the device matching the given DevEUI.
rpc Get(GetDeviceRequest) returns (GetDeviceResponse) {
option (google.api.http) = {
get: "/api/devices/{dev_eui}"
};
}
// List returns the available devices.
rpc List(ListDeviceRequest) returns (ListDeviceResponse) {
option (google.api.http) = {
get: "/api/devices"
};
}
// Delete deletes the device matching the given DevEUI.
rpc Delete(DeleteDeviceRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/api/devices/{dev_eui}"
};
}
// Update updates the device matching the given DevEUI.
rpc Update(UpdateDeviceRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
put: "/api/devices/{device.dev_eui}"
body: "*"
};
}
// CreateKeys creates the given device-keys.
rpc CreateKeys(CreateDeviceKeysRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/api/devices/{device_keys.dev_eui}/keys"
body: "*"
};
}
// GetKeys returns the device-keys for the given DevEUI.
rpc GetKeys(GetDeviceKeysRequest) returns (GetDeviceKeysResponse) {
option (google.api.http) = {
get: "/api/devices/{dev_eui}/keys"
};
}
// UpdateKeys updates the device-keys.
rpc UpdateKeys(UpdateDeviceKeysRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
put: "/api/devices/{device_keys.dev_eui}/keys"
body: "*"
};
}
// DeleteKeys deletes the device-keys for the given DevEUI.
rpc DeleteKeys(DeleteDeviceKeysRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/api/devices/{dev_eui}/keys"
};
};
// Activate (re)activates the device with the given parameters (for ABP or for importing OTAA activations).
rpc Activate(ActivateDeviceRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/api/devices/{device_activation.dev_eui}/activate"
body: "*"
};
}
// Deactivate de-activates the device.
rpc Deactivate(DeactivateDeviceRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/api/devices/{dev_eui}/activation"
};
}
// GetActivation returns the current activation details of the device (OTAA and ABP).
rpc GetActivation(GetDeviceActivationRequest) returns (GetDeviceActivationResponse) {
option (google.api.http) = {
get: "/api/devices/{dev_eui}/activation"
};
}
// GetRandomDevAddr returns a random DevAddr taking the NwkID prefix into account.
rpc GetRandomDevAddr(GetRandomDevAddrRequest) returns (GetRandomDevAddrResponse) {
option (google.api.http) = {
post: "/api/devices/{dev_eui}/getRandomDevAddr"
};
}
// StreamFrameLogs streams the uplink and downlink frame-logs for the given DevEUI.
// * 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(StreamDeviceFrameLogsRequest) returns (stream StreamDeviceFrameLogsResponse) {
option (google.api.http) = {
get: "/api/devices/{dev_eui}/frames"
};
}
// StreamEventLogs stream the device events (uplink payloads, ACKs, joins, errors).
// * This endpoint is intended for debugging only.
// * This endpoint does not work from a web-browser.
rpc StreamEventLogs(StreamDeviceEventLogsRequest) returns (stream StreamDeviceEventLogsResponse) {
option (google.api.http) = {
get: "/api/devices/{dev_eui}/events"
};
}
}
message Device {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
// Name of the device (if left blank, it will be set to the DevEUI).
string name = 2;
// ID of the application to which the device must be added.
// It is possible to move a device to a different application on update,
// given that both the old and the new application share the same
// service-profile.
int64 application_id = 3 [json_name = "applicationID"];
// Description of the device.
string description = 4;
// DeviceProfileID attached to the device.
string device_profile_id = 5 [json_name = "deviceProfileID"];
// Skip frame-counter checks (this is insecure, but could be helpful for debugging).
bool skip_f_cnt_check = 6;
// Reference altitude.
// When using geolocation, this altitude will be used as a reference
// (when supported by the geolocation-server) to increase geolocation
// accuracy.
double reference_altitude = 7;
// Variables (user defined).
// These variables can be used together with integrations to store tokens /
// secrets that must be configured per device. These variables are not
// exposed in the event payloads.
map<string, string> variables = 8;
// Tags (user defined).
// These tags are exposed in the event payloads or to integration. Tags are
// intended for aggregation and filtering.
map<string, string> tags = 9;
// Device is disabled.
bool is_disabled = 10;
}
message DeviceListItem {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
// Name of the device.
string name = 2;
// Application ID.
int64 application_id = 3 [json_name = "applicationID"];
// Description of the device.
string description = 4;
// Device-profile ID attached to the device.
string device_profile_id = 5 [json_name = "deviceProfileID"];
// Device-profile name.
string device_profile_name = 6;
// The device battery status (deprecated, use device_status_battery_level).
// 0: The end-device is connected to an external power source
// 1..254: The battery level, 1 being at minimum and 254 being at maximum
// 255: The end-device was not able to measure the battery level
// 256: The device-status is not available.
uint32 device_status_battery = 7;
// The device margin status
// -32..32: The demodulation SNR ration in dB
// 256: The device-status is not available.
int32 device_status_margin = 8;
// Device is connected to an external power source.
bool device_status_external_power_source = 10;
// Device battery status is unavailable.
bool device_status_battery_level_unavailable = 11;
// Device battery level as a percentage.
float device_status_battery_level = 12;
// The last time the application-server received any data from the device,
// or an empty string when the device never sent any data.
google.protobuf.Timestamp last_seen_at = 9 [json_name = "lastSeenAt"];
}
message DeviceKeys {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
// Network root key (HEX encoded).
// Note: For LoRaWAN 1.0.x, use this field for the LoRaWAN 1.0.x 'AppKey`!
string nwk_key = 2;
// Application root key (HEX encoded).
// Note: This field only needs to be set for LoRaWAN 1.1.x devices!
string app_key = 3;
// Gen application key (HEX encoded).
// This is an optional key that only must be set for LORaWAN 1.0.x devices
// that implement the remote multicast setup specification.
string gen_app_key = 4;
}
message CreateDeviceRequest {
// Device object to create.
Device device = 1;
}
message GetDeviceRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message GetDeviceResponse {
// Device object.
Device device = 1;
// Created at 2
// Updated at 3
// First seen at 4
// Last seen timestamp.
google.protobuf.Timestamp last_seen_at = 5 [json_name = "lastSeenAt"];
// The device battery status
// 0: The end-device is connected to an external power source
// 1..254: The battery level, 1 being at minimum and 254 being at maximum
// 255: The end-device was not able to measure the battery level
// 256: The device-status is not available.
uint32 device_status_battery = 6;
// The device margin status
// -32..32: The demodulation SNR ration in dB
// 256: The device-status is not available.
int32 device_status_margin = 20;
// Device location.
// This will set when the network-server was able to resolve the location
// using the geolocation-server.
common.Location location = 21;
}
message ListDeviceRequest {
// Max number of devices to return in the result-set.
int64 limit = 1;
// Offset in the result-set (for pagination).
int64 offset = 2;
// Application ID to filter on.
int64 application_id = 3 [json_name = "applicationID"];
// Search on name or DevEUI.
string search = 4;
// Multicast-group ID to filter on (string formatted UUID).
string multicast_group_id = 5 [json_name = "multicastGroupID"];
// Service-profile ID to filter on (string formatted UUID).
string service_profile_id = 6 [json_name = "serviceProfileID"];
// Tags to filter on.
map<string, string> tags = 7;
}
message ListDeviceResponse {
// Total number of devices available within the result-set.
int64 total_count = 1;
// Devices within this result-set.
repeated DeviceListItem result = 2;
}
message DeleteDeviceRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message UpdateDeviceRequest {
// Device object to update.
Device device = 1;
}
message CreateDeviceKeysRequest {
// Device-keys object to create.
DeviceKeys device_keys = 1;
}
message GetDeviceKeysRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message GetDeviceKeysResponse {
// Device-key object.
DeviceKeys device_keys = 1;
}
message UpdateDeviceKeysRequest {
// Device-keys object to update.
DeviceKeys device_keys = 1;
}
message DeleteDeviceKeysRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message DeviceActivation {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
// Device address (HEX encoded).
string dev_addr = 2;
// Application session key (HEX encoded).
string app_s_key = 3;
// Network session encryption key (HEX encoded).
string nwk_s_enc_key = 4;
// Serving network session integrity key (HEX encoded).
string s_nwk_s_int_key = 8;
// Forwarding network session integrity key (HEX encoded).
string f_nwk_s_int_key = 9;
// Uplink frame-counter.
uint32 f_cnt_up = 5;
// Downlink network frame-counter.
uint32 n_f_cnt_down = 6;
// Downlink application frame-counter.
uint32 a_f_cnt_down = 10;
}
message ActivateDeviceRequest {
DeviceActivation device_activation = 1;
}
message DeactivateDeviceRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message GetDeviceActivationRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message GetDeviceActivationResponse {
// Device-activation object.
DeviceActivation device_activation = 1;
}
message GetRandomDevAddrRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message GetRandomDevAddrResponse {
// Device address (HEX encoded).
string dev_addr = 1;
}
message StreamDeviceFrameLogsRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message StreamDeviceFrameLogsResponse {
oneof frame {
// Contains an uplink frame.
UplinkFrameLog uplink_frame = 1;
// Contains a downlink frame.
DownlinkFrameLog downlink_frame = 2;
}
}
message StreamDeviceEventLogsRequest {
// Device EUI (HEX encoded).
string dev_eui = 1 [json_name = "devEUI"];
}
message StreamDeviceEventLogsResponse {
// The event type.
string type = 1;
// The event payload in JSON encoding.
string payload_json = 2 [json_name = "payloadJSON"];
}