Bookmark Your Docs

The ESP-IDF is constantly evolving and changing. As such, it’s really important that you lock your firmware code to a specific version so you aren’t caught off guard when IDF changes. Additionally, it’s really important to make sure you are looking at the docs that match the version you are locked to. Not doing so can waste precious time.

SNTP Example

This is best illustrated with a simple example. Here is the 4.4.4 example for SNTP

static void initialize_sntp(void)
{
    ESP_LOGI(TAG, "Initializing SNTP");
    sntp_setoperatingmode(SNTP_OPMODE_POLL);
    sntp_setservername(0, "pool.ntp.org");
    sntp_set_time_sync_notification_cb(time_sync_notification_cb);
#ifdef CONFIG_SNTP_TIME_SYNC_METHOD_SMOOTH
    sntp_set_sync_mode(SNTP_SYNC_MODE_SMOOTH);
#endif
    sntp_init();
}

And here is the 4.4.5 example

static void initialize_sntp(void)
{
    ESP_LOGI(TAG, "Initializing SNTP");
    esp_sntp_setoperatingmode(ESP_SNTP_OPMODE_POLL);
    esp_sntp_setservername(0, "pool.ntp.org");
    sntp_set_time_sync_notification_cb(time_sync_notification_cb);
#ifdef CONFIG_SNTP_TIME_SYNC_METHOD_SMOOTH
    sntp_set_sync_mode(SNTP_SYNC_MODE_SMOOTH);
#endif
    esp_sntp_init();
}

It’s one minor patch version newer but notice they refactored the API. So if, at the time, you were going to the “latest” docs but were locked to 4.4.4 and tried to use the sample code it won’t compile and you would have wasted time trying to figure out why.

While the change was technically a fix it altered the recommended API for doing SNTP. Even if you had looked at the v4.4.5 Release Notes you would not have seen any mention of SNTP as the commit is mentioned as “esp-netif: Fixed thread-safety violations when accessing TCP/IP core functionality”. So unless you look through every commit you would not know this change occurred. So if you are looking at the wrong version of the documentation you will also, by association, be looking at the wrong linked sample code.

The fix for this is quite easy. In addition to locking your version of IDF you should also lock your version of the docs. This is easily achieved by bookmarking the version of the docs that match your IDF version.

Conclusion

This very simple practice will ensure you are always looking at the correct documentation that matches your version of IDF. It will save you time when referencing the docs and will prevent you from going down a sample rabbit hole that doesn’t apply to you.

Did you find this tip helpful? Join the community and get more content just like it in the weekly Production ESP32 newsletter. Concise, actionable content right in your inbox.