diff --git a/CHANGES.md b/CHANGES.md index 4166f99be..aeecb0b50 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -31,6 +31,7 @@ Changes from ns-3.37 to ns-3.38 * (internet-apps) Classes `v4Ping` and `Ping6` will be deprecated and removed in the future, replaced by the new `Ping` class. * (lr-wpan) Add file `src/lr-wpan/model/lr-wpan-constants.h` with common constants of the LR-WPAN module. * (lr-wpan) Remove the functions `LrWpanCsmaCa::GetUnitBackoffPeriod()` and `LrWpanCsmaCa::SetUnitBackoffPeriod()`, and move the constant `m_aUnitBackoffPeriod` to `src/lr-wpan/model/lr-wpan-constants.h`. +* (lr-wpan) Adds beacon payload handle support (MLME-SET.request) in **LrWpanMac**. ### Changes to build system diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index aadc6eefc..ab93dbd1f 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -24,6 +24,7 @@ Release 3-dev - (internet) !1229 - You can now ping broadcast addresses. - (core) !1236 - Added some macros to silence compiler warnings. The new macros are in **warnings.h**, and their use is not suggested unless for very specific cases. - (internet-apps) - A new Ping model that works for both IPv4 and IPv6 has been added, to replace the address family specific v4Ping and Ping6. +- (lr-wpan) !1268 - Adding beacon payload now its possible using MLME-SET.request primitive. ### Bugs fixed diff --git a/src/lr-wpan/examples/lr-wpan-mlme.cc b/src/lr-wpan/examples/lr-wpan-mlme.cc index ac2397c3d..92909349e 100644 --- a/src/lr-wpan/examples/lr-wpan-mlme.cc +++ b/src/lr-wpan/examples/lr-wpan-mlme.cc @@ -46,21 +46,20 @@ using namespace ns3; -static void -BeaconIndication(MlmeBeaconNotifyIndicationParams params, Ptr p) +void +BeaconIndication(MlmeBeaconNotifyIndicationParams params) { - NS_LOG_UNCOND(Simulator::Now().GetSeconds() - << " secs | Received BEACON packet of size " << p->GetSize()); + NS_LOG_UNCOND(Simulator::Now().GetSeconds() << " secs | Received BEACON packet of size "); } -static void +void DataIndication(McpsDataIndicationParams params, Ptr p) { NS_LOG_UNCOND(Simulator::Now().GetSeconds() << " secs | Received DATA packet of size " << p->GetSize()); } -static void +void TransEndIndication(McpsDataConfirmParams params) { // In the case of transmissions with the Ack flag activated, the transaction is only @@ -71,14 +70,14 @@ TransEndIndication(McpsDataConfirmParams params) } } -static void +void DataIndicationCoordinator(McpsDataIndicationParams params, Ptr p) { NS_LOG_UNCOND(Simulator::Now().GetSeconds() << "s Coordinator Received DATA packet (size " << p->GetSize() << " bytes)"); } -static void +void StartConfirm(MlmeStartConfirmParams params) { if (params.m_status == MLMESTART_SUCCESS) @@ -156,7 +155,7 @@ main(int argc, char* argv[]) //////////// Manual device association //////////////////// // Note: We manually associate the devices to a PAN coordinator - // because currently there is no automatic association behavior (bootstrap); + // (i.e. bootstrap is not used); // The PAN COORDINATOR does not need to associate or set its // PAN Id or its own coordinator id, these are set // by the MLME-start.request primitive when used. diff --git a/src/lr-wpan/model/lr-wpan-constants.h b/src/lr-wpan/model/lr-wpan-constants.h index 1c6cefa0a..4241df33a 100644 --- a/src/lr-wpan/model/lr-wpan-constants.h +++ b/src/lr-wpan/model/lr-wpan-constants.h @@ -44,6 +44,27 @@ namespace lrwpan * @{ */ +/////////////////// +// PHY constants // +/////////////////// + +/** + * The maximum packet size accepted by the PHY. + * See Table 22 in section 6.4.1 of IEEE 802.15.4-2006 + */ +constexpr uint32_t aMaxPhyPacketSize{127}; + +/** + * The turnaround time in symbol periods for switching the transceiver from RX to TX or + * vice-versa. + * See Table 22 in section 6.4.1 of IEEE 802.15.4-2006 + */ +constexpr uint32_t aTurnaroundTime{12}; + +/////////////////// +// MAC constants // +/////////////////// + /** * The minimum number of octets added by the MAC sublayer to the PSDU. * See IEEE 802.15.4-2011, section 6.4.1, Table 51. @@ -83,24 +104,23 @@ constexpr uint32_t aMaxLostBeacons{4}; */ constexpr uint32_t aMaxSIFSFrameSize{18}; -/** - * The maximum packet size accepted by the PHY. - * See Table 22 in section 6.4.1 of IEEE 802.15.4-2006 - */ -constexpr uint32_t aMaxPhyPacketSize{127}; - -/** - * The turnaround time in symbol periods for switching the transceiver from RX to TX or - * vice-versa. - * See Table 22 in section 6.4.1 of IEEE 802.15.4-2006 - */ -constexpr uint32_t aTurnaroundTime{12}; - /** * Number of symbols per CSMA/CA time unit, default 20 symbols. */ constexpr uint32_t aUnitBackoffPeriod{20}; +/** + * The maximum number of octets added by the MAC sublayer to the MAC payload o a a beacon frame. + * See IEEE 802.15.4-2011, section 6.4.1, Table 51. + */ +constexpr uint32_t aMaxBeaconOverhead{75}; + +/** + * The maximum size, in octets, of a beacon payload. + * See IEEE 802.15.4-2011, section 6.4.1, Table 51. + */ +constexpr uint32_t aMaxBeaconPayloadLenght{aMaxPhyPacketSize - aMaxBeaconOverhead}; + /** @} */ } // namespace lrwpan diff --git a/src/lr-wpan/model/lr-wpan-mac.cc b/src/lr-wpan/model/lr-wpan-mac.cc index b7067a46d..42ed71dad 100644 --- a/src/lr-wpan/model/lr-wpan-mac.cc +++ b/src/lr-wpan/model/lr-wpan-mac.cc @@ -214,6 +214,8 @@ LrWpanMac::LrWpanMac() uniformVar->SetAttribute("Max", DoubleValue(255.0)); m_macDsn = SequenceNumber8(uniformVar->GetValue()); m_macBsn = SequenceNumber8(uniformVar->GetValue()); + m_macBeaconPayload = nullptr; + m_macBeaconPayloadLength = 0; m_shortAddress = Mac16Address("00:00"); } @@ -267,7 +269,7 @@ LrWpanMac::DoDispose() m_mcpsDataIndicationCallback = MakeNullCallback>(); m_mlmeStartConfirmCallback = MakeNullCallback(); m_mlmeBeaconNotifyIndicationCallback = - MakeNullCallback>(); + MakeNullCallback(); m_mlmeSyncLossIndicationCallback = MakeNullCallback(); m_mlmePollConfirmCallback = MakeNullCallback(); m_mlmeScanConfirmCallback = MakeNullCallback(); @@ -824,6 +826,40 @@ LrWpanMac::MlmePollRequest(MlmePollRequestParams params) NS_FATAL_ERROR(this << " Poll request currently not supported"); } +void +LrWpanMac::MlmeSetRequest(LrWpanMacPibAttributeIdentifier id, Ptr attribute) +{ + MlmeSetConfirmParams confirmParams; + switch (id) + { + case macBeaconPayload: + if (attribute->macBeaconPayload->GetSize() > lrwpan::aMaxBeaconPayloadLenght) + { + confirmParams.m_status = MLMESET_INVALID_PARAMETER; + } + else + { + confirmParams.m_status = MLMESET_SUCCESS; + m_macBeaconPayload = attribute->macBeaconPayload; + m_macBeaconPayloadLength = attribute->macBeaconPayload->GetSize(); + } + break; + case macBeaconPayloadLength: + confirmParams.m_status = MLMESET_INVALID_PARAMETER; + break; + default: + // TODO: Add support for setting other attributes + confirmParams.m_status = MLMESET_UNSUPPORTED_ATTRIBUTE; + break; + } + + if (!m_mlmeSetConfirmCallback.IsNull()) + { + confirmParams.id = id; + m_mlmeSetConfirmCallback(confirmParams); + } +} + void LrWpanMac::SendOneBeacon() { @@ -833,9 +869,18 @@ LrWpanMac::SendOneBeacon() LrWpanMacHeader macHdr(LrWpanMacHeader::LRWPAN_MAC_BEACON, m_macBsn.GetValue()); m_macBsn++; BeaconPayloadHeader macPayload; - Ptr beaconPacket = Create(); + Ptr beaconPacket; LrWpanMacTrailer macTrailer; + if (m_macBeaconPayload == nullptr) + { + beaconPacket = Create(); + } + else + { + beaconPacket = m_macBeaconPayload; + } + macHdr.SetDstAddrMode(LrWpanMacHeader::SHORTADDR); macHdr.SetDstAddrFields(GetPanId(), Mac16Address("ff:ff")); @@ -1593,6 +1638,12 @@ LrWpanMac::SetMlmePollConfirmCallback(MlmePollConfirmCallback c) m_mlmePollConfirmCallback = c; } +void +LrWpanMac::SetMlmeSetConfirmCallback(MlmeSetConfirmCallback c) +{ + m_mlmeSetConfirmCallback = c; +} + void LrWpanMac::PdDataIndication(uint32_t psduLength, Ptr p, uint8_t lqi) { @@ -1985,7 +2036,7 @@ LrWpanMac::PdDataIndication(uint32_t psduLength, Ptr p, uint8_t lqi) beaconParams.m_panDescriptor = panDescriptor; beaconParams.m_sduLength = p->GetSize(); beaconParams.m_sdu = p; - m_mlmeBeaconNotifyIndicationCallback(beaconParams, originalPkt); + m_mlmeBeaconNotifyIndicationCallback(beaconParams); } } @@ -2071,7 +2122,9 @@ LrWpanMac::PdDataIndication(uint32_t psduLength, Ptr p, uint8_t lqi) MlmeBeaconNotifyIndicationParams beaconParams; beaconParams.m_bsn = receivedMacHdr.GetSeqNum(); beaconParams.m_panDescriptor = panDescriptor; - m_mlmeBeaconNotifyIndicationCallback(beaconParams, originalPkt); + beaconParams.m_sduLength = p->GetSize(); + beaconParams.m_sdu = p; + m_mlmeBeaconNotifyIndicationCallback(beaconParams); } } } diff --git a/src/lr-wpan/model/lr-wpan-mac.h b/src/lr-wpan/model/lr-wpan-mac.h index 298057dd7..c780d9bda 100644 --- a/src/lr-wpan/model/lr-wpan-mac.h +++ b/src/lr-wpan/model/lr-wpan-mac.h @@ -309,6 +309,45 @@ typedef enum MLMEPOLL_INVALID_PARAMETER = 9 } LrWpanMlmePollConfirmStatus; +/** + * \ingroup lr-wpan + * + * Table 33 of IEEE 802.15.4-2011 + */ +enum LrWpanMlmeSetConfirmStatus +{ + MLMESET_SUCCESS = 0, + MLMESET_READ_ONLY = 1, + MLMESET_UNSUPPORTED_ATTRIBUTE = 2, + MLMESET_INVALID_INDEX = 3, + MLMESET_INVALID_PARAMETER = 4 +}; + +/** + * \ingroup lr-wpan + * + * IEEE802.15.4-2011 MAC PIB Attribute Identifiers Table 52 in section 6.4.2 + * + */ +enum LrWpanMacPibAttributeIdentifier +{ + macBeaconPayload = 0, + macBeaconPayloadLength = 1 + // TODO: complete other MAC pib attributes +}; + +/** + * \ingroup lr-wpan + * + * IEEE802.15.4-2011 PHY PIB Attributes Table 52 in section 6.4.2 + */ +struct LrWpanMacPibAttributes : public SimpleRefCount +{ + Ptr macBeaconPayload; //!< The contents of the beacon payload. + uint8_t macBeaconPayloadLength{0}; //!< The length in octets of the beacon payload. + // TODO: complete other MAC pib attributes +}; + /** * \ingroup lr-wpan * @@ -318,8 +357,8 @@ struct PanDescriptor { LrWpanAddressMode m_coorAddrMode{SHORT_ADDR}; //!< The coordinator addressing mode corresponding //!< to the received beacon frame. - uint16_t m_coorPanId{ - 0xffff}; //!< The PAN ID of the coordinator as specified in the received beacon frame. + uint16_t m_coorPanId{0xffff}; //!< The PAN ID of the coordinator as specified in + //!< the received beacon frame. Mac16Address m_coorShortAddr; //!< The coordinator short address as specified in the coordinator //!< address mode. Mac64Address m_coorExtAddr; //!< The coordinator extended address as specified in the @@ -328,10 +367,10 @@ struct PanDescriptor uint8_t m_logChPage{0}; //!< The current channel page occupied by the network. SuperframeField m_superframeSpec; //!< The superframe specification as specified in the received //!< beacon frame. - bool m_gtsPermit{ - false}; //!< TRUE if the beacon is from the PAN coordinator that is accepting GTS requests. - uint8_t m_linkQuality{ - 0}; //!< The LQI at which the network beacon was received. Lower values represent lower LQI. + bool m_gtsPermit{false}; //!< TRUE if the beacon is from the PAN coordinator + //!< that is accepting GTS requests. + uint8_t m_linkQuality{0}; //!< The LQI at which the network beacon was received. + //!< Lower values represent lower LQI. Time m_timeStamp; //!< Beacon frame reception time. Used as Time data type in ns-3 to avoid //!< precision problems. }; @@ -600,6 +639,19 @@ struct MlmePollConfirmParams //!< MLME-poll.request. }; +/** + * \ingroup lr-wpan + * + * MLME-SET.confirm params. See 802.15.4-2011 Section 6.2.11.2 + */ +struct MlmeSetConfirmParams +{ + LrWpanMlmeSetConfirmStatus m_status{ + MLMESET_UNSUPPORTED_ATTRIBUTE}; //!< The result of the request to write + //!< the PIB attribute. + LrWpanMacPibAttributeIdentifier id; //!< The id of the PIB attribute that was written. +}; + /** * \ingroup lr-wpan * @@ -638,8 +690,7 @@ typedef Callback MlmeStartConfirmCallback; * \todo for now, we do not deliver all of the parameters in section * 802.15.4-2006 6.2.4.1 but just send up the packet. */ -typedef Callback> - MlmeBeaconNotifyIndicationCallback; +typedef Callback MlmeBeaconNotifyIndicationCallback; /** * \ingroup lr-wpan @@ -700,6 +751,15 @@ typedef Callback MlmeAssociateIndicationCal */ typedef Callback MlmeCommStatusIndicationCallback; +/** + * \ingroup lr-wpan + * + * This callback is called after a MlmeSetRequest has been called from + * the higher layer to set a PIB. It returns a status of the outcome of the + * write attempt. + */ +typedef Callback MlmeSetConfirmCallback; + /** * \ingroup lr-wpan * @@ -860,6 +920,16 @@ class LrWpanMac : public Object */ void MlmePollRequest(MlmePollRequestParams params); + /** + * IEEE 802.15.4-2011, section 6.2.11.1 + * MLME-SET.request + * Attempts to write the given value to the indicated PIB attribute. + * + * \param id the attributed identifier + * \param attribute the attribute value + */ + void MlmeSetRequest(LrWpanMacPibAttributeIdentifier id, Ptr attribute); + /** * Set the CSMA/CA implementation to be used by the MAC. * @@ -971,6 +1041,15 @@ class LrWpanMac : public Object */ void SetMlmePollConfirmCallback(MlmePollConfirmCallback c); + /** + * Set the callback for the confirmation of an attempt to write an attribute. + * The callback implements MLME-SET.confirm SAP of IEEE 802.15.4-2011, + * section 6.2.11.2 + * + * \param c the callback + */ + void SetMlmeSetConfirmCallback(MlmeSetConfirmCallback c); + // interfaces between MAC and PHY /** @@ -1214,6 +1293,19 @@ class LrWpanMac : public Object */ SequenceNumber8 m_macBsn; + /** + * The contents of the beacon payload. + * This value is set directly by the MLME-SET primitive. + * See IEEE 802.15.4-2011, section 6.4.2, Table 52. + */ + Ptr m_macBeaconPayload; + + /** + * The length, in octets, of the beacon payload. + * See IEEE 802.15.4-2011, section 6.4.2, Table 52. + */ + uint32_t m_macBeaconPayloadLength; + /** * The maximum number of retries allowed after a transmission failure. * See IEEE 802.15.4-2006, section 7.4.2, Table 86. @@ -1803,6 +1895,13 @@ class LrWpanMac : public Object */ Ptr m_csmaCa; + /** + * This callback is used to report the result of an attribute writing request + * to the upper layers. + * See IEEE 802.15.4-2011, section 6.2.11.2. + */ + MlmeSetConfirmCallback m_mlmeSetConfirmCallback; + /** * This callback is used to notify incoming beacon packets to the upper layers. * See IEEE 802.15.4-2011, section 6.2.4.1. diff --git a/src/lr-wpan/test/lr-wpan-mac-test.cc b/src/lr-wpan/test/lr-wpan-mac-test.cc index 880223bde..48d5766ff 100644 --- a/src/lr-wpan/test/lr-wpan-mac-test.cc +++ b/src/lr-wpan/test/lr-wpan-mac-test.cc @@ -308,11 +308,19 @@ class TestActiveScanPanDescriptors : public TestCase * \param params MLME scan confirm parameters */ void ScanConfirm(MlmeScanConfirmParams params); + /** + * Function used to notify the reception of a beacon with payload. + * + * \param params The MLME-BEACON-NOTIFY.indication parameters + */ + void BeaconNotifyIndication(MlmeBeaconNotifyIndicationParams params); void DoRun() override; - std::vector - m_panDescriptorList; //!< The list of PAN descriptors accumulated during the scan + std::vector m_panDescriptorList; //!< The list of PAN descriptors + //!< accumulated during the scan. + uint32_t g_beaconPayloadSize; //!< The size of the beacon payload received + //!< from a coordinator. }; TestActiveScanPanDescriptors::TestActiveScanPanDescriptors() @@ -333,13 +341,19 @@ TestActiveScanPanDescriptors::ScanConfirm(MlmeScanConfirmParams params) } } +void +TestActiveScanPanDescriptors::BeaconNotifyIndication(MlmeBeaconNotifyIndicationParams params) +{ + g_beaconPayloadSize = params.m_sdu->GetSize(); +} + void TestActiveScanPanDescriptors::DoRun() { /* - * [00:01] [00:02] [00:03] - * PAN Coordinator 1 (PAN: 5) End Device PAN Coordinator 2 (PAN: - * 7) + * [00:01] [00:02] [00:03] + * PAN Coordinator 1 (PAN: 5) End Device PAN Coordinator 2 (PAN: 7) + * * |--------100 m----------------|----------106 m -----------------------| * Channel 12 (Active Scan channels 11-14) Channel 14 * @@ -408,6 +422,10 @@ TestActiveScanPanDescriptors::DoRun() cb0 = MakeCallback(&TestActiveScanPanDescriptors::ScanConfirm, this); endNodeNetDevice->GetMac()->SetMlmeScanConfirmCallback(cb0); + MlmeBeaconNotifyIndicationCallback cb1; + cb1 = MakeCallback(&TestActiveScanPanDescriptors::BeaconNotifyIndication, this); + endNodeNetDevice->GetMac()->SetMlmeBeaconNotifyIndicationCallback(cb1); + ///////////////// // ACTIVE SCAN // ///////////////// @@ -427,7 +445,13 @@ TestActiveScanPanDescriptors::DoRun() params); // PAN coordinator N2 (PAN 7) is set to channel 14 in non-beacon mode but answer to beacon - // requests. + // requests. The second coordinator includes a beacon payload of 25 bytes using the + // MLME-SET.request primitive. + Ptr pibAttribute = Create(); + pibAttribute->macBeaconPayload = Create(25); + coord2NetDevice->GetMac()->MlmeSetRequest(LrWpanMacPibAttributeIdentifier::macBeaconPayload, + pibAttribute); + MlmeStartRequestParams params2; params2.m_panCoor = true; params2.m_PanId = 7; @@ -482,6 +506,10 @@ TestActiveScanPanDescriptors::DoRun() m_panDescriptorList[0].m_linkQuality, "Error, Coordinator 2 (PAN 7) LQI value should be less than Coordinator 1 (PAN 5)."); + NS_TEST_EXPECT_MSG_EQ(g_beaconPayloadSize, + 25, + "Error, Beacon Payload not received or incorrect size (25 bytes)"); + Simulator::Destroy(); }