Rename ttn_join()

include/TheThingsNetwork.h

@@ -474,11 +474,14 @@ class TheThingsNetwork
     }
 
     /**
-     * @brief Sets the credentials needed to activate the device via OTAA, without activating it.
+     * @brief Sets the keys needed to activate the device via OTAA, without activating it.
      *
      * The provided DevEUI, AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
      * this function is called, `nvs_flash_init()` must have been called once.
      *
+     * In order to reduce flash wear, this function detects if the keys have not changed
+     * and will not write them again.
+     * 
      * Call @ref join() to activate the device.
      *
      * @param devEui  DevEUI (16 character string with hexadecimal data)
@@ -491,6 +494,24 @@ class TheThingsNetwork
         return ttn_provision(devEui, appEui, appKey);
     }
 
+    /**
+     * @brief Sets the keys needed to activate the device via OTAA, without activating it.
+     *
+     * The provided DevEUI, AppEUI/JoinEUI and AppKey are only stored in RAM and will be lost
+     * when the device is powered off or put in deep sleep.
+     *
+     * Call @ref join() to activate the device.
+     *
+     * @param devEui  DevEUI (16 character string with hexadecimal data)
+     * @param appEui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
+     * @param appKey  AppKey of the device (32 character string with hexadecimal data)
+     * @return `true` if the provisioning was successful, `false`  if the provisioning failed
+     */
+    bool provisionTransiently(const char *devEui, const char *appEui, const char *appKey)
+    {
+        return ttn_provision_transiently(devEui, appEui, appKey);
+    }
+
     /**
      * @brief Sets the information needed to activate the device via OTAA, using the MAC to generate the DevEUI
      * and without activating it.
@@ -498,6 +519,9 @@ class TheThingsNetwork
      * The generated DevEUI and the provided AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
      * this function is called, `nvs_flash_init` must have been called once.
      *
+     * In order to reduce flash wear, this function detects if the keys have not changed
+     * and will not write them again.
+     * 
      * The DevEUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a DevEUI
      * by adding FFFE in the middle. So the MAC address A0:B1:C2:01:02:03 becomes the EUI A0B1C2FFFE010203.
      * This hexadecimal data can be entered into the DevEUI field in the TTN console.
@@ -556,7 +580,7 @@ class TheThingsNetwork
      */
     bool join()
     {
-        return ttn_join_provisioned();
+        return ttn_join();
     }
 
     /**
@@ -576,7 +600,7 @@ class TheThingsNetwork
      */
     bool join(const char *devEui, const char *appEui, const char *appKey)
     {
-        return ttn_join(devEui, appEui, appKey);
+        return ttn_join_with_keys(devEui, appEui, appKey);
     }
 
     /**
@@ -702,7 +726,8 @@ class TheThingsNetwork
 
     /**
      * @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage
-     * or have been provided as by a call to @ref join(const char*, const char*, const char*).
+     * or have been provided by a call to @ref join(const char*, const char*, const char*)
+     * or to @ref provisionTransiently(const char*, const char*, const char*).
      *
      * @return `true` if they are stored, complete and of the correct size, `false` otherwise
      */

include/ttn.h

@@ -467,12 +467,15 @@ extern "C"
     void ttn_set_subband(int band);
 
     /**
-     * @brief Sets the credentials needed to activate the device via OTAA, without activating it.
+     * @brief Sets the keys needed to activate the device via OTAA, without activating it.
      *
      * The provided DevEUI, AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
      * this function is called, `nvs_flash_init()` must have been called once.
      * 
-     * Call @ref ttn_join_provisioned() to activate the device.
+     * In order to reduce flash wear, this function detects if the keys have not changed
+     * and will not write them again.
+     *
+     * Call @ref ttn_join() to activate the device.
      *
      * @param dev_eui  DevEUI (16 character string with hexadecimal data)
      * @param app_eui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
@@ -481,6 +484,21 @@ extern "C"
      */
     bool ttn_provision(const char *dev_eui, const char *app_eui, const char *app_key);
 
+    /**
+     * @brief Sets the keys needed to activate the device via OTAA, without activating it.
+     *
+     * The provided DevEUI, AppEUI/JoinEUI and AppKey are only stored in RAM and will be lost
+     * when the device is powered off or put in deep sleep.
+     *
+     * Call @ref ttn_join() to activate the device.
+     *
+     * @param dev_eui  DevEUI (16 character string with hexadecimal data)
+     * @param app_eui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
+     * @param app_key  AppKey of the device (32 character string with hexadecimal data)
+     * @return `true` if the provisioning was successful, `false`  if the provisioning failed
+     */
+    bool ttn_provision_transiently(const char *dev_eui, const char *app_eui, const char *app_key);
+
     /**
      * @brief Sets the information needed to activate the device via OTAA, using the MAC to generate the DevEUI
      * and without activating it.
@@ -488,6 +506,9 @@ extern "C"
      * The generated DevEUI and the provided AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
      * this function is called, `nvs_flash_init` must have been called once.
      *
+     * In order to reduce flash wear, this function detects if the keys have not changed
+     * and will not write them again.
+     * 
      * The DevEUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a DevEUI
      * by adding FFFE in the middle. So the MAC address A0:B1:C2:01:02:03 becomes the EUI A0B1C2FFFE010203.
      * This hexadecimal data can be entered into the DevEUI field in the TTN console.
@@ -497,7 +518,7 @@ extern "C"
      * it is okay for that the LoRa communication of your application can easily be intercepted and that
      * forged data can be injected.
      *
-     * Call @ref ttn_join_provisioned() to activate.
+     * Call @ref ttn_join() to activate.
      *
      * @param app_eui  AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
      * @param app_key  AppKey of the device (32 character string with hexadecimal data)
@@ -517,7 +538,7 @@ extern "C"
      * by the provisioning task.
      *
      * If the device has already been provisioned (stored data in NVS, call of provision()
-     * or call of @ref ttn_join(), this function immediately returns.
+     * or call of @ref ttn_join_with_keys(), this function immediately returns.
      */
     void ttn_wait_for_provisioning(void);
 
@@ -534,7 +555,7 @@ extern "C"
      *
      * @return `true` if the activation was succesful, `false` if the activation failed
      */
-    bool ttn_join_provisioned(void);
+    bool ttn_join(void);
 
     /**
      * @brief Activates the device via OTAA using the provided keys.
@@ -551,7 +572,7 @@ extern "C"
      * @param app_key  AppKey of the device (32 character string with hexadecimal data)
      * @return `true` if the activation was succesful, `false` if the activation failed
      */
-    bool ttn_join(const char *dev_eui, const char *app_eui, const char *app_key);
+    bool ttn_join_with_keys(const char *dev_eui, const char *app_eui, const char *app_key);
 
     /**
      * @brief Resumes TTN communication after deep sleep.
@@ -559,7 +580,7 @@ extern "C"
      * The communcation state is restored from data previously saved in RTC memory.
      * The RF module and the TTN background task are started.
      * 
-     * This function is called instead of @ref ttn_join() or @ref ttn_join_provisioned()
+     * This function is called instead of @ref ttn_join_with_keys() or @ref ttn_join()
      * to continue with the established communication and to avoid a further join procedure.
      *
      * @return `true` if the device was able to resume, `false` otherwise.
@@ -616,7 +637,7 @@ extern "C"
      * provisioned keys nor the configured pins. The currentat device state (and activation)
      * are lost.
      *
-     * To restart communication, @ref ttn_join() and @ref ttn_join_provisioned() must be called.
+     * To restart communication, @ref ttn_join_with_keys() and @ref ttn_join() must be called.
      */
     void ttn_shutdown(void);
 
@@ -654,7 +675,7 @@ extern "C"
 
     /**
      * @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage
-     * or have been provided as by a call to @ref ttn_join().
+     * or have been provided by a call to @ref ttn_join_with_keys() or to @ref ttn_provision_transiently().
      *
      * @return `true` if they are stored, complete and of the correct size, `false` otherwise
      */

src/hal/hal_esp32.c

@@ -520,7 +520,9 @@ void hal_esp32_stop_lmic_task(void)
     gpio_isr_handler_remove(pin_dio0);
     gpio_isr_handler_remove(pin_dio1);
     disarm_timer();
+    set_next_alarm(0);
     xTaskNotify(lmic_task, NOTIFY_BIT_STOP, eSetBits);
+    lmic_task = xTaskGetCurrentTaskHandle();
 }
 
 

src/ttn.c

@@ -149,6 +149,11 @@ bool ttn_provision(const char *dev_eui, const char *app_eui, const char *app_key
     return ttn_provisioning_save_keys();
 }
 
+bool ttn_provision_transiently(const char *dev_eui, const char *app_eui, const char *app_key)
+{
+    return ttn_provisioning_decode_keys(dev_eui, app_eui, app_key);
+}
+
 bool ttn_provision_with_mac(const char *app_eui, const char *app_key)
 {
     if (!ttn_provisioning_from_mac(app_eui, app_key))
@@ -188,7 +193,7 @@ void ttn_wait_for_provisioning(void)
 #endif
 }
 
-bool ttn_join(const char *dev_eui, const char *app_eui, const char *app_key)
+bool ttn_join_with_keys(const char *dev_eui, const char *app_eui, const char *app_key)
 {
     if (!ttn_provisioning_decode_keys(dev_eui, app_eui, app_key))
         return false;
@@ -196,7 +201,7 @@ bool ttn_join(const char *dev_eui, const char *app_eui, const char *app_key)
     return join_core();
 }
 
-bool ttn_join_provisioned(void)
+bool ttn_join(void)
 {
     if (!ttn_provisioning_have_keys())
     {