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.
[ ] 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
[ ] 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
[ ] 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)
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:
140
141
147
TODO:
Examples:
Helpers:
TODO:
MAC layer:
TODO:
[^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:
TODO:
Other:
Additions:
TODO: