mm_driver.proto

Go to the documentation of this file.

syntax = "proto2";
import "goby/acomms/protobuf/driver_base.proto";
import "goby/acomms/protobuf/modem_message.proto";
import "goby/protobuf/option_extensions.proto";
import "dccl/option_extensions.proto";
 
package goby.acomms.micromodem.protobuf;
 
message NarrowBandLBLParams
{
    // for MICROMODEM_NARROWBAND_LBL_RANGING
    optional uint32 transmit_freq = 1;     // in hertz
    optional uint32 transmit_ping_ms = 2;  // length of tx ping
    repeated uint32 receive_freq =
        3;  // in hertz, first element (0) == beacon A, etc.
    optional uint32 receive_ping_ms = 4;  // length of rx ping
 
    optional uint32 turnaround_ms = 5;
    optional bool transmit_flag = 6
        [default =
             true];  // Flag to indicate whether the transmit signal is
                     // actually sent (1), or whether the ping is initiated
                     // with an external synchronization pulse (0).
 
    // meters
    optional uint32 lbl_max_range = 7 [default = 2000];
}
 
message REMUSLBLParams
{
    // for MICROMODEM_REMUS_LBL_RANGING
    // LSB->MSB is LBL beacons 1,2,3,... true is enabled, false is disabled
    // enable four beacons is b1111 == d15
    optional uint32 enable_beacons = 1 [default = 15];
    optional uint32 turnaround_ms = 2 [default = 50];
 
    // meters
    optional uint32 lbl_max_range = 3 [default = 1000];
}
 
message GenericLBLParams
{
    // for MICROMODEM_GENERIC_LBL_RANGING
    optional uint32 transmit_freq = 1;  // in hertz
    optional uint32 n_bits =
        2;  // number of bits to use from the signal sequence, same for outgoing
            // as well as incoming pings
    optional uint64 transmit_seq_code =
        3;  // outgoing sequence bits, packed into a 64 bit int
    optional uint32 receive_freq =
        4;  // in hertz, first element (0) == beacon A, etc.
    repeated uint64 receive_seq_code = 5;  // signals to receive
    optional uint32 bandwidth =
        6;  // chiprate/bandwidth, of outgoing and receive signals
 
    optional uint32 turnaround_ms = 7;
    // meters
    optional uint32 lbl_max_range = 8 [default = 2000];
}
 
message FMSweepParams
{
    // for MICROMODEM_FM_SWEEP
    required double start_freq = 1;
    required double stop_freq = 2;
    required double duration_ms = 3;
    optional uint32 number_repetitions = 4 [default = 1];
    optional double repetition_period_ms = 5 [default = 1000];
}
 
message MSequenceParams
{
    // for MICROMODEM_M_SEQUENCE
    required uint32 seqlen_bits =
        1;  // Sequence length, bits. Should be 2k-1, where k={4...16}
    required uint32 number_repetitions =
        2;  // number of repetitions, between 3 to 60.
    required uint32 carrier_cycles_per_chip = 3;
    required uint32 carrier_freq = 4;  // carrier, Hz
}
 
message Config
{
    // reset all NVRAM settings to factory before
    // setting ours ($CCCFG,ALL,0)
    optional bool reset_nvram = 1 [default = false];
 
    // add NVRAM configuration sentences to send to the modem
    // on startup (e.g. "$CACFG,SRC,1"). Omit the "$CACFG," here.
    // To reinitialize all values to factory settings, send "ALL,0"
    repeated string nvram_cfg = 2;  // e.g. "SRC,3"
 
    // set to a non-zero value to indicate that we are using the hydroid
    // gateway buoy which has a non-standard sentence structure (#M / !M
    // prefixes) *do not set for the normal WHOI Micro-Modem*
    optional uint32 hydroid_gateway_id = 3 [default = 0];
 
    // LBL parameters can be set globally here or on a per-transmission
    // basis
    optional NarrowBandLBLParams narrowband_lbl = 4;
    optional REMUSLBLParams remus_lbl = 5;
 
    optional int32 keep_alive_seconds = 6 [default = 10];
 
    optional int32 allowed_skew_ms = 7 [default = 1000];
 
    optional GenericLBLParams generic_lbl = 8;
 
    optional FMSweepParams fm_sweep = 9;
    optional MSequenceParams m_sequence = 10;
 
    optional bool use_application_acks = 20 [default = false];
    repeated uint32 additional_application_ack_modem_id = 21;
    
    optional bool query_cfg_on_startup = 22 [default = true];
 
    optional bool pad_partial_frames = 23 [
        default = false,
        (goby.field).description =
            "Pad partial frames with trailing zeros to reach the full frame length. This was a workaround for a bug in early versions of the MM2 firmware."
    ];
 
    message Revision
    {
    required int32 mm_major = 1;
    required int32 mm_minor = 2;
    required int32 mm_patch = 3;
    }
    
    optional Revision revision = 30;
 
    optional bool use_base64_fdp = 40 [default = false];
}
 
extend goby.acomms.protobuf.DriverConfig
{
    optional Config config = 1000;
}
 
enum ClockMode
{
    INVALID_CLOCK_MODE = -1;
    NO_SYNC_TO_PPS_AND_CCCLK_BAD = 0;
    NO_SYNC_TO_PPS_AND_CCCLK_GOOD = 1;
    SYNC_TO_PPS_AND_CCCLK_BAD = 2;
    SYNC_TO_PPS_AND_CCCLK_GOOD = 3;
}
 
message RangingReply
{
    option (dccl.msg).id = 128;
    option (dccl.msg).max_bytes = 32;
    option (dccl.msg).unit_system = "si";
    option (dccl.msg).codec_version = 3;
 
    // seconds
    repeated double one_way_travel_time = 1 [
        (dccl.field).min = 0,
        (dccl.field).max = 30,
        (dccl.field).precision = 3,
        (dccl.field).max_repeat = 4,
        (dccl.field).units = {base_dimensions: "T"}
    ];
    enum OWTTAmbiguity
    {
        OWTT_EXACT = 1;  // one_way_travel_time reported is correct and known
        OWTT_SECOND_AMBIGUOUS = 2;  // one way travel time fractional second is
                                    // correct, but second is unknown
    }
    optional OWTTAmbiguity ambiguity = 2 [default = OWTT_EXACT];
    optional bool is_one_way_synchronous = 3
        [default = false];  // if false, type given by ModemTransmission.type
    optional ClockMode receiver_clk_mode = 4
        [default = NO_SYNC_TO_PPS_AND_CCCLK_BAD];
    optional ClockMode sender_clk_mode = 5
        [default = NO_SYNC_TO_PPS_AND_CCCLK_BAD];
}
 
enum PacketType
{
    PACKET_TYPE_UNKNOWN = -1;
    FSK = 1;
    FSK_MINI = 2;
    PSK = 3;
    PSK_MINI = 4;
    FLEXIBLE_DATA_PACKET = 5;
}
 
enum ReceiveMode
{
    INVALID_RECEIVE_MODE = -1;
    RECEIVE_GOOD = 0;
    BAD_CRC = 1;
    PACKET_TIMEOUT = 2;
}
 
enum PSKErrorCode
{
    INVALID_PSK_ERROR_CODE = -1;
    NO_ERROR = 0;
    BAD_MODULATION_HEADER = 1;
    BAD_CRC_DATA_HEADER = 2;
    BAD_CRC_AT_LEAST_ONE_FRAME = 3;
    ERROR_ACCESSING_COPROC = 4;
    EQUALIZER_TIMEOUT = 5;
    MISSED_START_OF_PSK_PACKET = 6;
}
 
// $CACST,0,223413.0000,0,1440,25,0175,0166,75,01,01,01,03,1,007,006,0,3,3,0,146,03,04,-100,-1,000,-1.2,45,10000,2000
message ReceiveStatistics
{
    option (dccl.msg) = {
        id: 129,
        max_bytes: 32,
        unit_system: "si",
        codec_version: 3
    };
 
    // including in "version 0", or the original CACST
    required ReceiveMode mode = 1;
    required uint64 time = 2 [(dccl.field) = {
        codec: "_time",
        units: {prefix: "micro" base_dimensions: "T"}
    }];
    required ClockMode clock_mode = 3;
    optional int32 mfd_peak = 4 [(dccl.field).omit = true];
    required int32 mfd_power = 5
        [(dccl.field).min = -30, (dccl.field).max = 40];
    required int32 mfd_ratio = 6
        [(dccl.field).min = 0, (dccl.field).max = 16383];
    optional int32 spl = 7 [(dccl.field).omit = true];
    optional int32 shf_agn = 8 [(dccl.field).omit = true];
    optional int32 shf_ainpshift = 9 [(dccl.field).omit = true];
    optional int32 shf_ainshift = 10 [(dccl.field).omit = true];
    optional int32 shf_mfdshift = 11 [(dccl.field).omit = true];
    optional int32 shf_p2bshift = 12 [(dccl.field).omit = true];
    required int32 rate = 13 [(dccl.field).min = -1, (dccl.field).max = 6];
    required int32 source = 14 [(dccl.field).min = 0, (dccl.field).max = 127];
    required int32 dest = 15 [(dccl.field).min = 0, (dccl.field).max = 127];
    required PSKErrorCode psk_error_code = 16;
    required PacketType packet_type = 17;
    required int32 number_frames = 18
        [(dccl.field).min = 0, (dccl.field).max = 8];
    required int32 number_bad_frames = 19
        [(dccl.field).min = 0, (dccl.field).max = 8];
    required int32 snr_rss = 20 [(dccl.field).min = 0, (dccl.field).max = 255];
    required int32 snr_in = 21 [(dccl.field).min = -10, (dccl.field).max = 30];
    required int32 snr_out = 22 [(dccl.field).min = 0, (dccl.field).max = 25];
    required int32 snr_symbols = 23
        [(dccl.field).min = 0, (dccl.field).max = 30];
    required int32 mse_equalizer = 24
        [(dccl.field).min = -30, (dccl.field).max = 5];
    required int32 data_quality_factor = 25
        [(dccl.field).min = 0, (dccl.field).max = 255];
    required double doppler = 26 [
        (dccl.field).min = -3,
        (dccl.field).max = 3,
        (dccl.field).precision = 1
    ];
    required int32 stddev_noise = 27
        [(dccl.field).min = 0, (dccl.field).max = 255];
    required int32 carrier_freq = 28
        [(dccl.field).min = 100, (dccl.field).max = 30000];
    required int32 bandwidth = 29
        [(dccl.field).min = 1000, (dccl.field).max = 5000];
 
    // new for "version 6+", firmware 0.93.0.52+
    optional int32 version = 30 [default = 0, (dccl.field).omit = true];
    optional string date = 31 [(dccl.field).omit = true];
    optional int32 pcm = 32 [(dccl.field).omit = true];
}
 
enum TransmitMode
{
    INVALID_TRANSMIT_MODE = -1;
    TRANSMIT_SUCCESSFUL = 0;
    FETS_TOO_HOT = 1;
    EXTSYNC_TIMEOUT = 2;
    TX_INHIBITED = 3;
    DATA_TIMEOUT = 4;
}
 
message TransmitStatistics
{
    optional string date = 1;
    optional string time = 2;
    optional ClockMode clock_mode = 3;
    optional TransmitMode mode = 4;
    optional int32 probe_length = 5;
    optional int32 bandwidth = 6;
    optional int32 carrier_freq = 7;
    optional int32 rate = 8;
    optional int32 source = 9;
    optional int32 dest = 10;
    optional bool ack_requested = 11;
    optional int32 number_frames_expected = 12;
    optional int32 number_frames_sent = 13;
    optional PacketType packet_type = 14;
    optional int32 number_bytes = 15;
 
    optional int32 version = 100 [default = 0];
}
 
enum TransmissionType
{
    BASE_TYPE = 0;
 
    MICROMODEM_TWO_WAY_PING =
        1;  // modem 1 interrogates modem 2; modem 2 replies and modem 1
            // computes one way travel time: $CCMPC
    MICROMODEM_REMUS_LBL_RANGING = 2;  // modem 1 pings a REMUS network of long
                                       // baseline (LBL) beacons: $CCPDT
    MICROMODEM_NARROWBAND_LBL_RANGING =
        3;  // modem 1 pings up to four transponders: $CCPNT
    MICROMODEM_MINI_DATA =
        4;  // 13 bits (represented as a 1 frame, 2 byte data transmission where
            // data is AND'd with 0x1ff) mini data transmission
    MICROMODEM_FLEXIBLE_DATA =
        5;  // Flexible Data Protocol in Micro-Modem 2: Up to 100 bytes
    MICROMODEM_HARDWARE_CONTROL = 6;  // $CCMEC for writing hardware lines
    MICROMODEM_HARDWARE_CONTROL_REPLY =
        7;  // $CAMER response to writing hardware lines
    MICROMODEM_GENERIC_LBL_RANGING =
        8;  // $CCPGT Ping Generic Transponder from host to modem
    MICROMODEM_FM_SWEEP = 9;     // $CCSWP Send an FM sweep
    MICROMODEM_M_SEQUENCE = 10;  // $CCMSQ Send a maximal-length sequence
}
 
enum HardwareLine
{
    option allow_alias = true;
 
    MM2_GPIO1 = 5;
    MM2_GPIO2 = 6;
    MM2_GPIO3 = 3;
    MM2_GPIO4 = 2;
    MM2_GPIO5 = 4;
 
    MM1_EXTSEL1 = 1;
    MM1_EXTSEL2 = 2;
    MM1_GPIO = 3;
    MM1_COM1 = 7;
    MM1_COM2 = 8;
}
 
enum HardwareControlMode
{
    READ_LINE = 0;
    SET_VALUE = 1;
    TOGGLE_HIGH = 2;
    TOGGLE_LOW = 3;
}
 
enum HardwareControlArgument
{
    option allow_alias = true;
 
    MODE1_OFF = 0;
    MODE1_ON = 1;
 
    TOGGLE_1MS = 0;
    TOGGLE_HALF_SEC = 1;
    TOGGLE_1_SEC = 2;
    TOGGLE_2_SEC = 3;
    TOGGLE_6_SEC = 4;
    TOGGLE_10_SEC = 5;
    TOGGLE_20_SEC = 6;
    TOGGLE_30_SEC = 7;
 
    MODE0_ARG = 0;
}
 
message HardwareControl
{
    required HardwareLine line = 1;
    required HardwareControlMode mode = 2;
    optional HardwareControlArgument arg = 3 [default = MODE0_ARG];
}
 
message HardwareControlCommand
{
    option (dccl.msg).id = 515;
    option (dccl.msg).max_bytes = 32;
    option (dccl.msg).codec_version = 3;
 
    required int32 command_src = 1 [
        (dccl.field).min = 0,
        (dccl.field).max = 31,
        (dccl.field).in_head = true
    ];
    required int32 command_dest = 2 [
        (dccl.field).min = 0,
        (dccl.field).max = 31,
        (dccl.field).in_head = true
    ];
    optional uint64 time = 3
        [(dccl.field).in_head = true, (dccl.field).codec = "_time"];
 
    // destination of $CCMEC command (defaults to same as command_dest)
    optional int32 hw_ctl_dest = 4
        [(dccl.field).min = 0, (dccl.field).max = 31];
 
    optional HardwareControl control = 5;
}
 
message Transmission
{
    optional TransmissionType type = 1 [
        (goby.field).description =
            "Type of transmission if base `type` == DRIVER_SPECIFIC",
        default = BASE_TYPE
    ];
 
    // LBL parameters will be merged with configuration parameters. If a
    // parameter is set in both places, the ones set here take precedence.
    optional NarrowBandLBLParams narrowband_lbl = 2 [(dccl.field).omit = true];
    optional REMUSLBLParams remus_lbl = 3 [(dccl.field).omit = true];
 
    optional RangingReply ranging_reply = 4
        [(dccl.field).omit = true, (goby.field).cfg.action = NEVER];
    repeated ReceiveStatistics receive_stat = 5
        [(dccl.field).omit = true,
         (goby.field).cfg.action = NEVER];  // $CACST
    repeated TransmitStatistics transmit_stat = 6
        [(dccl.field).omit = true,
         (goby.field).cfg.action = NEVER];  // $CAXST
    repeated int32 frame_with_bad_crc = 7
        [(dccl.field).omit = true, (goby.field).cfg.action = NEVER];
 
    optional HardwareControl hw_ctl = 8 [(dccl.field).omit = true];
 
    optional GenericLBLParams generic_lbl = 9 [(dccl.field).omit = true];
    optional FMSweepParams fm_sweep = 10 [(dccl.field).omit = true];
    optional MSequenceParams m_sequence = 11 [(dccl.field).omit = true];
}
 
extend goby.acomms.protobuf.ModemTransmission
{
    optional Transmission transmission = 1000;
}
 
message MMApplicationAck
{
    option (dccl.msg).id = 10;
    option (dccl.msg).max_bytes = 32;
    option (dccl.msg).codec_version = 3;
 
    repeated AckPart part = 1 [(dccl.field).max_repeat = 4];
    message AckPart
    {
        required int32 ack_dest = 1
            [(dccl.field).min = 0, (dccl.field).max = 31];
 
        required uint32 acked_frames = 2
            [(dccl.field).min = 0, (dccl.field).max = 0xFFFFFFFF];
    }
 
    required bool ack_requested = 3;
    required uint32 frame_start = 4
        [(dccl.field).min = 0, (dccl.field).max = 31];
}