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

• [x] #137
  • #140
• [x] #157, #158
• [x] #173

Other global changes

• [x] Update README.md (f5f28c0, d2cc3e5, bc834b9, c14d1ad, fec9ec1, b32b8cf, b866c0b, 44c01e7)
• [x] #138
• [x] Redo GitHub workflows
  • #141
  • #147
  • Clarify CI workflow names (560d081)
• [x] #142
• [x] #144
• [x] #145
• [x] #146
• [x] #156
• [x] Bring documentation back online (#160)
• [x] #174
• [x] #175
• [x] #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

• [x] NetworkServerHelper: (#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 (#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[^1]
• [ ] 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

[^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.

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
• [ ] 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.