Design intent of filenaming for sdk/examples/esp_idf/common

I’m implementing the golioth-firmware-sdk, specifically for the ESP32S3, and I’m trying to wrap my head around the design intent for the files within the directory golioth-firmware-sdk/examples/esp_idf/common.

As in, there are files such as nvs.h/c, shell.c/h, wifi.c/h, and ble.c/h. However, those file names are also used within the esp-idf, which could cause some confusion when doing includes.

What is the intent for these files?

At this point, I’ve used the golioth_basics file as a starting point to pick and choose which features I need. From there, I’ve copied the common directory into the same directory, and renamed them all with golioth_ prefixes, to prevent any naming collisions, as well as many of the internal functions. This seems less than ideal because the contents of nvs/wifi/shell are just a repackaging of mostly ESP-IDF functions, with a couple Golioth specific facets.

Hey Seth,

Those files contains bits of helper code that we found were useful when developing the examples. These aren’t really related to Golioth directly, but they provide some helpful scaffolding around ESP-IDF features that we need in order to create a usable application to showcase specific usage of the SDK. Things like providing a way to input PSK/PSK-ID, or factoring out common code for wifi initialization.

These files aren’t required to use the SDK, but they are one way of doing things. Our expectation is that customers will implement their own shell commands, for example, or initialize WiFi in the way that makes the most sense for their product. And if our code is useful, they’re free to copy it into their own project, just as it sounds like you have done. The whole SDK is Apache licensed.

I agree, the naming conflicts with the ESP-IDF files are less than great. We’ll see about clearing that up.

As a general note, we’ve recently gotten some bandwidth to make improvements to the ESP-IDF example experience. We’re working to create additional, smaller examples for each service, and remove things that aren’t relevant to Golioth (for example, the BLE service to provision WiFi credentials is a cool piece of kit, but out of place). As part of that work, we’ll also look at how to make the common helper code more useful and easier to integrate.

Thanks for the feedback as always! If there’s any more specific suggestions or comments around these files and how they could work better for you, we’d love to hear them :slightly_smiling_face:

Ok, thanks for clearing that up. I’ll start migrating those into the appropriate places.

I’d say that starting with renaming those files would be best. Maybe something along the lines of golioth_wifi_helper.c/h to make things clearer.

Also, adding some comments within the files, similar to the comments in golioth_basics, would be very helpful.

Finally, a README about the intent within the common folder would be great.

Great suggestions, thanks Seth!

1 Like