collection_schemes.proto

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

option java_package = "com.amazonaws.iot.autobahn.schemas";
package Aws.IoTFleetWise.Schemas.CollectionSchemesMsg;

/*
 * Import common types reused across the project
 */
import "common_types.proto";

/*
 * List of collectionSchemes
 */
message CollectionSchemes {

    /*
     * List of collectionSchemes. On receipt of this, Edge will discard all collectionSchemes it currently has and enact these.
     */
    repeated CollectionScheme collection_schemes = 1;

    /*
     * Timestamp of when the collectionScheme list was created.
     */
    uint64 timestamp_ms_epoch = 2;
}

/*
 * A definition of an individual collectionScheme containing what/when/how to send vehicle data to cloud. A
 * collectionScheme can be condition based, with data sent whenever a condition evaluates to true, or it can be time
 * based, with data sent at periodic intervals.
 */
message CollectionScheme {

    /*
     * Synchronization ID of the campaign this collectionScheme is part of
     */
    string campaign_sync_id = 1;

    /*
     * Synchronization ID of the required decoder manifest for this collectionScheme
     */
    string decoder_manifest_sync_id = 2;

    /*
     * When collectionScheme should start in milliseconds since the Unix epoch
     */
    uint64 start_time_ms_epoch = 3;

    /*
     * When collectionScheme should expire in milliseconds since the Unix epoch. This collectionScheme expiration date
     * is meant to serve as an end date for a collectionScheme so it does not keep running forever in the case
     * that a vehicle permanently loses internet connection to the cloud
     */
    uint64 expiry_time_ms_epoch = 4;

    /*
     * A collectionScheme type containing attributes that are specific to that collectionScheme type. Currently support
     * time based (such as a heartbeat) and condition based collectionSchemes.
     */
    oneof collection_scheme_type {
        TimeBasedCollectionScheme time_based_collection_scheme = 5;
        ConditionBasedCollectionScheme condition_based_collection_scheme = 6;
    }

    /*
     * This specifies how much time to spend collecting data after a condition evaluates to true. When after_duration_ms
     * elapses whatever data collected up to that point ( if any was present on the vehicle ) is sent to the cloud.
     */
    uint32 after_duration_ms = 7;

    /*
     * All active DTCs including the time they were first seen active will be sent when the collectionScheme triggers.
     */
    bool include_active_dtcs = 8;

    /*
     * List of signal ids to collect or have attribute(s) required by a condition function node
     */
    repeated SignalInformation signal_information = 9;

    /*
     * List of Raw CAN Frame(s) to be collected and sent to cloud
     */
    repeated RawCanFrame raw_can_frames_to_collect = 10;

    /*
     * When true, all data will be written to persistent storage when vehicle doesn't not have an internet connection
     */
    bool persist_all_collected_data = 11;

    /*
     * When true, collected data will be compressed and then sent to cloud.
     */
    bool compress_collected_data = 12;

    /*
     * An integer between describing the priority for the data collection. CollectionSchemes with low priority numbers
     * will have higher priority and will be processed first.
     */
    uint32 priority = 13;

    /*
     * This field was never supported, so it should not be used any more.
     */
    reserved 14;
    reserved "probabilities";

    /*
     * This field was never supported, so it should not be used any more.
     */
    reserved 15;
    reserved "image_data";

    /*
     * Additional data for S3 upload.
     */
    S3UploadMetadata s3_upload_metadata = 16;

    /*
     * Configuration of store and forward campaign.
     */
    StoreAndForwardConfiguration store_and_forward_configuration = 17;
    // Signals to fetch configurations.
    repeated FetchInformation signal_fetch_information = 18;

    /*
     * Amazon Resource Name of the campaign this collectionScheme is part of
     */
    string campaign_arn = 19;
}
/*
 * Condition based fetch configuration
 */
message ConditionBasedFetchConfig {
    enum ConditionTriggerMode {

        /*
         * Condition will evaluate to true regardless of previous state
         */
        TRIGGER_ALWAYS = 0;

        /*
         * Condition will evaluate to true only when it previously evaluated to false
         */
        TRIGGER_ONLY_ON_RISING_EDGE = 1;
    }
    // Condition to be evaluated for fetch to trigger
    CommonTypesMsg.ConditionNode condition_tree = 1;
    // Trigger mode for condition
    ConditionTriggerMode condition_trigger_mode = 2;
}

/*
 * Time based fetch configuration
 */
message TimeBasedFetchConfig {
    // Max number of time action for fetch should be executed
    uint64 max_execution_count = 1;
    // Frequency for action execution
    uint64 execution_frequency_ms = 2;
    // Time after which max_execution_count should be reset to original value
    uint64 reset_max_execution_count_interval_ms = 3;
}

message FetchInformation {
    // Signal id that will be fetched
    uint32 signal_id = 1;

    // Fetch configuration for this signal
    oneof fetchConfig {
        TimeBasedFetchConfig time_based = 2;
        ConditionBasedFetchConfig  condition_based = 3;
    };
    // IOT Event expression language version for this config
    uint32 condition_language_version = 4;
    // Expression for the function(s) to call for fetch
    repeated CommonTypesMsg.ConditionNode actions = 5;
}


message S3UploadMetadata {

    /*
     * Bucket name for the S3 upload.
     */
    string bucket_name = 1;

    /*
     * Prefix for object to upload.
     */
    string prefix = 2;

    /*
     * Region of the S3 bucket.
     */
    string region = 3;

    /*
     * Account ID of the bucket owner, required to enforce the expected bucket owner
     */
    string bucket_owner_account_id = 4;
}

/*
 * Contains time based specific attributes necessary for time based collectionSchemes such as a heartbeat.
 */
message TimeBasedCollectionScheme {

    /*
     * Time in milliseconds that will be the interval of a time based collectionScheme if is_time_based_collection_scheme is
     * set to true. This field is unused if is_time_based_collection_scheme is set false.
     */
    uint32 time_based_collection_scheme_period_ms = 1;
}

/*
 * Contains condition based specific attributes necessary for condition based collectionSchemes
 */
message ConditionBasedCollectionScheme {

    /*
     * The minimum time in milliseconds required to elapse between conditions that evaluate to true for data to be sent
     * to the cloud.
     */
    uint32 condition_minimum_interval_ms = 1;

    /*
     * The version number associated with the event condition language used in the abstract syntax tree. We are starting
     * at 0 for alpha and we will increment as we add features
     */
    uint32 condition_language_version = 2;

    /*
     * Root condition node for the Abstract Syntax Tree.
     */
    CommonTypesMsg.ConditionNode condition_tree = 3;

    /*
     * Edge can monitor the previous state of a condition and use this information to allow the customer to set a
     * trigger mode similar to an oscilloscope trigger.
     */
    enum ConditionTriggerMode {

        /*
         * Condition will evaluate to true regardless of previous state
         */
        TRIGGER_ALWAYS = 0;

        /*
         * Condition will evaluate to true only when it previously evaluated to false
         */
        TRIGGER_ONLY_ON_RISING_EDGE = 1;
    }

    /*
     * A triggering mode can be applied to the condition to take in account the previous state of the condition.
     */
    ConditionTriggerMode condition_trigger_mode = 4;
}

/*
 * This message contains information of signals that are to be collected and sent to cloud, or are part of the condition
 * logic and require attribute information.
 */
message SignalInformation {

    /*
     * Unique identifier of a Signal. Maps directly to a signal defined in the decoder manifest.  Signal can also be an
     * OBDII PID.
     */
    uint32 signal_id = 1;

    /*
     * signal path specifies the location of partial signal. If signal_id refers to a primitive type, like all CANSignal, signal_path is not allowed be set
     * If signal_path for the signal defined in signal_id does not refer to a primitive type the ingestion will change to raw byte ingestion (not vehicle_data.proto)
     * PrimitiveTypeInComplexSignal is not used here as signal_path together with the signal_id might refer to an aggregated type and not only to primitive data
     */
    CommonTypesMsg.SignalPath signal_path = 6;

    /*
     * The size of the ring buffer that will contain the data points for this signal
     */
    uint32 sample_buffer_size = 2;

    /*
     * Minimum time period in milliseconds that must elapse between collecting samples. Samples arriving faster than
     * this period will be dropped. A value of 0 will collect samples as fast as they arrive.
     */
    uint32 minimum_sample_period_ms = 3;

    /*
     * The size of a fixed window in milliseconds which will be used by aggregate condition functions to calculate
     * min/max/avg etc.
     */
    uint32 fixed_window_period_ms = 4;

    /*
     * When true, this signal will not be collected and sent to cloud. It will only be used in the condition logic with
     * its associated fixed_window_period_ms. Default is false.
     */
    bool condition_only_signal = 5;

    /*
     * The Id of the partition where this signal should be stored. This Id will be used to index into the partition
     * configuration array.
     */
    uint32 data_partition_id = 7;
}

/*
 * A raw CAN frame specified to be collected and sent to the cloud.
 */
message RawCanFrame {

    /*
     * The interface ID specified by the Decoder Manifest. This will contain the physical channel id of the hardware CAN
     * Bus the frame is present on.
     */
    string can_interface_id = 1;

    /*
     * CAN Message ID to collect. This Raw CAN message will be collected. Whatever number of bytes present on the bus
     * for this message ID will be collected.
     */
    uint32 can_message_id = 2;

    /*
     * Ring buffer size used to store these sampled CAN frames. One CAN Frame is a sample.
     */
    uint32 sample_buffer_size = 3;

    /*
     * Minimum time period in milliseconds that must elapse between collecting samples. Samples arriving faster than
     * this period will be dropped. A value of 0 will collect samples as fast as they arrive.
     */
    uint32 minimum_sample_period_ms = 4;
}

/*
 * Store and Forward storage options, required. It defines where and how the data will be stored on the edge. It is only used when
 * spoolerMode=TO_DISK. May be non-null only when spoolerMode=TO_DISK.
 */
message StorageOptions {

    /*
     * The total amount of space allocated to this campaign including all overhead. Limited to a maximum of 1024TB.
     */
    uint64 maximum_size_in_bytes = 1;

    /*
     * Specifies where the data should be stored withing the device. Implementation is defined by the user who
     * integrates FWE with their filesystem library.
     */
    string storage_location = 2;

    /*
     * The minimum amount of time to keep data on disk after it is collected. When this TTL expires, data may be
     * deleted, but it is not guaranteed to be deleted immediately after expiry. Can hold TTL more than 132 years.
     */
    uint32 minimum_time_to_live_in_seconds = 3;

}

/*
 * Store and Forward upload options defines when the stored data may be uploaded. It is only used when
 * spoolerMode=TO_DISK. May be non-null only when spoolerMode=TO_DISK.
 */
message UploadOptions {

    /*
     * Root condition node for the Abstract Syntax Tree.
     */
    CommonTypesMsg.ConditionNode condition_tree = 1;
}

/*
 * Store and Forward configuration for each partition.
 */
message PartitionConfiguration {

    /*
     * Optional Store and Forward storage options. If not specified, data in this partition will be uploaded in
     * realtime.
     */
    StorageOptions storage_options = 1;

    /*
     * Store and Forward upload options defines when the stored data may be uploaded. It is only used when
     * spoolingMode=TO_DISK. May be non-null only when spoolingMode=TO_DISK.
     */
    UploadOptions upload_options = 2;
}

/*
 * When spoolingMode is set to TO_DISK and PartitionConfiguration is not Null, then store and forward subsystem will be
 * used to persistently store collected data. If non-null then spoolingMode must be TO_DISK.
 *
 * Optional. Required if any signalsToCollect specify a non-default partition.
 */
message StoreAndForwardConfiguration {

    /*
     * Array of Store and Forward configurations for each data partition.
     */
    repeated PartitionConfiguration partition_configuration = 1;
}