search

rgot-org / EzLoRaWAN

ESP 32 port of the Arduino TheThingsNetwork library.
4 stars 5 forks source link

readme

EzLoRaWAN

EzLoRaWAN is an evolution of the TheThingsNetwork_esp32 library. Indeed TheThingsNetwork_esp32 does not support SX126X type chips. This library uses the BasicMAC library as a replacement for mcci-catena/arduino-lmic. The objective of this library is to simplify as much as possible the configuration, the connection, the sending and receiving of frames to a LoRaWan network.

Configuration

The library is tested for EU868 frequency plan (SX1262 & SX1276 chips). TODO enhance and verify for other frenquency plans

Pin assignment and initialization is automatic for some boards (see list below). In this case an AUTOPIN constant is declared. the following boards are tested with AUTOPIN :

To add new board edit the file target-config.h

Without AUTOPIN (for example for generic cards) you must define the board type, the SPI and LoRa chip pins as follow :

In the sketch declare a const as follow:

const lmic_pinmap lmic_pins = {
    .nss = RADIO_CS_PIN,
    .tx = RADIO_TX_PIN,
    .rx = RADIO_RX_PIN,
    .rst = RADIO_RST_PIN,
    .dio = {RADIO_DIO0_PIN , RADIO_DIO1_PIN, RADIO_DIO2_PIN},
    .busy = RADIO_BUSY_PIN,
    .tcxo = RADIO_TCXO_PIN,
};

In setup function add :

SPI.begin(RADIO_SCLK_PIN, RADIO_MISO_PIN, RADIO_MOSI_PIN);

then call de begin() method. (See ttn-otaa.ino with board-config.h in ttn-otaa example for more details)

API Reference

Class: EzLoRaWAN

Include and instantiate the EzLoRaWAN class. The constructor initialize the library with the Streams it should communicate with. 

#include <EzLoRaWAN.h>
EzLoRaWAN  ttn;

API methods

Method: begin

Start the LoRaWAN stack. The LoRa chip type and the pinout (LoRa & SPI) must be declared before call this method. (see the above and the target-config.h file for more details)

void begin();

Method: getAppEui

Gets the provisioned AppEUI. The AppEUI is set using provision() or join().

size_t getAppEui(char *buffer, size_t size);

return AppEui as an array of char

String getAppEui();

return AppEui as String

Method: getDevEui

Gets the provisioned DevEUI. The DevEUI is set using provision() or join().

size_t getDevEui(char *buffer, size_t size, bool hardwareEUI=false);

return DevEUI as array of char

String getDevEui(bool hardwareEui=false);

return DevEUI as String

Method: isJoined

Check whether we have joined TTN

 bool isJoined();

return true if joined to TTN, false if not.

Method: showStatus

Writes information about the device and LoRa module to Serial .

void showStatus();

Will write something like:

---------------Status--------------
Device EUI: 004D22F44E5DXXXX
Application EUI: 70B3D57ED001XXXX
netid: 13
devaddr: 2601XXXX
NwkSKey: 6A2D3C24AD3C0D17614D7325BCXXXX
AppSKey: 9E68DCBEBF8AE9D891252FB7EXXXX
data rate: 5
tx power: 14dB
freq: 867100000Hz
-----------------------------------

Method: onMessage

Sets a function which will be called to process incoming messages. You'll want to do this in your setup() function and then define a void (*cb)(const byte* payload, size_t length, port_t port) function somewhere else in your sketch.

void onMessage(void (*cb)(const uint8_t *payload, size_t size, int rssi));

See the [ttn-otaa]https://github.com/rgot-org/EzLoRaWAN/blob/main/examples/ttn-otaa/ttn-otaa.ino) example.

Method: join

Activate the device via OTAA (default).

bool join();
bool join(const char *app_eui, const char *app_key, int8_t retries = -1, uint32_t retryDelay = 10000);
bool join(const char *dev_eui, const char *app_eui, const char *app_key, int8_t retries = -1, uint32_t retryDelay = 10000);

Returns true or false depending on whether it received confirmation that the activation was successful before the maximum number of attempts.

Call the method without the first two arguments if the device's LoRa module is provisioned or comes with NVS stored values. See provision, saveKeys and restoreKeys

Method: personalize

Activate the device via ABP.

bool personalize(const char *devAddr, const char *nwkSKey, const char *appSKey);
bool personalize();

Returns true or false depending on whether the activation was successful.

Call the method with no arguments if the device's LoRa module is provisioned or comes with NVS stored values. See provisionABP, saveKeys and restoreKeys

See the ttn_abp example.

Method: sendBytes

Send a message to the application using raw bytes.

bool sendBytes(uint8_t *payload, size_t length, uint8_t port = 1, uint8_t confirm = 0);

Method: poll

Calls sendBytes() with { 0x00 } as payload to poll for incoming messages.

int8_t poll(uint8_t port = 1, uint8_t confirm = 0);

Returns the result of sendBytes().

Method: provision

Sets the informations needed to activate the device via OTAA, without actually activating. Call join() without the first 2 arguments to activate.

bool provision(const char *appEui, const char *appKey);
bool provision(const char *devEui, const char *appEui, const char *appKey);

Sets the informations needed to activate the device via ABP, without actually activating. call personalize() without arguments to activate.

bool provisionABP(const char *devAddr, const char *nwkSKey, const char *appSKey);