packet_router.proto

syntax = "proto3";

package helium.packet_router;

import "region.proto";
import "data_rate.proto";

message packet_router_packet_report_v1 {
  enum packet_type {
    join = 0;
    uplink = 1;
  }

  uint64 gateway_tmst = 1;
  uint64 oui = 2;
  uint32 net_id = 3;
  // signal strength in dBm
  sint32 rssi = 4;
  // Frequency in hz
  uint32 frequency = 5;
  float snr = 6;
  data_rate datarate = 7;
  region region = 8;
  bytes gateway = 9;
  // Hash of `payload` within `message packet`
  bytes payload_hash = 10;
  uint32 payload_size = 11;
  bool free = 12;
  packet_type type = 13;
  // Timestamp in ms since unix epoch
  uint64 received_timestamp = 14;
}

message packet_router_packet_up_v1 {
  bytes payload = 1;
  uint64 timestamp = 2;
  // signal strength in dBm
  sint32 rssi = 3;
  // Frequency in hz
  uint32 frequency = 4;
  data_rate datarate = 5;
  float snr = 6;
  region region = 7;
  uint64 hold_time = 8;
  bytes gateway = 9;
  bytes signature = 10;
}

message packet_router_register_v1 {
  uint64 timestamp = 1;
  bytes gateway = 2;
  bytes signature = 3;
  bool session_capable = 4;
  uint32 packet_ack_interval = 5;
}

// Session offer from the packet router to the gateway. If the gateway wants to
// initiate a session key it should send a packet_router_session_init_v1 message
// to the packet router using data in this offer to propose a session key.
//
// This message is sent by packet router after the register command is sent by
// the gateway.
message packet_router_session_offer_v1 { bytes nonce = 1; }

// Initializes a session key with the packet router. The data in this init
// message has to be from the latest session offer the gateway has received, the
// session key is the public key that is to be used to verify packets by packet
// router, and this message is to be signed by the private key of the gateway.
// Once accepted the session key replaces the current (default is gateway) key
// as the verifier used by the packet router for upilnk packets.
//
// The session key is valid for the length of the current stream or until a next
// offer message is received from the packet router.
//
// Once the new verifier is set by the packet router, any signed packets that do
// not pass verification with the active verifier key are dropped.
message packet_router_session_init_v1 {
  bytes gateway = 1;
  bytes nonce = 2;
  bytes session_key = 3;
  bytes signature = 4;
}

message envelope_up_v1 {
  oneof data {
    packet_router_register_v1 register = 1;
    packet_router_packet_up_v1 packet = 2;
    packet_router_session_init_v1 session_init = 3;
  }
}

message window_v1 {
  uint64 timestamp = 1;
  // Frequency in hz
  uint32 frequency = 2;
  data_rate datarate = 3;
  bool immediate = 4;
}

message packet_router_packet_down_v1 {
  bytes payload = 1;
  window_v1 rx1 = 2;
  window_v1 rx2 = 3;
}

message packet_router_packet_ack_v1 { bytes payload_hash = 1; }

message envelope_down_v1 {
  oneof data {
    packet_router_packet_down_v1 packet = 1;
    packet_router_session_offer_v1 session_offer = 2;
    packet_router_packet_ack_v1 packet_ack = 3;
  }
}

service packet {
  rpc route(stream envelope_up_v1) returns (stream envelope_down_v1);
}