From 2f33131b14a2c239347ae7cb68de40c755bd2800 Mon Sep 17 00:00:00 2001 From: RobMeades Date: Fri, 19 Jan 2024 10:46:00 +0000 Subject: [PATCH] Hopefully improved instructions. --- example/sockets/main_ppp_espidf.c | 34 +++++++++++++++++++++---------- port/platform/esp-idf/README.md | 16 ++++++++++----- 2 files changed, 34 insertions(+), 16 deletions(-) diff --git a/example/sockets/main_ppp_espidf.c b/example/sockets/main_ppp_espidf.c index 8525441d..ae2f24c6 100644 --- a/example/sockets/main_ppp_espidf.c +++ b/example/sockets/main_ppp_espidf.c @@ -19,20 +19,32 @@ * IP stack of the ESP-IDF platform. * * For this example to run you must define U_CFG_PPP_ENABLE when - * building ubxlib and you must switch on the following in your - * sdkconfig file: + * building ubxlib (e.g. you could do this by including it in the + * U_FLAGS environment variable that the ubxlib ESP-IDF component + * looks for, e.g. set U_FLAGS=-DU_CFG_PPP_ENABLE). * - * CONFIG_LWIP_PPP_SUPPORT - * CONFIG_ESP_NETIF_TCPIP_LWIP - * CONFIG_LWIP_PPP_PAP_SUPPORT + * You must also bring in the right ESP-IDF components through menuconfig + * by going to "Component Config" and making sure that the following are + * ticked: * - * If your network operator requires a user name and password - * along with the APN **AND** requires CHAP authentication, then - * you must also switch on CONFIG_LWIP_PPP_CHAP_SUPPORT. + * - "ESP NETIF Adapter --> TCP/IP Stack Library (LwIP) --> LwIP" + * - "LWIP --> Enable PAP support" + * - if your network operator requires a user name and password along + * with the APN **AND** requires CHAP authentication, then also + * "LWIP --> Enable CHAP support". * - * If you are minimising the components built into your main - * application then you may need to add the ESP-IDF component - * "esp_netif" to your component list. + * Alternatively, if you prefer to set things up manually, rather than + * through menuconfig, then switch on the following in your sdkconfig + * file: + * + * - CONFIG_LWIP_PPP_SUPPORT + * - CONFIG_ESP_NETIF_TCPIP_LWIP + * - CONFIG_LWIP_PPP_PAP_SUPPORT + * - CONFIG_LWIP_PPP_CHAP_SUPPORT (if required) + * + * ...and, if you are minimising the components built into your main + * application, you may need to add the ESP-IDF component "esp_netif" + * to your component list. * * The choice of [cellular] module is made at build time, see the * README.md for instructions. diff --git a/port/platform/esp-idf/README.md b/port/platform/esp-idf/README.md index b7576d73..957668ab 100644 --- a/port/platform/esp-idf/README.md +++ b/port/platform/esp-idf/README.md @@ -8,15 +8,21 @@ These directories provide the implementation of the porting layer on the Espress - [test](test): contains tests that use ESP-IDF application APIs to check out the integration of `ubxlib` into ESP-IDF, e.g. at PPP level beneath LWIP. # PPP-Level Integration With Cellular -`ubxlib` depends on very few ESP-IDF components (see the directories beneath this one for how to perform a build) but note that, if you wish to include a PPP-level integration at the base of the ESP-IDF LWIP stack, allowing use of native ESP-IDF clients (e.g. MQTT) with a cellular connection, then you must define `U_CFG_PPP_ENABLE` when building `ubxlib` and you must switch on the following in your `sdkconfig` file: +`ubxlib` depends on very few ESP-IDF components (see the directories beneath this one for how to perform a build) but note that, if you wish to include a PPP-level integration at the base of the ESP-IDF LWIP stack, allowing use of native ESP-IDF clients (e.g. MQTT) with a cellular connection, then you must define `U_CFG_PPP_ENABLE` when building `ubxlib` (e.g. you could do this by [including it in the U_FLAGS environment variable](mcu/esp32/README.md) which the `ubxlib` ESP-IDF component looks for). +You can find an example of how to make a sockets connection using native Espressif function calls in [main_ppp_espidf.c](/example/sockets/main_ppp_espidf.c). + +## SDK Config: `menuconfig` +To bring in the right ESP-IDF components and compilation flags, you can do that through `menuconfig` by going to `Component Config` and making sure that `ESP NETIF Adapter --> TCP/IP Stack Library (LwIP) --> LwIP` is ticked; also make sure that `LWIP --> Enable PAP support` and, if your network operator requires a user name and password along with the APN **AND** requires CHAP authentication, then also `LWIP --> Enable CHAP support`, are ticked. + +## SDK Config: Manual Configuration +Alternatively, if you prefer to do this by hand, make sure that your `sdkconfig` file contains: - `CONFIG_LWIP_PPP_SUPPORT` - `CONFIG_ESP_NETIF_TCPIP_LWIP` - `CONFIG_LWIP_PPP_PAP_SUPPORT` - if your network operator requires a user name and password along with the APN **AND** requires CHAP authentication, then also switch on `CONFIG_LWIP_PPP_CHAP_SUPPORT` -If you are minimising the components built into your main application then you should add the ESP-IDF component `esp_netif` to the list. If you fail to do this your code will either fail to link because `_g_esp_netif_netstack_default_ppp` could not be found, or the initial PPP LCP negotiation phase with the module will fail. - -Note that adding the above configuration items seems to increase task stack size requirements in general; beware! +...and, if you are minimising the components built into your main application then you should add the ESP-IDF component `esp_netif` to the list. If you fail to do this your code will either fail to link because `_g_esp_netif_netstack_default_ppp` could not be found, or the initial PPP LCP negotiation phase with the module will fail. -You must also call `esp_netif_init()` and `esp_event_loop_create_default()` at start of day from your application code, otherwise ESP-IDF will not work correctly or will go "bang" somewhere in the IP stack at the point that a cellular connection is made. You can find an example of how to do all this and make a sockets connection in [main_ppp_espidf.c](/example/sockets/main_ppp_espidf.c). \ No newline at end of file +## Run-time Configuration +You must also call `esp_netif_init()` and `esp_event_loop_create_default()` at start of day from your application code, otherwise ESP-IDF will not work correctly or will go "bang" somewhere in the IP stack at the point that a cellular connection is made. \ No newline at end of file