Skip to content

Commit 24db1c8

Browse files
author
Hasnain Virk
committed
Updating docs
API documentation is updated to clear how the connection related return codes will work from now on.
1 parent 51f92b0 commit 24db1c8

File tree

3 files changed

+49
-75
lines changed

3 files changed

+49
-75
lines changed

‎features/lorawan/LoRaWANBase.h

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,14 @@ class LoRaWANBase {
4141
* Connect by Over The Air Activation or Activation By Personalization.
4242
* The connection type is selected at the setup.
4343
*
44-
* @return LORAWAN_STATUS_OK on success, a negative error code on
45-
* failure.
44+
* @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
45+
* a 'CONNECTED' event. Otherwise a negative error code.
46+
* Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
47+
*
48+
* For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned followed by
49+
* a 'CONNECTED' event when the JoinAccept is received. Otherwise a negative error code
50+
* is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no
51+
* event follows.
4652
*/
4753
virtual lorawan_status_t connect() = 0;
4854

@@ -53,8 +59,15 @@ class LoRaWANBase {
5359
* You need to define the parameters in the main application.
5460
*
5561
* @param connect Options how end-device will connect to gateway
56-
* @return LORAWAN_STATUS_OK on success, negative error code
57-
* on failure
62+
*
63+
* @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
64+
* a 'CONNECTED' event. Otherwise a negative error code.
65+
* Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
66+
*
67+
* For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned followed by
68+
* a 'CONNECTED' event when the JoinAccept is received. Otherwise a negative error code
69+
* is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no
70+
* event follows.
5871
*/
5972
virtual lorawan_status_t connect(const lorawan_connect_t &connect) = 0;
6073

‎features/lorawan/LoRaWANInterface.h

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@ class LoRaWANInterface: public LoRaWANBase {
6161
* all user-configured channels except the Join/Default channels. A CF-List can
6262
* configure a maximum of five channels other than the default channels.
6363
*
64-
* In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
6564
* To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
6665
* By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions
6766
* on these channels are severe and you may experience long delays or even failures in the confirmed traffic.
@@ -80,8 +79,14 @@ class LoRaWANInterface: public LoRaWANBase {
8079
* is important, at least for ABP. That's why we try to restore frame counters from
8180
* session information after a disconnection.
8281
*
83-
* @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS
84-
* on success, or a negative error code on failure.
82+
* @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
83+
* a 'CONNECTED' event. Otherwise a negative error code.
84+
* Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
85+
*
86+
* For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned followed by
87+
* a 'CONNECTED' event when the JoinAccept is received. Otherwise a negative error code
88+
* is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no
89+
* event follows.
8590
*/
8691
virtual lorawan_status_t connect();
8792

@@ -97,7 +102,6 @@ class LoRaWANInterface: public LoRaWANBase {
97102
* all user-configured channels except the Join/Default channels. A CF-List can
98103
* configure a maximum of five channels other than the default channels.
99104
*
100-
* In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
101105
* To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
102106
* By default, the PHY layers configure only the mandatory Join
103107
* channels. The retransmission back-off restrictions on these channels
@@ -120,8 +124,14 @@ class LoRaWANInterface: public LoRaWANBase {
120124
*
121125
* @param connect Options for an end device connection to the gateway.
122126
*
123-
* @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS,
124-
* a negative error code on failure.
127+
* @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
128+
* a 'CONNECTED' event. Otherwise a negative error code.
129+
* Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
130+
*
131+
* For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned followed by
132+
* a 'CONNECTED' event when the JoinAccept is received. Otherwise a negative error code
133+
* is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no
134+
* event follows.
125135
*/
126136
virtual lorawan_status_t connect(const lorawan_connect_t &connect);
127137

‎features/lorawan/LoRaWANStack.h

Lines changed: 16 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -84,78 +84,29 @@ class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
8484

8585
/** Connect OTAA or ABP using Mbed-OS config system
8686
*
87-
* Connect by Over The Air Activation or Activation By Personalization.
88-
* You need to configure the connection properly via the Mbed OS configuration
89-
* system.
90-
*
91-
* When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
92-
* However, this is not a real error. It tells you that the connection is in progress and you will
93-
* be notified of the completion via an event. By default, after the Join Accept message
94-
* is received, base stations may provide the node with a CF-List that replaces
95-
* all user-configured channels except the Join/Default channels. A CF-List can
96-
* configure a maximum of five channels other than the default channels.
97-
*
98-
* In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
99-
* To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
100-
* By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions
101-
* on these channels are severe and you may experience long delays or even failures in the confirmed traffic.
102-
* If you add more channels, the aggregated duty cycle becomes much more relaxed as compared to the Join (default) channels only.
103-
*
104-
* **NOTES ON RECONNECTION:**
105-
* Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
106-
* memory storage. Therefore, the state and frame counters cannot be restored after
107-
* a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
108-
* protocol, the state and frame counters are saved. Connecting again would try to
109-
* restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
110-
* to zero for OTAA and a new Join request lets the network server know
111-
* that the counters need a reset. The same is said about the ABP but there
112-
* is no way to convey this information to the network server. For a network
113-
* server, an ABP device is always connected. That's why storing the frame counters
114-
* is important, at least for ABP. That's why we try to restore frame counters from
115-
* session information after a disconnection.
116-
*
117-
* @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS
118-
* on success, or a negative error code on failure.
87+
* @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
88+
* a 'CONNECTED' event. Otherwise a negative error code.
89+
* Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
90+
*
91+
* For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned followed by
92+
* a 'CONNECTED' event when the JoinAccept is received. Otherwise a negative error code
93+
* is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no
94+
* event follows.
11995
*/
12096
lorawan_status_t connect();
12197

12298
/** Connect OTAA or ABP with parameters
123-
*
124-
* All connection parameters are chosen by the user and provided in the
125-
* data structure passed down.
126-
*
127-
* When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
128-
* However, this is not a real error. It tells you that connection is in progress and you will
129-
* be notified of completion via an event. By default, after Join Accept message
130-
* is received, base stations may provide the node with a CF-List which replaces
131-
* all user-configured channels except the Join/Default channels. A CF-List can
132-
* configure a maximum of five channels other than the default channels.
133-
*
134-
* In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
135-
* To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
136-
* By default, the PHY layers configure only the mandatory Join
137-
* channels. The retransmission back-off restrictions on these channels
138-
* are severe and you may experience long delays or even
139-
* failures in the confirmed traffic. If you add more channels, the aggregated duty
140-
* cycle becomes much more relaxed as compared to the Join (default) channels only.
141-
*
142-
* **NOTES ON RECONNECTION:**
143-
* Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
144-
* memory storage. Therefore, the state and frame counters cannot be restored after
145-
* a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
146-
* protocol, the state and frame counters are saved. Connecting again would try to
147-
* restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
148-
* to zero for OTAA and a new Join request lets the network server know
149-
* that the counters need a reset. The same is said about the ABP but there
150-
* is no way to convey this information to the network server. For a network
151-
* server, an ABP device is always connected. That's why storing the frame counters
152-
* is important, at least for ABP. That's why we try to restore frame counters from
153-
* session information after a disconnection.
15499
*
155100
* @param connect Options for an end device connection to the gateway.
156101
*
157-
* @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS,
158-
* a negative error code on failure.
102+
* @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
103+
* a 'CONNECTED' event. Otherwise a negative error code.
104+
* Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
105+
*
106+
* For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned followed by
107+
* a 'CONNECTED' event when the JoinAccept is received. Otherwise a negative error code
108+
* is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no
109+
* event follows.
159110
*/
160111
lorawan_status_t connect(const lorawan_connect_t &connect);
161112

0 commit comments

Comments
 (0)