interfaces/protobuf/schemas/cloudToEdge/decoder_manifest.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.DecoderManifestMsg;

message DecoderManifest {

  /*
   * Synchronization ID of the decoder manifest
   */
  string sync_id = 1;

  /*
   * List of signals that are sent and received on the CAN BUS in the vehicle
   */
  repeated CANSignal can_signals = 2;

  /*
   * List of OBDII-PID signals and corresponding decoding rules
   */
  repeated OBDPIDSignal obd_pid_signals = 3;

  /*
   * List of complex types
   * N.B. there must not be circular references between complex types
   */
  repeated ComplexType complex_types = 4;

  /*
   * List of complex signals, which refer to the complex types
   */
  repeated ComplexSignal complex_signals = 5;

  /*
   * List of custom decoding signals
   */
  repeated CustomDecodingSignal custom_decoding_signals = 6;
}

message CANSignal {

  /*
   * Unique integer identifier of the signal generated by Cloud Designer
   * Value zero is reserved for internal usage.
   * The most significant bit is reserved for internal usage.
   */
  uint32 signal_id = 1;

  /*
   * Interface ID for CAN network interface this signal is found on. The CAN network interface details are provided as
   * a part of the edge static configuration file.
   */
  string interface_id = 2;

  /*
   * CAN Message Id
   */
  uint32 message_id = 3;

  /*
   * True when signal is encoded in Big Endian
   */
  bool is_big_endian = 4;

  /*
   * True when signal is signed
   */
  bool is_signed = 5;

  /*
   * Start bit position of the signal in the message
   */
  uint32 start_bit = 6;

  /*
   * physical_signal_value = raw_value * factor + offset
   */
  double offset = 7;

  /*
   * physical_signal_value = raw_value * factor + offset
   */
  double factor = 8;

  /*
   * Length of the CAN signal
   */
  uint32 length = 9;

  /*
   * A CANSignal has always a primitive type, so here the primitive type can be defined.
   * If not present this value defaults to FLOAT64.
   */
  PrimitiveType primitive_type = 10;

  SignalValueType signal_value_type = 11;
}

/*
 * This is the OBDII-PID signal decoding rule. One OBDII-PID could contain multiple signals. Below section is the
 * decoder rule per signal, not per PID
 */
message OBDPIDSignal {

  /*
   * Unique numeric identifier for the OBDII-PID signal
   * Value zero is reserved for internal usage.
   * The most significant bit is reserved for internal usage.
   */
  uint32 signal_id = 1;

  /*
   * Interface ID for CAN network interface this signal is found on. The CAN network interface details are provided as
   * a part of the edge static configuration file.
   */
  string interface_id = 2;

  /*
   * Length of the PID response. Note this is not the signal byte length as PID might contain multiple signals
   */
  uint32 pid_response_length = 3;

  /*
   * OBDII-PID Service Mode for the signal in decimal
   */
  uint32 service_mode = 4;

  /*
   * OBD request PID in decimal
   */
  uint32 pid = 5;

  /*
   * scaling to decode OBD from raw bytes to double value
   * e.g. A * 0.0125 - 40. Scaling is 0.0125
   */
  double scaling = 6;

  /*
   * offset to decode OBD from raw bytes to double value
   * e.g. A * 0.0125 - 40. offset is -40.0
   */
  double offset = 7;

  /*
   * the start byte order (starting from 0th) for this signal in its PID query response
   * e.g. PID 0x14 contains two signals, with Signal B located in the 2nd byte startByte is 1
   */
  uint32 start_byte = 8;

  /*
   * number of bytes for this signal in its PID query response
   * e.g. PID 0x14 contains two signals. SHRFT is one byte. Its byteLength is 1
   */
  uint32 byte_length = 9;

  /*
   * Right shift on bits to decode this signal from raw bytes. Note the bit manipulation is only performed when
   * byteLength is 1. e.g. Boost Pressure B Control Status is bit 2, 3 on byte J. The right shift shall be 2 For
   * non-bitmask signals, the right shift shall always be 0
   */
  uint32 bit_right_shift = 10;

  /*
   * bit Mask Length to be applied to decode this signal from raw byte. Note the bit manipulation is only performed when
   * byteLength is 1. e.g. Boost Pressure B Control Status is bit 2, 3 on byte J. The bit Mask Length would be 2 For
   * non-bitmask signals, the bit Mask Length shall always be 8.
   */
  uint32 bit_mask_length = 11;

  /*
   * A OBDPIDSignal has always a primitive type, so here the primitive type can be defined.
   * If not present this value defaults to FLOAT64.
   */
  PrimitiveType primitive_type = 12;

  SignalValueType signal_value_type = 13;

  /*
   * True when signal is signed
   */
  bool is_signed = 14;
}

/*
 * Enum of primitive types used by PrimitiveData, CANSignal and OBDPIDSignal
 */
enum PrimitiveType {
  NULL = 0;
  BOOL = 1;
  UINT8 = 2;
  UINT16 = 3;
  UINT32 = 4;
  UINT64 = 5;
  INT8 = 6;
  INT16 = 7;
  INT32 = 8;
  INT64 = 9;
  FLOAT32 = 10;
  FLOAT64 = 11;
  STRING = 12;
}

enum SignalValueType {
  INTEGER = 0;
  FLOATING_POINT = 1;
}

/*
 * Primitive data decoding information used by ComplexType
 */
message PrimitiveData {
  PrimitiveType primitive_type = 1;
  double scaling = 2;
  double offset = 3;
}

enum StringEncoding {
  UTF_8 = 0;
  UTF_16 = 1;
}

message StringData {
  StringEncoding encoding = 1;
  /*
   * The size describes the number of code units so it can be bigger than the number of characters and depends on the encoding.
   * size = 0 means dynamic size see ComplexArray size field.
   */
  int64 size = 2;
}


/*
 * Complex array containing multiple elements of the same complex type
 */
message ComplexArray {
  /*
  * size > 0 : Fixed sized array always has the same size
  * size < 0 : The array has dynamic size but is never bigger than the maximum = size * -1
  * size = 0 : The array has dynamic size and a maximum estimate is unknown so from having 1 element
  *                  to multiple gigabyte can arrive as long as edge client can handle it
  */
  int64 size = 1;
  uint32 type_id = 2;
}

/*
 * Complex struct member containing type id and name
 */
message ComplexStructMember {
  uint32 type_id = 1;
  /* in the future additional details like the name as string could be added here */
}

/*
 * Complex struct containing complex types
 */
message ComplexStruct {
  repeated ComplexStructMember members = 1;
}

/*
 * Complex type, that can contain either: a primitive signal, a complex struct or a complex array
 */
message ComplexType {
  uint32 type_id = 1; // Must be unique across the whole decoder manifest
  oneof variant {
    PrimitiveData primitive_data = 2;
    ComplexStruct struct = 3;
    ComplexArray array = 4;
    StringData string_data = 5;
  }
}

message ComplexSignal {
  /*
   * Unique integer identifier of the signal across all types (  i.e. CANSignal, OBDPIDSignal, ComplexSignal)
   * As this signal_id refers to a complex type, when referenced in places where a primitive type is required it
   * has to be accompanied with a path that refers to a primitive type in a PrimitiveData leaf in root_type_id.
   * Value zero is reserved for internal usage.
   * The most significant bit is reserved for internal usage.
   */
  uint32 signal_id = 1;

  /*
   * Interface ID for the network interface this signal is found on. The network interface details are provided as
   * a part of the edge static configuration file.
   */
  string interface_id = 2;
   /*
   * Interface-specific message information. The pair interface_id and message_id should be unique across all ComplexSignals.
   * For ROS2 this is the topic on which the message is sent.
   */
  string message_id = 3;
   /*
   * Type id of the root signal. 0 is reserved for future usage.
   */
  uint32 root_type_id = 4;
}

message CustomDecodingSignal {
  /*
   * Unique FleetWise internal identifier of the signal across all types (  i.e. CANSignal, OBDPIDSignal, CustomDecodingSignal)
   * Value zero is reserved for internal usage.
   * The most significant bit is reserved for internal usage.
   */
  uint32 signal_id = 1;

  /*
   * Interface ID for the network interface this signal is found on. The network interface details are provided as
   * a part of the edge static configuration file.
   */
  string interface_id = 2;

  /*
   * Custom proprietary decoding identifier.
   */
  string custom_decoding_id = 3;

  /*
   * A CustomDecodingSignal has always a primitive type, so here the primitive type can be defined.
   * If not present this value defaults to FLOAT64.
   */
  PrimitiveType primitive_type = 4;
}