Wi-SUN api documentation changes #981

KariHaapalehto · 2019-02-28T08:16:54Z

No description provided.

rebase 28.2

SeppoTakalo · 2019-02-28T12:55:41Z

docs/api/networkinterfaces/MeshInterface.md


-The application can use the `LoWPANNDInterface` or `ThreadInterface` object for connecting to the mesh network. When successfully connected, the application can use the Mbed [C++ socket APIs](network-socket.html) to create a socket to start communication with a remote peer.
+The application can use the `LoWPANNDInterface`, WisunInterface` or `ThreadInterface` object for connecting to the mesh network. When successfully connected, the application can use the Mbed [C++ socket APIs](network-socket.html) to create a socket to start communication with a remote peer.


WisunInterface missing the first `

SeppoTakalo · 2019-02-28T12:58:31Z

docs/reference/configuration/mesh.md

@@ -276,3 +278,69 @@ Name: mbed-mesh-api.6lowpan-nd-security-mode
    Macro name: MBED_CONF_MBED_MESH_API_6LOWPAN_ND_SECURITY_MODE
    Value: NONE (set by library:mbed-mesh-api)
 ```
+
+#### Wi-SUN related configuration parameters


Configuration should be moved to their own page.
But I don't find the "Configuration" page anymore from os.mbed.com/docs.. it has been very well hidden.

But this is the place, were the thread and 6lowpan configurations are

Maybe it deserves a separate PR.

SeppoTakalo · 2019-02-28T13:10:32Z

@mikter Please review, or delegate someone from your team.

AnotherButler · 2019-02-28T15:13:06Z

Tagging @kegilbert to make sure this works with his config script

AnotherButler · 2019-02-28T20:57:27Z

Note to self: No code dependency because code already merged: ARMmbed/mbed-os#9838

kegilbert · 2019-02-28T21:25:50Z

There's a few sections as is that will pose issues with the configuration parameter auto-update script.

The tool works by collecting all markdown code blocks and attempting to grab the prefix from the block. That prefix is then used to collect the output of mbed compile --config -v --prefix <PREFIX> and replace the old configuration parameter list. This allows us to keep the list up to date each patch release with minimal effort.

The downsides to this script are mainly:

[Minor] Can't have multiple prefixes in a single code block. For example in configuration/mesh.md,

.....
Name: nanostack-hal.nvm_cfstore
    Description: Use cfstore as a NVM storage. Else RAM simulation will be used
    Defined by: library:nanostack-hal
    No value set
Name: nanostack.configuration
    Description: Build time configuration. Refer to Handbook for valid values. Default: full stack
    Defined by: library:nanostack
    Macro name: MBED_CONF_NANOSTACK_CONFIGURATION
    Value: nanostack_full (set by library:nanostack)

would be a problem since the nanostack parameter would be dropped (only nanostack-hal would be run). With some more work on the tool this could be changed if needed. The current work around would just be to move the prefix to its own code block segment.

[Major] You cannot split up a lengthy list such as mbed-mesh-api into more logical sections as it is done now in configuration/mesh.md as each section will just be replaced by the entirety of the output from mbed compile --config -v --prefix <PREFIX>.

The workaround for that was to combine all of the separated sections into one segment, loosing some depth and clarity in our ability to highlight or group together sections of configuration parameters, but guaranteeing an always up to date list of parameters.

AnotherButler · 2019-03-04T16:07:10Z

@KariHaapalehto Can you please make the requested changes, so our config update script works with this doc?

KariHaapalehto · 2019-03-05T08:19:40Z

@SeppoTakalo , could you please comment about [2].
I don't like, that we should combine all mesh-api configurations to one big table just because of the tool. It doesn't make our document any better. Mesh-api contains some generic configuration values and 3 separate interface related configurations. In my opinion they are now well grouped and should be kept separate. Should we just run the tool to update parameter lists and keep them separate?

AnotherButler · 2019-03-05T17:17:34Z

I'd like to keep all of our pages uniform, up to date and reflective of the code. We do have pages with separations (such as this one), but they're still grouped by code prefix. In this example, we've put the ones that start with "rtos" in one group and the ones that start with "events" in another.

Because the mesh parameters all start with the same prefix, it makes sense for them to belong together. It's painful to remember to manually change one page when we run a script on the others. Also, we eventually hope to put the script into CI, which would make manual changes difficult.

mikter · 2019-03-11T09:58:18Z

@artokin could you check these.

Also there was changes in the Wi-SUN/Thread documentations and I think here is a link to those. are these links still functional?

SeppoTakalo · 2019-03-11T10:12:43Z

I object against combining the values into one list.
This affects the readability too much. Makes it almost unreadable.

We should not choose between readability and maintainability.

KariHaapalehto · 2019-03-11T11:14:55Z

I just pushed update to this pr. I did run the tool and config blocks are updated from the tool output. Nanostack configuration is now splitted to separate blocks based on prefix. Mbed-mesh-api is still splitted to logical blocks, since combining them to one big block would affect to readability.

artokin · 2019-03-11T13:38:26Z

docs/reference/configuration/mesh.md


 For understanding the technologies and APIs, please refer to following sections before this one:

 - [Network connectivity in Mbed OS](../reference/networking.html) technology page.
- [6LoWPAN Mesh technology](../reference/mesh-tech.html) page.
- [6LoWPAN Mesh class reference](../apis/mesh-api.html) user API.
+- [Mesh technology](../reference/mesh-tech.html) page.


This has been changed, now 6LoWPAN_ND, Wi-SUN and Thread are having separate page

artokin · 2019-03-11T13:39:32Z

docs/reference/configuration/mesh.md

@@ -53,11 +53,12 @@ Option name | Features supported | Estimated binary size of Nanostack

 If you want to optimize the flash usage, you need to configure Nanostack. The configuration to choose depends mostly on the preferred use case.

-See the [6LoWPAN technology overview](mesh-tech.html) for the definition of star and mesh networks. These same principles apply also to the Thread protocol.
+See the [mesh technology overview](mesh-tech.html) for the definition of star and mesh networks. These same principles apply also to the Wi-SUN and Thread protocols.


mesh-tech now contains mainly 6LoWPAN_ND related information

star and mesh network definitions are at mesh-tech page, so no need to update this, but I'll update rest of the links

AnotherButler · 2019-03-11T20:56:57Z

@kegilbert has graciously agreed to update his script to make this page more readable.

Once he does, please resolve any merge conflicts.

kegilbert · 2019-03-11T22:37:35Z

PR is up, pending review. Will require a minor modification. On all mbed_mesh_api configuration parameter list blocks, please add the following tags following the opening '```' segment on the relevant portions:
heap

thread

6lowpan

wisun

Such as:

Generic Mbed mesh API configuration values

Generic configuration allows you to fine tune Nanostack's heap usage.

'''heap
Configuration parameters

Name: mbed-mesh-api.heap-size
Description: Nanostack's heap size [bytes: 0-65534]
Defined by: library:mbed-mesh-api
Macro name: MBED_CONF_MBED_MESH_API_HEAP_SIZE
Value: 32500 (set by library:mbed-mesh-api)
.....
'''

I can make the changes as well once the merge conflict is resolved if that'd be easier.

rebase

kegilbert

LGTM from my end, thanks!

Spell out number less than 10.

AnotherButler

Thanks for the PR 👍

Merge pull request #1 from ARMmbed/development

5126f41

rebase 28.2

KariHaapalehto force-pushed the wisun branch from 1bb21f4 to 703a490 Compare February 28, 2019 08:17

SeppoTakalo reviewed Feb 28, 2019

View reviewed changes

KariHaapalehto force-pushed the wisun branch from 703a490 to 0ef4b97 Compare February 28, 2019 13:04

SeppoTakalo approved these changes Feb 28, 2019

View reviewed changes

SeppoTakalo requested a review from mikter February 28, 2019 13:10

AnotherButler requested a review from kegilbert February 28, 2019 15:10

artokin mentioned this pull request Mar 1, 2019

Add Wi-SUN introduction #969

Merged

KariHaapalehto force-pushed the wisun branch from 0ef4b97 to d79d114 Compare March 11, 2019 10:41

artokin reviewed Mar 11, 2019

View reviewed changes

KariHaapalehto force-pushed the wisun branch from d79d114 to 627e0e8 Compare March 11, 2019 14:21

kegilbert mentioned this pull request Mar 11, 2019

Add tag based configuration parameter splitting #1007

Merged

KariHaapalehto and others added 2 commits March 12, 2019 09:23

Merge pull request #2 from ARMmbed/development

17a2154

rebase

Wi-SUN api documentation changes

0866eb8

KariHaapalehto force-pushed the wisun branch from 627e0e8 to 0866eb8 Compare March 12, 2019 08:26

kegilbert approved these changes Mar 12, 2019

View reviewed changes

Spell out number in MeshInterface.md

ca03c4d

Spell out number less than 10.

AnotherButler approved these changes Mar 12, 2019

View reviewed changes

AnotherButler merged commit bf2b8c9 into ARMmbed:development Mar 12, 2019


		The application can use the `LoWPANNDInterface` or `ThreadInterface` object for connecting to the mesh network. When successfully connected, the application can use the Mbed [C++ socket APIs](network-socket.html) to create a socket to start communication with a remote peer.
		The application can use the `LoWPANNDInterface`, WisunInterface` or `ThreadInterface` object for connecting to the mesh network. When successfully connected, the application can use the Mbed [C++ socket APIs](network-socket.html) to create a socket to start communication with a remote peer.

Wi-SUN api documentation changes #981

Wi-SUN api documentation changes #981

Uh oh!

Conversation

KariHaapalehto commented Feb 28, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SeppoTakalo commented Feb 28, 2019

Uh oh!

AnotherButler commented Feb 28, 2019

Uh oh!

AnotherButler commented Feb 28, 2019

Uh oh!

kegilbert commented Feb 28, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnotherButler commented Mar 4, 2019

Uh oh!

KariHaapalehto commented Mar 5, 2019

Uh oh!

AnotherButler commented Mar 5, 2019

Uh oh!

mikter commented Mar 11, 2019

Uh oh!

SeppoTakalo commented Mar 11, 2019

Uh oh!

KariHaapalehto commented Mar 11, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Mar 11, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kegilbert commented Mar 11, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Generic Mbed mesh API configuration values

Uh oh!

kegilbert left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kegilbert commented Feb 28, 2019 •

edited

Loading

AnotherButler commented Mar 11, 2019 •

edited

Loading

kegilbert commented Mar 11, 2019 •

edited

Loading

kegilbert left a comment •

edited

Loading