version.txt file format ?

[Baldhead]

Hi,

I am trying to put a app version information inside "version.txt" file located at $(PROJECT_PATH)/version.txt, like this:
https://docs.espressif.com/projects/esp ... pp-version

I only put a number inside file "version.txt" to test and not work.

How should this file be formatted ?
ie:
v2.1
2.1
Does it need to have any terminator character in this string ?

Do i need to enable something for esp-idf to use this file as the app version source ?

I tested like this:

Code: Select all

C:\.espressif\python_env\idf5.1_py3.11_env\Scripts\python.exe c:\esp-idf\components\esptool_py\esptool\esptool.py --chip esp32s3 image_info build/wss_server.bin
esptool.py v4.6.2
File size: 1410016 (bytes)
Image version: 1
Entry point: 40379800
5 segments

Segment 1: len 0x8711c load 0x3c0c0020 file_offs 0x00000018 [DROM]
Segment 2: len 0x05444 load 0x3fc9cb00 file_offs 0x0008713c [BYTE_ACCESSIBLE,MEM_INTERNAL,DRAM]
Segment 3: len 0x03a88 load 0x40378000 file_offs 0x0008c588 [MEM_INTERNAL,IRAM]
Segment 4: len 0xb7400 load 0x42000020 file_offs 0x00090018 [IROM]
Segment 5: len 0x10fac load 0x4037ba88 file_offs 0x00147420 [MEM_INTERNAL,IRAM]
Checksum: e9 (valid)

[MicroController]

Works for me. I put "1.2.3.4" (w/o the quotes, no newline or other terminator) into "version.txt" and upon boot I get

Code: Select all

...
I (177) cpu_start: App version:      1.2.3.4
...

Since esp_app_desc_t::version is a char[32] you can write any string <= 31 characters into the version.

[ESP_igrr]

Please try adding --version 2 after image_info command, then it should print the app metadata info (https://docs.espressif.com/projects/esp ... image-info)

[Baldhead]

Please try adding --version 2 after image_info command, then it should print the app metadata info (https://docs.espressif.com/projects/esp ... image-info)

Hi @ESP_igrr,

Using --version 2 does the trick:

Code: Select all

PS C:\esp32-Proj\WSS_SERVER_AND_UI_INTEGRATION_S3_12-12-2022> C:\.espressif\python_env\idf5.1_py3.11_env\Scripts\python.exe C:\esp-idf\components\esptool_py\esptool\esptool.py image_info --version 2 build/wss_server.bin
esptool.py v4.6.2
File size: 1409984 (bytes)
Detected image type: ESP32-S3

ESP32-S3 image header
=====================
Image version: 1
Entry point: 0x40379804
Segments: 5
Flash size: 32MB
Flash freq: 80m
Flash mode: DOUT

ESP32-S3 extended image header
==============================
WP pin: 0xee (disabled)
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
Chip ID: 9 (ESP32-S3)
Minimal chip revision: v0.0, (legacy min_rev = 0)
Maximal chip revision: v0.99

Segments information
====================
Segment   Length   Load addr   File offs  Memory types
-------  -------  ----------  ----------  ------------
      1  0x870ec  0x3c0c0020  0x00000018  DROM
      2  0x05444  0x3fc9cb00  0x0008710c  BYTE_ACCESSIBLE, MEM_INTERNAL, DRAM
      3  0x03ab8  0x40378000  0x0008c558  MEM_INTERNAL, IRAM
      4  0xb73c8  0x42000020  0x00090018  IROM
      5  0x10fa8  0x4037bab8  0x001473e8  MEM_INTERNAL, IRAM

ESP32-S3 image footer
=====================
Checksum: 0xb4 (valid)
Validation hash: 9f00abaf2fed6410b881d5c20e43a433f2889f84177eb8f9b649b22ce5912643 (valid)

Application information
=======================
Project name: wss_server
App version: 1.0.0
Compile time: Jul 23 2023 01:00:11
ELF file SHA256: ef703b110f814aff749388f8f3f44c1d6f4357de1972fc6fb59698db2dfde8a2
ESP-IDF: v5.1
Secure version: 0

The ota update use image version i think, i didn't know there was app version and image version.

How to "automate" image version ?

OTA example from here https://github.com/espressif/esp-idf/bl ... 91C1-L91C1

Code: Select all

#if CONFIG_FIRMWARE_VERSION_CHECK  
    if( memcmp(new_app_info->version, running_app_info.version, sizeof(new_app_info->version)) == 0 )
    {
        ESP_LOGW(TAG, "Current running version is the same as a new. We will not continue the update.");
        return ESP_FAIL;
    }
#endif

[ESP_igrr]

The ota update use image version i think, i didn't know there was app version and image version.

How to "automate" image version ?

I'm sorry, I can't understand this part.

The line of code you are pointing to uses the "version" field of esp_app_desc_t structure. This field can be set in a variety of ways, including version.txt which you have tried above. When you set the app version using version.txt, the corresponding field in app metadata structure will be set to the same value.

The "--version 2" argument I mentioned in the previous post is not related to application version or image version, it is just the version of the "image_info" command output.

[Baldhead]

The ota update use image version i think, i didn't know there was app version and image version.

How to "automate" image version ?

I'm sorry, I can't understand this part.

The line of code you are pointing to uses the "version" field of esp_app_desc_t structure. This field can be set in a variety of ways, including version.txt which you have tried above. When you set the app version using version.txt, the corresponding field in app metadata structure will be set to the same value.

The "--version 2" argument I mentioned in the previous post is not related to application version or image version, it is just the version of the "image_info" command output.

Automate i mean for future production purposes.

How to specify app version and image version in "version.txt" file ?
I think it is key value maybe or json format.
What key i should i use ?
What the file format as in the title of this issue/question.

ie: Inside "version.txt" file

Code: Select all

app_version: 1.0
image_version: 1.2.1

[ESP_igrr]

Sorry, still can't understand what is the "image version" you are mentioning. Could you explain what is the difference between "app version" and "image version"?

(As far as esp-idf is concerned, there is only "app version". Hence I am confused about the term "image version".)

Regarding automation: I would actually recommend to not use version.txt at all, and use Git tags for versioning the app. If version.txt doesn't exist, ESP-IDF determines the version of your app using "git describe" command. This is compatible with most Git workflows, as well as release processes in Github, Gitlab, etc., which rely on Git tags.

[Baldhead]

Sorry, still can't understand what is the "image version" you are mentioning. Could you explain what is the difference between "app version" and "image version"?

(As far as esp-idf is concerned, there is only "app version". Hence I am confused about the term "image version".)

Regarding automation: I would actually recommend to not use version.txt at all, and use Git tags for versioning the app. If version.txt doesn't exist, ESP-IDF determines the version of your app using "git describe" command. This is compatible with most Git workflows, as well as release processes in Github, Gitlab, etc., which rely on Git tags.

Could you explain what is the difference between "app version" and "image version" ?
I don't know either, I thought it was the same thing, maybe it can just update the apps, without changing the rest of the image.

Inside this appear: "Image version: 1" and "App version: 1.0.0"

Code: Select all

PS C:\esp32-Proj\WSS_SERVER_AND_UI_INTEGRATION_S3_12-12-2022> C:\.espressif\python_env\idf5.1_py3.11_env\Scripts\python.exe C:\esp-idf\components\esptool_py\esptool\esptool.py image_info --version 2 build/wss_server.bin
esptool.py v4.6.2
File size: 1409984 (bytes)
Detected image type: ESP32-S3

ESP32-S3 image header
=====================
Image version: 1
Entry point: 0x40379804
Segments: 5
Flash size: 32MB
Flash freq: 80m
Flash mode: DOUT

ESP32-S3 extended image header
==============================
WP pin: 0xee (disabled)
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
Chip ID: 9 (ESP32-S3)
Minimal chip revision: v0.0, (legacy min_rev = 0)
Maximal chip revision: v0.99

Segments information
====================
Segment   Length   Load addr   File offs  Memory types
-------  -------  ----------  ----------  ------------
      1  0x870ec  0x3c0c0020  0x00000018  DROM
      2  0x05444  0x3fc9cb00  0x0008710c  BYTE_ACCESSIBLE, MEM_INTERNAL, DRAM
      3  0x03ab8  0x40378000  0x0008c558  MEM_INTERNAL, IRAM
      4  0xb73c8  0x42000020  0x00090018  IROM
      5  0x10fa8  0x4037bab8  0x001473e8  MEM_INTERNAL, IRAM

ESP32-S3 image footer
=====================
Checksum: 0xb4 (valid)
Validation hash: 9f00abaf2fed6410b881d5c20e43a433f2889f84177eb8f9b649b22ce5912643 (valid)

Application information
=======================
Project name: wss_server
App version: 1.0.0
Compile time: Jul 23 2023 01:00:11
ELF file SHA256: ef703b110f814aff749388f8f3f44c1d6f4357de1972fc6fb59698db2dfde8a2
ESP-IDF: v5.1
Secure version: 0

Regarding automation: I would actually recommend to not use version.txt at all, and use Git tags for versioning the app. If version.txt doesn't exist, ESP-IDF determines the version of your app using "git describe" command. This is compatible with most Git workflows, as well as release processes in Github, Gitlab, etc., which rely on Git tags.

Thank's for the suggestion, but if i use git describe inside my project folder, doesn't work.
Sorry for my ignorance, but i don't know how to work with git and versioning yet.

Code: Select all

C:\esp32-Proj\WSS_SERVER_AND_UI_INTEGRATION_S3_12-12-2022>git describe
fatal: not a git repository (or any of the parent directories): .git

[ESP_igrr]

ESP32-S3 image header
=====================
Image version: 1

This is just a version of the application image format. It is not related to the version of your application. It doesn't change when you make a new version of the application. It would only change if Espressif decided to modify the format in which apps are stored. You can ignore it, as it's a number only relevant internally in ESP-IDF and esptool.

Application information
=======================
Project name: wss_server
App version: 1.0.0

This is the actual version of the application, it can be used when checking for an OTA update.

Sorry for my ignorance, but i don't know how to work with git and versioning yet.

Code: Select all

C:\esp32-Proj\WSS_SERVER_AND_UI_INTEGRATION_S3_12-12-2022>git describe
fatal: not a git repository (or any of the parent directories): .git

That's totally fine, Git can take a bit of time to learn! Github has pretty nice tutorials about Git, which are valid whether you are using Github for version control or not.

If you can't use Git tags for versioning, you can still use version.txt file or you can set `PROJECT_VER` variable in project CMakeLists.txt file.