Skip to content

Commit 000adb0

Browse files
Hasnain VirkCruz Monrreal II
Hasnain Virk
authored and
Cruz Monrreal II
committed
Updating docs
API documentation is updated to clear how the connection related return codes will work from now on.
1 parent b6fbb97 commit 000adb0

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)