From 77b9eb5dbaf8ac4900242a3ea328edc155624c58 Mon Sep 17 00:00:00 2001 From: Arto Kinnunen Date: Mon, 15 Mar 2021 16:14:58 +0200 Subject: [PATCH 1/2] Improve WisunInterface set_network_size docs Clarify set_network_size usage and possible parameter values. Clarify wisun-network-size help text in mbed-mesh-api/mbed_lib.json --- .../mbed-mesh-api/WisunInterface.h | 40 +++++++++++++------ .../nanostack/mbed-mesh-api/mbed_lib.json | 4 +- 2 files changed, 30 insertions(+), 14 deletions(-) diff --git a/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h b/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h index 0a4a43b5dc..5beebbde53 100644 --- a/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h +++ b/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h @@ -185,24 +185,40 @@ public: /** * \brief Set Wi-SUN network size. * - * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time. - * If device is already connected to the Wi-SUN network then device will restart network discovery after - * changing the network size. + * Function stores network size parameter to the mbed-mesh-api and uses it when connect() is called for the next + * time. If a device is already connected to the Wi-SUN network, then the device will restart network discovery + * after changing the network size. * - * Default value: medium - * Small network size: less than hundred devices - * Medium network size: hundreds of devices - * Large network size: thousands of devices - * Certificate: used on testing + * It is recommended to set the correct network size because the Wi-SUN network configuration parameters are + * adjusted based on the selected network size. A network configured for a small amount of devices may not work + * optimally for large number of devices. This is because the network bandwidth is divided with all the devices in + * the network. Enough bandwidth must be reserved for application data usage as well as the Wi-SUN network + * operations. Application should adapt to the network characteristics by using the InternetSocket methods + * get_stagger_estimate_to_address and get_rtt_estimate_to_address. * - * When network size is changed, it will override all or some of the following configuration values: + * The network size is measured as hundreds of devices that are expected to join to the network. For example, + * for a 400-device network set network size to 4. The Wi-SUN stack will internally use one of the four possible + * configuration buckets based on the selected network size and data rate. The configuration buckets are defined + * for a small, medium, large and xlarge networks. + * + * For example, with 150kbs data rate set network size to: + * - 1 to use small configuration bucket. + * - 8 to use medium configuration bucket. + * - 15 to use large configuration bucket. + * - 25 to use xlarge configuration bucket. + * + * By default Wi-SUN stack is configured to use medium sized network. + * + * The network size should be set to 0 when running certification tests. + * + * When the 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. * - * 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 + * network size, they need to set again using above function calls. * - * \param network_size Network size in hundreds of devices (e.g. 1200 devices is 12), 0x00 for network size certificate. + * \param network_size Network size in hundreds of devices (e.g. 12 for 1200 devices), 0 for certificate testing. * \return MESH_ERROR_NONE on success. * \return MESH_ERROR_UNKNOWN in case of failure. * */ diff --git a/features/nanostack/mbed-mesh-api/mbed_lib.json b/features/nanostack/mbed-mesh-api/mbed_lib.json index 9a074ecbd4..4278e60141 100644 --- a/features/nanostack/mbed-mesh-api/mbed_lib.json +++ b/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 hundreds of devices in the network) will be used.", "value": null }, "wisun-regulatory-domain": { @@ -187,7 +187,7 @@ "root-certificate-len": { "help": "Root certificate length; optional for PEM format, must be defined for DER format", "value": null - }, + }, "own-certificate": { "help": "Own certificate; in PEM format must be a null terminated c-string, in DER format the own-certificate-len must be set", "value": null From c84e30af255c99f0bacf09428dd22c4f5619b28f Mon Sep 17 00:00:00 2001 From: Arto Kinnunen Date: Tue, 23 Mar 2021 11:44:47 +0200 Subject: [PATCH 2/2] Review corrections Updated based on review comments. --- .../mbed-mesh-api/WisunInterface.h | 29 +++++++------------ 1 file changed, 10 insertions(+), 19 deletions(-) diff --git a/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h b/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h index 5beebbde53..763659f031 100644 --- a/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h +++ b/features/nanostack/mbed-mesh-api/mbed-mesh-api/WisunInterface.h @@ -189,35 +189,26 @@ public: * time. If a device is already connected to the Wi-SUN network, then the device will restart network discovery * after changing the network size. * - * It is recommended to set the correct network size because the Wi-SUN network configuration parameters are + * It is recommended to set the correct network size because some Wi-SUN network configuration parameters are * adjusted based on the selected network size. A network configured for a small amount of devices may not work * optimally for large number of devices. This is because the network bandwidth is divided with all the devices in * the network. Enough bandwidth must be reserved for application data usage as well as the Wi-SUN network - * operations. Application should adapt to the network characteristics by using the InternetSocket methods - * get_stagger_estimate_to_address and get_rtt_estimate_to_address. + * operations. In addition, the application should adapt to the network characteristics by using the InternetSocket + * methods get_stagger_estimate_to_address() and get_rtt_estimate_to_address(). * * The network size is measured as hundreds of devices that are expected to join to the network. For example, - * for a 400-device network set network size to 4. The Wi-SUN stack will internally use one of the four possible - * configuration buckets based on the selected network size and data rate. The configuration buckets are defined - * for a small, medium, large and xlarge networks. + * for a 400-device network set network size to 4. * - * For example, with 150kbs data rate set network size to: - * - 1 to use small configuration bucket. - * - 8 to use medium configuration bucket. - * - 15 to use large configuration bucket. - * - 25 to use xlarge configuration bucket. + * The Wi-SUN stack will automatically adjust timing and RPL configuration values based on the selected network + * size and data rate. If a customized timing or RPL values are needed, the APIs below should be invoked after + * changing the network size: + * - set_timing_parameters() to set timing settings to the Wi-SUN interface. + * - rpl_parameters_set() to set RPL settings to the Border Router interface. * - * By default Wi-SUN stack is configured to use medium sized network. + * By default the Wi-SUN stack is configured to use a few hundreds of devices. * * The network size should be set to 0 when running certification tests. * - * When the 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. - * - * When the 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. - * * \param network_size Network size in hundreds of devices (e.g. 12 for 1200 devices), 0 for certificate testing. * \return MESH_ERROR_NONE on success. * \return MESH_ERROR_UNKNOWN in case of failure.