[feature-wisun] Improve WisunInterface set_network_size docs #14431

artokin · 2021-03-15T14:23:11Z

Summary of changes

Clarify set_network_size usage and possible parameter values.

Impact of changes

Migration actions required

Documentation

Pull request type

[x] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[] Feature update (New feature / Functionality change / New API)
[] Major update (Breaking change E.g. Return code change / API behaviour change)

Test results

[x] No Tests required for this change (E.g docs only update)
[] Covered by existing mbed-os tests (Greentea or Unittest)
[] Tests / results supplied as part of this PR

Reviewers

ciarmcom · 2021-03-15T14:30:20Z

@artokin, thank you for your changes.
@ARMmbed/mbed-os-maintainers please review.

mbed-ci · 2021-03-16T12:47:31Z

Test run: SUCCESS

Summary: 10 of 10 test jobs passed
Build number : 1
Build artifacts

mikter · 2021-03-16T12:54:23Z

features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h

+     *
+     * The network size is measured as hundreds of devices. For example:
+     * - set network size to 1 to use Wi-SUN network with less than 100 devices (small).
+     * - set network size to 8 to use Wi-SUN network with 100-800 devices (medium).


We need to remove the limits on devices as the amount of devices is dependent on the data rate so
medium settings is used from 500, 1000, 1500 to 2500 devices depending the data rate

So it would be better to just say that there is 4 buckets of settings which are selected based on data rate and device amount

This field ONLY gives the device amount
so
1 = 100
2=200
5=500
20=2000

Pull request has been modified.

artokin · 2021-03-17T09:55:59Z

Rebased and updated documentation based on the review comments. Would you please review again?

0xc0170 · 2021-03-17T11:47:08Z

CI started

mikter · 2021-03-17T12:54:03Z

features/nanostack/mbed-mesh-api/mbed_lib.json

@@ -121,7 +121,7 @@
            "value": "\"Wi-SUN Network\""
        },
        "wisun-network-size": {
-            "help": "Expected amount of devices in the network as 100s of devices. with possible pre defined constants NETWORK_SIZE_SMALL, NETWORK_SIZE_MEDIUM, NETWORK_SIZE_LARGE, NETWORK_SIZE_XLARGE. if set to 0 Wi-SUN Certification configuration values are used. If don't define this(default null), then NETWORK_SIZE_MEDIUM will be used.",
+            "help": "Expected amount of devices in the network as hundreds of devices. Use any number or one of the predefined values NETWORK_SIZE_SMALL, NETWORK_SIZE_MEDIUM, NETWORK_SIZE_LARGE or NETWORK_SIZE_XLARGE. Set to 0 to use Wi-SUN Certification configuration values. If set to null, then NETWORK_SIZE_MEDIUM (meaning up to 800 devices in 150kbs data rate) will be used.",


meaning up to 800 devices in 150kbs data rate -> Meaning hundreds of devices in the network

80 is going to be changed but it always is hundreds

mbed-ci · 2021-03-17T12:57:58Z

Test run: SUCCESS

Summary: 10 of 10 test jobs passed
Build number : 2
Build artifacts

Clarify set_network_size usage and possible parameter values. Clarify wisun-network-size help text in mbed-mesh-api/mbed_lib.json

Pull request has been modified.

juhhei01 · 2021-03-19T06:37:18Z

features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h

     * - Timing settings set by set_timing_parameters() of the Wi-SUN interface.
     * - RPL settings set by rpl_parameters_set() of the Border Router interface.
     *
-     * When network size is changed, and if timing or RPL values should be other than defaults set by stack for the network size,
-     * they need to set again using above function calls.
+     * When the network size is changed, and if timing or RPL values should be other than defaults set by stack for the


This is only change Border router RPL configs.

There will be "configuration buckets based on the selected network size and data rate" for the four options, but is there also suitable configuration buckets for other values like"4"? or application need to handle other configurations by itself?
If no configuration buckets for other size, there are two API list here, set_timing_parameters/rpl_parameters_set, is it meant once change network to "4", only there two parameters need to change? how?

Only configuration Application needs to set is the network size and the stack will select the correct configuration that it will use based on the network size and data rate

All values from 1 to 254 will result in some selection made by stack so any value can be given even 4 meaning expected amount of devices in network is 400 devices.

tz-arm · 2021-03-22T07:49:30Z

features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h

+     * - 1 to use small configuration bucket.
+     * - 8 to use medium configuration bucket.
+     * - 15 to use large configuration bucket.
+     * - 25 to use xlarge configuration bucket.


If we prefer customer to use the "number of hundreds devices" as network size, I would propose to remove all concept, micros and comments about " small, medium, large, xlarge", the duplicate concept/usage will cause confusion。

tz-arm · 2021-03-22T07:56:29Z

features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h

     *
-     * When network size is changed, it will override all or some of the following configuration values:
+     * When the network size is changed, it will override all or some of the following configuration values:


Propose to use ” the network size setting will refresh and generate new configurations bucket based on bandwidth the input network size value.
If the customized timing or RPL values is needed, the below two API should be invoked after network size setting.

Updated based on review comments.

tz-arm · 2021-03-23T10:01:28Z

features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h

-     * When network size is changed, it will override all or some of the following configuration values:
-     * - Timing settings set by set_timing_parameters() of the Wi-SUN interface.
-     * - RPL settings set by rpl_parameters_set() of the Border Router interface.
+     * By default the Wi-SUN stack is configured to use a few hundreds of devices.


That's seems simple and clear, thanks for the update!
Just one question, if the "by default ... a few hundreds" should be "4 means 4 hundreds" as default?

adbridge · 2021-03-25T15:35:06Z

Ci started

mbed-ci · 2021-03-25T19:29:46Z

Test run: SUCCESS

Summary: 10 of 10 test jobs passed
Build number : 3
Build artifacts

artokin requested a review from mikter March 15, 2021 14:23

mergify bot added the release-version: feature branch label Mar 15, 2021

ciarmcom requested a review from a team March 15, 2021 14:30

ciarmcom added the needs: review label Mar 15, 2021

0xc0170 previously approved these changes Mar 15, 2021

View reviewed changes

mergify bot added needs: CI and removed needs: review labels Mar 15, 2021

artokin requested review from TuomoHautamaki, juhhei01, JarkkoPaso and mikaleppanen March 16, 2021 08:52

mergify bot added ready for merge and removed needs: CI labels Mar 16, 2021

mikter reviewed Mar 16, 2021

View reviewed changes

0xc0170 added needs: review and removed ready for merge labels Mar 16, 2021

artokin force-pushed the update_set_network_size_documentation branch from c5fee38 to 4b96ef6 Compare March 17, 2021 09:54

artokin requested a review from mikter March 17, 2021 11:25

mikter reviewed Mar 17, 2021

View reviewed changes

artokin force-pushed the update_set_network_size_documentation branch 2 times, most recently from 0326880 to 0cce166 Compare March 17, 2021 13:19

mikter previously approved these changes Mar 17, 2021

View reviewed changes

mergify bot added needs: CI and removed needs: review labels Mar 17, 2021

Improve WisunInterface set_network_size docs

77b9eb5

Clarify set_network_size usage and possible parameter values. Clarify wisun-network-size help text in mbed-mesh-api/mbed_lib.json

artokin force-pushed the update_set_network_size_documentation branch from 0cce166 to 77b9eb5 Compare March 18, 2021 09:45

artokin requested a review from tz-arm March 18, 2021 09:46

This was referenced Mar 18, 2021

Improve WisunInterface set_network_size docs #14442

Merged

[mbed-os-5.15] Improve WisunInterface set_network_size docs #14443

Merged

artokin changed the title ~~Improve WisunInterface set_network_size docs~~ [feature-wisun] Improve WisunInterface set_network_size docs Mar 18, 2021

juhhei01 reviewed Mar 19, 2021

View reviewed changes

tz-arm reviewed Mar 22, 2021

View reviewed changes

Review corrections

c84e30a

Updated based on review comments.

artokin requested a review from tz-arm March 23, 2021 09:46

tz-arm reviewed Mar 23, 2021

View reviewed changes

tz-arm approved these changes Mar 23, 2021

View reviewed changes

mikter approved these changes Mar 23, 2021

View reviewed changes

mergify bot added ready for merge and removed needs: CI labels Mar 25, 2021

adbridge merged commit beebd93 into ARMmbed:feature-wisun Mar 26, 2021

mergify bot removed the ready for merge label Mar 26, 2021

artokin deleted the update_set_network_size_documentation branch March 26, 2021 15:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[feature-wisun] Improve WisunInterface set_network_size docs #14431

[feature-wisun] Improve WisunInterface set_network_size docs #14431

artokin commented Mar 15, 2021

ciarmcom commented Mar 15, 2021

mbed-ci commented Mar 16, 2021

mikter Mar 16, 2021

artokin commented Mar 17, 2021

0xc0170 commented Mar 17, 2021

mikter Mar 17, 2021

mbed-ci commented Mar 17, 2021

juhhei01 Mar 19, 2021

tz-arm Mar 22, 2021 •

edited

mikter Mar 22, 2021

tz-arm Mar 22, 2021

tz-arm Mar 22, 2021

tz-arm Mar 23, 2021

adbridge commented Mar 25, 2021

mbed-ci commented Mar 25, 2021

[feature-wisun] Improve WisunInterface set_network_size docs #14431

[feature-wisun] Improve WisunInterface set_network_size docs #14431

Conversation

artokin commented Mar 15, 2021

Summary of changes

Impact of changes

Migration actions required

Documentation

Pull request type

Test results

Reviewers

ciarmcom commented Mar 15, 2021

mbed-ci commented Mar 16, 2021

Choose a reason for hiding this comment

artokin commented Mar 17, 2021

0xc0170 commented Mar 17, 2021

Choose a reason for hiding this comment

mbed-ci commented Mar 17, 2021

Choose a reason for hiding this comment

tz-arm Mar 22, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adbridge commented Mar 25, 2021

mbed-ci commented Mar 25, 2021

tz-arm Mar 22, 2021 •

edited