How to migrate IDF project to ADF project (or: how to incorporate ADF into an IDF project)?

[sb_espressif]

Hi, I have a project I've sketched out using esp-idf v 5.1.2 in vscode; it works great, and I'd now like to incorporate some audio functionality. I'm trying to understand what steps I need to take to do this without starting from an example project.

I can look at the example projects of course, and refer to them for audio pipeline code, but before I get to that stage I'm just trying to make my current 'vanilla' idf project 'aware' of ADF. It's not at all clear to me from the current documentation how I might do this.

Some things I tried:
I added this to my top-level project CMakeLists.txt:

Code: Select all

list(APPEND EXTRA_COMPONENT_DIRS "/path/to/esp-adf/esp-adf-v2.6/components")
include($ENV{ADF_PATH}/CMakeLists.txt)

I don't know if the above two lines are redundant to one another. When I try to build my project, I now see these errors:

Code: Select all

/dev/github/esp-adf/esp-adf-v2.6/components/esp_peripherals/include/esp_peripherals.h:78:32: error: unknown type name 'xTimerHandle'; did you mean 'TimerHandle_t'?
   78 | typedef void (*timer_callback)(xTimerHandle tmr);
      |                                ^~~~~~~~~~~~
      |                                TimerHandle_t
/dev/github/esp-adf/esp-adf-v2.6/components/esp_peripherals/include/esp_peripherals.h:371:88: error: unknown type name 'timer_callback'
  371 | esp_err_t esp_periph_start_timer(esp_periph_handle_t periph, TickType_t interval_tick, timer_callback callback);
      |                                                                                        ^~~~~~~~~~~~~~
[956/1165] Building C object esp-idf/esp_dispatcher/CMakeFiles/__idf_esp_dispatcher.dir/periph_service.c.obj
ninja: build stopped: subcommand failed.

I can see ADF options showing up in menuconfig, so I think I might be on the right track, but the above errors make it clear I'm not all the way properly set up yet. Can anyone help?

Again I'm using IDF 5.1.2, and ADF 2.6. I *think* these two are compatible?

Something that's especially unclear to me is that esp-adf seems to contain a (entire?) copy of esp-idf within it? I would love to understand this better - is esp-adf meant to exist completely apart from an existing esp-idf install? I see a few youtube videos that suggest not setting IDF-path to avoid compiler errors like the above, but this seems less like an official recommendation and more like hackery (which I would like to avoid).

[j1mmy3]

Again I'm using IDF 5.1.2, and ADF 2.6. I *think* these two are compatible?

I will say right off, I just got my first ESP board a week ago so I know very little myself. That being said, I just got the example program to work (after about 4 days! lol) and yes, `IDF 5.1.2` and `ADF 2.6` are compatible. I used both of those. I never was able to get the master ADF to work but 2.6 worked for me.

Something that's especially unclear to me is that esp-adf seems to contain a (entire?) copy of esp-idf within it? I would love to understand this better - is esp-adf meant to exist completely apart from an existing esp-idf install?

I struggled with this as well. And sort of by chance, some research and help from GitHub Copilot I did not use the `export.sh` from the ADF framework and instead used the one from the IDF framework. This is what worked for me but that is honestly about all I can say about it. I am sure others have a much better explanation. Lastly, I also decided *not* to set the IDF path as well, like you've heard already it's to avoid the compiler errors..but I think you might have a good point on hackery as I have NO IDEA why that worked. lol

Anyways, I mainly wanted to say that `IDF 5.1.2` and `ADF 2.6` worked well together for me and got a bit long-winded....as I just got it all working tonight and was relieved I got to that point!

[sb_espressif]

Hey thanks! I'd sort of given up that anyone might chime in here. To try to offer some help back, here are some things I've learned from banging around myself with ADF:

--I *think* ADF includes a full copy of IDF within itself to ensure compatibility. It is not strictly necessary to use it, but seems to be there for convenience.
--The IDF within ADF is a "git submodule". This phrase is one that was new to me, and it's important - it implies that 1) the IDF within ADF is a "branch within a branch" as far as git goes, which means 2) its version can be controlled independently of ADF if you know enough git jiujitsu (which I had to learn to get to this point).
--You can use the following git commands to understand what version of IDF is actually being installed within ADF:

git submodule foreach 'echo `git rev-parse --short HEAD` $path'
git submodule foreach 'echo $path: `git rev-parse HEAD`'

These just return checkin hashes though, not tags.
To understand tags (which are used to describe versions),
we need to go into the esp-adf/esp-idf submodule, then do:

git describe --tags --abbrev=0

Doing this, we learn that the IDF included inside ADF 2.6 is:
v4.4.4


--There is a top-level CMakelists.txt file inside the ADF folder that overrides IDF_PATH to be "$ENV{ADF_PATH}/esp-idf/". This part was very useful for me to help me understand what's going on - adding ADF to a project effectively overrides the IDF_PATH to be that of the IDF version within ADF.
--I think the docs for ADF that instruct you first to set up IDF and then ADF misleadingly imply there is a relationship between the two; in reality, I think the IDF setup is mostly meant to get the rest of the toolchain (the xtensa compiler and other stuff esp needs) into place - the IDF itself gets superceded in the end.

Finally, if you're like me and want to be pedantic about understanding what version of what you're using, you can do this:

cd esp-adf
git checkout v2.6 // This sets the ADF version, but not any submodules
cd ./esp-idf
git clean -fdX // remove any untracked changes.
git reset --hard v5.1.2 // This sets the internal-to-adf IDF version to 5.1.2
git clean -fdX // re-clean, to remove any cruft directories.

At this point, theoretically we should have ADF at v2.6,
and IDF at 5.1.2.

Beyond this, I have found ADF to be quite inscrutable, and it's been very hard to find or get help learning it. So I've given up and moved forward with other audio libraries for now...I think working with ADF feels quite a bit more difficult to understand than the (relatively easy-to-learn time I've had with) IDF. For my stuff, I need to get into the guts of audio stuff (doing resampling, time stretching and other signal processing stuff), and ADF *seems* like it might not be designed for that.

Anyway, thanks again for chiming in, makes this feel a bit less lonely. Good luck!

[hyuan75]

I am developing application with ESP32, I am also new to ESP. So, following official guide, using Visual Code installed IDF firstly and developed several applications wit IDF to practice toolchain.
Now I need to add audio features(speech recognition) to application , so installed ADF(v2.6) manually following guide.
My original IDF was installed with VSCode extension which is v5.2.1, under C:\Users\hyuan\esp\esp-idf, ADF was installed under C:\Users\hyuan\esp\esp-adf, and adf includes a integrated IDF(v4.4.4).

The problem for me is , when I created application from example, building system always use my first installed IDF(v5.2.1) , how I can instruct building system(under VSCode) to use the integrated IDF(v4.4.4) , checked menuconfig using VSCode , there's no setting can allow me to set alternative IDF path to point to integrated IDF(v4.4.4) ?

Thanks

[hyuan75]

Seems I should change esp idf path win , in vscode UI setting(command plate) , to C:\Users\hyuan\esp\esp-adf\esp-idf which will guide building system to use IDF within ADF.

[YoannJS]

Hi @sb_espressif,

It may be too late, but I just found out your post as I faced the exact same issue, and turns out that you only need to enable "configENABLE_BACKWARD_COMPATIBILITY" in sdkconfig to remove the error. I found this by comparing a working ADF example to my main project, previously using only IDF, and both using the same IDF version.

[vigyanabikshu]

Than you. With ESP IDF5.1.3/ADF2.6 I was struggling compiling adf code. enabling "configENABLE_BACKWARD_COMPATIBILITY" in sdkconfig worked.