Merge pull request #82 from mcci-catena/issue81

Fix #81: allowed uplink to arbitrary port. Improve docs.

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.)

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(

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
 |
 \****************************************************************************/
 
@@ -74,7 +61,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 +73,7 @@ bool Arduino_LoRaWAN::SendBuffer(
                 }
 
         const int iResult = LMIC_setTxData2(
-                                /* port: */ 1,
+                                /* port: */ port != 0 ? port : 1,
                                 const_cast<xref2u1_t>(pBuffer),
                                 nBuffer,
                                 /* confirmed? */ fConfirmed