ControlMessage.proto

/**
 * FILE: ControlMessage.proto
 * BRIEF: Control messages are used to control the flow of the system, they are used to ensure that all nodes are aware of the current state of the system
 * AUTHOR: Christopher Chan (cjchanx)
 */
syntax = "proto3";
package Proto;
import "CoreProto.proto";

/* Control Message ------------------------------------------------------------------*/

/* This acts as the core wrapper message for all SOAR Control and Command Messages, all messages
 * should be wrapped in this message. This message is used to identify the message type
 * and the source of the message.
 *
 *
 * Note that all Control Messages should be ACKed by the target node. If the target node does not ACK the message, the source node should resend the message.
 */
message ControlMessage {
    // Message Path
    Node source = 1; // This is the source of the message (the node that sent the message)
    Node target = 2; // This is the destination of the message, if this is a broadcast message, this should be set to NODE_ANY

    /* There are much more robust RDT implementations, but for simplicity, we will use a sequence number simply to verify
     * ACKs are for the correct respective message. Each SOURCE node maintains a counting UINT32_T that is incremented for EVERY
     * message send to ANY source (if we want to make this more robust, we can use a unique sequence number per message path but that
     * would require an N_NODES array of sequence numbers which is not necessary for our purposes).
     */
    uint32 source_sequence_num = 4; // This is the sequence number of the message, should start at (1), if its 0 it does not need to be ACKed (ie. Non-essential Telemetry)

    // Message Data
    oneof message {
        // Control Messages
        AckNack ack = 5;
        AckNack nack = 6;
        Ping ping = 7;
        Heartbeat hb = 8;
        SystemState sys_state = 9;
        SystemControl sys_ctrl = 10;
        HeartbeatState hb_state = 11;
        FastLog fast_log = 12;
    }
}

/* Control / Flow Messages ------------------------------------------------------------------*/

/* ACK and NACK should be used on all Control and Command messages, for important paths such as
   RCU -> DMB, DMB -> PBB the sending node needs to keep a timer and alert the RCU operator if the
   message is not ACKed within a certain time period. (In the case of DMB -> PBB attempting retransmits would be a good idea) */
message AckNack {
    Node acking_msg_source = 1; // The source of the message that is being acknowledged or nacked
    MessageID acking_msg_id = 2; // The message ID of the message that is being acknowledged or nacked
    uint32 acking_sequence_num = 3; // The sequence number of the message that is being acknowledged or nacked
}

/* Ping can be used to test continuity of a message path, the ping message should be sent to the target node
   and the target node should respond with an ACK message with the ping_ack_id set to the ping message ID */
message Ping {
    uint32 ping_ack_id = 1; // The expected response message ID in the ACK response to this message
    uint32 ping_response_sequence_num = 2; // The expected response sequence number in the ACK response to this message
    bool sys_state_response_required = 3;  // If true, the target node should respond with a SystemState message
}

/* Heartbeats are used to continuously ensure communication continuity, the heartbeat message should be sent to the target node
   and the target node should respond with an ACK message with the specified response sequence number 
   
   Heartbeat messages must be validated by the wrapping layer source and target nodes */
message Heartbeat {
    uint32 hb_response_sequence_num = 1; // The expected response sequence number in the ACK response to this message
}

/* System State Broadcasts are used to broadcast the current state of the system, this is used to ensure that all nodes
   are aware of the current state of the system.
   
   This is sent on things such as primary state machine changes, on system boot, or to signal a failure */
message SystemState {
    enum State {
        SYS_INVALID = 0;

        // These are used to signal bootup and reset events
        SYS_BOOTUP_COMPLETE = 1;        // System has booted up and is ready to accept commands - used to signal first boot
        SYS_ASSERT_FAILURE_RESET = 2;   // Assert failure triggered a reset
        SYS_UNCAUGHT_RESET = 3;         // Hardfault or other uncaught exception triggered a reset

        // These are used to signal current operation status
        SYS_NORMAL_OPERATION = 4;       // System is in normal operation

        // SoarProto v1.3.2
        SYS_HEARTBEAT_LOSS_HALF_WARNING = 5; // The system has lost heartbeat and 1/2 of the time to abort has passed
        SYS_HEARTBEAT_LOST_ABORTING = 6;     // The system has lost heartbeat and is aborting
    }

    State sys_state = 1; // The current state of the system
    optional RocketState rocket_state = 2; // If this is the DMB, this will respond with the current RocketSM State
}

/* System control commands may not necessarily be handled by the board */
message SystemControl {
    enum Command {
        SYS_INVALID = 0;

        // These are used to signal bootup and reset events
        SYS_RESET = 1;                  // Reset the system
        SYS_FLASH_ERASE = 2;            // Erase the flash memory (only erases logging data)
        SYS_LOG_PERIOD_CHANGE = 3;      // Change the log period, to the provided period in seconds as cmd_param 

        // SoarProto v1.3.2
        HEARTBEAT_ENABLE = 4;           // Enable heartbeat timeout-abort
        HEARTBEAT_DISABLE = 5;          // Disable heartbeat timeout-abort

        SYS_FLASH_LOG_ENABLE = 6;             // Enable logging
        SYS_FLASH_LOG_DISABLE = 7;            // Disable logging

        SYS_CRITICAL_FLASH_FULL_ERASE = 8;    // Erase the entire flash memory (including state and log data)
    }

    Command sys_cmd = 1;  // The current state of the system
    uint32 cmd_param = 2; // The parameter for the command, if applicable
}

/* Heartbeat Telemetry ------------------------------------------------------------------*/
message HeartbeatState {
    enum TimerState {
        UNINITIALIZED = 0;
        COUNTING = 1;
        PAUSED = 2;
        COMPLETE = 3;
    }
 
    TimerState timer_state = 1; // The current state of the timer
    uint32 timer_period = 2; // The original period of the timer in milliseconds
    uint32 timer_remaining = 3; // The remaining time on the timer in milliseconds
}

/* FastLog Command ---------------------------------------------------------------------*/
message FastLog {
    enum FastLogCommand {
        FL_PEND = 0;  // Should be sent on IGNITION
        FL_START = 1; // Should be sent on LAUNCH (record T-1 s of data prior to this point), records 10 s of data
        FL_SEND = 2;  // Should be sent on COAST, will send the data at 100 Hz for (100s required) at 5 minute intervals
        FL_RESET = 3; // Reset the Fast Log state machine
    }

    FastLogCommand cmd = 1; // The command to send to the Fast Log state machine
}