Technology/Connectivity refactoring #470

SeppoTakalo · 2018-03-26T16:37:40Z

DONE

~~New Reference/Technology/Connectivity section that gathers all, not just IP based, connectivity options.~~
~~LoRa will move under Reference/Technology/Connectivity/Lora~~
~~LoRa API will stay under Reference/API~~
~~Network interfaces will have new page and move away from Socket API.~~
~~Mesh tutorial will move to under Technology (partially already is)~~
~~Mesh content from Socket page will move to Reference/API/Mesh~~

To be done in another PR

New page about Mesh configuration under Reference/Configuration/Mesh
Add more text to networking configuration section. Currently it is just a big blob about fields without any textual description of effects.

CC: @AnotherButler Please comment, is this going to right direction?
Any other feedback?

NOTE: Most of the bullets from that list are not yet done. I just wanted to make visible of what I'm going to do, as the PR will eventually be way too big to review.

NOTE: ONLY MERGE INTO `new_engine`. DO NOT MERGE INTO 5.8.

0Grit · 2018-03-26T18:11:28Z

Sounds like a good start.
Really like that IP Networking gets a dedicated section.
Not enough people realize how important the distinction between IP and non-IP connectivity is.

SeppoTakalo · 2018-03-27T08:52:20Z

@mikaleppanen @kjbracey-arm @AnttiKauppila @AriParkkila
Please review from technical point of view.

SeppoTakalo · 2018-03-27T14:07:04Z

@AnotherButler Please review.

For the remaining work, I will be reworking another PR. This can be merged in as it is.

Stuff here is targeting Mbed OS 5.9, so should not be merged for 5.8 branch.

AnotherButler · 2018-03-29T22:05:28Z

@SeppoTakalo I hope you don't mind, but I edited your initial comment with your most recent note, so I don't accidentally merge this into the live 5.8 docs.

AnotherButler · 2018-03-29T22:06:25Z

@MarceloSalazar @GarySwansonARM Y'all might be interested in this PR.

MarceloSalazar · 2018-04-03T15:12:43Z

As initial work looks great! I'd love to see this in a staging environment at some point in the future.

mikaleppanen · 2018-04-04T06:57:03Z

docs/reference/technology/connectivity/networking.md

+
+|Stack|Network protocols supported|Use cases|Limitations|
+|-----|---------------------------|---------|-----------|
+|LwIP|IPv4, IPv6, PPP|Ethernet, WiFi, 2G/3G/4G Cellular|4 sockets, 1 interface, no routing|


4 sockets is configuration option, so I think it is not a limitation. Application designer can choose to configure more sockets to lwip, with a cost of additional ram.

I know it can be configured. Many things can be, but to keep this page simple, I don't wan't to clutter it with extra information that will be presented later in the same book.

Technology section is before configuration section, so I don't want to refer it before it has been introduced.

SeppoTakalo · 2018-04-04T08:45:27Z

@AnotherButler have you now reviewed this?

When can we see it merged in and visible in the staging environment?

I have follow up documents coming and I want to finish this first. Or should I keep appending this one?

kjbracey · 2018-04-04T09:31:31Z

docs/reference/api/connectivity/networksocket/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 to create a socket to start communication with a remote peer.
+
+Mbed OS provides `NanostackEthernetInterface` for Ethernet.


This is still there to allow you to use any existing NanostackEthernetPhy drivers, but not really needed in the EMAC world. You should be using EthernetInterface to use EMAC drivers with Nanostack.

Maybe just drop the paragraph as it's nothing to do with mesh interfaces.

This does remind me that I should have at least actually stuck a "deprecated" on it. Main sticking point is that the K64F Nanostack driver still works a bit better than the EMAC one for cable detection logic.

I'll drop the reference as it is deprecated.

I did not actually touch this part at all, just moved it away from Socket page to its proper location.

kjbracey · 2018-04-04T09:36:35Z

docs/reference/technology/connectivity/networking.md

+On Mesh networks, Nanostack uses IEEE 802.15.4 radios for transmitting and receiving packets.
+The RF driver implements the `NanostackRfPhy` API.
+
+This driver type has not other usecases so it is implemented in C using Nanostack specific API.


Nice set of diagrams above - feels a little incomplete to be missing the diagram for this one.

AnttiKauppila · 2018-04-05T07:12:21Z

docs.json

@@ -89,7 +89,19 @@
            },
            {
                "title": "Technology",
+                "intro": {
+                    "type": "markdown",
+                    "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/tecnology.md"


Is there a typo in the link?
Should it be technology.md

SeppoTakalo · 2018-04-05T09:07:34Z

Fixed typo in .json and rebased

SeppoTakalo · 2018-04-05T14:49:01Z

@AnotherButler Images are now replaced with links to s3-us-west-2.amazonaws.com
When can we expect to see those images there?

How can anyone review if all the pictures and diagrams are gone. Should we wait until merge before converting links.

AnotherButler

I've left some final comments for you to address before we look at this on the test site.

AnotherButler · 2018-04-09T20:22:27Z

docs.json

+                    },
+                    {
+                        "type": "markdown",
+                        "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/USB.md"


Please remove USB from the .json. It's not on master yet.

AnotherButler · 2018-04-09T20:25:50Z

docs.json

-                        "intro": {
-                            "type": "markdown",
-                            "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lora.md"
-                        },
                        "sources": [{


I don't think the user API should start with lorawanevents.md. Could we move this, so it stays with intro-to-lora.md?

LoRaWANInterface is the API. It is the network interface that developers use.

Explanation of LoRa itself has moved to Technology/Connectivity/intro-to-lora.md

AnotherButler · 2018-04-09T20:26:47Z

docs.json

@@ -436,15 +464,7 @@
                    },
                    {
                        "title": "LoRaWAN",
-                        "intro": {


If we remove this section (or at least its formatting) from the .json, it will mess up the formatting of the documentation. It's OK to move the page, but we need to keep this formatting.

How can I fix the formatting?
Intro section itself has moved to Technology/Connectivity/intro-to-lora.md

AnotherButler · 2018-04-09T20:58:31Z

docs/reference/api/connectivity/lorawan/lora.md

@@ -1,3 +0,0 @@
-## LoRa on Arm Mbed OS


I'm confused. Did we delete this page or just rename it?

Delete.

Intro is moved to Technology/Connectivity/Intro.
I'm not sure what should stay here. I'll consult Hasnain about that.

AnotherButler · 2018-04-09T20:59:49Z

docs/reference/api/connectivity/networksocket/MeshInterface.md

+
+Currently, 6LoWPAN-ND (neighbor discovery) and Thread bootstrap modes are supported.
+
+##### Module configuration


This section needs to move the configuration section of the reference book.

AnotherButler · 2018-04-09T21:00:57Z

docs/reference/technology/connectivity/connectivity.md

@@ -0,0 +1,45 @@
+### Network connectivity in Mbed OS


I'm interested in seeing this page on the test site. I may want to tweak/change it after seeing it then.

AnotherButler · 2018-04-09T21:20:08Z

docs/reference/technology/connectivity/networking.md

+
+The Socket API is the common API among all IP connectivity methods. All network stacks in Mbed OS provide the same Socket API, making applications portable among different connectivity methods or even stacks.
+
+In the OSI model, the Socket API relates to layer 4, the Transport layer. In Mbed OS, the Socket API supports both [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) and [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol) protocols.


Could we link to our own TCP and UDP instead of Uncyclopedia?

Or maybe I should just remove the links.
This section is about technology in general, not the API itself, so I was trying to link to some neutral page that explains the technology for those who do not understand it.

Link to API section is two lines below

AnotherButler · 2018-04-09T21:20:36Z

docs/reference/technology/connectivity/networking.md

@@ -0,0 +1,93 @@
+### IP networking
+
+IP Networking in Mbed OS is layered in three clearly defined API levels. The diagram below shows the layers next to the closest matching [OSI model](https://en.wikipedia.org/wiki/OSI_model) layers.


Could we please link somewhere more credible than Uncyclopedia?

More credible?
This is first hit in the Google if you search for OSI model. So it is the most linked one.
I'm not sure there are more stable sites that we can confidently link on, and still assume after couple of years that the link is still valid.

OSI Model is a theoretical model from academic text book. Defined by the ISO organization. Most computer science students recognize it. But because it is theoretical, there are not many sites that host proper textbook explanation about it, others that Uncyclopedia. If you can recommend me one, I can change the link.

Proper standard about it, is behind pay-wall https://ieeexplore.ieee.org/document/1094702/

AnotherButler · 2018-04-09T21:20:52Z

docs/reference/technology/connectivity/networking.md

+
+In the OSI model, the Socket API relates to layer 4, the Transport layer. In Mbed OS, the Socket API supports both [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) and [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol) protocols.
+
+Refer to [TODO:Socket API](networksockets.md) reference for usage instructions.


Please update the todos.

AnotherButler · 2018-04-09T21:21:00Z

docs/reference/technology/connectivity/networking.md

+- 6LoWPAN-ND mesh networking.
+- Thread mesh networking.
+
+Refer to [TODO: sockets/interface API reference](api/connectivity/networkinterface.md) for usage instructions.


Please update the todos.

What is the address of the final link?
I have not understood the mechanism here.

If docs/reference/api/connectivity/networksocket/networksocket.md becames /docs/development/reference/network-socket.html then what will be the docs/reference/api/connectivity/networksocket/networkinterface.md?

Is the link based on title of the page or file name?

AnotherButler · 2018-04-09T21:22:54Z

We'll upload the images to AWS, and then you'll be able to see all of them properly.

AriParkkila · 2018-04-10T06:10:41Z

Could this link to docs/reference/technology/connectivity/cellular.md introduced in PR #489

SeppoTakalo · 2018-04-10T08:22:44Z

@AriParkkila I'll add the links once that PR is in.

Edit document for positioning, and add sentence for additional context.

Copy edit file, mostly for active voice, agreement, formatting and general phrasing.

Make minor copy edits.

Copy edit file for grammar and formatting.

AnotherButler · 2018-04-10T15:54:38Z

I'm going to merge this, so we can all see what it looks like on the test site. We can create any further changes needed in a new PR.

@SeppoTakalo @MarceloSalazar @GarySwansonARM @sg- Could y'all please review these pages on our internal test site?

SeppoTakalo · 2018-04-10T16:01:17Z

Yes!
I can have internal review meeting here, as this is related to #489 and we need to make these two changes match.

SeppoTakalo changed the title ~~WIP: Early review of Technology/Connectivity refactoring~~ Review of Technology/Connectivity refactoring Mar 27, 2018

SeppoTakalo changed the title ~~Review of Technology/Connectivity refactoring~~ Technology/Connectivity refactoring Mar 27, 2018

AnotherButler requested review from mikaleppanen, kjbracey, AnttiKauppila and AriParkkila March 29, 2018 22:00

AnttiKauppila approved these changes Apr 3, 2018

View reviewed changes

mikaleppanen approved these changes Apr 4, 2018

View reviewed changes

SeppoTakalo mentioned this pull request Apr 4, 2018

Expand Ethernet interface intro #481

Closed

kjbracey reviewed Apr 4, 2018

View reviewed changes

kjbracey approved these changes Apr 4, 2018

View reviewed changes

AnttiKauppila reviewed Apr 5, 2018

View reviewed changes

AnotherButler reviewed Apr 9, 2018

View reviewed changes

SeppoTakalo mentioned this pull request Apr 10, 2018

Updated ethernet and wifi interface description #472

Merged

Seppo Takalo added 4 commits April 10, 2018 11:31

Add intro page to technology section.

8d777dd

Move USB after connectivity+ add connectivity placeholder

67d9562

Continue on refactoring the Reference/Techology/Connetivity section.

33ab3e0

Add image that compares different connectivity options.

1d77bcc

Seppo Takalo and others added 17 commits April 10, 2018 11:31

Add IP networking section

79258a3

Move LoRa after the Mesh networking.

81c49da

Add Network Interface section

061a5e9

Add Network driver information

a2984fb

Add link layer configuration section.

0275964

Move Mesh documentation to its own section.

50b8535

Edit technology.md

f7bcd5f

Edit document for positioning, and add sentence for additional context.

Copy edit connectivity.md

fd4ea7f

Copy edit file, mostly for active voice, agreement, formatting and general phrasing.

Drop the reference to NanostackEthernetInterface.

bdea47e

Add picture for Nanostack's RF driver

1d4a28d

Fix typo

5afe2fa

Expand Ethernet interface intro

c4a906f

Copy edit EthInterface.md

57797bc

Make minor copy edits.

Copy edit networking.md

6cabaa1

Copy edit file for grammar and formatting.

Updated ethernet and wifi interface description

b0b01f9

Remove USB from Technology

2961e1d

Fix TODO links

08d3f9b

AnotherButler merged commit db3eb69 into ARMmbed:new_engine Apr 10, 2018

SeppoTakalo mentioned this pull request Apr 13, 2018

Hide headers from connectivity page. #493

Merged


		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 to create a socket to start communication with a remote peer.

		Mbed OS provides `NanostackEthernetInterface` for Ethernet.


		Currently, 6LoWPAN-ND (neighbor discovery) and Thread bootstrap modes are supported.

		##### Module configuration


		The Socket API is the common API among all IP connectivity methods. All network stacks in Mbed OS provide the same Socket API, making applications portable among different connectivity methods or even stacks.

		In the OSI model, the Socket API relates to layer 4, the Transport layer. In Mbed OS, the Socket API supports both [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) and [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol) protocols.

		@@ -0,0 +1,93 @@
		### IP networking

		IP Networking in Mbed OS is layered in three clearly defined API levels. The diagram below shows the layers next to the closest matching [OSI model](https://en.wikipedia.org/wiki/OSI_model) layers.


		In the OSI model, the Socket API relates to layer 4, the Transport layer. In Mbed OS, the Socket API supports both [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) and [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol) protocols.

		Refer to [TODO:Socket API](networksockets.md) reference for usage instructions.

Technology/Connectivity refactoring #470

Technology/Connectivity refactoring #470

Uh oh!

Conversation

SeppoTakalo commented Mar 26, 2018 • edited by AnotherButler Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DONE

To be done in another PR

NOTE: ONLY MERGE INTO new_engine. DO NOT MERGE INTO 5.8.

Uh oh!

0Grit commented Mar 26, 2018

Uh oh!

SeppoTakalo commented Mar 27, 2018

Uh oh!

SeppoTakalo commented Mar 27, 2018

Uh oh!

AnotherButler commented Mar 29, 2018

Uh oh!

AnotherButler commented Mar 29, 2018

Uh oh!

MarceloSalazar commented Apr 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SeppoTakalo commented Apr 4, 2018

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 Apr 5, 2018

Uh oh!

SeppoTakalo commented Apr 5, 2018

Uh oh!

AnotherButler left a comment

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Apr 9, 2018

Uh oh!

AriParkkila commented Apr 10, 2018

SeppoTakalo commented Mar 26, 2018 •

edited by AnotherButler

Loading

NOTE: ONLY MERGE INTO `new_engine`. DO NOT MERGE INTO 5.8.