lorawan: Ongoing changes to the module

[non-det-alle]

lorawan: Ongoing changes to the module

The lorawan module is going through a series of changes.

The present issue is raised to document and list future changes and changes done so far.
The list is meant to break up a previous huge PR (#135) into more digestible pieces.

Feel free to open a discussion below on any of the proposed changes.

Table of contents

• Fixes and Changes
  • Code maintenance
  • Examples
  • Helpers
  • MAC layer
  • PHY layer
  • Other
• Additions

Fixes and Changes

Code maintenance

Timely support of new ns-3 releases

• Update supported ns-3 version to 3.40 #137
  • Fix null check in PeriodicSender #140
• Update supported ns-3 version to ns-3.41 #157, Fix errors in the CI pipeline introduced by ns-3.41 #158
• Update CI pipeline and bump supported ns-3 version to ns-3.43 #173

Other global changes

• Update README.md (f5f28c0, d2cc3e5, bc834b9, c14d1ad, fec9ec1, b32b8cf, b866c0b, 44c01e7)
• Format all files to current ns-3 .clang-format rules #138
• Redo GitHub workflows
  • Reproduce ns-3 per-commit CI pipelines (push, MR) #141
  • Additional changes and fixes to the GitHub CI #147
  • Clarify CI workflow names (560d081)
• Remove emacs lines from all files #142
• Fix doxygen errors in the module #144
• Add examples-to-run.py to module's tests #145
• Apply .clang-tidy linting rules to all files #146
• Complete the doxygen documentation #156
• Bring documentation back online (Broken documentation #160)
• Keep minimal dependencies in CMakeLists.txt #174
• Loop file names in examples' CMakeLists.txt #175
• Prefer explicit DynamicCast in place of GetObject for downcasting #176
• Implement of DoInitialize and DoDispose where needed
• Update & expand documentation doc/lorawan.rst
• Organize model files into [app, mac, phy] directory structure

TODO:

• Expand test coverage

Examples

• lorawan-energy-model-example.cc: add more logging
• Move utility functions of examples to external file (utilities.cc)

Helpers

• NetworkServerHelper: (Expose p2p connection of gateways and server (#150) #151)
• LoraHelper: refactor to LorawanHelper (in the future we could introduce a LoraHelper to only deploy PHY layer)
• LoraHelper: add system to control tracing granularity as [PKT, DEV, SF, GW, NET]
• Use static call form of LorawanMacHelper::SetSpreadingFactorsUp()
• LorawanMacHelper/AdrComponent: exact implementation of default ADR algorithm
• LoraPhyHelper: remove enum in favor of typeId for factory config
• LoraPhyHelper: add InterferenceHelper factory as in WhyPhyHelper
• LoraPhyHelper: remove unused txPriority setting
• LoraPhyHelper: move num reception path setting into GatewayLoraPhy

TODO:

• Improve tracing system (improve where trace sources are connected, how packet tracker is instantiated)

MAC layer

• Order members and improve scoping in LorawanMac, MacCommand, GatewayLorawanMac, EndDeviceLorawanMac, ClassAEndDeviceLorawanMac
• Clean up and rework MAC layer to make it more accessible and to remove duplication
• LorawanMacHeader: refactor MType to FType to match specs (TS001-1.0.4)
• EndDeviceLorawanMac: refactor to BaseEndDeviceLorawanMac
• EndDeviceLorawanMac: exact implementation of the ADR backoff algorithm in devices (ED-side Adaptive Data Rate (ADR) update and ADR Backoff #171)
• EndDeviceLorawanMac: remove redundant (& unused) LogicalLoraChannel management functions
• Refactor frameHdr (and macHdr) to fHdr (and mHdr) to match specs (TS001-1.0.4)
• EndDeviceLorawanMac: refactor DRAdapt to ADRBackoff to match specs (TS001-1.0.4)
• EndDeviceLorawanMac: refactor maxNumbTx to NbTrans to match specs (TS001-1.0.4)
• EndDeviceLorawanMac: refactor DRControl to ADRBit to match specs (TS001-1.0.4)
• EndDeviceLorawanMac: remake LoraRetxParameters to LorawanMacTxContext to track the MAC layer transmission (Tx) context (current packet, acks, re-Txs, busy state) and to clean up the code¹
• RecvWindowManager class to isolate the class A reception window scheduling process
• LorawanMac: add receive callback for upper layer (application) forwarding
• LorawanMac: fix max payload constraint naming from App to Mac
• LorawanMac: keep track of PHY parameters to use for transmission
• LoraDeviceAddress: fix NwkAddr constructor input param name in header
• SubBand: downgrade from object to SimpleRefCount
• LogicalLoraChannel: refactor to LogicalChannel
• LogicalLoraChannel: downgrade to SimpleRefCount
• LogicalLoraChannel: add ReplyFrequency + getter/setter
• LogicalLoraChannelHelper: refactor to LogicalChannelManager
• LogicalLoraChannelHelper: use map and indices to store/access channels (in line with how they are managed in TS001-1.0.4)

TODO:

• Specialize LoraFrameHeader to stop having to call fHdr.SetAsUplink() (for instance, UplinkLoraFrameHeader and DownlinkLoraFrameHeader)
• MAC layer: better distribution of functionality among parent/childs for devices and gateways (e.g., isn't already Class A the base lorawan device (see, TS001-1.0.4)? Do we need a parent class specific to generic lorawan devices?) Maybe BaseEndDevice could directly be ClassAEndDevice

PHY layer

• Order members and improve scoping in LoraPhy, GatewayLoraPhy, EndDeviceLoraPhy
• LoraPhy::LoraTxParameters: refactor to LoraPhyTxParameters
• LoraChannel: separate uplink and downlink receivers (more realistic + optimized performance in unconfirmed scenarios)
• LoraInterferenceHelper: refactor CollisionMatrix enum to IsolationMatrix
• LoraInterferenceHelper: refactor SNIR to SIR (we are not considering noise here)
• LoraInterferenceHelper: define sirMatrix_t type for isolation matrix
• LoraInterferenceHelper: set isolation matrix using attribute system
• LoraInterferenceHelper: lambda implementation of CleanOldEvents
• LoraInterferenceHelper: set CROCE matrix to default one
• LoraPhy: set default SF to 12 according to specs (TS001-1.0.4)
• LoraPhy: num preamble symbols uint16_t according to SX1272 datasheet
• LoraPhy: use TimeOnAir instead of OnAirTime as in specs
• LoraPhy: use Time class for TimeOnAir computation
• Remove SimpleEndDeviceLoraPhy (and SimpleGatewayLoraPhy) and merge functionality with non-Simple class
• GatewayLoraPhy: remove unused frequency vector and functions coming from obsolete model of ReceptionPath
• GatewayLoraPhy: set ReceptionPath number with attribute system
• GatewayLoraPhy::ReceptionPath: remove unused SetEvent member function
• GatewayLoraPhy: metadata insertion in tag & fix tracing callbacks positions
• EndDeviceLoraPhy: modernize iterators to range-based loops
• EndDeviceLoraPhy: assume that the MAC layer must switch the state to standby before sending (SX1272 & SX1276-7-8-9 datasheets)
• EndDeviceLoraPhy: metadata insertion in tag & fix tracing callbacks positions
• EndDeviceLoraPhy: implement TxFinished for automatic state switching (SX1272 & SX1276-7-8-9 datasheets)
• EndDeviceLoraPhy: remove bloat IsOnFrequency function
• EndDeviceLoraPhy: LoraPhy should be in RX mode instead of STANDBY during reception windows #181
• MacCommand: downgrade from object to SimpleRefCount
• MacCommand: implement TypeId
• MacCommand: implement LinkCheckReq destructor
• MacCommand: complete NewChannelReq::Print & RxTimingSetupReq::Print implementation
• LinkAdrReq: 0 repetitions returns 1 to match specs (TS001-1.0.4)
• RxParamSetupReq/NewChannelReq: fix endianess of freq. in Deserialize

TODO:

• LoraChannel: add option to ignore uplink and downlink quasi-orthogonality (fully interfering)
• LoraInterferenceHelper: better interference model for CROCE matrix (isolation values are obtain for an average number of overlapping symbols over 1-20 != GOURSAUD where refer to full overlap)

Other

• Convert all frequencies to Hz instead of MHz
• Directly connect application and MAC, skipping LoraNetDevice (more realistic)
• Remove lora-utils for now because practically unused (values are always in dB or dBm)
• LoraTag: expand class to carry a copy of all PHY layer metadata (tx/rx params & stats) of a packet
• HexGridPositionAllocator: remake as generator
• AdrComponent: static ADR impl. to be called from LorawanMacHelper (remove code duplication)

Additions

• RangePositionAllocator: allocate posistions uniformly in range of a provided set of nodes
• Support for rx/tx pcap tracing (see LoraTap, LorawanHelper, LoraPhy, EndDeviceLoraPhy and GatewayLoraPhy)
• PoissonSender app and relative helper
• App helper to instantiate use cases from [IEEE C802.16p-11/0102r2]
• LoraPacketTracker: limit memory usage with periodic old-packet cleanup
• LoraPacketTracker: function to print stats at the end of simulation
• PeriodicSenderHelper: possibility to use random variable to extract the periodicity for each device
• LoraApplication with getters/setters of avg time interval and pkt size (parent class of Periodic/Poisson/OneShot Senders)
• LoraFrameHeader: manage possibility of MAC commands piggybacked in the FPRPayload
• EndDeviceLoraPhy: early packet filtering based on preamble start (SX1272 datasheet)
• MacCommand: implement and manage RxTimingSetupAns, TxParamSetupAns, DlChannelReq MAC primitives
• EndDeviceLorawanMac: add support for cryptographic libraries for MIC generation and DL payload decryption

TODO:

• Allow any type of connection between the NS and GWs
• EndDeviceStatus: store pkts in circular buffer to limit memory usage
• LorawanMacHelper: create separate file (per region) to load regional parameters
• AnimationInterface: add support for LoRa wireless packet tracing with a PR to the main ns-3 repo.

Footnotes

1. The busy state prevents the MAC layer from sending a new packet in-between a previous Tx and its reception windows. Effectively, the 'context' structure acts as a size-1 buffer in case the APP layer requests a new Tx while the Tx context is already busy (Tx + recv windows), or if we need to wait due to duty-cycle limitations or to re-transmit a same packet. The context is overwritable: a NEW Tx requested by the APP layer will take the place of re-transmissions scheduled for a previous packet (if any) or a packet Tx postponed by the duty-cycle (basically, only the packet will change because the MAC layer will still need to wait). This maintains the behaviour implemented before, but re-implements it in a tidier way. PS_1: another option would be to discard any new Tx requests by the APP layer if the MAC layer is not done with the current context. PS_2: technically, the APP layer should have the responsability to check with the MAC layer how much time remains to wait for a new Tx, and thus manage an eventual frame buffering (and maybe, in case of duty-cycle limitations, also having the option of sending anyway, increasing time-to-wait of future Txs). In addition, we probably shouldn't overwrite scheduled re-Txs, but just tell the APP layer that the MAC is still busy until the re-Tx process is complete. Unfortunately, this complicates implementing applications because there is no standard behaviour for this defined in the specs. ↩