protos/dmi/sw_management_service.proto

syntax = "proto3";

option go_package = "github.com/opencord/device-management-interface/v3/go/dmi";
package dmi;

import "dmi/commons.proto";
import "dmi/hw.proto";
import "dmi/sw_image.proto";

// The software management concept described here is aligned with WT-383a3 (Revision: 06 April 2020).
// In particular Section 11 Software management
// TODO check model

// Protos for managing the software on a hardware device

message SoftwareVersionInformation {
    repeated ImageVersion active_versions = 1;
    repeated ImageVersion standby_versions = 2;
}

message GetSoftwareVersionInformationResponse {
    enum Reason {
        UNDEFINED_REASON = 0;
        UNKNOWN_DEVICE = 1;
        INTERNAL_ERROR = 2;
        DEVICE_UNREACHABLE = 3;
    }
    Status status = 1;
    Reason reason = 2;
    SoftwareVersionInformation info = 3;
    string reason_detail = 4;
}

message DownloadImageRequest {
    Uuid device_uuid = 1;
    ImageInformation image_info = 2;
}

message ConfigRequest {
    Uuid device_uuid = 1;
    // Location of the configuration file, authentication (user/pass) if any should be in the url string
    // The config_url would contain the protocol, credentials, the IP address/DNS of the server and the path of the file
    // e.g. sftp://download_user:download_pass@192.168.0.1:22/OLT-configs/config-v1.2.3.xml
    string config_url = 2;
}

message ConfigResponse {
    enum Reason {
        UNDEFINED_REASON = 0;
        UNKNOWN_DEVICE = 1;
        INTERNAL_ERROR = 2;
        ERROR_FETCHING_CONFIG = 3;
        INVALID_CONFIG = 4;
        OPERATION_ALREADY_IN_PROGRESS = 5;
        DEVICE_UNREACHABLE = 6;
    }
    Status status = 1;
    Reason reason = 2;
    string reason_detail = 3;
}

message StartupConfigInfoRequest {
    Uuid device_uuid = 1;
}

message StartupConfigInfoResponse {
    enum Reason {
        UNDEFINED_REASON = 0;
        UNKNOWN_DEVICE = 1;
        INTERNAL_ERROR = 2;
        DEVICE_UNREACHABLE = 3;
    }
    Status status = 1;
    Reason reason = 2;
    // The config_url is an optional attribute, the device manager could return the location from
    // where the config was downloaded. Also it would not be present/empty for a fresh device into which the
    // startup config would have been installed in the factory.
    string config_url = 3;
    // The version of the startup configuration. It is recommended to use semVer, but the DM implementations
    // and operators could choose any other format as well.
    string version = 4;
    string reason_detail = 5;
}

service NativeSoftwareManagementService {
    // Get the software version information of the Active and Standby images
    rpc GetSoftwareVersion(HardwareID) returns(GetSoftwareVersionInformationResponse);

    // Downloads and installs the image in the standby partition, returns the status/progress of the Install
    rpc DownloadImage(DownloadImageRequest) returns(stream ImageStatus);

    // Activates and runs the OLT with the image in the standby partition. If things are fine this image will
    // henceforth be marked as the Active Partition. The old working image would remain on the Standby partition.
    // Any possibly required (sub-)steps like "commit" are left to the "Device Manager"
    rpc ActivateImage(HardwareID) returns(stream ImageStatus);

    // Marks the image in the Standby as Active and reboots the device, so that it boots from that image which was in the standby.
    // This API is to be used if operator wants to go back to the previous software
    rpc RevertToStandbyImage(HardwareID) returns(stream ImageStatus);

    // This API can be used to let the devices pickup their properitary configuration which they need at startup.
    rpc UpdateStartupConfiguration(ConfigRequest) returns(stream ConfigResponse);

    // This API can be used to retrieve information about the current startup configuration that a device is using
    rpc GetStartupConfigurationInfo(StartupConfigInfoRequest) returns(StartupConfigInfoResponse);

    // If needed we can add this later
    //rpc SubscribeToEvents() returns (stream );
}