Hopefully improved instructions.

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.

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