Merge pull request #799 from mcci-catena/issue576

Add control over battery level response for DevStatusAns MAC message

Author: terrillmoore

README.md

@@ -1248,6 +1248,7 @@ function uflt12f(rawUflt12)
   - Warn about Feather pin wiring requirements ([#755](https://github.com/mcci-catena/arduino-lmic/issues/755), thanks to [@d-a-v](https://github.com/d-a-v)).
   - Fix typos in this document ([#780](https://github.com/mcci-catena/arduino-lmic/issues/780), thanks [@PeeJay](https://github.com/PeeJay)).
   - Fix additional warnings on non-ARM platforms ([#791](https://github.com/mcci-catena/arduino-lmic/issues/791), thanks [@d-a-v](https://github.com/d-a-v)).
+  - Allow application to set the value to be used in `DeviceStatusAns` MAC messages ([#576](https://github.com/mcci-catena/arduino-lmic/issues/576) and [#560](https://github.com/mcci-catena/arduino-lmic/issues/560), thanks to [@altishchenko](https://github.com/altishchenko)).
 
 - v4.0 is a major release; changes are significant enough to be "likely breaking". It includes the following changes.
 

src/lmic/lmic.c

@@ -119,7 +119,7 @@ void os_wmsbf4 (xref2u1_t buf, u4_t v) {
 
 #if !defined(os_getBattLevel)
 u1_t os_getBattLevel (void) {
-    return MCMD_DEVS_BATT_NOINFO;
+    return LMIC.client.devStatusAns_battery;
 }
 #endif
 
@@ -2815,6 +2815,7 @@ void LMIC_reset (void) {
 
 void LMIC_init (void) {
     LMIC.opmode = OP_SHUTDOWN;
+    LMIC.client.devStatusAns_battery = MCMD_DEVS_BATT_NOINFO;
     LMICbandplan_init();
 }
 
@@ -3102,3 +3103,47 @@ int LMIC_getNetworkTimeReference(lmic_time_reference_t *pReference) {
 #endif // LMIC_ENABLE_DeviceTimeReq
     return 0;
 }
+
+///
+/// \brief set battery level to be returned by `DevStatusAns`.
+///
+/// \param uBattLevel is the 8-bit value to be returned. Per LoRaWAN 1.0.3 line 769,
+///             this is \c MCMD_DEVS_EXT_POWER (0) if on external power,
+///             \c MCMD_DEVS_NOINFO (255) if not able to measure battery level,
+///             or a value in [ \c MCMD_DEVS_BATT_MIN, \c MCMD_DEVS_BATT_MAX ], numerically
+///             [1, 254], to represent the charge state of the battery. Note that
+///             this is not millivolts.
+///
+/// \returns
+///     This function returns the previous value of the battery level.
+///
+/// \details
+///     The LMIC maintains an idea of the current battery state, initially set to
+///     \c MCMD_DEVS_NOINFO after the call to LMIC_init(). The appplication then calls
+///     this function from time to time to update the battery level.
+///
+///     It is possible (in non-Arduino environments) to supply a local implementation
+///     of os_getBatteryLevel(). In that case, it's up to the implementation to decide
+///     whether to use the value supplied by this API.
+///
+///     This implementation was chosen to minimize the risk of a battery measurement
+///     introducting breaking delays into the LMIC.
+///
+u1_t LMIC_setBatteryLevel(u1_t uBattLevel) {
+    const u1_t result = LMIC.client.devStatusAns_battery;
+
+    LMIC.client.devStatusAns_battery = uBattLevel;
+    return result;
+}
+
+///
+/// \brief get battery level that is to be returned by `DevStatusAns`.
+///
+/// \returns
+///     This function returns the saved value of the battery level.
+///
+/// \see LMIC_setBatteryLevel()
+///
+u1_t LMIC_getBatteryLevel(void) {
+    return LMIC.client.devStatusAns_battery;
+}

src/lmic/lmic.h

@@ -106,7 +106,7 @@ extern "C"{
 	((((major)*UINT32_C(1)) << 24) | (((minor)*UINT32_C(1)) << 16) | (((patch)*UINT32_C(1)) << 8) | (((local)*UINT32_C(1)) << 0))
 
 #define	ARDUINO_LMIC_VERSION    \
-    ARDUINO_LMIC_VERSION_CALC(4, 0, 1, 1)  /* 4.0.1-pre1 */
+    ARDUINO_LMIC_VERSION_CALC(4, 1, 0, 1)  /* 4.1.0-pre1 */
 
 #define	ARDUINO_LMIC_VERSION_GET_MAJOR(v)	\
 	((((v)*UINT32_C(1)) >> 24u) & 0xFFu)
@@ -459,7 +459,7 @@ struct lmic_client_data_s {
     u2_t        clockError;                 //! Inaccuracy in the clock. CLOCK_ERROR_MAX represents +/-100% error
 
     /* finally, things that are (u)int8_t */
-    /* none at the moment */
+    u1_t        devStatusAns_battery;       //!< value to report in MCMD_DevStatusAns message.
 };
 
 /*
@@ -740,6 +740,9 @@ int LMIC_registerEventCb(lmic_event_cb_t *pEventCb, void *pUserData);
 
 int LMIC_findNextChannel(uint16_t *, const uint16_t *, uint16_t, int);
 
+u1_t LMIC_getBatteryLevel(void);
+u1_t LMIC_setBatteryLevel(u1_t /* uBattLevel */);
+
 // APIs for client half of compliance.
 typedef u1_t lmic_compliance_rx_action_t;
 

src/lmic/lorabase_as923.h

@@ -76,14 +76,14 @@ enum { DR_PAGE_AS923 = 0x10 * (LMIC_REGION_as923 - 1) };
 enum { AS923_LMIC_REGION_EIRP = 1 };         // region uses EIRP
 
 enum { AS923JP_LBT_US = 5000 };         // microseconds of LBT time -- 5000 ==>
-					// 5 ms. We use us rather than ms for
-					// future 128us support, and just for
-					// backward compatibility -- there
-					// is code that uses the _US constant,
-					// and it's awkward to break it.
+                                        // 5 ms. We use us rather than ms for
+                                        // future 128us support, and just for
+                                        // backward compatibility -- there
+                                        // is code that uses the _US constant,
+                                        // and it's awkward to break it.
 
 enum { AS923JP_LBT_DB_MAX = -80 };      // maximum channel strength in dB; if TX
-					// we measure more than this, we don't tx.
+                                        // we measure more than this, we don't tx.
 
 // AS923 v1.1, all channels face a 1% duty cycle. So this will have to change
 // in the future via a config. But this code base needs major changes for

src/lmic/oslmic.h

@@ -238,7 +238,7 @@ void os_wmsbf4 (xref2u1_t buf, u4_t value);
 u2_t os_rlsbf2 (xref2cu1_t buf);
 #endif
 #ifndef os_wlsbf2
-//! Write 16-bit quntity into buffer in little endian byte order.
+//! Write 16-bit quantity into buffer in little endian byte order.
 void os_wlsbf2 (xref2u1_t buf, u2_t value);
 #endif