From a5023c7519925301e3757ae03d1a7f43e4df7216 Mon Sep 17 00:00:00 2001 From: Terry Moore Date: Mon, 18 Feb 2019 04:56:36 -0500 Subject: [PATCH 1/3] Fix #81: add additional paramter for port nubmer --- src/Arduino_LoRaWAN.h | 3 ++- src/lib/SendBuffer.cpp | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/Arduino_LoRaWAN.h b/src/Arduino_LoRaWAN.h index 67651a2..c7fbdcb 100644 --- a/src/Arduino_LoRaWAN.h +++ b/src/Arduino_LoRaWAN.h @@ -395,7 +395,8 @@ class Arduino_LoRaWAN size_t nBuffer, SendBufferCbFn *pDoneFn = nullptr, void *pCtx = nullptr, - bool fConfirmed = false + bool fConfirmed = false, + uint8_t port = 1 ); typedef void ReceivePortBufferCbFn( diff --git a/src/lib/SendBuffer.cpp b/src/lib/SendBuffer.cpp index 65d7c3f..5031943 100644 --- a/src/lib/SendBuffer.cpp +++ b/src/lib/SendBuffer.cpp @@ -74,7 +74,8 @@ bool Arduino_LoRaWAN::SendBuffer( size_t nBuffer, SendBufferCbFn *pDoneFn, void *pDoneCtx, - bool fConfirmed + bool fConfirmed, + uint8_t port ) { if (this->m_fTxPending || LMIC.opmode & OP_TXRXPEND) @@ -85,7 +86,7 @@ bool Arduino_LoRaWAN::SendBuffer( } const int iResult = LMIC_setTxData2( - /* port: */ 1, + /* port: */ port != 0 ? port : 1, const_cast(pBuffer), nBuffer, /* confirmed? */ fConfirmed From 24a9e042379697ba750f49480a908426d3fcb44d Mon Sep 17 00:00:00 2001 From: Terry Moore Date: Mon, 18 Feb 2019 04:56:52 -0500 Subject: [PATCH 2/3] Clean up comments --- src/lib/SendBuffer.cpp | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/src/lib/SendBuffer.cpp b/src/lib/SendBuffer.cpp index 5031943..89262a6 100644 --- a/src/lib/SendBuffer.cpp +++ b/src/lib/SendBuffer.cpp @@ -36,10 +36,7 @@ Revision history: /****************************************************************************\ | -| Manifest constants & typedefs. -| -| This is strictly for private types and constants which will not -| be exported. +| Manifest constants & typedefs. | \****************************************************************************/ @@ -49,23 +46,13 @@ Revision history: | | Read-only data. | -| If program is to be ROM-able, these must all be tagged read-only -| using the ROM storage class; they may be global. -| \****************************************************************************/ /****************************************************************************\ | -| VARIABLES: -| -| If program is to be ROM-able, these must be initialized -| using the BSS keyword. (This allows for compilers that require -| every variable to have an initializer.) Note that only those -| variables owned by this module should be declared here, using the BSS -| keyword; this allows for linkers that dislike multiple declarations -| of objects. +| Variables | \****************************************************************************/ From 073d5b440538b2cfb297a18c5194658783a1debe Mon Sep 17 00:00:00 2001 From: Terry Moore Date: Mon, 18 Feb 2019 05:05:05 -0500 Subject: [PATCH 3/3] Improve documentation --- README.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/README.md b/README.md index ce58f0b..38346b1 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,20 @@ - [Using the LMIC's pre-configured pinmaps](#using-the-lmics-pre-configured-pinmaps) - [Supplying a pinmap](#supplying-a-pinmap) - [Details on use](#details-on-use) +- [APIs](#apis) + - [Starting operation](#starting-operation) + - [Poll and update the LMIC](#poll-and-update-the-lmic) + - [Reset the LMIC](#reset-the-lmic) + - [Shut down the LMIC](#shut-down-the-lmic) + - [Register an event listener](#register-an-event-listener) + - [Send an event to all listeners](#send-an-event-to-all-listeners) + - [Manipulate the Debug Mask](#manipulate-the-debug-mask) + - [Output a formatted log message](#output-a-formatted-log-message) + - [Get the configured LoRaWAN region, country code, and network name](#get-the-configured-lorawan-region-country-code-and-network-name) + - [Send a buffer](#send-a-buffer) + - [Register a Receive-Buffer Callback](#register-a-receive-buffer-callback) + - [Get DevEUI, AppEUI, AppKey](#get-deveui-appeui-appkey) + - [Test provisioning state](#test-provisioning-state) - [Release History](#release-history) - [Notes](#notes) @@ -165,6 +179,100 @@ void setup() { 4. Implement the required methods. +## APIs + +### Starting operation + +The `begin()` APIs are used to start the LMIC engine. There are three forms. See ["Details on use,"](#details-on-use) above. + +### Poll and update the LMIC + +```c++ +void Arduino_LoRaWAN::loop(void); +``` + +This method must be called periodically in order to keep the LMIC operating. For class-A devices, this need only be called while actively pushing an uplink, or while a task is pending in the LMIC's time-driven queue. + +### Reset the LMIC + +```c++ +void Arduino_LoRaWAN::reset(void); +``` + +Cancel any pending operations and reinitialize all internal state. + +### Shut down the LMIC + +```c++ +void Arduino_LoRaWAN::Shutdown(void); +``` + +Shut down the LMIC. Any attempt to transmit while shut down will fail. + +### Register an event listener + +```c++ +typedef void ARDUINO_LORAWAN_EVENT_FN( + void *pUserData, + uint32_t eventCode + ); + +bool Arduino_LoRaWAN::RegisterListener( + ARDUINO_LORAWAN_EVENT_FN *pEvent, + void *pUserData + ); +``` + +Clients may register event functions using `RegisterListener`. The event function is called on each event from the LMIC. Up to four listeners may be registered. There's no way to cancel a registration. + +### Send an event to all listeners + +_To be documented._ + +### Manipulate the Debug Mask + +_To be documented._ + +### Output a formatted log message + +_To be documented._ + +### Get the configured LoRaWAN region, country code, and network name + +_To be documented._ + +### Send a buffer + +```c++ +typedef void Arduino_LoRaWAN::SendBufferCbFn( + void *pClientData, + bool fSuccess + ); + +bool Arduino_LoRaWAN::SendBuffer( + const uint8_t *pBuffer, + size_t nBuffer, + SendBufferCbFn *pDoneFn = nullptr, + void *pClientData = nullptr, + bool fConfirmed = false, + uint8_t port = 1 + ); +``` + +Send message from `pBuffer`; call `pDoneFn(pClientData, status)` when the message has either been transmitted or abandoned. + +### Register a Receive-Buffer Callback + +_To be documented._ + +### Get DevEUI, AppEUI, AppKey + +_To be documented._ + +### Test provisioning state + +_To be documented._ + ## Release History - v0.5.3 is a patch release. It fixes a platformio compile warning, and also fixes another missing return for `Arduino_LoRaWAN::begin()` (this time in an overload in the header file.)