diff --git a/examples/hello_world/main/main.cpp b/examples/hello_world/main/main.cpp index ef314df..870bf16 100644 --- a/examples/hello_world/main/main.cpp +++ b/examples/hello_world/main/main.cpp @@ -18,15 +18,17 @@ #include "TheThingsNetwork.h" // NOTE: -// The LoRaWAN frequency and the radio chip must be configured by running 'make menuconfig'. +// The LoRaWAN frequency and the radio chip must be configured by running 'idf.py menuconfig'. // Go to Components / The Things Network, select the appropriate values and save. -// Copy the below hex string from the "Device EUI" field -// on your device's overview page in the TTN console. -const char *devEui = "????????????????"; +// Copy the below hex strings from the TTN console (Applications > Your application > End devices +// > Your device > Activation information) -// Copy the below two lines from bottom of the same page +// AppEUI (sometimes called JoinEUI) const char *appEui = "????????????????"; +// DevEUI +const char *devEui = "????????????????"; +// AppKey const char *appKey = "????????????????????????????????"; // Pins and other resources diff --git a/examples/mac_address/main/main.cpp b/examples/mac_address/main/main.cpp index 4b13fa7..1b44a99 100644 --- a/examples/mac_address/main/main.cpp +++ b/examples/mac_address/main/main.cpp @@ -17,15 +17,21 @@ #include "TheThingsNetwork.h" + // NOTE: -// The LoRaWAN frequency and the radio chip must be configured by running 'make menuconfig'. +// The LoRaWAN frequency and the radio chip must be configured by running 'idf.py menuconfig'. // Go to Components / The Things Network, select the appropriate values and save. -// Copy the below two lines from the bottom -// of your device's overview page in the TTN console. +// Copy the below hex strings from the TTN console (Applications > Your application > End devices +// > Your device > Activation information) + +// AppEUI (sometimes called JoinEUI) const char *appEui = "????????????????"; + +// AppKey const char *appKey = "????????????????????????????????"; + // Pins and other resources #define TTN_SPI_HOST HSPI_HOST #define TTN_SPI_DMA_CHAN 1 diff --git a/examples/monitoring/main/main.cpp b/examples/monitoring/main/main.cpp index 5087821..498fdd9 100644 --- a/examples/monitoring/main/main.cpp +++ b/examples/monitoring/main/main.cpp @@ -17,18 +17,22 @@ #include "TheThingsNetwork.h" + // NOTE: -// The LoRaWAN frequency and the radio chip must be configured by running 'make menuconfig'. +// The LoRaWAN frequency and the radio chip must be configured by running 'idf.py menuconfig'. // Go to Components / The Things Network, select the appropriate values and save. -// Copy the below hex string from the "Device EUI" field -// on your device's overview page in the TTN console. -const char *devEui = "????????????????"; +// Copy the below hex strings from the TTN console (Applications > Your application > End devices +// > Your device > Activation information) -// Copy the below two lines from bottom of the same page +// AppEUI (sometimes called JoinEUI) const char *appEui = "????????????????"; +// DevEUI +const char *devEui = "????????????????"; +// AppKey const char *appKey = "????????????????????????????????"; + // Pins and other resources #define TTN_SPI_HOST HSPI_HOST #define TTN_SPI_DMA_CHAN 1 diff --git a/examples/provisioning/main/main.cpp b/examples/provisioning/main/main.cpp index e50333c..cff9ad2 100644 --- a/examples/provisioning/main/main.cpp +++ b/examples/provisioning/main/main.cpp @@ -17,10 +17,12 @@ #include "TheThingsNetwork.h" + // NOTE: // The LoRaWAN frequency and the radio chip must be configured by running 'make menuconfig'. // Go to Components / The Things Network, select the appropriate values and save. + // Pins and other resources #define TTN_SPI_HOST HSPI_HOST #define TTN_SPI_DMA_CHAN 1 diff --git a/examples/shutdown/main/main.cpp b/examples/shutdown/main/main.cpp index be23730..0daa569 100644 --- a/examples/shutdown/main/main.cpp +++ b/examples/shutdown/main/main.cpp @@ -17,18 +17,22 @@ #include "TheThingsNetwork.h" + // NOTE: -// The LoRaWAN frequency and the radio chip must be configured by running 'make menuconfig'. +// The LoRaWAN frequency and the radio chip must be configured by running 'idf.py menuconfig'. // Go to Components / The Things Network, select the appropriate values and save. -// Copy the below hex string from the "Device EUI" field -// on your device's overview page in the TTN console. -const char *devEui = "????????????????"; +// Copy the below hex strings from the TTN console (Applications > Your application > End devices +// > Your device > Activation information) -// Copy the below two lines from bottom of the same page +// AppEUI (sometimes called JoinEUI) const char *appEui = "????????????????"; +// DevEUI +const char *devEui = "????????????????"; +// AppKey const char *appKey = "????????????????????????????????"; + // Pins and other resources #define TTN_SPI_HOST HSPI_HOST #define TTN_SPI_DMA_CHAN 1 diff --git a/include/TheThingsNetwork.h b/include/TheThingsNetwork.h index 5d7446c..d644c89 100644 --- a/include/TheThingsNetwork.h +++ b/include/TheThingsNetwork.h @@ -210,38 +210,38 @@ public: /** * @brief Sets the credentials needed to activate the device via OTAA, without activating it. * - * The provided device EUI, app EUI and app key are saved in non-volatile memory. Before + * 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 join() to activate the device. * - * @param devEui Device EUI (16 character string with hexadecimal data) - * @param appEui Application EUI of the device (16 character string with hexadecimal data) - * @param appKey App Key of the device (32 character string with hexadecimal data) + * @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 provision(const char *devEui, const char *appEui, const char *appKey) { return ttn_provision(devEui, appEui, appKey); } /** - * @brief Sets the information needed to activate the device via OTAA, using the MAC to generate the device EUI + * @brief Sets the information needed to activate the device via OTAA, using the MAC to generate the DevEUI * and without activating it. * - * The generated device EUI and the provided app EUI and app key are saved in non-volatile memory. Before + * 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. * - * The device EUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a device EUI + * 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 Device EUI field in the TTN console. + * This hexadecimal data can be entered into the DevEUI field in the TTN console. * - * Generating the device EUI from the MAC address allows to flash the same app EUI and app key to a batch of - * devices. However, using the same app key for multiple devices is insecure. Only use this approach if + * Generating the DevEUI from the MAC address allows to flash the same AppEUI/JoinEUI and AppKey to a batch of + * devices. However, using the same AppKey for multiple devices is insecure. Only use this approach if * it is okay for that the LoRa communication of your application can easily be intercepted and that * forged data can be injected. * * Call join() to activate. * - * @param appEui Application EUI of the device (16 character string with hexadecimal data) - * @param appKey App Key of the device (32 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 provisionWithMAC(const char *appEui, const char *appKey) { return ttn_provision_with_mac(appEui, appKey); } @@ -254,7 +254,7 @@ public: void startProvisioningTask() { ttn_start_provisioning_task(); } /** - * @brief Waits until the device EUI, app EUI and app key have been provisioned + * @brief Waits until the DevEUI, AppEUI/JoinEUI and AppKey have been provisioned * by the provisioning task. * * If the device has already been provisioned (stored data in NVS, call of provision() @@ -266,7 +266,7 @@ public: /** * @brief Activates the device via OTAA. * - * The app EUI, app key and dev EUI must have already been provisioned by a call to provision(). + * The DevEUI, AppEUI/JoinEUI and AppKey must have already been provisioned by a call to provision(). * Before this function is called, `nvs_flash_init()` must have been called once. * * The function blocks until the activation has completed or failed. @@ -276,15 +276,15 @@ public: bool join() { return ttn_join_provisioned(); } /** - * @brief Sets the device EUI, app EUI and app key and activate the device via OTAA. + * @brief Sets the DevEUI, AppEUI/JoinEUI and AppKey and activate the device via OTAA. * - * The device EUI, app EUI and app key are NOT saved in non-volatile memory. + * The DevEUI, AppEUI/JoinEUI and AppKey are NOT saved in non-volatile memory. * * The function blocks until the activation has completed or failed. * - * @param devEui Device EUI (16 character string with hexadecimal data) - * @param appEui Application EUI of the device (16 character string with hexadecimal data) - * @param appKey App Key of the device (32 character string with hexadecimal data) + * @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 activation was succesful, `false` if the activation failed */ bool join(const char *devEui, const char *appEui, const char *appKey) { return ttn_join(devEui, appEui, appKey); } @@ -324,7 +324,7 @@ public: void onMessage(TTNMessageCallback callback) { ttn_on_message(callback); } /** - * @brief Checks if device EUI, app EUI and app key have been stored in non-volatile storage + * @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage * or have been provided as by a call to join(const char*, const char*, const char*). * * @return `true` if they are stored, complete and of the correct size, `false` otherwise diff --git a/include/ttn.h b/include/ttn.h index ea981f9..592089a 100644 --- a/include/ttn.h +++ b/include/ttn.h @@ -205,38 +205,38 @@ void ttn_set_subband(int band); /** * @brief Sets the credentials needed to activate the device via OTAA, without activating it. * - * The provided device EUI, app EUI and app key are saved in non-volatile memory. Before + * 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 join() to activate the device. * - * @param dev_eui Device EUI (16 character string with hexadecimal data) - * @param app_eui Application EUI of the device (16 character string with hexadecimal data) - * @param app_key App Key of the device (32 character string with hexadecimal data) + * @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(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 device EUI + * @brief Sets the information needed to activate the device via OTAA, using the MAC to generate the DevEUI * and without activating it. * - * The generated device EUI and the provided app EUI and app key are saved in non-volatile memory. Before + * 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. * - * The device EUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a device EUI + * 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 Device EUI field in the TTN console. + * This hexadecimal data can be entered into the DevEUI field in the TTN console. * - * Generating the device EUI from the MAC address allows to flash the same app EUI and app key to a batch of - * devices. However, using the same app key for multiple devices is insecure. Only use this approach if + * Generating the DevEUI from the MAC address allows to flash the same AppEUI/JoinEUI and AppKey to a batch of + * devices. However, using the same AppKey for multiple devices is insecure. Only use this approach if * it is okay for that the LoRa communication of your application can easily be intercepted and that * forged data can be injected. * * Call join() to activate. * - * @param app_eui Application EUI of the device (16 character string with hexadecimal data) - * @param app_key App Key of the device (32 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_with_mac(const char *app_eui, const char *app_key); @@ -249,7 +249,7 @@ bool ttn_provision_with_mac(const char *app_eui, const char *app_key); void ttn_start_provisioning_task(void); /** - * @brief Waits until the device EUI, app EUI and app key have been provisioned + * @brief Waits until the DevEUI, AppEUI/JoinEUI and AppKey have been provisioned * by the provisioning task. * * If the device has already been provisioned (stored data in NVS, call of provision() @@ -261,7 +261,7 @@ void ttn_wait_for_provisioning(void); /** * @brief Activates the device via OTAA. * - * The app EUI, app key and dev EUI must have already been provisioned by a call to provision(). + * The DevEUI, AppEUI/JoinEUI and AppKey must have already been provisioned by a call to provision(). * Before this function is called, `nvs_flash_init()` must have been called once. * * The function blocks until the activation has completed or failed. @@ -271,15 +271,15 @@ void ttn_wait_for_provisioning(void); bool ttn_join_provisioned(void); /** - * @brief Sets the device EUI, app EUI and app key and activate the device via OTAA. + * @brief Sets the DevEUI, AppEUI/JoinEUI and AppKey and activate the device via OTAA. * - * The device EUI, app EUI and app key are NOT saved in non-volatile memory. + * The DevEUI, AppEUI/JoinEUI and AppKey are NOT saved in non-volatile memory. * * The function blocks until the activation has completed or failed. * - * @param dev_eui Device EUI (16 character string with hexadecimal data) - * @param app_eui Application EUI of the device (16 character string with hexadecimal data) - * @param app_key App Key of the device (32 character string with hexadecimal data) + * @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 activation was succesful, `false` if the activation failed */ bool ttn_join(const char *dev_eui, const char *app_eui, const char *app_key); @@ -316,7 +316,7 @@ ttn_response_code_t ttn_transmit_message(const uint8_t *payload, size_t length, void ttn_on_message(ttn_message_cb callback); /** - * @brief Checks if device EUI, app EUI and app key have been stored in non-volatile storage + * @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage * or have been provided as by a call to join(const char*, const char*, const char*). * * @return `true` if they are stored, complete and of the correct size, `false` otherwise diff --git a/src/ttn.c b/src/ttn.c index b1f050a..2fcbb49 100644 --- a/src/ttn.c +++ b/src/ttn.c @@ -202,7 +202,7 @@ bool join_core() { if (!ttn_provisioning_have_keys()) { - ESP_LOGW(TAG, "Device EUI, App EUI and/or App key have not been provided"); + ESP_LOGW(TAG, "DevEUI, AppEUI/JoinEUI and/or AppKey have not been provided"); return false; } diff --git a/src/ttn_provisioning.c b/src/ttn_provisioning.c index e36388d..7139b5b 100644 --- a/src/ttn_provisioning.c +++ b/src/ttn_provisioning.c @@ -378,7 +378,7 @@ bool decode(bool incl_dev_eui, const char *dev_eui, const char *app_eui, const c if (incl_dev_eui && (strlen(dev_eui) != 16 || !hex_str_to_bin(dev_eui, buf_dev_eui, 8))) { - ESP_LOGW(TAG, "Invalid device EUI: %s", dev_eui); + ESP_LOGW(TAG, "Invalid DevEUI: %s", dev_eui); return false; } @@ -387,7 +387,7 @@ bool decode(bool incl_dev_eui, const char *dev_eui, const char *app_eui, const c if (strlen(app_eui) != 16 || !hex_str_to_bin(app_eui, buf_app_eui, 8)) { - ESP_LOGW(TAG, "Invalid application EUI: %s", app_eui); + ESP_LOGW(TAG, "Invalid AppEUI/JoinEUI: %s", app_eui); return false; } @@ -405,7 +405,6 @@ bool decode(bool incl_dev_eui, const char *dev_eui, const char *app_eui, const c memcpy(global_app_key, buf_app_key, sizeof(global_app_key)); have_keys = !is_all_zeros(global_dev_eui, sizeof(global_dev_eui)) - && !is_all_zeros(global_app_eui, sizeof(global_app_eui)) && !is_all_zeros(global_app_key, sizeof(global_app_key)); return true; @@ -442,7 +441,7 @@ bool ttn_provisioning_save_keys() ESP_ERROR_CHECK(res); result = true; - ESP_LOGI(TAG, "Dev and app EUI and app key saved in NVS storage"); + ESP_LOGI(TAG, "DevEUI, AppEUI/JoinEUI and AppKey saved in NVS storage"); done: nvs_close(handle); @@ -482,16 +481,15 @@ bool ttn_provisioning_restore_keys(bool silent) memcpy(global_app_key, buf_app_key, sizeof(global_app_key)); have_keys = !is_all_zeros(global_dev_eui, sizeof(global_dev_eui)) - && !is_all_zeros(global_app_eui, sizeof(global_app_eui)) && !is_all_zeros(global_app_key, sizeof(global_app_key)); if (have_keys) { - ESP_LOGI(TAG, "Dev and app EUI and app key have been restored from NVS storage"); + ESP_LOGI(TAG, "DevEUI, AppEUI/JoinEUI and AppKey have been restored from NVS storage"); } else { - ESP_LOGW(TAG, "Dev and app EUI and app key are invalid (zeroes only)"); + ESP_LOGW(TAG, "DevEUI or DevEUI is invalid (zeroes only)"); } done: