Adding LoRaWAN docs for Mbed-OS 5.8 #414

hasnainvirk · 2018-02-16T01:04:26Z

No description provided.

hasnainvirk · 2018-02-16T01:08:43Z

@AnotherButler Please review. This will go first ARMmbed/mbed-os#6087

AnttiKauppila

Looks good to me.

kivaisan · 2018-03-01T11:09:03Z

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

+|`TX_DONE` | When a packet is transmitted |
+| `TX_TIMEOUT` | When stack was unable to send packet in TX window  |
+| `TX_ERROR` | A general TX error  |
+| `TX_CRYPTO_ERROR` | f MIC fails, or any other crypto relted error  |


"f" -> "If"
"relted" -> "related"

kivaisan · 2018-03-01T11:09:57Z

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

+| `TX_TIMEOUT` | When stack was unable to send packet in TX window  |
+| `TX_ERROR` | A general TX error  |
+| `TX_CRYPTO_ERROR` | f MIC fails, or any other crypto relted error  |
+| `TX_SCHEDULING_ERROR` | hen stack is unable to schedule packet  |


"hen" -> "When"

kivaisan · 2018-03-01T11:13:35Z

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

+	return battery_level;
+}
+
+callbacks.link_check_resp = mbed::callback(your_lbattery_level);


callbacks.battery_level = mbed::callback(your_battery_level);

kivaisan · 2018-03-01T11:22:27Z

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

+|`LORAWAN_STATUS_PORT_INVALID` | -1015 | Invalid port |
+|`LORAWAN_STATUS_CONNECT_IN_PROGRESS` |- 1016 | Connection in progress (application should wait for CONNECT event) |
+|`LORAWAN_STATUS_NO_ACTIVE_SESSIONS` | -1017 | No active session in progress |
+|`LORAWAN_STATUS_IDLE` |- 1018 | Stack idle at the moment|


This table does not show up properly

kivaisan · 2018-03-01T11:23:11Z

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

+|`LORAWAN_STATUS_LENGTH_ERROR` |- 1010 | Payload lenght error |
+| `LORAWAN_STATUS_DEVICE_OFF`| -1011 | the device is off, i.e., disconnected state |
+| `LORAWAN_STATUS_NOT_INITIALIZED` | -1012| Stack not initialized  |
+| `LORAWAN_STATUS_UNSUPPORTED` | -1013|hUnsupported service |


"hUnsupported" -> "Unsupported"

kivaisan · 2018-03-01T11:23:31Z

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

+| `LORAWAN_STATUS_FREQ_AND_DR_INVALID` | -1006| When stack was unable to send packet in TX window  |
+|`LORAWAN_STATUS_NO_NETWORK_JOINED` | -1009 | Device is not part of a network yet (Applicable only for OTAA) |
+|`LORAWAN_STATUS_LENGTH_ERROR` |- 1010 | Payload lenght error |
+| `LORAWAN_STATUS_DEVICE_OFF`| -1011 | the device is off, i.e., disconnected state |


"the" -> "The"

kivaisan · 2018-03-01T11:24:05Z

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

+|`LORAWAN_STATUS_WOULD_BLOCK`| -1001 | Stack cannot send at the moment or have nothing to read|
+| `LORAWAN_STATUS_SERVICE_UNKNOWN`| -1002 | Unknown service request |
+| `LORAWAN_STATUS_PARAMETER_INVALID`| -1003 | Invalid parameter  |
+| `LORAWAN_STATUS_FREQUENCY_INVALID` | -1004| Invalid frequency  |


For consistensy, please check spaces around "|" -characters

hasnainvirk · 2018-03-01T11:29:17Z

@kivaisan I will send a patch shortly.

AnotherButler

@hasnainvirk Thanks for the great docs. I've left a few comments and queries for you to address.

AnotherButler · 2018-02-28T19:42:04Z

docs/reference/api/api.md

@@ -6,6 +6,7 @@ The [APIs](/docs/v5.7/introduction/glossary.html) in this document are organized
 - [Drivers](/docs/v5.7/reference/drivers.html): analog and digital input and outputs and digital interfaces.
 - [RTOS](/docs/v5.7/reference/rtos.html): handling tasks and events in Mbed OS.
 - [Network Socket](/docs/v5.7/reference/network-socket.html): network sockets, Ethernet, Wi-Fi, cellular and mesh networking.
+- [LoRaWAN](/docs/v5.8/reference/lorawan.html): low power wide area network.


👍 Thanks for remembering to add this section.

AnotherButler · 2018-02-28T19:50:16Z

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

+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_radio.html)
+
+### LoRaRadio example


Please add an example here from Mbed teams. For an example, please see the LowPowerTicker user API.

@AnttiKauppila Could you please communicate to Amanda through email the reason why we are not posting an embedded example ? I didn't not get hold of the full context when we were discussing this.

@AnotherButler Okay, I got clearance to tell you the reason. Please note that we do have a very simple example code which do exist at os.mbed.com, https://os.mbed.com/teams/mbed-os-examples/code/lorawan-example/. But this is private. We can't make it public as it will need at least two months of process through legal and we don't have enough time for it. So for the time being it will suffice to just provide a link for the github repository which contains full example code.

I'm fine with this going in without an example for now, but we should add an example as soon as possible.

Hi Amanda, example is now public and ready for Online compiler

This is valid link currently:
https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_lo_ra_radio.html

AnotherButler · 2018-02-28T19:51:05Z

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

+
+### LoRaRadio class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_radio.html)


This link doesn't work. Please fix it or let me know when it will go into effect.

I think it will work after the release. I am not sure. I just followed what others had been doing here. Seemingly, the script to fetch doxygen from Mbed-OS would make it work during the release process.

This is valid link currently:
https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_lo_ra_radio.html

AnotherButler · 2018-03-01T22:21:41Z

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

+
+Arm Mbed OS provides a native network stack for LoRaWAN, which can run on any Mbed Enabled device with a LoRa radio onboard. 
+
+The [LoRaWANInterface](https://github.com/ARMmbed/mbed-os/blob/feature-lorawan/features/lorawan/LoRaWANInterface.h) provides a C++ API for connecting to the internet over a LoRa network.


We prefer not to link to GitHub. Is there a Doxygen page we could link to, instead?

@AnttiKauppila This relates to #414 (comment). Please clarify the reason to Amanda.

@AnotherButler Please check this #414 (comment)

We should use real doxygen tag here, but can we change this after release Amanda when we know the real path? Or is there already some doxygen generated for the release?

This is valid link currently:
https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_lo_ra_w_a_n_interface.html

AnotherButler · 2018-03-01T22:23:12Z

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

+
+## LoRaWANInterface class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_w_a_n_interfcae.html)


Note: This link doesn't work even after I update the spelling to "interface.html" Please fix it or let me know when it will go into effect.

oh. The spellings :) I wrote this document when I was travelling and had terrible flu :) Affects are pretty obvious. Yeah, the link may work only after the release. I am not actually sure how this works. My assumption is that when you will update docs for 5.8 (during release process), a script will fetch doxygen and this link would start working.

AnotherButler · 2018-03-01T22:24:17Z

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

+
+To bring up the Mbed LoRaWAN stack, consider the following progression: 
+
+1) An [EventQueue](https://os.mbed.com/docs/v5.8/reference/eventqueue.html) object. 


Query: Do these numbers indicate steps that need to happen in order? Or is it more of a logical grouping of items? [This only matters because we use numbers for ordered steps and bullets for unordered groupings.]

Its an ordered progression.

This is valid link
https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classevents_1_1_event_queue.html

AnotherButler · 2018-03-01T22:26:41Z

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

@@ -0,0 +1,91 @@
+<h2 id="lorawan-configuration">Configuring Mbed LoRaWAN Stack</h2>


I this content should go on this page: https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/configuration/Connectivity.md

Do you mind if we move it there and make it match that format?

I am afraid not. There are many reasons why not. For instance, LoRaWAN is non-IP that's why it is out of the Network Socket scope. Secondly, the purpose of this page is just to let user know what he can overwrite in terms of configuration and how to do it. I think the link you provided, is used for creating json config files for embedded example codes which are then exported to Online Compiler. We are not embedding any example in the docs at the moment (@AnttiKauppila will communicate the reason).

@hasnainvirk Thanks for the response.

The linked page is for all connectivity, not just IP.

If you like, we can add an empty line between the components, the way we did between the general purpose file system and LittleFS-specific configs: https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/configuration/Storage.md

I don't understand your next point. The purpose of the page I linked is also to let users know what they can overwrite in terms of configuration. Could you please elaborate?

Thank you and @AnttiKauppila for clarifying about the examples. It makes sense not to include private examples.

AnotherButler · 2018-03-01T22:27:45Z

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

+
+### LoRaWAN example
+
+Please visit our [github example repository](https://github.com/ARMmbed/mbed-os-example-lorawan) and follow the instructions in the `README.md`.


Could you please move this example to Mbed teams? I don't have permissions to, but I would like to transclude this example like we do for other APIs.

@AnttiKauppila Related to the comments above.

@AnotherButler Please check this #414 (comment)

This must be used here as a correct link: https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan

I don't have access to Hasnain's fork or this repo, so could you please replace this Amanda?

Pekka has corrected this link already together with Antti.

AnotherButler · 2018-03-01T22:48:03Z

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

+
+#### Link check response handler
+
+This callback is added when it is desired to send a link check request MAC command. 


Query: Could you please rephrase this sentence? I'm not sure what it means.

Sure, I will try to make it more clearer.

Update content to fit our template.

Copy edit for branding, formatting and minor grammar fixes.

Copy edit for active voice, consistent tense and spelling.

Spelling mistakes are corrected. Table in error codes is streamlined. Context clearance in lorawanevents.md

hasnainvirk · 2018-03-02T10:58:47Z

@kivaisan @AnotherButler Please review again.

kivaisan

Just fix those extra spaces in error codes. Otherwise ok

kivaisan · 2018-03-02T12:24:38Z

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

+|`LORAWAN_STATUS_PORT_INVALID`| -1015 | Invalid port |
+|`LORAWAN_STATUS_CONNECT_IN_PROGRESS`|- 1016 | Connection in progress (application should wait for CONNECT event) |
+|`LORAWAN_STATUS_NO_ACTIVE_SESSIONS`| -1017 | No active session in progress |
+|`LORAWAN_STATUS_IDLE`|- 1018 | Stack idle at the moment|


Remove space between - and the number for these errors:
-1010
-1016
-1018

Hi @AnotherButler, would it be possible for you to do these 3 whitespace modifications Kimmo requested? Both Hasnain and Kimmo are on holiday.

@AnttiKauppila Sure thing. I'll do that shortly.

Update spacing formatting.

Standardize spacing, and remove Latin abbreviation.

Update links for proper rendering.

Update link from filesystem to LoRaWAN.

Update example formatting to match other APIs, and fix spacing in ordered progression.

Update formatting again for consistency.

Update example link because the engine can be picky.

Update links for rendering and so as not to link to GitHub.

AnttiKauppila approved these changes Mar 1, 2018

View reviewed changes

kivaisan suggested changes Mar 1, 2018

View reviewed changes

kivaisan reviewed Mar 1, 2018

View reviewed changes

AnotherButler reviewed Mar 1, 2018

View reviewed changes

Hasnain Virk and others added 5 commits March 2, 2018 12:56

Adding LoRaWAN docs for Mbed-OS 5.8

b40124c

Update loraradio.md

134ecd5

Update content to fit our template.

Copy edit lorawan.md

6c214cd

Copy edit for branding, formatting and minor grammar fixes.

Copy edit lorawanevents.md

d028686

Copy edit for active voice, consistent tense and spelling.

ERRATA

ac707d5

Spelling mistakes are corrected. Table in error codes is streamlined. Context clearance in lorawanevents.md

kivaisan approved these changes Mar 2, 2018

View reviewed changes

Amanda Butler and others added 10 commits March 5, 2018 17:30

Fix spaces in errorcodes.md

b8bf550

Update spacing formatting.

A link fix as proposed by Antti.

6b6b377

Update formatting in errorcodes.md

50381dd

Standardize spacing, and remove Latin abbreviation.

Update links in loraradio.md

51c6659

Update links for proper rendering.

Fix link in loraradio.md

1af1fa7

Update link from filesystem to LoRaWAN.

Update formatting in lorawan.md

b78854d

Update example formatting to match other APIs, and fix spacing in ordered progression.

Update spacing in errorcodes.md again

7d5f993

Update formatting again for consistency.

Fix link in loraradio.md

5e7113a

Update example link because the engine can be picky.

Update links in lorawan.md

1bbbb2c

Update links for rendering and so as not to link to GitHub.

Merge branch 'new_engine' into lorwan_docs

358148d

AnotherButler merged commit 5da8d50 into ARMmbed:new_engine Mar 12, 2018


		[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_radio.html)

		### LoRaRadio example


		### LoRaRadio class reference

		[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_radio.html)


		Arm Mbed OS provides a native network stack for LoRaWAN, which can run on any Mbed Enabled device with a LoRa radio onboard.

		The [LoRaWANInterface](https://github.com/ARMmbed/mbed-os/blob/feature-lorawan/features/lorawan/LoRaWANInterface.h) provides a C++ API for connecting to the internet over a LoRa network.


		## LoRaWANInterface class reference

		[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_w_a_n_interfcae.html)


		To bring up the Mbed LoRaWAN stack, consider the following progression:

		1) An [EventQueue](https://os.mbed.com/docs/v5.8/reference/eventqueue.html) object.

		@@ -0,0 +1,91 @@
		<h2 id="lorawan-configuration">Configuring Mbed LoRaWAN Stack</h2>


		### LoRaWAN example

		Please visit our [github example repository](https://github.com/ARMmbed/mbed-os-example-lorawan) and follow the instructions in the `README.md`.


		#### Link check response handler

		This callback is added when it is desired to send a link check request MAC command.

Adding LoRaWAN docs for Mbed-OS 5.8 #414

Adding LoRaWAN docs for Mbed-OS 5.8 #414

Uh oh!

Conversation

hasnainvirk commented Feb 16, 2018

Uh oh!

hasnainvirk commented Feb 16, 2018

Uh oh!

AnttiKauppila 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!

hasnainvirk commented Mar 1, 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!

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!

AnttiKauppila Mar 9, 2018 •

edited

Loading