#include <STM32LoRaWAN.h>

Public Member Functions

bool continuousWave (uint32_t frequency, int8_t powerdBm, uint16_t timeout)

Initialization

bool begin (_lora_band band)

OTAA Join

This method can be used to join the network using the OTAA (over-the-air-activation) method, where the device uses the credentials specified here to negotiate a session (including session address and encryption keys) with the network by exchanging messages.

The appEUI and appKey are mandatory, the devEUI can be omitted, in which case the devEUI baked into the chip is used.

For both EUIs and the key, you can pass a hex-encoded (MSB-first) string (String object or const char*), for the EUIs also a raw integer (64-bits).

These methods will perform multiple join attempts and block until the join completes successfully, or a timeout (60 seconds) occurs.

There are some subtle differences with MKRWAN in how the join process works:

MKRWAN returns directly after the timeout, while this library finishes the running join attempt before joinOTAA returns.
With MKRWAN the module continues doing join attempts in the background, while this library stops attempting them after joinOTAA returns.
With MKRWAN the module automatically decreases/alternates the datarate in a region-specific way for all regions, this library uses the configured datarate (with datarate()) for most regions, but uses fixed datarates (according to LoRaWAN regional parameters) for US915/AU915/AS923.

MKRWAN API difference:

Timeout parameter omitted (also omitted in MKRWAN_v2)

Added version that accepts uint64_t appEUI

Differences in timeout and retry datarate handling

bool joinOTAA (const char *appEui, const char *appKey, const char *devEui)

bool joinOTAA (const char *appEui, const char *appKey)

bool joinOTAA (String appEui, String appKey)

bool joinOTAA (String appEui, String appKey, String devEui)

bool joinOTAA (uint64_t appEui, const char *appKey, uint64_t devEui)

bool joinOTAA (uint64_t appEui, const char *appKey)

bool joinOTAA (uint64_t appEui, String appKey, uint64_t devEui)

bool joinOTAA (uint64_t appEui, String appKey)

bool joinOTAA ()

ABP Join

This method can be used to join the network using the ABP method, where the session address and keys are preconfigured and no exchange with the network is needed before data can be sent.

For the address and both keys, you can pass a hex-encoded (MSB-first) string (String object or const char*), for the address also a raw integer (32-bits).

Warning: This library does not preserve frame counters in non-volatile storage, so it starts at zero after every reset. This only works when the server disables framecounter-based replay attacks, otherwise only the first session will work and data will be dropped after the first reset.

Note: An ABP join returns immediately, it does not need to wait for the network, so there is no separate non-blocking/async version of this method.

bool joinABP (const char *devAddr, const char *nwkSKey, const char *appSKey)

bool joinABP (String devAddr, String nwkSKey, String appSKey)

bool joinABP (uint32_t devAddr, String nwkSKey, String appSKey)

bool joinABP ()

Packet sending

These methods allow sending a data packet.

After a join was completed, sending a packet consists of calling beginPacket(), writing data to using the Stream write methods, and calling endPacket() to finish up and send the packet.

The port number to use for the packet can be set using setPort() (to be called before endPacket()). A confirmed packet can be sent using the parameter to endPacket(), which will request the network to confirm the packet was received (but if not, no automatic retries are done).

The send() method offers an alternative (and always non-blocking) API, where you pass a payload already built into your own buffer.

void beginPacket ()

int endPacket (bool confirmed=false)

Stream/Print writing

These are standard methods defined by the Arduino Stream (or actually its Print superclass) class to allow writing data into a packet being built.

In addition to the methods listed here, all methods offered by the Arduino Print class are also available (but at the time of writing, unfortunately not documented by Arduino).

There is one addition, there is a templated write method that accepts any type of object (e.g. a struct, integer, etc.) and writes its memory representation into the packet. When using this, note that data will be written exactly as the processor stores it in memory, so typically little-endian.

virtual size_t write (uint8_t c)

virtual size_t write (const uint8_t *buffer, size_t size)

template<typename T >

size_t write (T val)

virtual int availableForWrite ()

virtual void flush ()

Packet reception

These methods are about reception of downlink packets.

After an uplink packet was fully sent, a received downlink packet can be checked by calling parsePacket() (or simply available() to see if any bytes are ready to read). If so, the contents of the packet can be read using the Stream read methods.

int parsePacket ()

uint8_t getDownlinkPort ()

Stream reading

These are standard methods defined by the Arduino Stream class to allow reading received data.

In addition to the methods listed here, all methods offered by the Arduino Stream class are also available, see https://www.arduino.cc/reference/en/language/functions/communication/stream/

After a packet is received, the available() method can be used to query how much bytes are in the packet (or after some bytes were read, how many are left to be read), and various read() versions can be used to read the data.

Note: If data is left unread when a new packet is received, the new data will be appended to the unread data and it becomes impossible to query where the first packet ends and the second begins. It is recommended to always fully read any received data before transmitting a new packet (which is, in class A LoRaWAN, the only time a new packet can be received).

int read (uint8_t *buf, size_t size)

virtual int available ()

virtual int read ()

virtual int peek ()

Setters for identifiers and keys

These methods allow setting various identifiers and keys.

You can pass a hex-encoded (MSB-first) string (String object or const char*), or a raw integer (32-bits for DevAddr and 64-bits for EUIs, keys are too long to be passed as an integer).

MKRWAN API difference:: Not supported by MKRWAN

bool setDevEui (const char *value)

bool setDevEui (String value)

bool setDevEui (uint64_t value)

bool setAppEui (const char *value)

bool setAppEui (String value)

bool setAppEui (uint64_t value)

bool setDevAddr (const char *value)

bool setDevAddr (String value)

bool setDevAddr (uint32_t value)

bool setAppKey (const char *value)

bool setAppKey (String value)

bool setNwkKey (const char *value)

bool setNwkKey (String value)

bool setAppSKey (const char *value)

bool setAppSKey (String value)

bool setNwkSKey (const char *value)

bool setNwkSKey (String value)

Getters for identifiers

These methods allow getting various identifiers.

The value is written into the pointer passed, which can be a String object to get a hex-encoded (MSB-first) string, or a raw integer (32-bits for DevAddr and 64-bits for EUIs).

Note that encryption keys cannot be retrieved.

bool getDevEui (String *value)

bool getDevEui (uint64_t *value)

bool getAppEui (String *value)

bool getAppEui (uint64_t *value)

bool getDevAddr (String *value)

bool getDevAddr (uint32_t *value)

Querying current state

String deviceEUI ()

String getDevAddr ()

bool connected ()

bool busy ()

operator bool ()

Radio / transmission configuration

These methods allow configuring various radio and transmission parameters.

bool dataRate (uint8_t dr)

int getDataRate ()

bool power (uint8_t index)

bool power (_rf_mode mode, uint8_t index)

bool powerdB (int8_t db)

uint8_t getPort ()

bool setPort (uint8_t port)

bool setADR (bool adr)

int getADR ()

Advanced configuration

These methods allow configuring advanced settings, which are usually not required for normal operation.

bool dutyCycle (bool on)

bool publicNetwork (bool publicNetwork)

int getRX2DR ()

bool setRX2DR (uint8_t dr)

uint32_t getRX2Freq ()

bool setRX2Freq (uint32_t freq)

int getrxfreq ()

Channel manipulation

These methods allow manipulating the list of enabled channels.

The number of channels that are actually available and defined and their frequency and other settings are region-dependent. The fixed frequency regions (US915 and AU915) have 96 fixed channels, while the other regions have just a couple (up to 16) of channels defined.

Note: The list of channels will be reset when starting an OTAA join an when the join completes. Also, the network can send commands to modify the channel plan (define new channels or replace them, and enable/disable them), also as part of ADR messages.

bool enableChannel (unsigned pos)

bool disableChannel (unsigned pos)

bool modifyChannelEnabled (unsigned pos, bool value)

bool isChannelEnabled (unsigned pos)

Frame counters

These methods allow access to the up and down frame counters.

Note: Currently setting the framecounters is not supported, since the underlying LoRaWAN library has no obvious way to set these. This might be implemented in the future with some extra work.

int32_t getFCU ()

int32_t getFCD ()

bool setFCD (uint16_t fcd)

bool setFCU (uint16_t fcu)

Advanced MIB access

These methods allow direct access to the MIB (Mac Information Base) layer of the underlying stack to set and query values. These are only intended for advanced usage, when the regular API does not provide sufficient access.

Parameters

name	Parameter name, only used in error messages

bool mibGet (const char *name, Mib_t type, MibRequestConfirm_t &mibReq)

bool mibGetBool (const char *name, Mib_t type, bool *value)

bool mibGetUint8 (const char *name, Mib_t type, uint8_t *value)

bool mibGetInt8 (const char *name, Mib_t type, int8_t *value)

bool mibGetUint32 (const char *name, Mib_t type, uint32_t *value)

bool mibGetUint64 (const char *name, Mib_t type, uint64_t *value)

bool mibGetHex (const char *name, Mib_t type, String *value)

bool mibGetRxChannelParams (const char *name, Mib_t type, RxChannelParams_t *value)

bool mibGetPtr (const char *name, Mib_t type, void **value)

bool mibSet (const char *name, Mib_t type, MibRequestConfirm_t &mibReq)

bool mibSetBool (const char *name, Mib_t type, bool value)

bool mibSetUint8 (const char *name, Mib_t type, uint8_t value)

bool mibSetInt8 (const char *name, Mib_t type, int8_t value)

bool mibSetUint32 (const char *name, Mib_t type, uint32_t value)

bool mibSetUint64 (const char *name, Mib_t type, uint64_t value)

bool mibSetHex (const char *name, Mib_t type, const char *value)

bool mibSetRxChannelParams (const char *name, Mib_t type, RxChannelParams_t value)

bool mibSetPtr (const char *name, Mib_t type, void *value)

size_t mibHexSize (const char *name, Mib_t type)

Non-blocking (async) methods

These are variants of other methods that are asynchronous, i.e. these start an operation and then return immediately without waiting (blocking) for the operation to complete.

After calling these methods, the sketch must periodically call the maintain() method to allow any background work to be performed. This must be done at least until busy() returns false. You can use maintainUntilIdle() for this if you no longer have other things to do while waiting.

bool joinOTAAAsync ()

int endPacketAsync (bool confirmed=false)

bool send (const uint8_t *payload, size_t size, bool confirmed)

uint8_t lastAck ()

void maintain ()

void maintainUntilIdle ()

void setMaintainNeededCallback (std::function< void(void)> callback)

void setBatteryLevelCallback (std::function< uint8_t(void)> callback)

Dummy implementations

These methods have only dummy implementations, because no meaningful implementations exist and having a dummy implementation is harmless (and also helps to make some examples work without modification).

String version ()

void minPollInterval (unsigned long)

Missing methods

These methods are present in MKRWAN, but are not implemented in this library (because they are specific to the module-based serial approach used by MKRWAN, are for testing purposes only or have better API not tied to the MKRWAN AT commands available.

These methods are declared in this library, but marked so the compiler can generate a friendly error message when they are used.

bool setCFM (bool cfm)

int getCFM ()

int getCFS ()

bool begin (_lora_band band, uint32_t baud, uint16_t config=SERIAL_8N2)

bool autoBaud (unsigned long timeout=10000L)

void setBaud (unsigned long baud)

String getTConf ()

String setTConf (String params)

bool enTtone ()

bool restart ()

void poll ()

bool sleep (bool on=true)

bool factoryDefault ()

bool format (bool hexMode)

void dumb ()

bool init ()

bool configureClass (_lora_class _class)

String getNwkSKey ()

String getAppSKey ()

String applicationKey ()

bool sendMask (String newMask)

bool sendMask ()

String getChannelMask ()

int getChannelMaskSize (_lora_band band)

bool configureBand (_lora_band band)

Protected Member Functions
uint64_t	builtinDevEUI ()

static bool void	clear_rx ()

void	add_rx (const uint8_t *buf, size_t len)

Static Protected Member Functions
static void	MacMcpsConfirm (McpsConfirm_t *McpsConfirm)

static void	MacMcpsIndication (McpsIndication_t McpsIndication, LoRaMacRxStatus_t RxStatus)

static void	MacMlmeConfirm (MlmeConfirm_t *MlmeConfirm)

static void	MacMlmeIndication (MlmeIndication_t MlmeIndication, LoRaMacRxStatus_t RxStatus)

static void	MacProcessNotify ()

static uint8_t	GetBatteryLevel ()

static const char *	toString (LoRaMacStatus_t)

static const char *	toString (LoRaMacEventInfoStatus_t)

static const char *	toString (Mlme_t)

static const char *	toString (Mcps_t)

static uint8_t	parseHex (char c)

static bool	parseHex (uint8_t dest, const char hex, size_t dest_len)

static char	toHex (uint8_t b)

static bool	toHex (String dest, const uint8_t src, size_t src_len)

static uint32_t	makeUint32 (uint8_t a, uint8_t b, uint8_t c, uint8_t d)

static bool	failure (const char *fmt,...) __attribute__((format(printf

Protected Attributes
LoRaMacPrimitives_t	LoRaMacPrimitives

LoRaMacCallback_t	LoRaMacCallbacks

uint8_t	tx_dr = DR_4

uint8_t	tx_port = 2

uint8_t	rx_port = 0

bool	nwk_key_set = false

uint8_t	tx_buf [255]

uint8_t *	tx_ptr

uint8_t	rx_buf [255]

uint8_t *	rx_ptr

bool	last_tx_acked = false

uint32_t	fcnt_up = 0

uint32_t	fcnt_down = 0

std::function< void(void)>	maintain_needed_callback

std::function< uint8_t(void)>	battery_level_callback

bool	mac_process_pending = false

Static Protected Attributes
static STM32LoRaWAN *	instance

static constexpr uint32_t	DEFAULT_JOIN_TIMEOUT = 60000

Member Function Documentation

◆ add_rx()

void STM32LoRaWAN::add_rx	(	const uint8_t *	buf,
		size_t	len
	)

protected

Add data to the rx buffer

◆ applicationKey()

String STM32LoRaWAN::applicationKey ( )

MKRWAN API difference:: Not implemented by this library: Keys cannot be retrieved

◆ autoBaud()

bool STM32LoRaWAN::autoBaud ( unsigned long timeout = 10000L )

MKRWAN API difference:: Not implemented by this library: no serial link to configure

◆ available()

int STM32LoRaWAN::available ( )

virtual

◆ availableForWrite()

int STM32LoRaWAN::availableForWrite ( )

virtual

Returns how many bytes can still be written into the current packet.

This takes the maximum payload size at the current datarate into account. When this is called directly after beginPacket(), it returns the maximum payload size.

You can usually write more than this amount, but then sending the packet with endPacket() will likely fail.

◆ begin() [1/2]

bool STM32LoRaWAN::begin ( _lora_band band )

Initialize the library. Must be called before any other methods.

Parameters

band	The region/band to use. See _lora_band for allowed values.

Note: The selected band must be within the frequency range of the board design, this cannot be automatically checked by the software.

◆ begin() [2/2]

bool STM32LoRaWAN::begin	(	_lora_band	band,
		uint32_t	baud,
		uint16_t	config = `SERIAL_8N2`
	)

MKRWAN API difference:: Not implemented by this library: no serial link to configure

◆ beginPacket()

void STM32LoRaWAN::beginPacket ( )

◆ builtinDevEUI()

uint64_t STM32LoRaWAN::builtinDevEUI ( )

protected

Generate the builtin DevEUI for this board

◆ busy()

bool STM32LoRaWAN::busy ( )

Returns whether the modem is currently busy processing a request. After a non-blocking request (e.g. unconfirmed uplink), this returns true until the request is completed and then returns false until some new request is made.

MKRWAN API difference:: Not supported by MKRWAN

◆ clear_rx()

static bool void STM32LoRaWAN::clear_rx ( )

inlineprotected

Empty the rx buffer

◆ configureBand()

bool STM32LoRaWAN::configureBand ( _lora_band band )

This could be supported, but needs careful consideration and complete re-initialization.

MKRWAN API difference:: Not implemented by this library: Changing band after initialization not supported

◆ configureClass()

bool STM32LoRaWAN::configureClass ( _lora_class _class )

MKRWAN API difference:: Not implemented by this library: only class A supported

◆ connected()

bool STM32LoRaWAN::connected ( )

Returns whether connected to the network (i.e. for OTAA a successful join exchange has happened, or for ABP session information has been supplied by calling joinABP).

◆ continuousWave()

bool STM32LoRaWAN::continuousWave	(	uint32_t	frequency,
		int8_t	powerdBm,
		uint16_t	timeout
	)

Set the radio into continuous wave (CW) mode. In this mode radio outputs a signal at the specified frequency and power for the specified duration.

Used only for compliance testing and antenna testing.

Parameters

frequency	Frequency in Hz.
powerdBm	transmit power in dBm.
timeout	Duration in seconds.

Returns: true if CW mode was activated successfully.

◆ dataRate()

bool STM32LoRaWAN::dataRate ( uint8_t dr )

Set the datarate to use for future packets. If ADR is enabled, that might change the datarate again (but the rate passed should be used for at least one uplink packet).

◆ deviceEUI()

String STM32LoRaWAN::deviceEUI ( )

Return the currently configured deviceEUI. On startup, this is the EUI for the chip (stored in ROM). If changed (i.e. with joinOTAA() or setDevEUI()), the changed value is returned instead.

◆ disableChannel()

bool STM32LoRaWAN::disableChannel ( unsigned pos )

◆ dumb()

void STM32LoRaWAN::dumb ( )

MKRWAN API difference:: Not implemented by this library: no protocol stream to configure

◆ dutyCycle()

bool STM32LoRaWAN::dutyCycle ( bool on )

When false is passed, duty cycle limits are no longer checked.

Warning: Use with care, disabling duty cycle limits can cause violations of laws and regulations around use of the RF spectrum!

◆ enableChannel()

bool STM32LoRaWAN::enableChannel ( unsigned pos )

◆ endPacket()

int STM32LoRaWAN::endPacket ( bool confirmed = false )

Finalize and send a packet previously prepared using beginPacket() and write().

This blocks until the packet is completely sent an both RX windows have been completed.

Returns: The number of bytes sent when successful, or -1 when the packet could not be sent. For confirmed packets, also returns -1 when no confirmation was received (in that case the packet might still have been sent correctly).

MKRWAN API difference:: This library blocks for all packets, not just confirmed packets.

◆ endPacketAsync()

int STM32LoRaWAN::endPacketAsync ( bool confirmed = false )

Finalize and asynchronously send a packet. This can be used in place of endPacket() when you do not want blocking behavior.

The return value only reflects whether the packet could successfully queued, to see if a confirmed packet was actually confirmed by the network, call lastAck().

MKRWAN API difference:: Not supported by MKRWAN

◆ enTtone()

bool STM32LoRaWAN::enTtone ( )

MKRWAN API difference:: Not implemented by this library: test method only

◆ factoryDefault()

bool STM32LoRaWAN::factoryDefault ( )

MKRWAN API difference:: Not implemented by this library: no remote module to reset

◆ failure()

bool STM32LoRaWAN::failure	(	const char *	fmt,
			...
	)

staticprotected

Helper that prints an error and then always returns false, to allow for combining reporting and returning in a single line.

◆ flush()

virtual void STM32LoRaWAN::flush ( )

inlinevirtual

This is a no-op, to send written data, use endPacket().

MKRWAN API difference:: Dummy implementation in this library

◆ format()

bool STM32LoRaWAN::format ( bool hexMode )

MKRWAN API difference:: Not implemented by this library: no protocol stream to configure

◆ getADR()

int STM32LoRaWAN::getADR ( )

Return whether ADR (automatic datarate) is enabled.

◆ getAppEui() [1/2]

bool STM32LoRaWAN::getAppEui ( String * value )

inline

◆ getAppEui() [2/2]

bool STM32LoRaWAN::getAppEui ( uint64_t * value )

inline

◆ getAppSKey()

String STM32LoRaWAN::getAppSKey ( )

MKRWAN API difference:: Not implemented by this library: Keys cannot be retrieved

◆ GetBatteryLevel()

uint8_t STM32LoRaWAN::GetBatteryLevel ( )

staticprotected

◆ getCFM()

int STM32LoRaWAN::getCFM ( )

MKRWAN API difference:: Not implemented by this library: confirmed uplinked better handled through endPacket()

◆ getCFS()

int STM32LoRaWAN::getCFS ( )

MKRWAN API difference:: Not implemented by this library: confirmed uplinked better handled through endPacket()

◆ getChannelMask()

String STM32LoRaWAN::getChannelMask ( )

MKRWAN API difference:: Not implemented by this library: seems to be an internal method in MKRWAN (use enableChannel/disableChannel instead)

◆ getChannelMaskSize()

int STM32LoRaWAN::getChannelMaskSize ( _lora_band band )

MKRWAN API difference:: Not implemented by this library: seems to be an internal method in MKRWAN (use enableChannel/disableChannel instead)

◆ getDataRate()

int STM32LoRaWAN::getDataRate ( )

Retrieve the current datarate (possibly modified by ADR)

◆ getDevAddr() [1/3]

String STM32LoRaWAN::getDevAddr ( )

◆ getDevAddr() [2/3]

bool STM32LoRaWAN::getDevAddr ( String * value )

inline

◆ getDevAddr() [3/3]

bool STM32LoRaWAN::getDevAddr ( uint32_t * value )

inline

◆ getDevEui() [1/2]

bool STM32LoRaWAN::getDevEui ( String * value )

inline

◆ getDevEui() [2/2]

bool STM32LoRaWAN::getDevEui ( uint64_t * value )

inline

◆ getDownlinkPort()

uint8_t STM32LoRaWAN::getDownlinkPort ( )

inline

Returns the port number of the most recently received packet.

◆ getFCD()

int32_t STM32LoRaWAN::getFCD ( )

Return the frame counter of the most recent downlink message that was received.

◆ getFCU()

int32_t STM32LoRaWAN::getFCU ( )

Return the frame counter of the most recent uplink message that was completely transmitted (i.e. after the RX windows have passed).

◆ getNwkSKey()

String STM32LoRaWAN::getNwkSKey ( )

MKRWAN API difference:: Not implemented by this library: Keys cannot be retrieved

◆ getPort()

uint8_t STM32LoRaWAN::getPort ( )

Return the port used for data transmission.

MKRWAN API difference:: Not supported by MKRWAN

◆ getRX2DR()

int STM32LoRaWAN::getRX2DR ( )

Return the datarate used for the RX2 window.

◆ getRX2Freq()

uint32_t STM32LoRaWAN::getRX2Freq ( )

Return the frequency used for the RX2 window.

◆ getrxfreq()

int STM32LoRaWAN::getrxfreq ( )

Alias of getRX2Freq() for MKRWAN_v2 compatibility

◆ getTConf()

String STM32LoRaWAN::getTConf ( )

MKRWAN API difference:: Not implemented by this library: test method

◆ init()

bool STM32LoRaWAN::init ( )

MKRWAN API difference:: Not implemented by this library: seems to be an internal method in MKRWAN

◆ isChannelEnabled()

bool STM32LoRaWAN::isChannelEnabled ( unsigned pos )

◆ joinABP() [1/4]

bool STM32LoRaWAN::joinABP ( )

Perform a join with parameters previously set using after using setDevAddr(), setNwkSKey() and setAppSKey().

MKRWAN API difference:: Not supported by MKRWAN

◆ joinABP() [2/4]

bool STM32LoRaWAN::joinABP	(	const char *	devAddr,
		const char *	nwkSKey,
		const char *	appSKey
	)

inline

◆ joinABP() [3/4]

bool STM32LoRaWAN::joinABP	(	String	devAddr,
		String	nwkSKey,
		String	appSKey
	)

inline

◆ joinABP() [4/4]

bool STM32LoRaWAN::joinABP	(	uint32_t	devAddr,
		String	nwkSKey,
		String	appSKey
	)

inline

◆ joinOTAA() [1/9]

bool STM32LoRaWAN::joinOTAA ( )

Perform a join with parameters previously set using after using setAppEui(), setAppKey() and optionally setDevEui().

MKRWAN API difference:: Not supported by MKRWAN

◆ joinOTAA() [2/9]

bool STM32LoRaWAN::joinOTAA	(	const char *	appEui,
		const char *	appKey
	)

inline

◆ joinOTAA() [3/9]

bool STM32LoRaWAN::joinOTAA	(	const char *	appEui,
		const char *	appKey,
		const char *	devEui
	)

inline

◆ joinOTAA() [4/9]

bool STM32LoRaWAN::joinOTAA	(	String	appEui,
		String	appKey
	)

inline

◆ joinOTAA() [5/9]

bool STM32LoRaWAN::joinOTAA	(	String	appEui,
		String	appKey,
		String	devEui
	)

inline

◆ joinOTAA() [6/9]

bool STM32LoRaWAN::joinOTAA	(	uint64_t	appEui,
		const char *	appKey
	)

inline

MKRWAN API difference:: Not supported by MKRWAN

◆ joinOTAA() [7/9]

bool STM32LoRaWAN::joinOTAA	(	uint64_t	appEui,
		const char *	appKey,
		uint64_t	devEui
	)

inline

MKRWAN API difference:: Not supported by MKRWAN

◆ joinOTAA() [8/9]

bool STM32LoRaWAN::joinOTAA	(	uint64_t	appEui,
		String	appKey
	)

inline

MKRWAN API difference:: Not supported by MKRWAN

◆ joinOTAA() [9/9]

bool STM32LoRaWAN::joinOTAA	(	uint64_t	appEui,
		String	appKey,
		uint64_t	devEui
	)

inline

MKRWAN API difference:: Not supported by MKRWAN

◆ joinOTAAAsync()

bool STM32LoRaWAN::joinOTAAAsync ( )

Do an asynchronous OTAA join using previously configured AppEui, AppKey and optionally DevEui. This can be used in place of joinOTAA() when you do not want blocking behavior.

This initiates a single join attempt (one JoinReq message). After both receive windows are complete, busy() will become false and the sketch can call connected() to see if the join attempt was successful. If not, it is up to the sketch to decide on retries.

MKRWAN API difference:: Not supported by MKRWAN

◆ lastAck()

uint8_t STM32LoRaWAN::lastAck ( )

inline

Returns true when the most recently transmitted packet has received a confirmation from the network (if requested). Directly after transmitting any packet, this will return false and it will become true when the ack is received (which is, at the latest, when busy() becomes false again).

MKRWAN API difference:: Not supported by MKRWAN

◆ MacMcpsConfirm()

void STM32LoRaWAN::MacMcpsConfirm ( McpsConfirm_t * McpsConfirm )

staticprotected

◆ MacMcpsIndication()

void STM32LoRaWAN::MacMcpsIndication	(	McpsIndication_t *	McpsIndication,
		LoRaMacRxStatus_t *	RxStatus
	)

staticprotected

◆ MacMlmeConfirm()

void STM32LoRaWAN::MacMlmeConfirm ( MlmeConfirm_t * MlmeConfirm )

staticprotected

◆ MacMlmeIndication()

void STM32LoRaWAN::MacMlmeIndication	(	MlmeIndication_t *	MlmeIndication,
		LoRaMacRxStatus_t *	RxStatus
	)

staticprotected

◆ MacProcessNotify()

void STM32LoRaWAN::MacProcessNotify ( )

staticprotected

◆ maintain()

void STM32LoRaWAN::maintain ( )

Perform any pending work, or quickly return if there is none.

While the stack is busy, this method should be called very frequently to ensure accurate timing. It is automatically called by all blocking methods in this library.

◆ maintainUntilIdle()

void STM32LoRaWAN::maintainUntilIdle ( )

Call maintain() to process any background work for as long as the stack is busy (i.e. until busy() returns false).

MKRWAN API difference:: Not supported by MKRWAN

◆ makeUint32()

static uint32_t STM32LoRaWAN::makeUint32	(	uint8_t	a,
		uint8_t	b,
		uint8_t	c,
		uint8_t	d
	)

inlinestaticprotected

Build a uint32_t from four bytes (big-endian, a is MSB)

◆ mibGet()

bool STM32LoRaWAN::mibGet	(	const char *	name,
		Mib_t	type,
		MibRequestConfirm_t &	mibReq
	)

◆ mibGetBool()

bool STM32LoRaWAN::mibGetBool	(	const char *	name,
		Mib_t	type,
		bool *	value
	)

◆ mibGetHex()

bool STM32LoRaWAN::mibGetHex	(	const char *	name,
		Mib_t	type,
		String *	value
	)

◆ mibGetInt8()

bool STM32LoRaWAN::mibGetInt8	(	const char *	name,
		Mib_t	type,
		int8_t *	value
	)

◆ mibGetPtr()

bool STM32LoRaWAN::mibGetPtr	(	const char *	name,
		Mib_t	type,
		void **	value
	)

◆ mibGetRxChannelParams()

bool STM32LoRaWAN::mibGetRxChannelParams	(	const char *	name,
		Mib_t	type,
		RxChannelParams_t *	value
	)

◆ mibGetUint32()

bool STM32LoRaWAN::mibGetUint32	(	const char *	name,
		Mib_t	type,
		uint32_t *	value
	)

◆ mibGetUint64()

bool STM32LoRaWAN::mibGetUint64	(	const char *	name,
		Mib_t	type,
		uint64_t *	value
	)

◆ mibGetUint8()

bool STM32LoRaWAN::mibGetUint8	(	const char *	name,
		Mib_t	type,
		uint8_t *	value
	)

◆ mibHexSize()

size_t STM32LoRaWAN::mibHexSize	(	const char *	name,
		Mib_t	type
	)

◆ mibSet()

bool STM32LoRaWAN::mibSet	(	const char *	name,
		Mib_t	type,
		MibRequestConfirm_t &	mibReq
	)

◆ mibSetBool()

bool STM32LoRaWAN::mibSetBool	(	const char *	name,
		Mib_t	type,
		bool	value
	)

◆ mibSetHex()

bool STM32LoRaWAN::mibSetHex	(	const char *	name,
		Mib_t	type,
		const char *	value
	)

◆ mibSetInt8()

bool STM32LoRaWAN::mibSetInt8	(	const char *	name,
		Mib_t	type,
		int8_t	value
	)

◆ mibSetPtr()

bool STM32LoRaWAN::mibSetPtr	(	const char *	name,
		Mib_t	type,
		void *	value
	)

◆ mibSetRxChannelParams()

bool STM32LoRaWAN::mibSetRxChannelParams	(	const char *	name,
		Mib_t	type,
		RxChannelParams_t	value
	)

◆ mibSetUint32()

bool STM32LoRaWAN::mibSetUint32	(	const char *	name,
		Mib_t	type,
		uint32_t	value
	)

◆ mibSetUint64()

bool STM32LoRaWAN::mibSetUint64	(	const char *	name,
		Mib_t	type,
		uint64_t	value
	)

◆ mibSetUint8()

bool STM32LoRaWAN::mibSetUint8	(	const char *	name,
		Mib_t	type,
		uint8_t	value
	)

◆ minPollInterval()

void STM32LoRaWAN::minPollInterval ( unsigned long )

inline

Dummy for MKRWAN compatibility. Exact purpose on MKRWAN is unclear, see https://github.com/arduino-libraries/MKRWAN/issues/25

MKRWAN API difference:: Dummy implementation in this library

◆ modifyChannelEnabled()

bool STM32LoRaWAN::modifyChannelEnabled	(	unsigned	pos,
		bool	value
	)

MKRWAN API difference:: Not supported by MKRWAN

◆ operator bool()

STM32LoRaWAN::operator bool ( )

inline

Converts this object into a bool (e.g. for using in an if directly), returning the same value as connected().

◆ parseHex() [1/2]

uint8_t STM32LoRaWAN::parseHex ( char c )

staticprotected

Convert a single hex char into its numerical value

◆ parseHex() [2/2]

bool STM32LoRaWAN::parseHex	(	uint8_t *	dest,
		const char *	hex,
		size_t	dest_len
	)

staticprotected

Convert a hex string into a binary buffer

◆ parsePacket()

int STM32LoRaWAN::parsePacket ( )

Alias of available(), returns the number of bytes available to read.

Note: The MKRWAN documentation suggests this method must be called before calling read, but the code gives no indication that this is at all required.

◆ peek()

int STM32LoRaWAN::peek ( )

virtual

◆ poll()

void STM32LoRaWAN::poll ( )

MKRWAN API difference:: Not implemented by this library: no remote module to poll

◆ power() [1/2]

bool STM32LoRaWAN::power	(	_rf_mode	mode,
		uint8_t	index
	)

inline

Set the transmit power (MKRWAN version)

See also: power(uint8_t) for details.

Parameters

mode	This parameter is ignored, the mode is automatically determined based on the selected power.
index	See power(uint8_t) for details.

◆ power() [2/2]

bool STM32LoRaWAN::power ( uint8_t index )

Set the transmit power (MKRWAN_v2 version)

Parameters

index This sets the power index which is passed to the underlying stack directly. Unexpectedly, a value of 0 indicates the maximum power, and higher values decrease the value in steps of 2dB (so 0 = max, 1 = -2dB, 2 = -4dB, etc.).

The available options depend on the region (see the TX_POWER constants in LoRaMacInterfaces.h), but indices 0-5 should be supported by all regions (but most regions support additional values).

If an unavailable option is passed, this method will fail and return false.

◆ powerdB()

bool STM32LoRaWAN::powerdB ( int8_t db )

Set transmit power in dB.

Parameters

db	The transmit power in dB. It must be 0 or negative, where 0 is the maximum power and negative values indicate how much dB below the maximum to operate.

Note that only even values are supported, but an uneven value will be rounded down automatically.

The available options depend on the region (see the TX_POWER constants in LoRaMacInterfaces.h), but down to -10 dB should be supported by all regions (but most regions support additional values, down to -28 dB for some regions).

MKRWAN API difference:: Not supported by MKRWAN

◆ publicNetwork()

bool STM32LoRaWAN::publicNetwork ( bool publicNetwork )

Configure the syncword to use. The default is the "public" (LoRaWAN standard) syncword, when set to false this uses another syncword that is often recommended for "private" networks.

◆ read() [1/2]

int STM32LoRaWAN::read ( )

virtual

◆ read() [2/2]

int STM32LoRaWAN::read	(	uint8_t *	buf,
		size_t	size
	)

◆ restart()

bool STM32LoRaWAN::restart ( )

MKRWAN API difference:: Not implemented by this library: no remote module to restart

◆ send()

bool STM32LoRaWAN::send	(	const uint8_t *	payload,
		size_t	size,
		bool	confirmed
	)

Send a packet asynchronously by passing a buffer. This can be used instead of beginPacket() / write() / endPacket(), when you prefer building the data to send in an external buffer and do not want to skip one buffer copy.

The return value only reflects whether the packet could successfully queued, to see if a confirmed packet was actually confirmed by the network, call lastAck().

MKRWAN API difference:: Not supported by MKRWAN

◆ sendMask() [1/2]

bool STM32LoRaWAN::sendMask ( )

MKRWAN API difference:: Not implemented by this library: seems to be an internal method in MKRWAN (use enableChannel/disableChannel instead)

◆ sendMask() [2/2]

bool STM32LoRaWAN::sendMask ( String newMask )

MKRWAN API difference:: Not implemented by this library: seems to be an internal method in MKRWAN (use enableChannel/disableChannel instead)

◆ setADR()

bool STM32LoRaWAN::setADR ( bool adr )

Enable or disable ADR (automatic datarate).

This is enabled by default and allows the network to increase the datarate used (when sending downlink commands) when transmissions from this device are received with sufficient quality that a higher datarate is expected to still be received. In addition, it causes the device to request periodic confirmations and lets it reduce the datarate when transmissions are left unconfirmed.

Together, these two mechanisms should ensure the highest possible datarate is used, maximizing bandwidth and/or reducing spectrum usage (time on air).

◆ setAppEui() [1/3]

bool STM32LoRaWAN::setAppEui ( const char * value )

inline

◆ setAppEui() [2/3]

bool STM32LoRaWAN::setAppEui ( String value )

inline

◆ setAppEui() [3/3]

bool STM32LoRaWAN::setAppEui ( uint64_t value )

inline

◆ setAppKey() [1/2]

bool STM32LoRaWAN::setAppKey ( const char * value )

inline

◆ setAppKey() [2/2]

bool STM32LoRaWAN::setAppKey ( String value )

inline

◆ setAppSKey() [1/2]

bool STM32LoRaWAN::setAppSKey ( const char * value )

inline

◆ setAppSKey() [2/2]

bool STM32LoRaWAN::setAppSKey ( String value )

inline

◆ setBatteryLevelCallback()

void STM32LoRaWAN::setBatteryLevelCallback ( std::function< uint8_t(void)> callback )

inline

Registers a callback that is called whenever there is a DevStatusReq.

BAT_LEVEL_EXT_SRC - The end-device is connected to an external power source BAT_LEVEL_EMPTY - The battery is empty 1..254 - The battery level, 1 being at minimum and 254 being at maximum BAT_LEVEL_FULL - The battery is full BAT_LEVEL_NO_MEASURE - The end-device was not able to measure the battery level

MKRWAN API difference:: Not supported by MKRWAN

◆ setBaud()

void STM32LoRaWAN::setBaud ( unsigned long baud )

MKRWAN API difference:: Not implemented by this library: no serial link to configure

◆ setCFM()

bool STM32LoRaWAN::setCFM ( bool cfm )

MKRWAN API difference:: Not implemented by this library: confirmed uplinked better handled through endPacket()

◆ setDevAddr() [1/3]

bool STM32LoRaWAN::setDevAddr ( const char * value )

inline

◆ setDevAddr() [2/3]

bool STM32LoRaWAN::setDevAddr ( String value )

inline

◆ setDevAddr() [3/3]

bool STM32LoRaWAN::setDevAddr ( uint32_t value )

inline

◆ setDevEui() [1/3]

bool STM32LoRaWAN::setDevEui ( const char * value )

inline

◆ setDevEui() [2/3]

bool STM32LoRaWAN::setDevEui ( String value )

inline

◆ setDevEui() [3/3]

bool STM32LoRaWAN::setDevEui ( uint64_t value )

inline

◆ setFCD()

bool STM32LoRaWAN::setFCD ( uint16_t fcd )

MKRWAN API difference:: Not implemented by this library

◆ setFCU()

bool STM32LoRaWAN::setFCU ( uint16_t fcu )

MKRWAN API difference:: Not implemented by this library

◆ setMaintainNeededCallback()

void STM32LoRaWAN::setMaintainNeededCallback ( std::function< void(void)> callback )

inline

Registers a callback that is called whenever there is some work to do and the maintain() function must be called soon.

Warning: This callback is called from an interrupt handler, so it should not do any work and definitely not call maintain(), but just set a flag, enable a task, or something similarly short, and make sure to do that in a interrupt-safe manner.

When using this callback, it is not needed to call the maintain() method unless this callback is called, allowing applications to be more efficient, or use sleeping (but care should be taken to prevent race conditions).

Only one callback can be active at the same time, so any previously configured callback is replaced by the new one passed.

MKRWAN API difference:: Not supported by MKRWAN

◆ setNwkKey() [1/2]

bool STM32LoRaWAN::setNwkKey ( const char * value )

inline

◆ setNwkKey() [2/2]

bool STM32LoRaWAN::setNwkKey ( String value )

inline

◆ setNwkSKey() [1/2]

bool STM32LoRaWAN::setNwkSKey ( const char * value )

inline

◆ setNwkSKey() [2/2]

bool STM32LoRaWAN::setNwkSKey ( String value )

inline

◆ setPort()

bool STM32LoRaWAN::setPort ( uint8_t port )

Set the port to be used for data transmission.

◆ setRX2DR()

bool STM32LoRaWAN::setRX2DR ( uint8_t dr )

Set the datarate used for the RX2 window. The network might override this value using downlink commands (typically only in OTAA mode).

◆ setRX2Freq()

bool STM32LoRaWAN::setRX2Freq ( uint32_t freq )

Set the frequency used for the RX2 window. The network might override this value using downlink commands (typically only in OTAA mode).

◆ setTConf()

String STM32LoRaWAN::setTConf ( String params )

MKRWAN API difference:: Not implemented by this library: test method only

◆ sleep()

bool STM32LoRaWAN::sleep ( bool on = true )

MKRWAN API difference:: Not implemented by this library: no remote module to sleep

◆ toHex() [1/2]

bool STM32LoRaWAN::toHex	(	String *	dest,
		const uint8_t *	src,
		size_t	src_len
	)

staticprotected

Convert a binary buffer to a hex string

◆ toHex() [2/2]

char STM32LoRaWAN::toHex ( uint8_t b )

staticprotected

Convert a nibble (0-15) to a hex char

◆ toString() [1/4]

const char * STM32LoRaWAN::toString ( LoRaMacEventInfoStatus_t status )

staticprotected

Convert an enum value into string containing its name. The string returned is a static constant, so no memory management needed.

◆ toString() [2/4]

const char * STM32LoRaWAN::toString ( LoRaMacStatus_t status )

staticprotected

Convert an enum value into string containing its name. The string returned is a static constant, so no memory management needed.

◆ toString() [3/4]

const char * STM32LoRaWAN::toString ( Mcps_t mcps )

staticprotected

Convert an enum value into string containing its name. The string returned is a static constant, so no memory management needed.

◆ toString() [4/4]

const char * STM32LoRaWAN::toString ( Mlme_t mlme )

staticprotected

Convert an enum value into string containing its name. The string returned is a static constant, so no memory management needed.

◆ version()

String STM32LoRaWAN::version ( )

inline

Dummy for MKRWAN compatibility. On MKRWAN this returned the module firmware version, but this does not apply here.

MKRWAN API difference:: Dummy implementation in this library

◆ write() [1/3]

size_t STM32LoRaWAN::write	(	const uint8_t *	buffer,
		size_t	size
	)

virtual

◆ write() [2/3]

template<typename T >

size_t STM32LoRaWAN::write ( T val )

inline

◆ write() [3/3]

size_t STM32LoRaWAN::write ( uint8_t c )

virtual

Member Data Documentation

◆ battery_level_callback

std::function<uint8_t(void)> STM32LoRaWAN::battery_level_callback

protected

◆ DEFAULT_JOIN_TIMEOUT

constexpr uint32_t STM32LoRaWAN::DEFAULT_JOIN_TIMEOUT = 60000

staticconstexprprotected

◆ fcnt_down

uint32_t STM32LoRaWAN::fcnt_down = 0

protected

◆ fcnt_up

uint32_t STM32LoRaWAN::fcnt_up = 0

protected

◆ instance

STM32LoRaWAN * STM32LoRaWAN::instance

staticprotected

◆ last_tx_acked

bool STM32LoRaWAN::last_tx_acked = false

protected

◆ LoRaMacCallbacks

LoRaMacCallback_t STM32LoRaWAN::LoRaMacCallbacks

protected

Initial value:

= {
      .GetBatteryLevel = GetBatteryLevel,
      .GetTemperatureLevel = nullptr,
      .GetUniqueId = nullptr, 
      .GetDevAddress = nullptr, 
      .NvmDataChange = nullptr,
      .MacProcessNotify = MacProcessNotify,
    }

◆ LoRaMacPrimitives

LoRaMacPrimitives_t STM32LoRaWAN::LoRaMacPrimitives

protected

Initial value:

= {
      .MacMcpsConfirm = MacMcpsConfirm,
      .MacMcpsIndication = MacMcpsIndication,
      .MacMlmeConfirm = MacMlmeConfirm,
      .MacMlmeIndication = MacMlmeIndication,
    }

◆ mac_process_pending

bool STM32LoRaWAN::mac_process_pending = false

protected

◆ maintain_needed_callback

std::function<void(void)> STM32LoRaWAN::maintain_needed_callback

protected

◆ nwk_key_set

bool STM32LoRaWAN::nwk_key_set = false

protected

◆ rx_buf

uint8_t STM32LoRaWAN::rx_buf[255]

protected

◆ rx_port

uint8_t STM32LoRaWAN::rx_port = 0

protected

Port for most recently received packet

◆ rx_ptr

uint8_t* STM32LoRaWAN::rx_ptr

protected

◆ tx_buf

uint8_t STM32LoRaWAN::tx_buf[255]

protected

◆ tx_dr

uint8_t STM32LoRaWAN::tx_dr = DR_4

protected

Datarate for joining and data transmission (until ADR changes it, if enabled). This defaults to DR 4 since that is the fastest/highest (least spectrum usage) DR that is supported by all regions. If this DR has insufficient range, the join process (and ADR) will fall back to lower datarates automatically.

◆ tx_port

uint8_t STM32LoRaWAN::tx_port = 2

protected

Port for data transmissions. Default taken from MKRWAN_v2 / mkrwan1300-fw

◆ tx_ptr

uint8_t* STM32LoRaWAN::tx_ptr

protected

The documentation for this class was generated from the following files:

src/STM32LoRaWAN.h
src/STM32LoRaWAN.cpp

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Member Function Documentation

◆ add_rx()

◆ applicationKey()

◆ autoBaud()

◆ available()

◆ availableForWrite()

◆ begin() [1/2]

◆ begin() [2/2]

◆ beginPacket()

◆ builtinDevEUI()

◆ busy()

◆ clear_rx()

◆ configureBand()

◆ configureClass()

◆ connected()

◆ continuousWave()

◆ dataRate()

◆ deviceEUI()

◆ disableChannel()

◆ dumb()

◆ dutyCycle()

◆ enableChannel()

◆ endPacket()

◆ endPacketAsync()

◆ enTtone()

◆ factoryDefault()

◆ failure()

◆ flush()

◆ format()

◆ getADR()

◆ getAppEui() [1/2]

◆ getAppEui() [2/2]

◆ getAppSKey()

◆ GetBatteryLevel()

◆ getCFM()

◆ getCFS()

◆ getChannelMask()

◆ getChannelMaskSize()

◆ getDataRate()

◆ getDevAddr() [1/3]

◆ getDevAddr() [2/3]

◆ getDevAddr() [3/3]

◆ getDevEui() [1/2]

◆ getDevEui() [2/2]

◆ getDownlinkPort()

◆ getFCD()

◆ getFCU()

◆ getNwkSKey()

◆ getPort()

◆ getRX2DR()

◆ getRX2Freq()

◆ getrxfreq()

◆ getTConf()

◆ init()

◆ isChannelEnabled()

◆ joinABP() [1/4]

◆ joinABP() [2/4]

◆ joinABP() [3/4]

◆ joinABP() [4/4]

◆ joinOTAA() [1/9]

◆ joinOTAA() [2/9]

◆ joinOTAA() [3/9]

◆ joinOTAA() [4/9]

◆ joinOTAA() [5/9]

◆ joinOTAA() [6/9]

◆ joinOTAA() [7/9]

◆ joinOTAA() [8/9]

◆ joinOTAA() [9/9]

◆ joinOTAAAsync()

◆ lastAck()

◆ MacMcpsConfirm()

◆ MacMcpsIndication()

◆ MacMlmeConfirm()

◆ MacMlmeIndication()

◆ MacProcessNotify()