Add CodingRate's stream insertion and extraction operators + tidy up LoraPhy::GetOnAirTime func (#212)

* CodingRate: add operator<< and operator>>

This makes logging easier and allows passing in a CodingRate from
command line.

* Convert enum CodingRate to enum class

* LoraPhy::GetOnAirTime(): explicit casts to double

---------

Co-authored-by: Alessandro Aimi <[email protected]>

Author: maribu

examples/aloha-throughput.cc

@@ -242,7 +242,7 @@ main(int argc, char* argv[])
         LoraTxParameters txParams;
         txParams.sf = sf;
         txParams.headerDisabled = false;
-        txParams.codingRate = CODING_RATE_4_5;
+        txParams.codingRate = CodingRate::CR_4_5;
         txParams.bandwidthHz = 125000;
         txParams.nPreamble = 8;
         txParams.crcEnabled = true;

model/end-device-lorawan-mac.cc

@@ -96,7 +96,7 @@ EndDeviceLorawanMac::EndDeviceLorawanMac()
     : m_nbTrans(1),
       m_dataRate(0),
       m_txPowerDbm(14),
-      m_codingRate(CODING_RATE_4_5),
+      m_codingRate(CodingRate::CR_4_5),
       // LoraWAN default
       m_headerDisabled(false),
       // LoraWAN default

model/end-device-lorawan-mac.h

@@ -24,7 +24,7 @@ namespace ns3
 namespace lorawan
 {
 
-enum CodingRate : uint8_t;
+enum class CodingRate : uint8_t;
 
 /**
  * @ingroup lorawan

model/gateway-lorawan-mac.cc

@@ -69,7 +69,7 @@ GatewayLorawanMac::Send(Ptr<Packet> packet)
     LoraTxParameters params;
     params.sf = GetSfFromDataRate(dataRate);
     params.headerDisabled = false;
-    params.codingRate = CODING_RATE_4_5;
+    params.codingRate = CodingRate::CR_4_5;
     params.bandwidthHz = GetBandwidthFromDataRate(dataRate);
     params.nPreamble = 8;
     params.crcEnabled = true;

model/lora-phy.cc

@@ -164,24 +164,28 @@ LoraPhy::GetOnAirTime(Ptr<Packet> packet, LoraTxParameters txParams)
     double tSym = GetTSym(txParams).GetSeconds();
 
     // Compute the preamble duration
-    double tPreamble = (double(txParams.nPreamble) + 4.25) * tSym;
+    auto nPreamble = static_cast<double>(txParams.nPreamble);
+    double tPreamble = (nPreamble + 4.25) * tSym;
 
     // Payload size
-    uint32_t pl = packet->GetSize(); // Size in bytes
-    NS_LOG_DEBUG("Packet of size " << pl << " bytes");
+    uint32_t payloadLen = packet->GetSize(); // Size in bytes
+    NS_LOG_DEBUG("Packet of size " << payloadLen << " bytes");
 
-    // This step is needed since the formula deals with double values.
+    // Safety casts since the formula deals with double values.
+    auto pl = static_cast<double>(payloadLen);
+    auto sf = static_cast<double>(txParams.sf);
+    auto cr = static_cast<double>(txParams.codingRate);
     // de = 1 when the low data rate optimization is enabled, 0 otherwise
     // h = 1 when header is implicit, 0 otherwise
-    double de = txParams.lowDataRateOptimizationEnabled ? 1 : 0;
-    double h = txParams.headerDisabled ? 1 : 0;
-    double crc = txParams.crcEnabled ? 1 : 0;
+    // crc = 1 when cyclic redundancy check is present, 0 otherwise
+    double de = txParams.lowDataRateOptimizationEnabled ? 1.0 : 0.0;
+    double h = txParams.headerDisabled ? 1.0 : 0.0;
+    double crc = txParams.crcEnabled ? 1.0 : 0.0;
 
     // num and den refer to numerator and denominator of the time on air formula
-    double num = 8.0 * pl - 4 * txParams.sf + 28 + 16 * crc - 20 * h;
-    double den = 4 * (txParams.sf - 2 * de);
-    double payloadSymbNb =
-        8 + std::max(std::ceil(num / den) * (txParams.codingRate + 4), double(0));
+    double num = 8.0 * pl - 4.0 * sf + 28.0 + 16.0 * crc - 20.0 * h;
+    double den = 4.0 * (sf - 2.0 * de);
+    double payloadSymbNb = 8.0 + std::max(std::ceil(num / den) * (cr + 4.0), 0.0);
 
     // Time to transmit the payload
     double tPayload = payloadSymbNb * tSym;
@@ -196,11 +200,59 @@ LoraPhy::GetOnAirTime(Ptr<Packet> packet, LoraTxParameters txParams)
     return Seconds(tPreamble + tPayload);
 }
 
+std::ostream&
+operator<<(std::ostream& os, const CodingRate& codingRate)
+{
+    switch (codingRate)
+    {
+    case CodingRate::CR_4_5:
+        return os << "4/5";
+    case CodingRate::CR_4_6:
+        return os << "4/6";
+    case CodingRate::CR_4_7:
+        return os << "4/7";
+    case CodingRate::CR_4_8:
+        return os << "4/8";
+    default:
+        NS_FATAL_ERROR("Unknown coding rate value");
+        return (os << "UNKNOWN");
+    }
+}
+
+std::istream&
+operator>>(std::istream& is, CodingRate& codingRate)
+{
+    std::string value;
+    is >> value;
+    if (value == "4/5")
+    {
+        codingRate = CodingRate::CR_4_5;
+    }
+    else if (value == "4/6")
+    {
+        codingRate = CodingRate::CR_4_6;
+    }
+    else if (value == "4/7")
+    {
+        codingRate = CodingRate::CR_4_7;
+    }
+    else if (value == "4/8")
+    {
+        codingRate = CodingRate::CR_4_8;
+    }
+    else
+    {
+        is.setstate(std::ios_base::failbit);
+    }
+    NS_ABORT_MSG_IF(is.bad(), "Failure to parse " << value);
+    return is;
+}
+
 std::ostream&
 operator<<(std::ostream& os, const LoraTxParameters& params)
 {
     os << "SF: " << unsigned(params.sf) << ", headerDisabled: " << params.headerDisabled
-       << ", codingRate: " << unsigned(params.codingRate) << ", bandwidthHz: " << params.bandwidthHz
+       << ", codingRate: " << params.codingRate << ", bandwidthHz: " << params.bandwidthHz
        << ", nPreamble: " << params.nPreamble << ", crcEnabled: " << params.crcEnabled
        << ", lowDataRateOptimizationEnabled: " << params.lowDataRateOptimizationEnabled << ")";
 

model/lora-phy.h

@@ -26,14 +26,24 @@ class LoraChannel;
  *
  * Enumeration of the LoRa supported coding rates
  */
-enum CodingRate : uint8_t
+enum class CodingRate : uint8_t
 {
-    CODING_RATE_4_5 = 1, //!< Coding rate 4/5
-    CODING_RATE_4_6 = 2, //!< Coding rate 4/6
-    CODING_RATE_4_7 = 3, //!< Coding rate 4/7
-    CODING_RATE_4_8 = 4, //!< Coding rate 4/8
+    CR_4_5 = 1, //!< Coding rate 4/5
+    CR_4_6,     //!< Coding rate 4/6
+    CR_4_7,     //!< Coding rate 4/7
+    CR_4_8,     //!< Coding rate 4/8
 };
 
+/**
+ * Allow logging of CodingRate like any other data type.
+ */
+std::ostream& operator<<(std::ostream& os, const CodingRate& codingRate);
+
+/**
+ * Allow parsing of CodingRate from CommandLine.
+ */
+std::istream& operator>>(std::istream& is, CodingRate& codingRate);
+
 /**
  * @ingroup lorawan
  *
@@ -42,12 +52,12 @@ enum CodingRate : uint8_t
  */
 struct LoraTxParameters
 {
-    uint8_t sf = 7;                          //!< Spreading Factor
-    bool headerDisabled = false;             //!< Whether to use implicit header mode
-    CodingRate codingRate = CODING_RATE_4_5; //!< Code rate (obtained as 4/(codingRate+4))
-    uint32_t bandwidthHz = 125000;           //!< Bandwidth in Hz
-    uint32_t nPreamble = 8;                  //!< Number of preamble symbols
-    bool crcEnabled = true;                  //!< Whether Cyclic Redundancy Check (CRC) is enabled
+    uint8_t sf = 7;                             //!< Spreading Factor
+    bool headerDisabled = false;                //!< Whether to use implicit header mode
+    CodingRate codingRate = CodingRate::CR_4_5; //!< Code rate (obtained as 4/(codingRate+4))
+    uint32_t bandwidthHz = 125000;              //!< Bandwidth in Hz
+    uint32_t nPreamble = 8;                     //!< Number of preamble symbols
+    bool crcEnabled = true; //!< Whether Cyclic Redundancy Check (CRC) is enabled
     bool lowDataRateOptimizationEnabled = false; //!< Whether low data rate optimization is enabled
 };
 

test/lorawan-test-suite.cc

@@ -1014,7 +1014,7 @@ TimeOnAirTest::DoRun()
     LoraTxParameters txParams;
     txParams.sf = 7;
     txParams.headerDisabled = false;
-    txParams.codingRate = CODING_RATE_4_5;
+    txParams.codingRate = CodingRate::CR_4_5;
     txParams.bandwidthHz = 125000;
     txParams.nPreamble = 8;
     txParams.crcEnabled = true;
@@ -1031,7 +1031,7 @@ TimeOnAirTest::DoRun()
     duration = LoraPhy::GetOnAirTime(packet, txParams);
     NS_TEST_EXPECT_MSG_EQ_TOL(duration.GetSeconds(), 0.072192, 0.0001, "Unexpected duration");
 
-    txParams.codingRate = CODING_RATE_4_6;
+    txParams.codingRate = CodingRate::CR_4_6;
     duration = LoraPhy::GetOnAirTime(packet, txParams);
     NS_TEST_EXPECT_MSG_EQ_TOL(duration.GetSeconds(), 0.078336, 0.0001, "Unexpected duration");
 
@@ -1075,7 +1075,7 @@ TimeOnAirTest::DoRun()
     duration = LoraPhy::GetOnAirTime(packet, txParams);
     NS_TEST_EXPECT_MSG_EQ_TOL(duration.GetSeconds(), 2.629632, 0.0001, "Unexpected duration");
 
-    txParams.codingRate = CODING_RATE_4_5;
+    txParams.codingRate = CodingRate::CR_4_5;
     duration = LoraPhy::GetOnAirTime(packet, txParams);
     NS_TEST_EXPECT_MSG_EQ_TOL(duration.GetSeconds(), 2.301952, 0.0001, "Unexpected duration");
 }