syntax = "proto3";

package api;

option go_package = "github.com/chirpstack/chirpstack/api/go/v4";
option java_package = "io.chirpstack.api";
option java_multiple_files = true;
option java_outer_classname = "MulticastGroupProto";

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


// MulticastGroupService is the service managing multicast-groups.
service MulticastGroupService {
    // Create the given multicast group.
    rpc Create(CreateMulticastGroupRequest) returns (CreateMulticastGroupResponse) {}

    // Get returns the multicast group for the given ID.
    rpc Get(GetMulticastGroupRequest) returns (GetMulticastGroupResponse) {}

    // Update the given multicast group.
    rpc Update(UpdateMulticastGroupRequest) returns (google.protobuf.Empty) {}

    // Delete the multicast-group with the given ID.
    rpc Delete(DeleteMulticastGroupRequest) returns (google.protobuf.Empty) {}

    // List the available multicast groups.
    rpc List(ListMulticastGroupsRequest) returns (ListMulticastGroupsResponse) {}

    // Add a device to the multicast group.
    rpc AddDevice(AddDeviceToMulticastGroupRequest) returns (google.protobuf.Empty) {}

    // Remove a device from the multicast group.
    rpc RemoveDevice(RemoveDeviceFromMulticastGroupRequest) returns (google.protobuf.Empty) {}

    // Add the given item to the multcast group queue.
    rpc Enqueue(EnqueueMulticastGroupQueueItemRequest) returns (EnqueueMulticastGroupQueueItemResponse) {}

    // Flush the queue for the given multicast group.
    rpc FlushQueue(FlushMulticastGroupQueueRequest) returns (google.protobuf.Empty) {}

    // List the items in the multicast group queue.
    rpc ListQueue(ListMulticastGroupQueueRequest) returns (ListMulticastGroupQueueResponse) {}
}

enum MulticastGroupType {
    // Class C.
    CLASS_C = 0;

    // Class-B.
    CLASS_B = 1;
}

message MulticastGroup {
    // ID (UUID).
    // This will be generated automatically on create.
    string id = 1;

    // Name.
    string name = 2;

    // Application ID.
    // After creation, this can not be updated.
    string application_id = 3;

    // Region.
    common.Region region = 4;

    // Multicast address (HEX encoded DevAddr).
    string mc_addr = 5;

    // Multicast network session key (HEX encoded AES128 key).
    string mc_nwk_s_key = 6;

    // Multicast application session key (HEX encoded AES128 key).
    string mc_app_s_key = 7;

    // Frame-counter.
    uint32 f_cnt = 8;

    // Multicast group type.
    MulticastGroupType group_type = 9;

    // Data-rate.
    uint32 dr = 10;

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

    // Ping-slot period (only for Class-B).
    uint32 class_b_ping_slot_period = 12;
}

message MulticastGroupListItem {
    // ID.
    string id = 1;

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

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

    // Name.
    string name = 4;

    // Region.
    common.Region region = 5;

    // Multicast group type.
    MulticastGroupType group_type = 6;
}

message CreateMulticastGroupRequest {
    // Multicast group to create.
    MulticastGroup multicast_group = 1;
}

message CreateMulticastGroupResponse {
    // ID of created multicast group (UUID).
    string id = 1;
}

message GetMulticastGroupRequest {
    // Multicast group ID.
    string id = 1;
}

message GetMulticastGroupResponse {
    // Multicast group object.
    MulticastGroup multicast_group = 1;

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

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

message UpdateMulticastGroupRequest {
    // Multicast group object to update.
    MulticastGroup multicast_group = 1;
}

message DeleteMulticastGroupRequest {
    // Multicast group iD.
    string id = 1;
}

message ListMulticastGroupsRequest {
    // Max number of multicast groups to return in the result-set.
    uint32 limit = 1;

    // Offset in the result-set (for pagination).
    uint32 offset = 2;

    // If set, the given string will be used to search on name.
    string search = 3;

    // Application ID to list the multicast groups for.
    string application_id = 4;
}

message ListMulticastGroupsResponse {
    // Total number of multicast groups.
    uint32 total_count = 1;

    // Result-test.
    repeated MulticastGroupListItem result = 2;
}

message AddDeviceToMulticastGroupRequest {
    // Multicast group ID.
    string multicast_group_id = 1;

    // Device EUI (HEX encoded).
    string dev_eui = 2;
}

message RemoveDeviceFromMulticastGroupRequest {
    // Multicast group ID.
    string multicast_group_id = 1;

    // Device EUI (HEX encoded).
    string dev_eui = 2;
}

message MulticastGroupQueueItem {
    // Multicast group ID.
    string multicast_group_id = 1;

    // Downlink frame-counter.
    // This will be automatically set on enqueue.
    uint32 f_cnt = 2;

    // FPort (must be > 0).
    uint32 f_port = 3;

    // Payload.
    bytes data = 4;
}

message EnqueueMulticastGroupQueueItemRequest {
    // Multicast queue-item to enqueue.
    MulticastGroupQueueItem multicast_group_queue_item = 1;
}

message EnqueueMulticastGroupQueueItemResponse {
    // Frame-counter of the enqueued payload.
    uint32 f_cnt = 1;
}

message FlushMulticastGroupQueueRequest {
    // Multicast group ID.
    string multicast_group_id = 1;
}

message ListMulticastGroupQueueRequest {
    // Multicast group ID.
    string multicast_group_id = 1;
}

message ListMulticastGroupQueueResponse {
    repeated MulticastGroupQueueItem items = 1;
}