Skip to content

Commit 207bf46

Browse files
matthijskooijmanmatthijskooijman
committed
docs: Make overview documentation complete
1 parent 8adffe1 commit 207bf46

File tree

1 file changed

+170
-4
lines changed

1 file changed

+170
-4
lines changed

‎docs/overview.md

+170-4
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,34 @@ library](https://www.arduino.cc/reference/en/libraries/mkrwan/)
1212
library should usually work on the other too (but note below for some
1313
caveats).
1414

15+
In the Arduino IDE, the supported NUCLEO-WL55JC1 board can be configured
16+
in the Tools menu by selecting "Nucleo-64" under "Board", and then "Nucleo WL55JC" under
17+
"Board part number". You likely also want to enable "Core logs" under
18+
"Debug symbols and core logs" (see more below).
19+
20+
The main part of this documentation can be found in the STM32LoRaWAN
21+
class documentation.
22+
1523
## Supported features
24+
- Works with the NUCLEO-WL55JC1 board (other WL55-based boards are
25+
probably easy to support, but might need some changes).
26+
- LoRaWAN 1.0.3 with random nonces
27+
- OTAA and ABP joining (but framecounters are not saved for ABP)
28+
- Class A, with confirmed and unconfirmed uplink and downlink. Port and
29+
datarate can be set for uplinks.
30+
- Various radio parameters configurable.
31+
- Automatic Data Rate (ADR) and other Mac commands as specified by
32+
LoRaWAN.
1633

17-
## Library structure
34+
Not supported:
35+
- Storing data in non-volatile storage (e.g. framecounters for ABP, or
36+
nonce for LoRaWAN 1.0.4 incremental OTAA nonces).
37+
- Class B and C (the underlying stack has support for this, but this is
38+
not enabled or tested).
39+
- Hardware AES encryption.
40+
- Automatic sleeping (can be implemented in the sketch).
1841

42+
## Library structure
1943
The STM32LoRaWAN class is the main entrypoint for this library. Your
2044
sketch must create one instance of this class (in the examples named
2145
`modem`).
@@ -35,12 +59,154 @@ to send a reply packet. To see if any data was received, use the
3559
\ref reception "reception methods" and the actual data can be read using
3660
the \ref stream "Stream methods" (e.g. `available()` and `read()`).
3761

38-
## Errors and logging
39-
bool return values
40-
debug logging option in IDE
62+
## Core logging
63+
This library uses the STM32Duino `core_debug()` mechanism for logging to
64+
the default serial port. This mechanism is disabled by default, but can
65+
be enabled in the board options in the Arduino IDE (Tools -> Debug
66+
Symbols and core logs").
67+
68+
When enabled, the library prints informational messages and also error
69+
messages.
70+
71+
## Error handling
72+
Most methods that change or do something return a `bool` value that
73+
indicates whether the operation was successful. Typically, if the `false`
74+
is returned, the operation was not executed at all, though it might have
75+
been done partially.
76+
77+
Methods do not return more details about what went wrong exactly (i.e.
78+
no error codes), like the MKRWAN library. However, whenever a method
79+
returns false, there will also be an error message printed to the core
80+
log (e.g. serial when enabled, see above), so it is recommended to run
81+
with core logs enabled.
4182

4283
## Examples
84+
How to use this library is probably easiest learned from the examples.
85+
The library currently supplies these two examples:
86+
87+
- Basic.ino has a very basic sketch that shows setting up the library,
88+
joining the network (using OTAA or ABP) and transmitting packets
89+
periodically. It also shows how to read downlink packets. To use this
90+
sketch, configure device credentials in the `joinOTAA()` or
91+
`joinABP()` calls.
92+
93+
- LoraSendAndReceive is a similar sketch, but is a bit more
94+
interactive, so might be a good starting point. This sketch is taken
95+
(nearly) verbatim from the MKRWAN. Credentials are configured in the
96+
accompanying `arduino_secrets.h` file.
97+
98+
All examples default to the EU868 frequency plan, so if are in
99+
a different region, be sure to change the argument to
100+
STM32LoRaWAN::begin() accordingly.
43101

44102
## Differences with MKRWAN
103+
Where possible, the API offered by this library is identical to the
104+
MKRWAN library. In some cases, this library offers additional methods
105+
not present in MKRWAN.
106+
107+
One big difference is that all normal methods in this library are
108+
blocking (in MKRWAN, joining and confirmed uplinks are blocking, but
109+
unconfirmed uplinks return immediately). For more advanced cases,
110+
non-blocking/asynchronous methods are available as well. See below for
111+
details.
112+
113+
Additionally, some minor improvements were made to the API (more
114+
appropriate types, for example) that can hopefully be applied to the
115+
MKRWAN library as well.
116+
117+
All differences with the MKRWAN API have been clearly marked in the
118+
reference documentation, and a list can be found on the \ref extensions
119+
page.
120+
121+
### Blocking and asynchronous behavior
122+
There is big hardware difference between the MKRWAN and the STM32WL:
123+
with MKRWAN, the LoRaWAN stack runs in a completely different module
124+
that can independently run background tasks such as handling reception,
125+
only needing to communicate the results to the main microcontroller
126+
using a UART.
127+
128+
For this library, the LoRaWAN stack runs in the main microcontroller, so
129+
needs cooperation of the sketch to run these background tasks. The RTC
130+
(and its alarm interrupt handler) is used to handle timing critical
131+
things, but some tasks need to happen in the mainloop.
132+
133+
In practice, when using the normal (non-async) methods, this is all
134+
handled automatically - the normal methods simply block until the join
135+
or TX+RX is fully done, doing any work directly. When these methods
136+
return, the library is idle again and there is no need for mainloop work
137+
anymore.
138+
139+
However, when the sketch wants to do other work while waiting for
140+
airtime or for the RX windows, it can use the async functions instead.
141+
These functions start some operation and then immediately return while
142+
the library is still busy (has future work to do). While the library is
143+
busy (some pending task, mostly waiting for RX windows or waiting for TX
144+
airtime), the sketch must regularly allow the library to perform some
145+
work. This is done by calling the `maintain()` method, which checks to
146+
see if there is some work to be done and does it.
147+
148+
\note All timing-critical work (mostly starting RX at the right moment)
149+
is done inside the interrupt handler, it should not be problematic when
150+
`maintain()` is called a couple (probably even up to a hundred)
151+
milliseconds after new work has become available, but in general it is
152+
good to just call it often, especially during long processing (if there
153+
is no work, it will return quickly).
154+
155+
For even more advanced usecases, sketches can use
156+
STM32LoRaWAN::setMaintainNeededCallback() to register a callback that is
157+
called whenever there is some background work to be done. This can be
158+
used to remove the need to call `maintain()` all the time (just make
159+
sure that `maintain()` is called from the main loop after the callback
160+
was called) and can even be used to implement sleeping between bits of
161+
work (see below).
162+
163+
## Low power applications
164+
This library does not handle low-power and sleeping automatically, but
165+
has been designed to allow the sketch to implement this.
166+
167+
In particular:
168+
- Whenever the radio is not actively used, it is put into sleep mode,
169+
minimizing power usage from the radio module.
170+
171+
- When the library is idle (no operation in progress, `busy()`
172+
returning false) it requires no attention and should not generate any
173+
interrupts (until the sketch starts a new operation). The MCU can be
174+
put into a sleep mode at the sketch's discretion.
175+
176+
In this scenario, the RTC must ideally be kept running. It will not
177+
generate any interrupts, but will be used for timing duty cycle
178+
limits.
179+
180+
- When the library *is* running an operation, the microcontroller can
181+
also be put in sleep mode, provided that the RTC and radio modules
182+
are kept enabled and can wake up the MCU with their interrupts.
183+
184+
To prevent race conditions (where a work-generating interrupt is
185+
triggered between the last call to `maintain()` and actually
186+
sleeping), some care will be needed. For example using
187+
STM32LoRaWAN::setMaintainNeededCallback() to set a flag when there is
188+
pending work, and when it is time for sleeping disable interrupts,
189+
check the flag and only if it is unset, actually sleep. This way,
190+
when more work is triggered (e.g. by the RTC IRQ) just before
191+
sleeping, that IRQ will be postponed and cause the MCU to wake up
192+
immediately after sleeping and the work can be handled.
193+
194+
Note that sleeping has not actually been tested during development of
195+
this library, so if you run into problems (or successfully implement any
196+
of this), please open a Github issue.
197+
198+
## Used resources
199+
This library makes use of:
200+
201+
- The radio module, obviously. The library handles enabling the module
202+
and the associated SPI block, so nothing is needed in the sketch.
45203

204+
- The RTC for timing. This library currently completely configures the
205+
RTC and defines the interrupt handler, making it impossible to use
206+
the RTC for anything else. In the future, this library could be
207+
modified to co-exist with e.g. the STM32RTC library or use
208+
a (low-power) timer instead of the RTC, but this is not possible
209+
right now.
46210

211+
- A number of GPIO pins that are connected to external RF circuitry on
212+
the board. This just uses the Arduino `digitalWrite()` functions.

0 commit comments

Comments
 (0)