Device Details Protobuf Definitions

The following example common_value.proto file describes the supported data types that are common across the device details. The values contain a string representation of the value and the data type of the data.

/*
 * Copyright (c) 2017 General Electric Company. All rights reserved.
 *
 * The copyright to the computer software herein is the property of
 * General Electric Company. The software may be used and/or copied only
 * with the written permission of General Electric Company or in accordance
 * with the terms and conditions stipulated in the agreement/contract
 * under which the software has been supplied.
 */

/*
 * Describes the structures of key-value pairs.
 */

syntax = "proto3";

package com.ge.predixmachine.protobuf;

option java_multiple_files = true;
option java_package = "com.ge.predixmachine.datamodel.common";
option java_generate_equals_and_hash = true;

// A generic value in any of the supported datatypes.
message Value
{
    // The value in string format
    // Default: Empty string
    string value = 1;

    // Type of data represented in value field
    // Default: DataType.DATATYPE_STRING
    DataType data_type = 2;
}

enum DataType
{
    // Default
    // A string of UTF-8 encoded characters.
    // Default: Empty string
    DATATYPE_STRING = 0;

    // A byte array
    // Default: Empty array
    DATATYPE_BINARY = 1;

    // The boolean data type has only two possible values: true and false
    // Default: false
    DATATYPE_BOOLEAN = 2;

    // 32-bit floating point number
    // Default: 0.0f
    DATATYPE_FLOAT = 3;

    // 64-bit floating point number
    // Default: 0.0d
    DATATYPE_DOUBLE = 4;

    // 32-bit signed two's complement integer
    // Minimum value: -2^31
    // Maximum value: 2^31-1
    // Default: 0
    DATATYPE_INT = 5;

    // 64-bit signed two's complement integer
    // Minimum value: -2^63
    // Maximum value: 2^63-1
    // Default: 0L
    DATATYPE_LONG = 6;

    // A point in time represented in RFC3399 format
    // Examples: "2016-10-28T03:20:23+00:00", "2016-10-25T03:54:43.230Z", "2016-10-24T18:15:30-05:00"
    // Default: UTC Epoch time ("0001-01-01T00:00:00Z")
    DATATYPE_TIMESTAMP = 15;

    // Other Proto supported types
    // DATATYPE_UINT32
    // DATATYPE_UINT64
    // DATATYPE_SINT32
    // DATATYPE_SING64
    // DATATYPE_FIXED32
    // DATATYPE_FIXED64
    // DATATYPE_SFIXED32
    // DATATYPE_SFIX64
}

The following example edge_device_info.proto file describes the data structures for device info.

/*
 * Copyright (c) 2016 General Electric Company. All rights reserved.
 *
 * The copyright to the computer software herein is the property of
 * General Electric Company. The software may be used and/or copied only
 * with the written permission of General Electric Company or in accordance
 * with the terms and conditions stipulated in the agreement/contract
 * under which the software has been supplied.
 */

/*
 * Describes the structures of Device Info.
 */

syntax = "proto3";

import "google/protobuf/timestamp.proto";
import "common_value.proto";

package com.ge.predixmachine.protobuf;

option java_multiple_files = true;
option java_package = "com.ge.predixmachine.datamodel.gateway";
option java_generate_equals_and_hash = true;

//
// Represents the static information of a device.
// This information is collected on the device and passed to Edge Manager via Cloud Gateway.
//
message DeviceInfo
{
    repeated HardwareInfo hardware_info = 1;
    repeated SimInfo sim_info = 2;

    map<string, Value> attributes = 100;
}

//
// Represents the dynamic information of a device.
// This information is collected on the device and passed to Edge Manager via Cloud Gateway.
//
message DeviceStatus
{
    repeated PowerSupplyStatus power_supply_status = 1;
    repeated BluetoothStatus bluetooth_status = 2;
    repeated WifiStatus wifi_status = 3;

    CpuStatus cpu_status = 4;
    MemoryStatus memory_status = 5;
    google.protobuf.Timestamp boot_time = 6;

    repeated NetworkInfo network_info = 7;
    repeated CellularStatus cellular_status = 8;

    repeated DiskStatus disk_status = 9;

    map<string, Value> attributes = 100;
}

//
// Represents the custom information of a device.
// This information is collected on the device and passed to Edge Manager via Cloud Gateway.
//
message DeviceProperties
{
    map<string, Value> attributes = 100;
}

//
// A list of vendor-installed software on a device.
// This information is collected on the device and passed to Edge Manager via Cloud Gateway.
//
message SoftwareInfoList
{
    repeated SoftwareInfo software_info = 1;
}

// Information of hardware installed on the device.
message HardwareInfo
{
    // Category like cpu, modem, antenna, disk, memory, etc.
    string category = 1;
    // Manufacturer of hardware
    string manufacturer = 2;
    // Model information of hardware
    string model = 3;
    // Firmware information of hardware
    string firmware = 4;

    // Other information of hardware
    // @Deprecated Use attributes instead.
    map<string,string> properties = 100;

    // Other information of hardware
    // @since 17.1
    map<string, Value> attributes = 101;
}

// SIM card information
message SimInfo
{
    string iccid = 1;
    string imei = 2;
    map<string, Value> attributes = 100;
}

// Dynamic status of power supply
message PowerSupplyStatus
{
    string type = 1; // AC, DC, battery, UPS, etc.
    string state = 2;
    int32 percentage_full = 3; // Only for battery & UPS types
    string description = 20;
    map<string, Value> attributes = 100;
}

// Dynamic bluetooth status
message BluetoothStatus
{
    bool enabled = 1;
    bool connected = 2;
    string profile = 3;
    string connected_device = 4;
    map<string, Value> attributes = 100;
}

// Dynamic wifi status
message WifiStatus
{
    bool enabled = 1;
    bool connected = 2;
    string ssid = 3;
    map<string, Value> attributes = 100;
}

// Dynamic cellular status
message CellularStatus
{
    // Identifier of the cellular module
    string id = 1;

    // Network mode, for example GSM, WCDMA, TD-SCDMA, LTE, etc.
    string network_mode = 3;

    // Data in bytes transferred since the beginning of the month
    uint64 data_volume = 5;

    // Signal strength, for example
    // - rssi - Received Signal Strength Indicator (dBm)
    // - rsrp - Reference Signal Received Power (dBm)
    // - rsrq - Reference Signal Received Quality (dBm)
    // - sinr - Signal to Interference plus Noise Ratio (dBm)
    // - rscp - Received signal code power (dBm)
    // - ecio - Energy per Chip to Interference of Other cell ration (dBm)
    map<string, int32> signal_strength = 10;

    // Generic properties
    map<string, Value> attributes = 100;
}

// Dynamic CPU status
message CpuStatus
{
    double cpu_percent_user = 1;
//    double cpu_percent_nice = 2;
    double cpu_percent_system = 3;
    double cpu_percent_idle = 4;
//    double cpu_percent_iowait = 5;
//    double cpu_percent_irq = 6;
//    double cpu_percent_softirq = 7;
//    double cpu_percent_steal = 8;
//    double cpu_percent_guest = 9;
//    double cpu_percent_guest_nice = 10;

    // Load average over 1, 5, and 15 minutes. The load average is the average number of jobs in the run queue.
    repeated double cpu_load_average = 15;
}

message MemoryStatus
{
    int64 total_bytes = 1;
    int64 free_bytes = 2;
}

message DiskStatus
{
    // Name of disk
    string name = 1;

    // Type of disk
    string type = 2;

    // True if this is the disk running Predix Machine
    bool machine_disk = 3;

    // Size of disk in bytes.
    int64 total_bytes = 7;

    // Number of unallocated bytes on the disk.
    int64 free_bytes = 8;
}

message NetworkInfo
{
    string name = 1;
    string display_name = 2;
    repeated string ipv4_addresses = 3;
    repeated string ipv6_addresses = 4;
}

// Information of a software package
message SoftwareInfo
{
    string name = 1;
    string vendor = 2;
    SoftwareType type = 3;
    string version = 4;
    google.protobuf.Timestamp install_time = 5;
    string status = 6;
    string description = 20;

    map<string, Value> attributes = 100;
}

// Type of software.
enum SoftwareType
{
    UNKNOWN_TYPE = 0; // Default
    APPLICATION_TYPE = 1;
    SYSTEM_TYPE = 2;
    CONFIGURATION_TYPE = 3;
}

// Information of Predix Machine
message MachineInfo
{
    // Version of Predix machine running on the device.
    string machine_version = 1;

    // Information of the Predix Machine bundles running on the device.
    repeated MachineBundle bundle = 2;

    // Version of the OSGi container running on the device.
    string prosyst_version = 3;

    // Number of days remaining on the OSGi container license.
    string prosyst_key_expire = 4;

    // Version of the Java running on the device.
    string java_version = 5;

    // Vendor of the Java JDK
    string java_vendor = 6;

    // Information of the Predix Machine components running on the device.
    repeated MachineServiceComponent service = 7;

    // Information of the operating system running on the device.
    OsInfo os_info = 8;
}

message OsInfo
{
    string os_name = 1;
    string os_version = 2;
    string os_arch = 3;
}

message MachineBundle
{
    // Symbolic name of bundle
    string name = 1;
    // Version of the bundle
    string version = 2;
    // State of the bundle
    MachineBundleState state = 3;
}

enum MachineBundleState
{
    UNINSTALLED = 0;  // Default
    INSTALLED = 1;
    RESOLVED = 2;
    STARTING = 3;
    STOPPING = 4;
    ACTIVE = 5;
}

message MachineServiceComponent
{
    // Symbolic name of ServiceComponent
    string name = 1;
    // State of the component
    MachineServiceComponentState state = 2;
    // Provided service instances
    string provided_services = 3;
}

enum MachineServiceComponentState
{
    STATE_UNKNOWN = 0;  // Default
    STATE_DISABLED = 1;
    STATE_UNSATISFIED = 2;
    STATE_ACTIVE = 3;
}


////////////////////////////////////////////////////
// EDGE ALERT
////////////////////////////////////////////////////

//
// Represents the structure of an alert.
// Alerts collected from device or cloud services are propagated to Edge Manager.
//
message EdgeAlert
{
    // This determines the handler for the alert
    // Currently supported types:
    // - SIM_USAGE
    // - DEVICE_ONLINE_OFFLINE
    // - OPENVPN_STATUS
    // - CELLULAR_STRENGTH
    string alert_type = 1;

    // Identifier of the device where the alert originates from.
    // Default to empty string.
    string device_id = 2;

    // Type of originator where this alert comes from.
    // Default to ALERT_SOURCE_UNKNOWN if not specified.
    AlertSourceType source_type = 5;

    // Identifier of the source where the alert originates from. (max length: 64)
    // For example, a SIM ID for SIM_USAGE alerts, or OpenVpn client ID for OPENVPN_STATUS alerts, etc.
    string source = 6;

    // Severity of alert.
    // Default to ALERT_SEVERITY_UNKNOWN if not specified.
    AlertSeverity severity = 8;

    // Description of alert. (max length: 255)
    // For example, "SIM usage exceeded 100% of usage plan"
    string description = 10;

    // Timestamp of when this alert is created.
    // Default to the Epoch time if not specified.
    google.protobuf.Timestamp timestamp = 12;

    // Status of alert.
    // Default to ALERT_STATUS_UNKNOWN if not specified.
    AlertStatus status = 15;
}

message EdgeAlertList
{
    repeated EdgeAlert edge_alert = 1;
}

enum AlertSourceType
{
    ALERT_SOURCE_UNKNOWN = 0; // Default
    ALERT_SOURCE_DEVICE = 1;
    ALERT_SOURCE_SIM = 2;
    ALERT_SOURCE_OPENVPN = 3;
}

enum AlertSeverity
{
    ALERT_SEVERITY_UNKNOWN = 0; // Default
    ALERT_SEVERITY_CRITICAL = 2;
    ALERT_SEVERITY_ERROR = 5;
    ALERT_SEVERITY_WARNING = 8;
    ALERT_SEVERITY_INFO = 11;
}

enum AlertStatus
{
    ALERT_STATUS_UNKNOWN = 0;  // Default
    ALERT_STATUS_OPEN = 1;
    ALERT_STATUS_ACKNOWLEDGED = 2;
    ALERT_STATUS_CLOSED = 3;
}