| User | Revision | Line number | New contents of line |
|---|
| borlanic |
0:02dd72d1d465
|
1
|
/**
|
| borlanic |
0:02dd72d1d465
|
2
|
* Copyright (c) 2017, Arm Limited and affiliates.
|
| borlanic |
0:02dd72d1d465
|
3
|
* SPDX-License-Identifier: Apache-2.0
|
| borlanic |
0:02dd72d1d465
|
4
|
*
|
| borlanic |
0:02dd72d1d465
|
5
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
| borlanic |
0:02dd72d1d465
|
6
|
* you may not use this file except in compliance with the License.
|
| borlanic |
0:02dd72d1d465
|
7
|
* You may obtain a copy of the License at
|
| borlanic |
0:02dd72d1d465
|
8
|
*
|
| borlanic |
0:02dd72d1d465
|
9
|
* http://www.apache.org/licenses/LICENSE-2.0
|
| borlanic |
0:02dd72d1d465
|
10
|
*
|
| borlanic |
0:02dd72d1d465
|
11
|
* Unless required by applicable law or agreed to in writing, software
|
| borlanic |
0:02dd72d1d465
|
12
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
| borlanic |
0:02dd72d1d465
|
13
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
| borlanic |
0:02dd72d1d465
|
14
|
* See the License for the specific language governing permissions and
|
| borlanic |
0:02dd72d1d465
|
15
|
* limitations under the License.
|
| borlanic |
0:02dd72d1d465
|
16
|
*/
|
| borlanic |
0:02dd72d1d465
|
17
|
|
| borlanic |
0:02dd72d1d465
|
18
|
#ifndef LORAWANINTERFACE_H_
|
| borlanic |
0:02dd72d1d465
|
19
|
#define LORAWANINTERFACE_H_
|
| borlanic |
0:02dd72d1d465
|
20
|
|
| borlanic |
0:02dd72d1d465
|
21
|
#include "platform/Callback.h"
|
| borlanic |
0:02dd72d1d465
|
22
|
#include "LoRaWANStack.h"
|
| borlanic |
0:02dd72d1d465
|
23
|
#include "LoRaRadio.h"
|
| borlanic |
0:02dd72d1d465
|
24
|
#include "LoRaWANBase.h"
|
| borlanic |
0:02dd72d1d465
|
25
|
|
| borlanic |
0:02dd72d1d465
|
26
|
class LoRaWANInterface: public LoRaWANBase {
|
| borlanic |
0:02dd72d1d465
|
27
|
|
| borlanic |
0:02dd72d1d465
|
28
|
public:
|
| borlanic |
0:02dd72d1d465
|
29
|
|
| borlanic |
0:02dd72d1d465
|
30
|
/** Constructs a LoRaWANInterface using the LoRaWANStack instance underneath.
|
| borlanic |
0:02dd72d1d465
|
31
|
*
|
| borlanic |
0:02dd72d1d465
|
32
|
* Currently, LoRaWANStack is a singleton and you should only
|
| borlanic |
0:02dd72d1d465
|
33
|
* construct a single instance of LoRaWANInterface.
|
| borlanic |
0:02dd72d1d465
|
34
|
*
|
| borlanic |
0:02dd72d1d465
|
35
|
*/
|
| borlanic |
0:02dd72d1d465
|
36
|
LoRaWANInterface(LoRaRadio& radio);
|
| borlanic |
0:02dd72d1d465
|
37
|
|
| borlanic |
0:02dd72d1d465
|
38
|
virtual ~LoRaWANInterface();
|
| borlanic |
0:02dd72d1d465
|
39
|
|
| borlanic |
0:02dd72d1d465
|
40
|
/** Initialize the LoRa stack.
|
| borlanic |
0:02dd72d1d465
|
41
|
*
|
| borlanic |
0:02dd72d1d465
|
42
|
* You must call this first to be able to use the LoRa stack.
|
| borlanic |
0:02dd72d1d465
|
43
|
*
|
| borlanic |
0:02dd72d1d465
|
44
|
* @param ev_queue A pointer to EventQueue provided by the application.
|
| borlanic |
0:02dd72d1d465
|
45
|
*
|
| borlanic |
0:02dd72d1d465
|
46
|
* @return 0 on success, a negative error code on failure.
|
| borlanic |
0:02dd72d1d465
|
47
|
*/
|
| borlanic |
0:02dd72d1d465
|
48
|
virtual lorawan_status_t initialize(events::EventQueue *ev_queue);
|
| borlanic |
0:02dd72d1d465
|
49
|
|
| borlanic |
0:02dd72d1d465
|
50
|
/** Connect OTAA or ABP using Mbed-OS config system
|
| borlanic |
0:02dd72d1d465
|
51
|
*
|
| borlanic |
0:02dd72d1d465
|
52
|
* Connect by Over The Air Activation or Activation By Personalization.
|
| borlanic |
0:02dd72d1d465
|
53
|
* You need to configure the connection properly via the Mbed OS configuration
|
| borlanic |
0:02dd72d1d465
|
54
|
* system.
|
| borlanic |
0:02dd72d1d465
|
55
|
*
|
| borlanic |
0:02dd72d1d465
|
56
|
* When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
|
| borlanic |
0:02dd72d1d465
|
57
|
* However, this is not a real error. It tells you that the connection is in progress and you will
|
| borlanic |
0:02dd72d1d465
|
58
|
* be notified of the completion via an event. By default, after the Join Accept message
|
| borlanic |
0:02dd72d1d465
|
59
|
* is received, base stations may provide the node with a CF-List that replaces
|
| borlanic |
0:02dd72d1d465
|
60
|
* all user-configured channels except the Join/Default channels. A CF-List can
|
| borlanic |
0:02dd72d1d465
|
61
|
* configure a maximum of five channels other than the default channels.
|
| borlanic |
0:02dd72d1d465
|
62
|
*
|
| borlanic |
0:02dd72d1d465
|
63
|
* In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
|
| borlanic |
0:02dd72d1d465
|
64
|
* To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
|
| borlanic |
0:02dd72d1d465
|
65
|
* By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions
|
| borlanic |
0:02dd72d1d465
|
66
|
* on these channels are severe and you may experience long delays or even failures in the confirmed traffic.
|
| borlanic |
0:02dd72d1d465
|
67
|
* If you add more channels, the aggregated duty cycle becomes much more relaxed as compared to the Join (default) channels only.
|
| borlanic |
0:02dd72d1d465
|
68
|
*
|
| borlanic |
0:02dd72d1d465
|
69
|
* **NOTES ON RECONNECTION:**
|
| borlanic |
0:02dd72d1d465
|
70
|
* Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
|
| borlanic |
0:02dd72d1d465
|
71
|
* memory storage. Therefore, the state and frame counters cannot be restored after
|
| borlanic |
0:02dd72d1d465
|
72
|
* a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
|
| borlanic |
0:02dd72d1d465
|
73
|
* protocol, the state and frame counters are saved. Connecting again would try to
|
| borlanic |
0:02dd72d1d465
|
74
|
* restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
|
| borlanic |
0:02dd72d1d465
|
75
|
* to zero for OTAA and a new Join request lets the network server know
|
| borlanic |
0:02dd72d1d465
|
76
|
* that the counters need a reset. The same is said about the ABP but there
|
| borlanic |
0:02dd72d1d465
|
77
|
* is no way to convey this information to the network server. For a network
|
| borlanic |
0:02dd72d1d465
|
78
|
* server, an ABP device is always connected. That's why storing the frame counters
|
| borlanic |
0:02dd72d1d465
|
79
|
* is important, at least for ABP. That's why we try to restore frame counters from
|
| borlanic |
0:02dd72d1d465
|
80
|
* session information after a disconnection.
|
| borlanic |
0:02dd72d1d465
|
81
|
*
|
| borlanic |
0:02dd72d1d465
|
82
|
* @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS
|
| borlanic |
0:02dd72d1d465
|
83
|
* on success, or a negative error code on failure.
|
| borlanic |
0:02dd72d1d465
|
84
|
*/
|
| borlanic |
0:02dd72d1d465
|
85
|
virtual lorawan_status_t connect();
|
| borlanic |
0:02dd72d1d465
|
86
|
|
| borlanic |
0:02dd72d1d465
|
87
|
/** Connect OTAA or ABP with parameters
|
| borlanic |
0:02dd72d1d465
|
88
|
*
|
| borlanic |
0:02dd72d1d465
|
89
|
* All connection parameters are chosen by the user and provided in the
|
| borlanic |
0:02dd72d1d465
|
90
|
* data structure passed down.
|
| borlanic |
0:02dd72d1d465
|
91
|
*
|
| borlanic |
0:02dd72d1d465
|
92
|
* When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
|
| borlanic |
0:02dd72d1d465
|
93
|
* However, this is not a real error. It tells you that connection is in progress and you will
|
| borlanic |
0:02dd72d1d465
|
94
|
* be notified of completion via an event. By default, after Join Accept message
|
| borlanic |
0:02dd72d1d465
|
95
|
* is received, base stations may provide the node with a CF-List which replaces
|
| borlanic |
0:02dd72d1d465
|
96
|
* all user-configured channels except the Join/Default channels. A CF-List can
|
| borlanic |
0:02dd72d1d465
|
97
|
* configure a maximum of five channels other than the default channels.
|
| borlanic |
0:02dd72d1d465
|
98
|
*
|
| borlanic |
0:02dd72d1d465
|
99
|
* In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
|
| borlanic |
0:02dd72d1d465
|
100
|
* To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
|
| borlanic |
0:02dd72d1d465
|
101
|
* By default, the PHY layers configure only the mandatory Join
|
| borlanic |
0:02dd72d1d465
|
102
|
* channels. The retransmission back-off restrictions on these channels
|
| borlanic |
0:02dd72d1d465
|
103
|
* are severe and you may experience long delays or even
|
| borlanic |
0:02dd72d1d465
|
104
|
* failures in the confirmed traffic. If you add more channels, the aggregated duty
|
| borlanic |
0:02dd72d1d465
|
105
|
* cycle becomes much more relaxed as compared to the Join (default) channels only.
|
| borlanic |
0:02dd72d1d465
|
106
|
*
|
| borlanic |
0:02dd72d1d465
|
107
|
* **NOTES ON RECONNECTION:**
|
| borlanic |
0:02dd72d1d465
|
108
|
* Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
|
| borlanic |
0:02dd72d1d465
|
109
|
* memory storage. Therefore, the state and frame counters cannot be restored after
|
| borlanic |
0:02dd72d1d465
|
110
|
* a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
|
| borlanic |
0:02dd72d1d465
|
111
|
* protocol, the state and frame counters are saved. Connecting again would try to
|
| borlanic |
0:02dd72d1d465
|
112
|
* restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
|
| borlanic |
0:02dd72d1d465
|
113
|
* to zero for OTAA and a new Join request lets the network server know
|
| borlanic |
0:02dd72d1d465
|
114
|
* that the counters need a reset. The same is said about the ABP but there
|
| borlanic |
0:02dd72d1d465
|
115
|
* is no way to convey this information to the network server. For a network
|
| borlanic |
0:02dd72d1d465
|
116
|
* server, an ABP device is always connected. That's why storing the frame counters
|
| borlanic |
0:02dd72d1d465
|
117
|
* is important, at least for ABP. That's why we try to restore frame counters from
|
| borlanic |
0:02dd72d1d465
|
118
|
* session information after a disconnection.
|
| borlanic |
0:02dd72d1d465
|
119
|
*
|
| borlanic |
0:02dd72d1d465
|
120
|
* @param connect Options for an end device connection to the gateway.
|
| borlanic |
0:02dd72d1d465
|
121
|
*
|
| borlanic |
0:02dd72d1d465
|
122
|
* @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS,
|
| borlanic |
0:02dd72d1d465
|
123
|
* a negative error code on failure.
|
| borlanic |
0:02dd72d1d465
|
124
|
*/
|
| borlanic |
0:02dd72d1d465
|
125
|
virtual lorawan_status_t connect(const lorawan_connect_t &connect);
|
| borlanic |
0:02dd72d1d465
|
126
|
|
| borlanic |
0:02dd72d1d465
|
127
|
/** Disconnect the current session.
|
| borlanic |
0:02dd72d1d465
|
128
|
*
|
| borlanic |
0:02dd72d1d465
|
129
|
* @return LORAWAN_STATUS_DEVICE_OFF on successfully shutdown.
|
| borlanic |
0:02dd72d1d465
|
130
|
*/
|
| borlanic |
0:02dd72d1d465
|
131
|
virtual lorawan_status_t disconnect();
|
| borlanic |
0:02dd72d1d465
|
132
|
|
| borlanic |
0:02dd72d1d465
|
133
|
/** Validate the connectivity with the network.
|
| borlanic |
0:02dd72d1d465
|
134
|
*
|
| borlanic |
0:02dd72d1d465
|
135
|
* Application may use this API to submit a request to the stack for
|
| borlanic |
0:02dd72d1d465
|
136
|
* validation of its connectivity to a Network Server. Under the hood, this
|
| borlanic |
0:02dd72d1d465
|
137
|
* API schedules a Link Check Request command (LinkCheckReq) for the network
|
| borlanic |
0:02dd72d1d465
|
138
|
* server and once the response, i.e., LinkCheckAns MAC command is received
|
| borlanic |
0:02dd72d1d465
|
139
|
* from the Network Server, user provided method is called.
|
| borlanic |
0:02dd72d1d465
|
140
|
*
|
| borlanic |
0:02dd72d1d465
|
141
|
* One way to use this API may be the validation of connectivity after a long
|
| borlanic |
0:02dd72d1d465
|
142
|
* deep sleep. Mbed LoRaWANStack piggy-backs the MAC commands with data
|
| borlanic |
0:02dd72d1d465
|
143
|
* frame payload so the application needs to try sending something and the Network
|
| borlanic |
0:02dd72d1d465
|
144
|
* Server may respond during the RX slots.
|
| borlanic |
0:02dd72d1d465
|
145
|
*
|
| borlanic |
0:02dd72d1d465
|
146
|
* This API is usable only when the 'link_check_resp' callback is set by
|
| borlanic |
0:02dd72d1d465
|
147
|
* the application. See add_lora_app_callbacks API. If the above mentioned
|
| borlanic |
0:02dd72d1d465
|
148
|
* callback is not set, a LORAWAN_STATUS_PARAMETER_INVALID error is thrown.
|
| borlanic |
0:02dd72d1d465
|
149
|
*
|
| borlanic |
0:02dd72d1d465
|
150
|
* First parameter to callback function is the demodulation margin and
|
| borlanic |
0:02dd72d1d465
|
151
|
* the second parameter is the number of gateways that successfully received
|
| borlanic |
0:02dd72d1d465
|
152
|
* the last request.
|
| borlanic |
0:02dd72d1d465
|
153
|
*
|
| borlanic |
0:02dd72d1d465
|
154
|
* A 'Link Check Request' MAC command remains set for every subsequent
|
| borlanic |
0:02dd72d1d465
|
155
|
* transmission, until/unless application explicitly turns it off using
|
| borlanic |
0:02dd72d1d465
|
156
|
* remove_link_check_request() API.
|
| borlanic |
0:02dd72d1d465
|
157
|
*
|
| borlanic |
0:02dd72d1d465
|
158
|
* @return LORAWAN_STATUS_OK on successfully queuing a request, or
|
| borlanic |
0:02dd72d1d465
|
159
|
* a negative error code on failure.
|
| borlanic |
0:02dd72d1d465
|
160
|
*
|
| borlanic |
0:02dd72d1d465
|
161
|
*/
|
| borlanic |
0:02dd72d1d465
|
162
|
virtual lorawan_status_t add_link_check_request();
|
| borlanic |
0:02dd72d1d465
|
163
|
|
| borlanic |
0:02dd72d1d465
|
164
|
/** Removes link check request sticky MAC command.
|
| borlanic |
0:02dd72d1d465
|
165
|
*
|
| borlanic |
0:02dd72d1d465
|
166
|
* Any already queued request may still get entertained. However, no new
|
| borlanic |
0:02dd72d1d465
|
167
|
* requests will be made.
|
| borlanic |
0:02dd72d1d465
|
168
|
*/
|
| borlanic |
0:02dd72d1d465
|
169
|
virtual void remove_link_check_request();
|
| borlanic |
0:02dd72d1d465
|
170
|
|
| borlanic |
0:02dd72d1d465
|
171
|
/** Sets up a particular data rate
|
| borlanic |
0:02dd72d1d465
|
172
|
*
|
| borlanic |
0:02dd72d1d465
|
173
|
* `set_datarate()` first verifies whether the data rate given is valid or not.
|
| borlanic |
0:02dd72d1d465
|
174
|
* If it is valid, the system sets the given data rate to the channel.
|
| borlanic |
0:02dd72d1d465
|
175
|
*
|
| borlanic |
0:02dd72d1d465
|
176
|
* @param data_rate The intended data rate, for example DR_0 or DR_1.
|
| borlanic |
0:02dd72d1d465
|
177
|
* Please note, that the macro DR_* can mean different
|
| borlanic |
0:02dd72d1d465
|
178
|
* things in different regions.
|
| borlanic |
0:02dd72d1d465
|
179
|
* @return LORAWAN_STATUS_OK if everything goes well, otherwise
|
| borlanic |
0:02dd72d1d465
|
180
|
* a negative error code.
|
| borlanic |
0:02dd72d1d465
|
181
|
*/
|
| borlanic |
0:02dd72d1d465
|
182
|
virtual lorawan_status_t set_datarate(uint8_t data_rate);
|
| borlanic |
0:02dd72d1d465
|
183
|
|
| borlanic |
0:02dd72d1d465
|
184
|
/** Enables adaptive data rate (ADR).
|
| borlanic |
0:02dd72d1d465
|
185
|
*
|
| borlanic |
0:02dd72d1d465
|
186
|
* The underlying LoRaPHY and LoRaMac layers handle the data rate automatically
|
| borlanic |
0:02dd72d1d465
|
187
|
* for the user, based upon the radio conditions (network congestion).
|
| borlanic |
0:02dd72d1d465
|
188
|
*
|
| borlanic |
0:02dd72d1d465
|
189
|
* @return LORAWAN_STATUS_OK or negative error code otherwise.
|
| borlanic |
0:02dd72d1d465
|
190
|
*/
|
| borlanic |
0:02dd72d1d465
|
191
|
virtual lorawan_status_t enable_adaptive_datarate();
|
| borlanic |
0:02dd72d1d465
|
192
|
|
| borlanic |
0:02dd72d1d465
|
193
|
/** Disables adaptive data rate.
|
| borlanic |
0:02dd72d1d465
|
194
|
*
|
| borlanic |
0:02dd72d1d465
|
195
|
* When adaptive data rate (ADR) is disabled, you can either set a certain
|
| borlanic |
0:02dd72d1d465
|
196
|
* data rate or the MAC layer selects a default value.
|
| borlanic |
0:02dd72d1d465
|
197
|
*
|
| borlanic |
0:02dd72d1d465
|
198
|
* @return LORAWAN_STATUS_OK or negative error code otherwise.
|
| borlanic |
0:02dd72d1d465
|
199
|
*/
|
| borlanic |
0:02dd72d1d465
|
200
|
virtual lorawan_status_t disable_adaptive_datarate();
|
| borlanic |
0:02dd72d1d465
|
201
|
|
| borlanic |
0:02dd72d1d465
|
202
|
/** Sets up the retry counter for confirmed messages.
|
| borlanic |
0:02dd72d1d465
|
203
|
*
|
| borlanic |
0:02dd72d1d465
|
204
|
* Valid for confirmed messages only.
|
| borlanic |
0:02dd72d1d465
|
205
|
*
|
| borlanic |
0:02dd72d1d465
|
206
|
* The number of trials to transmit the frame, if the LoRaMAC layer did not
|
| borlanic |
0:02dd72d1d465
|
207
|
* receive an acknowledgment. The MAC performs a data rate adaptation as in
|
| borlanic |
0:02dd72d1d465
|
208
|
* the LoRaWAN Specification V1.0.2, chapter 18.4, table on page 64.
|
| borlanic |
0:02dd72d1d465
|
209
|
*
|
| borlanic |
0:02dd72d1d465
|
210
|
* Note, that if number of retries is set to 1 or 2, MAC will not decrease
|
| borlanic |
0:02dd72d1d465
|
211
|
* the datarate, if the LoRaMAC layer did not receive an acknowledgment.
|
| borlanic |
0:02dd72d1d465
|
212
|
*
|
| borlanic |
0:02dd72d1d465
|
213
|
* @param count The number of retries for confirmed messages.
|
| borlanic |
0:02dd72d1d465
|
214
|
*
|
| borlanic |
0:02dd72d1d465
|
215
|
* @return LORAWAN_STATUS_OK or a negative error code.
|
| borlanic |
0:02dd72d1d465
|
216
|
*/
|
| borlanic |
0:02dd72d1d465
|
217
|
virtual lorawan_status_t set_confirmed_msg_retries(uint8_t count);
|
| borlanic |
0:02dd72d1d465
|
218
|
|
| borlanic |
0:02dd72d1d465
|
219
|
/** Sets the channel plan.
|
| borlanic |
0:02dd72d1d465
|
220
|
*
|
| borlanic |
0:02dd72d1d465
|
221
|
* You can provide a list of channels with appropriate parameters filled
|
| borlanic |
0:02dd72d1d465
|
222
|
* in. However, this list is not absolute. The stack applies a CF-List whenever
|
| borlanic |
0:02dd72d1d465
|
223
|
* available, which means that the network can overwrite your channel
|
| borlanic |
0:02dd72d1d465
|
224
|
* frequency settings right after Join Accept is received. You may try
|
| borlanic |
0:02dd72d1d465
|
225
|
* to set up any channel or channels after that, and if the channel requested
|
| borlanic |
0:02dd72d1d465
|
226
|
* is already active, the request is silently ignored. A negative error
|
| borlanic |
0:02dd72d1d465
|
227
|
* code is returned if there is any problem with parameters.
|
| borlanic |
0:02dd72d1d465
|
228
|
*
|
| borlanic |
0:02dd72d1d465
|
229
|
* Please note that this API can also be used to add a single channel to the
|
| borlanic |
0:02dd72d1d465
|
230
|
* existing channel plan.
|
| borlanic |
0:02dd72d1d465
|
231
|
*
|
| borlanic |
0:02dd72d1d465
|
232
|
* There is no reverse mechanism in the 1.0.2 specification for a node to request
|
| borlanic |
0:02dd72d1d465
|
233
|
* a particular channel. Only the network server can initiate such a request.
|
| borlanic |
0:02dd72d1d465
|
234
|
* You need to ensure that the corresponding base station supports the channel or channels being added.
|
| borlanic |
0:02dd72d1d465
|
235
|
*
|
| borlanic |
0:02dd72d1d465
|
236
|
* If your list includes a default channel (a channel where Join Requests
|
| borlanic |
0:02dd72d1d465
|
237
|
* are received) you cannot fully configure the channel parameters.
|
| borlanic |
0:02dd72d1d465
|
238
|
* Either leave the channel settings to default or check your
|
| borlanic |
0:02dd72d1d465
|
239
|
* corresponding PHY layer implementation. For example, LoRaPHYE868.
|
| borlanic |
0:02dd72d1d465
|
240
|
*
|
| borlanic |
0:02dd72d1d465
|
241
|
* @param channel_plan The channel plan to set.
|
| borlanic |
0:02dd72d1d465
|
242
|
*
|
| borlanic |
0:02dd72d1d465
|
243
|
* @return LORAWAN_STATUS_OK on success, a negative error
|
| borlanic |
0:02dd72d1d465
|
244
|
* code on failure.
|
| borlanic |
0:02dd72d1d465
|
245
|
*/
|
| borlanic |
0:02dd72d1d465
|
246
|
virtual lorawan_status_t set_channel_plan(const lorawan_channelplan_t &channel_plan);
|
| borlanic |
0:02dd72d1d465
|
247
|
|
| borlanic |
0:02dd72d1d465
|
248
|
/** Gets the channel plans from the LoRa stack.
|
| borlanic |
0:02dd72d1d465
|
249
|
*
|
| borlanic |
0:02dd72d1d465
|
250
|
* Once you have selected a particular PHY layer, a set of channels
|
| borlanic |
0:02dd72d1d465
|
251
|
* is automatically activated. Right after connecting, you can use this API
|
| borlanic |
0:02dd72d1d465
|
252
|
* to see the current plan. Otherwise, this API returns the channel
|
| borlanic |
0:02dd72d1d465
|
253
|
* plan that you have set using `set_channel_plan()`.
|
| borlanic |
0:02dd72d1d465
|
254
|
*
|
| borlanic |
0:02dd72d1d465
|
255
|
* @param channel_plan The current channel plan information.
|
| borlanic |
0:02dd72d1d465
|
256
|
*
|
| borlanic |
0:02dd72d1d465
|
257
|
* @return LORAWAN_STATUS_OK on success, a negative error
|
| borlanic |
0:02dd72d1d465
|
258
|
* code on failure.
|
| borlanic |
0:02dd72d1d465
|
259
|
*/
|
| borlanic |
0:02dd72d1d465
|
260
|
virtual lorawan_status_t get_channel_plan(lorawan_channelplan_t &channel_plan);
|
| borlanic |
0:02dd72d1d465
|
261
|
|
| borlanic |
0:02dd72d1d465
|
262
|
/** Removes an active channel plan.
|
| borlanic |
0:02dd72d1d465
|
263
|
*
|
| borlanic |
0:02dd72d1d465
|
264
|
* You cannot remove default channels (the channels the base stations are listening to).
|
| borlanic |
0:02dd72d1d465
|
265
|
* When a plan is abolished, only the non-default channels are removed.
|
| borlanic |
0:02dd72d1d465
|
266
|
*
|
| borlanic |
0:02dd72d1d465
|
267
|
* @return LORAWAN_STATUS_OK on success, a negative error
|
| borlanic |
0:02dd72d1d465
|
268
|
* code on failure.
|
| borlanic |
0:02dd72d1d465
|
269
|
*/
|
| borlanic |
0:02dd72d1d465
|
270
|
virtual lorawan_status_t remove_channel_plan();
|
| borlanic |
0:02dd72d1d465
|
271
|
|
| borlanic |
0:02dd72d1d465
|
272
|
/** Removes a single channel.
|
| borlanic |
0:02dd72d1d465
|
273
|
*
|
| borlanic |
0:02dd72d1d465
|
274
|
* You cannot remove default channels (the channels the base stations are listening to).
|
| borlanic |
0:02dd72d1d465
|
275
|
*
|
| borlanic |
0:02dd72d1d465
|
276
|
* @param index The channel index.
|
| borlanic |
0:02dd72d1d465
|
277
|
*
|
| borlanic |
0:02dd72d1d465
|
278
|
* @return LORAWAN_STATUS_OK on success, a negative error
|
| borlanic |
0:02dd72d1d465
|
279
|
* code on failure.
|
| borlanic |
0:02dd72d1d465
|
280
|
*/
|
| borlanic |
0:02dd72d1d465
|
281
|
virtual lorawan_status_t remove_channel(uint8_t index);
|
| borlanic |
0:02dd72d1d465
|
282
|
|
| borlanic |
0:02dd72d1d465
|
283
|
/** Send message to gateway
|
| borlanic |
0:02dd72d1d465
|
284
|
*
|
| borlanic |
0:02dd72d1d465
|
285
|
* @param port The application port number. Port numbers 0 and 224
|
| borlanic |
0:02dd72d1d465
|
286
|
* are reserved, whereas port numbers from 1 to 223
|
| borlanic |
0:02dd72d1d465
|
287
|
* (0x01 to 0xDF) are valid port numbers.
|
| borlanic |
0:02dd72d1d465
|
288
|
* Anything out of this range is illegal.
|
| borlanic |
0:02dd72d1d465
|
289
|
*
|
| borlanic |
0:02dd72d1d465
|
290
|
* @param data A pointer to the data being sent. The ownership of the
|
| borlanic |
0:02dd72d1d465
|
291
|
* buffer is not transferred. The data is copied to the
|
| borlanic |
0:02dd72d1d465
|
292
|
* internal buffers.
|
| borlanic |
0:02dd72d1d465
|
293
|
*
|
| borlanic |
0:02dd72d1d465
|
294
|
* @param length The size of data in bytes.
|
| borlanic |
0:02dd72d1d465
|
295
|
*
|
| borlanic |
0:02dd72d1d465
|
296
|
* @param flags A flag used to determine what type of
|
| borlanic |
0:02dd72d1d465
|
297
|
* message is being sent, for example:
|
| borlanic |
0:02dd72d1d465
|
298
|
*
|
| borlanic |
0:02dd72d1d465
|
299
|
* MSG_UNCONFIRMED_FLAG = 0x01
|
| borlanic |
0:02dd72d1d465
|
300
|
* MSG_CONFIRMED_FLAG = 0x02
|
| borlanic |
0:02dd72d1d465
|
301
|
* MSG_MULTICAST_FLAG = 0x04
|
| borlanic |
0:02dd72d1d465
|
302
|
* MSG_PROPRIETARY_FLAG = 0x08
|
| borlanic |
0:02dd72d1d465
|
303
|
* MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
|
| borlanic |
0:02dd72d1d465
|
304
|
* used in conjunction with MSG_UNCONFIRMED_FLAG and
|
| borlanic |
0:02dd72d1d465
|
305
|
* MSG_CONFIRMED_FLAG depending on the intended use.
|
| borlanic |
0:02dd72d1d465
|
306
|
*
|
| borlanic |
0:02dd72d1d465
|
307
|
* MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
|
| borlanic |
0:02dd72d1d465
|
308
|
* a confirmed message flag for a proprietary message.
|
| borlanic |
0:02dd72d1d465
|
309
|
* MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
|
| borlanic |
0:02dd72d1d465
|
310
|
* mutually exclusive.
|
| borlanic |
0:02dd72d1d465
|
311
|
*
|
| borlanic |
0:02dd72d1d465
|
312
|
*
|
| borlanic |
0:02dd72d1d465
|
313
|
* @return The number of bytes sent, or
|
| borlanic |
0:02dd72d1d465
|
314
|
* LORAWAN_STATUS_WOULD_BLOCK if another TX is
|
| borlanic |
0:02dd72d1d465
|
315
|
* ongoing, or a negative error code on failure.
|
| borlanic |
0:02dd72d1d465
|
316
|
*/
|
| borlanic |
0:02dd72d1d465
|
317
|
virtual int16_t send(uint8_t port, const uint8_t* data, uint16_t length,
|
| borlanic |
0:02dd72d1d465
|
318
|
int flags);
|
| borlanic |
0:02dd72d1d465
|
319
|
|
| borlanic |
0:02dd72d1d465
|
320
|
/** Receives a message from the Network Server on a specific port.
|
| borlanic |
0:02dd72d1d465
|
321
|
*
|
| borlanic |
0:02dd72d1d465
|
322
|
* @param port The application port number. Port numbers 0 and 224
|
| borlanic |
0:02dd72d1d465
|
323
|
* are reserved, whereas port numbers from 1 to 223
|
| borlanic |
0:02dd72d1d465
|
324
|
* (0x01 to 0xDF) are valid port numbers.
|
| borlanic |
0:02dd72d1d465
|
325
|
* Anything out of this range is illegal.
|
| borlanic |
0:02dd72d1d465
|
326
|
*
|
| borlanic |
0:02dd72d1d465
|
327
|
* @param data A pointer to buffer where the received data will be
|
| borlanic |
0:02dd72d1d465
|
328
|
* stored.
|
| borlanic |
0:02dd72d1d465
|
329
|
*
|
| borlanic |
0:02dd72d1d465
|
330
|
* @param length The size of data in bytes
|
| borlanic |
0:02dd72d1d465
|
331
|
*
|
| borlanic |
0:02dd72d1d465
|
332
|
* @param flags A flag is used to determine what type of
|
| borlanic |
0:02dd72d1d465
|
333
|
* message is being sent, for example:
|
| borlanic |
0:02dd72d1d465
|
334
|
*
|
| borlanic |
0:02dd72d1d465
|
335
|
* MSG_UNCONFIRMED_FLAG = 0x01,
|
| borlanic |
0:02dd72d1d465
|
336
|
* MSG_CONFIRMED_FLAG = 0x02
|
| borlanic |
0:02dd72d1d465
|
337
|
* MSG_MULTICAST_FLAG = 0x04,
|
| borlanic |
0:02dd72d1d465
|
338
|
* MSG_PROPRIETARY_FLAG = 0x08
|
| borlanic |
0:02dd72d1d465
|
339
|
*
|
| borlanic |
0:02dd72d1d465
|
340
|
* MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
|
| borlanic |
0:02dd72d1d465
|
341
|
* used in conjunction with MSG_UNCONFIRMED_FLAG and
|
| borlanic |
0:02dd72d1d465
|
342
|
* MSG_CONFIRMED_FLAG depending on the intended use.
|
| borlanic |
0:02dd72d1d465
|
343
|
*
|
| borlanic |
0:02dd72d1d465
|
344
|
* MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
|
| borlanic |
0:02dd72d1d465
|
345
|
* a confirmed message flag for a proprietary message.
|
| borlanic |
0:02dd72d1d465
|
346
|
*
|
| borlanic |
0:02dd72d1d465
|
347
|
* MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
|
| borlanic |
0:02dd72d1d465
|
348
|
* not mutually exclusive, i.e., the user can subscribe to
|
| borlanic |
0:02dd72d1d465
|
349
|
* receive both CONFIRMED AND UNCONFIRMED messages at
|
| borlanic |
0:02dd72d1d465
|
350
|
* the same time.
|
| borlanic |
0:02dd72d1d465
|
351
|
*
|
| borlanic |
0:02dd72d1d465
|
352
|
* @return It could be one of these:
|
| borlanic |
0:02dd72d1d465
|
353
|
* i) 0 if there is nothing else to read.
|
| borlanic |
0:02dd72d1d465
|
354
|
* ii) Number of bytes written to user buffer.
|
| borlanic |
0:02dd72d1d465
|
355
|
* iii) LORAWAN_STATUS_WOULD_BLOCK if there is
|
| borlanic |
0:02dd72d1d465
|
356
|
* nothing available to read at the moment.
|
| borlanic |
0:02dd72d1d465
|
357
|
* iv) A negative error code on failure.
|
| borlanic |
0:02dd72d1d465
|
358
|
*/
|
| borlanic |
0:02dd72d1d465
|
359
|
virtual int16_t receive(uint8_t port, uint8_t* data, uint16_t length, int flags);
|
| borlanic |
0:02dd72d1d465
|
360
|
|
| borlanic |
0:02dd72d1d465
|
361
|
/** Receives a message from the Network Server on any port.
|
| borlanic |
0:02dd72d1d465
|
362
|
*
|
| borlanic |
0:02dd72d1d465
|
363
|
* @param data A pointer to buffer where the received data will be
|
| borlanic |
0:02dd72d1d465
|
364
|
* stored.
|
| borlanic |
0:02dd72d1d465
|
365
|
*
|
| borlanic |
0:02dd72d1d465
|
366
|
* @param length The size of data in bytes
|
| borlanic |
0:02dd72d1d465
|
367
|
*
|
| borlanic |
0:02dd72d1d465
|
368
|
* @param port Return the number of port to which message was received.
|
| borlanic |
0:02dd72d1d465
|
369
|
*
|
| borlanic |
0:02dd72d1d465
|
370
|
* @param flags Return flags to determine what type of message was received.
|
| borlanic |
0:02dd72d1d465
|
371
|
* MSG_UNCONFIRMED_FLAG = 0x01
|
| borlanic |
0:02dd72d1d465
|
372
|
* MSG_CONFIRMED_FLAG = 0x02
|
| borlanic |
0:02dd72d1d465
|
373
|
* MSG_MULTICAST_FLAG = 0x04
|
| borlanic |
0:02dd72d1d465
|
374
|
* MSG_PROPRIETARY_FLAG = 0x08
|
| borlanic |
0:02dd72d1d465
|
375
|
*
|
| borlanic |
0:02dd72d1d465
|
376
|
* @return It could be one of these:
|
| borlanic |
0:02dd72d1d465
|
377
|
* i) 0 if there is nothing else to read.
|
| borlanic |
0:02dd72d1d465
|
378
|
* ii) Number of bytes written to user buffer.
|
| borlanic |
0:02dd72d1d465
|
379
|
* iii) LORAWAN_STATUS_WOULD_BLOCK if there is
|
| borlanic |
0:02dd72d1d465
|
380
|
* nothing available to read at the moment.
|
| borlanic |
0:02dd72d1d465
|
381
|
* iv) A negative error code on failure.
|
| borlanic |
0:02dd72d1d465
|
382
|
*/
|
| borlanic |
0:02dd72d1d465
|
383
|
virtual int16_t receive(uint8_t* data, uint16_t length, uint8_t& port, int& flags);
|
| borlanic |
0:02dd72d1d465
|
384
|
|
| borlanic |
0:02dd72d1d465
|
385
|
/** Add application callbacks to the stack.
|
| borlanic |
0:02dd72d1d465
|
386
|
*
|
| borlanic |
0:02dd72d1d465
|
387
|
* 'lorawan_app_callbacks' is a structure that holds pointers to the application
|
| borlanic |
0:02dd72d1d465
|
388
|
* provided methods which are needed to be called in response to certain
|
| borlanic |
0:02dd72d1d465
|
389
|
* requests. The structure is default constructed to set all pointers to NULL.
|
| borlanic |
0:02dd72d1d465
|
390
|
* So if the user does not provide the pointer, a response will not be posted.
|
| borlanic |
0:02dd72d1d465
|
391
|
* However, the 'lorawan_events' callback is mandatory to be provided as it
|
| borlanic |
0:02dd72d1d465
|
392
|
* contains essential events.
|
| borlanic |
0:02dd72d1d465
|
393
|
*
|
| borlanic |
0:02dd72d1d465
|
394
|
* Events that can be posted to user via 'lorawan_events' are:
|
| borlanic |
0:02dd72d1d465
|
395
|
*
|
| borlanic |
0:02dd72d1d465
|
396
|
* CONNECTED - When the connection is complete
|
| borlanic |
0:02dd72d1d465
|
397
|
* DISCONNECTED - When the protocol is shut down in response to disconnect()
|
| borlanic |
0:02dd72d1d465
|
398
|
* TX_DONE - When a packet is sent
|
| borlanic |
0:02dd72d1d465
|
399
|
* TX_TIMEOUT, - When stack was unable to send packet in TX window
|
| borlanic |
0:02dd72d1d465
|
400
|
* TX_ERROR, - A general TX error
|
| borlanic |
0:02dd72d1d465
|
401
|
* TX_CRYPTO_ERROR, - If MIC fails, or any other crypto relted error
|
| borlanic |
0:02dd72d1d465
|
402
|
* TX_SCHEDULING_ERROR, - When stack is unable to schedule packet
|
| borlanic |
0:02dd72d1d465
|
403
|
* RX_DONE, - When there is something to receive
|
| borlanic |
0:02dd72d1d465
|
404
|
* RX_TIMEOUT, - Not yet mapped
|
| borlanic |
0:02dd72d1d465
|
405
|
* RX_ERROR - A general RX error
|
| borlanic |
0:02dd72d1d465
|
406
|
*
|
| borlanic |
0:02dd72d1d465
|
407
|
* Other responses to certain standard requests are an item for the future.
|
| borlanic |
0:02dd72d1d465
|
408
|
* For example, a link check request could be sent whenever the device tries
|
| borlanic |
0:02dd72d1d465
|
409
|
* to send a message and if the network server responds with a link check resposne,
|
| borlanic |
0:02dd72d1d465
|
410
|
* the stack notifies the application be calling the appropriate method. For example,
|
| borlanic |
0:02dd72d1d465
|
411
|
* 'link_check_resp' callback could be used to collect a response for a link check
|
| borlanic |
0:02dd72d1d465
|
412
|
* request MAC command and the result is thus transported to the application
|
| borlanic |
0:02dd72d1d465
|
413
|
* via callback function provided.
|
| borlanic |
0:02dd72d1d465
|
414
|
*
|
| borlanic |
0:02dd72d1d465
|
415
|
* As can be seen from declaration, mbed::Callback<void(uint8_t, uint8_t)> *link_check_resp)
|
| borlanic |
0:02dd72d1d465
|
416
|
* carries two parameters. First one is Demodulation Margin and the second one
|
| borlanic |
0:02dd72d1d465
|
417
|
* is number of gateways involved in the path to network server.
|
| borlanic |
0:02dd72d1d465
|
418
|
*
|
| borlanic |
0:02dd72d1d465
|
419
|
* An example of using this API with a latch onto 'lorawan_events' could be:
|
| borlanic |
0:02dd72d1d465
|
420
|
*
|
| borlanic |
0:02dd72d1d465
|
421
|
* LoRaWANInterface lorawan(radio);
|
| borlanic |
0:02dd72d1d465
|
422
|
* lorawan_app_callbacks cbs;
|
| borlanic |
0:02dd72d1d465
|
423
|
* static void my_event_handler();
|
| borlanic |
0:02dd72d1d465
|
424
|
*
|
| borlanic |
0:02dd72d1d465
|
425
|
* int main()
|
| borlanic |
0:02dd72d1d465
|
426
|
* {
|
| borlanic |
0:02dd72d1d465
|
427
|
* lorawan.initialize(&queue);
|
| borlanic |
0:02dd72d1d465
|
428
|
* cbs.events = mbed::callback(my_event_handler);
|
| borlanic |
0:02dd72d1d465
|
429
|
* lorawan.add_app_callbacks(&cbs);
|
| borlanic |
0:02dd72d1d465
|
430
|
* lorawan.connect();
|
| borlanic |
0:02dd72d1d465
|
431
|
* }
|
| borlanic |
0:02dd72d1d465
|
432
|
*
|
| borlanic |
0:02dd72d1d465
|
433
|
* static void my_event_handler(lora_events_t events)
|
| borlanic |
0:02dd72d1d465
|
434
|
* {
|
| borlanic |
0:02dd72d1d465
|
435
|
* switch(events) {
|
| borlanic |
0:02dd72d1d465
|
436
|
* case CONNECTED:
|
| borlanic |
0:02dd72d1d465
|
437
|
* //do something
|
| borlanic |
0:02dd72d1d465
|
438
|
* break;
|
| borlanic |
0:02dd72d1d465
|
439
|
* case DISCONNECTED:
|
| borlanic |
0:02dd72d1d465
|
440
|
* //do something
|
| borlanic |
0:02dd72d1d465
|
441
|
* break;
|
| borlanic |
0:02dd72d1d465
|
442
|
* case TX_DONE:
|
| borlanic |
0:02dd72d1d465
|
443
|
* //do something
|
| borlanic |
0:02dd72d1d465
|
444
|
* break;
|
| borlanic |
0:02dd72d1d465
|
445
|
* default:
|
| borlanic |
0:02dd72d1d465
|
446
|
* break;
|
| borlanic |
0:02dd72d1d465
|
447
|
* }
|
| borlanic |
0:02dd72d1d465
|
448
|
* }
|
| borlanic |
0:02dd72d1d465
|
449
|
*
|
| borlanic |
0:02dd72d1d465
|
450
|
* @param callbacks A pointer to the structure containing application
|
| borlanic |
0:02dd72d1d465
|
451
|
* callbacks.
|
| borlanic |
0:02dd72d1d465
|
452
|
*/
|
| borlanic |
0:02dd72d1d465
|
453
|
virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks);
|
| borlanic |
0:02dd72d1d465
|
454
|
|
| borlanic |
0:02dd72d1d465
|
455
|
/** Change device class
|
| borlanic |
0:02dd72d1d465
|
456
|
*
|
| borlanic |
0:02dd72d1d465
|
457
|
* Change current device class.
|
| borlanic |
0:02dd72d1d465
|
458
|
*
|
| borlanic |
0:02dd72d1d465
|
459
|
* @param device_class The device class
|
| borlanic |
0:02dd72d1d465
|
460
|
*
|
| borlanic |
0:02dd72d1d465
|
461
|
* @return LORAWAN_STATUS_OK on success,
|
| borlanic |
0:02dd72d1d465
|
462
|
* LORAWAN_STATUS_UNSUPPORTED is requested class is not supported,
|
| borlanic |
0:02dd72d1d465
|
463
|
* or other negative error code if request failed.
|
| borlanic |
0:02dd72d1d465
|
464
|
*/
|
| borlanic |
0:02dd72d1d465
|
465
|
virtual lorawan_status_t set_device_class(const device_class_t device_class);
|
| borlanic |
0:02dd72d1d465
|
466
|
};
|
| borlanic |
0:02dd72d1d465
|
467
|
|
| borlanic |
0:02dd72d1d465
|
468
|
#endif /* LORAWANINTERFACE_H_ */
|