Skip to content

lorawan: Ongoing changes to the module #139

New issue
New issue
Open
Open
lorawan: Ongoing changes to the module#139
Assignees
pagmattnon-det-alle
Labels
enhancement
@non-det-alle

Description

@non-det-alle
non-det-alle
opened on Oct 19, 2023

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

Other global changes

TODO:

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

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

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

  • Refactor all frequencies from MHz (double) to Hz (uint32_t) #179
  • 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. ↩

Metadata

Metadata

Assignees

Labels

enhancement

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions