pig-farm-controller/internal/infra/transport/proto/device.proto

syntax = "proto3";

package device;

option go_package = "internal/domain/device/proto";

// --- 日志相关 ---

// LogLevel 定义了日志的严重级别。
enum LogLevel {
  LOG_LEVEL_UNSPECIFIED = 0; // 未指定
  DEBUG = 1;                 // 调试信息
  INFO = 2;                  // 普通信息
  WARN = 3;                  // 警告
  ERROR = 4;                 // 错误
}

// LogEntry 代表一条由设备生成的日志记录。
message LogEntry {
  int64 timestamp_unix = 1; // 日志生成的Unix时间戳 (秒)
  LogLevel level = 2;       // 日志级别
  string message = 3;       // 日志内容
}

// --- 核心指令与数据结构 ---

// 平台生成的原始485指令，单片机直接发送到总线
message Raw485Command {
  int32 bus_number = 1;    // 总线号，用于指示单片机将指令发送到哪个总线
  bytes command_bytes = 2; // 原始485指令的字节数组
}

// 一个完整的、包含所有元数据的批量采集任务。
message BatchCollectCommand {
  string correlation_id = 1;        // 用于关联请求和响应的唯一ID
  repeated CollectTask tasks = 2;   // 采集任务列表
}

// 定义了单个采集任务的“意图”。
message CollectTask {
  Raw485Command command = 1; // 平台生成的原始485指令
}

// 这是设备响应的、极致精简的数据包。
message CollectResult {
  string correlation_id = 1;   // 从下行指令中原样返回的关联ID
  repeated float values = 2;   // 按预定顺序排列的采集值
}

// OTA（空中下载）升级指令，包含完整的固件包。
message OtaUpgradeCommand {
  string firmware_version = 1;    // 目标固件版本, e.g., "v1.2.3"
  string firmware_hash = 2;       // 固件包的SHA-256哈希值，用于完整性校验
  bytes firmware_package = 3;     // 完整的固件二进制文件
}

// 设备端执行OTA升级后的状态报告 (上行)。
message OtaUpgradeStatus {
  // 状态码: 0=成功, 1=哈希校验失败, 2=烧录失败, 3=空间不足, 99=其他未知错误
  int32 status_code = 1;
  // 设备当前运行的固件版本 (升级后或升级失败时)
  string current_firmware_version = 2;
}

// 控制设备日志上传的指令 (下行)。
message ControlLogUploadCommand {
  bool enable = 1; // true = 开始上传, false = 停止上传
  uint32 duration_seconds = 2; // 指定上传持续时间（秒）。
}

// 设备用于向平台批量上传日志的请求 (上行)。
message LogUploadRequest {
  repeated LogEntry entries = 1; // 一批日志条目
}

// 平台向设备发送的Ping指令，用于检查存活性。
message Ping {
  // 可以留空，指令本身即代表意图
}

// 设备对Ping的响应，或设备主动上报的心跳。
// 它包含了设备的关键状态信息。
message Pong {
  string firmware_version = 1;       // 当前固件版本
  // 可以扩展更多状态, e.g., int32 uptime_seconds = 2;
}


// --- 顶层指令包装器 ---

// Instruction 封装了所有与设备间的通信。
// 使用 oneof 来确保每个消息只有一个负载类型，这在嵌入式系统中是高效且类型安全的。
message Instruction {
  oneof payload {
    // --- 下行指令 (平台 -> 设备) ---
    Raw485Command raw_485_command = 1;
    BatchCollectCommand batch_collect_command = 2;
    OtaUpgradeCommand ota_upgrade_command = 3;
    ControlLogUploadCommand control_log_upload_command = 4;
    Ping ping = 6;

    // --- 上行数据 (设备 -> 平台) ---
    CollectResult collect_result = 101;
    OtaUpgradeStatus ota_upgrade_status = 102;
    LogUploadRequest log_upload_request = 103;
    Pong pong = 104;
  }
}