LoRaWAN: ClockSynch/Multicast/Fragmentation Plugins & session handling #9707
Conversation
hasnainvirk
changed the title
|
@hasnainvirk, thank you for your changes. |
hasnainvirk
force-pushed
the
session_impl
branch
from
573e8e4
to
8c3997a
Compare
|
@hasnainvirk Please replace all instances of |
Usually RX2 frequency is fixed as per regional parameter specifications but there can be exceptions. Network servers are allowed to change RX2 frequency using Mac commands or out of the band mechanisms. We have introduces APIs in this commit which will enable the application to modify or restore RX2 window frequency.
Trivial helper functions perform operations on bit fields and masks.
The stack will now maintain a register with a maximum of 4 multicast session entries. The maximum number of session contexts is dictated by the LoRaWAN remote multicast setup specifcation v1.0.0. 'register_multicast_address()' API is used to set an entry into the multicast register, 'get_multicast_addr_register()' API is used to acquire a handle to the multicast register itself and 'verify_multicast_freq_and_dr()' API is used to verify frequency and data rate parameters if requested by the network in a special case (i.e., a switch to class C at a given time with a given frequency and SF). When a multicast downlink is received, the stack looks-up the multicast register for the address match. If a match is found, other session specific parameters in the register entry, i.e., frmae ocunters and security keys are loaded to be used for the stack for successful reception and decryption. The application is notified about the reception as it would normally be notified (i.e., RX_DONE event). If the downlink doesn't match any of the multicast addresses or the unicast address, the packet is dropped and an adrress failure is notified to the application.
This plug-in or application extension implements LoRaWAN Application Layer Clock Synchronization Specification v1.0.0. It is supposed to exist in-tree as an on-demand plugin. Applications can use the plug-in to synchronize their clocks with network if the protocol version is v1.0.2 or lower. For v1.0.3 and higher, use of DevTimeReq mac command is recommended. The plugin is completely detached from the core stack or application logic. It just provides easy to use interface to handle Clock sync commands. The application is reponsible for actual transmission of uplinks at the clock sync port and evoking the plugin upon reception of a clock sync command.
This is an implementation of LoRaWAN Remote Multicast Setup Specification v1.0.0. It is supposed to be used as an on-demand plug-in/application extension. Basic operation of the control package includes parsing of multicast control commands (traffic on port 200), their interpretation and generation of appropriate responses. Before passing in any control commands, the application must activate the package by feeding it the root key which will be used to derive multicast key encryption key (McKEKey). This McKEKey is then ued to derive network and application session keys when the multicast address is conveyed to the device using MCAST_GROUP_SETUP request. The root key in case of LoRaWAN 1.0.X is a special out-of-band pre-provisioned key. For v1.1.X AppKey is used as root key for this plugin too. The application is responsible for the transmission of responses at port 200 which are generated by the plug-in.
This is an implementation of LoRaWAN Fragmentation Control Block Transport Specification v1.0.0. It can be used in a variety of ways, e.g., receiving a large payload chopped into smaller fragments. A specific example where this plug-in can be used is the firmware update. The plug-in involves three components: FragmentationControlPackage - Helps the application in parsing, interpreting, and responding to control commands. FragAssembler - Keeps track of fragments received, fragments lost and performs FEC harnessing redundancy packets. FragBDWrapper - A wrapper class for a block device
hasnainvirk
force-pushed
the
session_impl
branch
from
8c3997a
to
cc2d5c8
Compare
|
@AnttiKauppila Please review again. |
Left over style issues for LoRaWAN plugins and sessions are resolved in this commit.
Very simple byte access helper functions 'write_four_bytes' and read_four_bytes()' are moved to their own source file rather than placing them in lorawan_data_structures.h.
API Docs are added for 'update_multicast_addr_register(...)' and 'check_multicast_params(...)' which was missing from previous commits.
LoRaWANTimer class is responsible for providing time base for the LoRaWAN stack in Mbed OS. It derives its core monotonic clock from the EventQueue which is essentially a millisecond ticker or equivalent (in tickless mode). LoRaWAN network can assist the device for device level time synchronization using ClockSynchronization protocol (for v1.0.2) or by replying to DevTimeReq MAC command (for v1.0.3 and above). The time base used for device synchronization using above methods is purely based on GPS epoch and needs no conversion to UTC or TAI etc (no adjustment for leap seconds either). Therefore we have extended the LoRaWANTimer APIs to account for GPS time base if assisted by the network. get_gps_time() is the API to use to acquire GPS time base from the stack. If the network never assisted the device with a time stamp, a value of zero is returned which means GPS time base is not available. set_gps_time(time) API is used to set a given GPS time-stamp when the network sends it. These APIs are hooked via LoRaMAC to LoRaWANInterface which exposes the access to the application.
Provides hooks for the internal APIs handling GPS time base for device synchronization. In addition to that 'set_system_time_utc(...)' API is added which have no roots in the stack. Its just a helper for the application developer to acquire UTC time base given the difference between TAI and UTC time bases.
Conversion to UTC time base and utilization is not necessitated by the LoRa Alliance and the Network servers are expected to use GPS time base without leap second conversion at least for device synchronization. Hence we modify the code to account for only GPS time base.
Using macros to implement logic is discouraged. Changing COUNT_SET_BITS to a helper function count_set_bits(...).
We don't need to convert for UTC from GPS time, hence we don't need configurations for time base differences.
hasnainvirk
force-pushed
the
session_impl
branch
from
d596439
to
80e2ddc
Compare
An API was introduced to change RX2 frequency on demand. However, the config should be coupled with a fixed on-demand data rate as well. We have modified the API to account for data rate too.
0xc0170
changed the title
Isn't this closer to Functionality change ? Adding new classes = functionality ? This definitely needs release notes section addition here.
If this is not captured in our LICENSE file, please add it there. |
| @@ -0,0 +1,91 @@ | |||
| /* | |||
| * PackageLicenseDeclared: Apache-2.0 | |||
There was a problem hiding this comment.
Not SPDX-License-Identifier instead as in other files, I Can see just two here using this identifier instead
There was a problem hiding this comment.
@0xc0170 FragAssembler is based on third party code. But yeah, you are right, FragBDWrapper should have SPDX-License-Identifier. Will fix that.
For testing: Unit tests will be added to the PR once #9219 gets merged. After #9219, we will do a doc update to this PR plus unit tests.
For protocol implementation testing, we wrote an Application Server that talks to Public TTN LoRaWAN network . It can be found here https://github.com/hasnainvirk/lorawan-ttn-as-test.
At the moment there is no real life implementation for these protocols (plug-ins). We are the first. That's why we had to come up with this testing solution. The AS is written in golang, so I am not sure how we can integrate it in CI. However, we would definitely like to see some tests around this.
New classes have no dependency on the stack and vice versa. They are plug-ins/application extensions that ease out the implementation details for the developers and cover the FUOTA angle. The new APIs which are being added here doesn't change the core stack behaviour, they compliment the existing implementation. However, I understand your view point, we will need more than release notes here. We will need elaborate documentation which is a future item for me. I will add text for release notes here, and come up with docs later. I am waiting for #9219 to go in though.
It is manifested in the license text. |
|
@hasnainvirk Yes, I'd like to have the tests in https://github.com/ARMmbed/mbed-lorawan-update-client/tree/master/TESTS migrated here. |
Need a little time for this. Working on SX126X drivers. |
|
This PR is at risk of missing 5.12 release as it's marked as "needs: work". Code freeze is coming! On Friday 1st. Please make necessary updates ASAP and make sure the reviewers are aligned for prompt code inspection. |
@bulislaw I am afraid we are going to miss 5.12 train on this one. The reason is that the unittest and interop tests cannot be posted in the given time frame. I gather that the unittest and interop tests are required by the reviewers which perfectly makes sense. |
0xc0170
added
release-version: 5.13.0-rc1
and removed
release-version: 5.12.0-rc1
labels
|
Moved to 5.13 for now |
|
@hasnainvirk ok, understood |
|
@hasnainvirk Are there any available updates on this PR? |
|
@hasnainvirk As there has been no updates on this PR for a considerable period of time, I am closing this. Please re-open when there are further updates. |
|
@hasnainvirk Is this needed? |
|
@AnttiKauppila Here is the latest version https://github.com/hasnainvirk/mbed-os/commits/session_impl. It essentially provides 4 enhancements: i) Proper Multicast handling in the stack |
|
I was looking for a fragmentation library(with FEC) in mbed for sx1276 lora. Is this going to be merged soon? Or is there any other library which will help me with fragmentation and FEC? |
|
@amol1000 This contains a fragmentation library with FEC: https://github.com/ARMmbed/mbed-lorawan-update-client. Not supported by anyone, but the fragmentation code works fine. |
|
Is it sill plan for mbed OS to support FUOTA for LoRaWAN ? |
Description
This PR provides implementation for three different protocol specs:
i) LoRaWAN Application Layer Clock Synchronization Specification v1.0.0
ii) LoRaWAN Remote Multicast Setup Specification v1.0.0
iii) LoRaWAN Fragmented Data Block Transport Specification v1.0.0
The implementations of these protocols are provided as plug-ins/add-ins/application-extensions and can be used by the application on-demand. The plug-ins can be used independently as well as in association to perform various tasks, e.g., device synchronization, multicast sessions, transport of larger data in fragments, firmware updates etc.
In addition to that a bunch of new APIs are added which serve multiple purposes. They fill-in the holes in our current offering plus they facilitate the plug-ins.
One of the classes introduced here, FragAssembler is directly derived from a 3rd party source and is used for FEC. The original license is maintained, and augmented with Arm BSD-Clause3 license. Only style and some minor performance tweaks are added to the original source.
Pull request type
Reviewers
@AnttiKauppila @janjongboom