improve documentation

[Adrianotiger]

Checklist

• Checked the issue tracker for similar issues to ensure this is not a duplicate
• Read the documentation to confirm the issue is not addressed there and your configuration is set correctly
• Tested with the latest version to ensure the issue hasn't been fixed

How often does this bug occurs?

always

Expected behavior

I should be able to program the flash also with ESPLoader.connect and ESPLoader.detectChip

Actual behavior (suspected bug)

If I use detectChip, I am not able to upload the bin file. If I use connect, I am not able to finish the flash (serial error appears at the end).
But no info is given to see what function should be used to connect the ESP. main() is not a user friendly word but it is the function you need to use if you want use writeFlash.

Error logs or terminal output

>> With `ESPLoader.connect()` or `ESPLoader.detectChip()`: 
Debug: Chip Magic 9
Connected to chip: ESP32-S3
Debug: flash_id
Debug: check_command write target memory
Debug: check_command write target memory
Debug: check_command write target memory
Debug: check_command write target memory
Debug: check_command write target memory
Debug: check_command write target memory
Debug: check_command write target memory
Flash size : undefined
Debug: EspLoader program
Debug: Data Length 623552
Debug: Image Length 623552
Debug: _update_image_flash_params keep undefined undefined
Debug: Image MD5 4ec9a3adbd3293cf34667d70c2106cf7
Compressed 623552 bytes to 341947...
Debug: check_command enter compressed flash mode
Took 0.0s to erase flash block
Debug: Write loop 65536 0 21
Writing at 0x10000... (4%)
Debug: flash_defl_block 78 da
Debug: check_command write compressed data to flash after seq 0
Debug: Write loop 65536 1 21
Writing at 0x1a788... (9%)
Debug: flash_defl_block f5 4a
Debug: check_command write compressed data to flash after seq 1
Debug: Write loop 65536 2 21
Writing at 0x26f65... (14%)
Debug: flash_defl_block 4e 4d
Debug: check_command write compressed data to flash after seq 2
Debug: Write loop 65536 3 21
Writing at 0x34754... (19%)
Debug: flash_defl_block d7 69
Debug: check_command write compressed data to flash after seq 3
Debug: Write loop 65536 4 21
Writing at 0x41ad4... (23%)
Debug: flash_defl_block 3 e6
Debug: check_command write compressed data to flash after seq 4
Debug: Write loop 65536 5 21
Writing at 0x470fb... (28%)
Debug: flash_defl_block 61 13
Debug: check_command write compressed data to flash after seq 5
Debug: Write loop 65536 6 21
Writing at 0x4ca9e... (33%)
Debug: flash_defl_block 90 60
Debug: check_command write compressed data to flash after seq 6
Debug: Write loop 65536 7 21
Writing at 0x52cd1... (38%)
Debug: flash_defl_block d6 27
Debug: check_command write compressed data to flash after seq 7
Debug: Write loop 65536 8 21
Writing at 0x58db5... (42%)
Debug: flash_defl_block 5 4e
Debug: check_command write compressed data to flash after seq 8
Debug: Write loop 65536 9 21
Writing at 0x5e9ed... (47%)
Debug: flash_defl_block c4 f2
Debug: check_command write compressed data to flash after seq 9
Debug: Write loop 65536 10 21
Writing at 0x644d8... (52%)
Debug: flash_defl_block 9d 59
Debug: check_command write compressed data to flash after seq 10
Debug: Write loop 65536 11 21
Writing at 0x69ac3... (57%)
Debug: flash_defl_block eb 25
Debug: check_command write compressed data to flash after seq 11
Debug: Write loop 65536 12 21
Writing at 0x6fa57... (61%)
Debug: flash_defl_block 3d e3
Debug: check_command write compressed data to flash after seq 12
Debug: Write loop 65536 13 21
Writing at 0x74fdc... (66%)
Debug: flash_defl_block fc 30
Debug: check_command write compressed data to flash after seq 13
Debug: Write loop 65536 14 21
Writing at 0x7a50f... (71%)
Debug: flash_defl_block f5 9
Debug: check_command write compressed data to flash after seq 14
Debug: Write loop 65536 15 21
Writing at 0x80222... (76%)
Debug: flash_defl_block ca bf
Debug: check_command write compressed data to flash after seq 15
Debug: Write loop 65536 16 21
Writing at 0x86833... (80%)
Debug: flash_defl_block ce f3
Debug: check_command write compressed data to flash after seq 16
Debug: Write loop 65536 17 21
Writing at 0x90e98... (85%)
Debug: flash_defl_block 62 60
Debug: check_command write compressed data to flash after seq 17
Debug: Write loop 65536 18 21
Writing at 0x97670... (90%)
Debug: flash_defl_block 75 d8
Debug: check_command write compressed data to flash after seq 18
Debug: Write loop 65536 19 21
Writing at 0x9cfb4... (95%)
Debug: flash_defl_block e7 f
Debug: check_command write compressed data to flash after seq 19
Debug: Write loop 65536 20 21
Writing at 0xa2bf2... (100%)
Debug: flash_defl_block b7 bf
Debug: check_command write compressed data to flash after seq 20
Wrote 623552 bytes (341947 compressed) at 0x10000 in 30.402 seconds.
Debug: check_command calculate md5sum
...
TRACE 32782.000 Received full packet: 01110400ffffff0001050000
Error reading from serial port: Error: Read timeout exceeded
TRACE 37786.000 No serial data received.

Steps to reproduce the behavior

Use the example and replace main() with connect() or detectChip()

Project release version

0.5.6

System architecture

Intel/AMD 64-bit (modern PC, older Mac)

Operating system

Windows

Operating system version

10

Shell

ZSH

Additional context

No response

[brianignacio5]

Why do you expect ESPLoader.connect and ESPLoader.detectChip to be able to write to your device flash ?

I do agree we need to improve the documentation as the example alone, while showing how the esptool-js can be used is not enough. There is also API documentation here https://espressif.github.io/esptool-js/docs/index.html but also the function documentation could be improved as well.

[Adrianotiger]

Why do you expect ESPLoader.connect and ESPLoader.detectChip to be able to write to your device flash ?

I do agree we need to improve the documentation as the example alone, while showing how the esptool-js can be used is not enough. There is also API documentation here https://espressif.github.io/esptool-js/docs/index.html but also the function documentation could be improved as well.

Yes, I started with this API documentation. Once everything was implemented, you need to connect the device. Normally, you do it with the "connect" method.
Once connected, you should be able to write and read information as write and read blocks.

But this is not possible. So I found an example, where you can read more, thanks to detectChip, but also with this method, it was not possible.

There is only 1 example that show how to write a flash block and I still doesn't know why you need to call main instead of connect.

[brianignacio5]

Did you see the example project in this repository ? https://github.com/espressif/esptool-js/tree/main/examples/typescript

[Adrianotiger]

Did you see the example project in this repository? https://github.com/espressif/esptool-js/tree/main/examples/typescript

Yes. And thanks to this example I finally was able to burn the flash block.

I am sure, if you work with this tool, you understand what to use and why. But I am a "noob" and just was trying to use it to burn a block. After reading the documentation, I was thinking that "connect" should be the right function to use. But it isn't and there is no way to find why it isn't. Ever if you try to burn the flash, you just get a notification that the serial port does not give any answer.

I know, that with "connect", "detectChip" and "main", the ESP will be connected over the "Transport". But what is the difference between these 3 connections? Why is it possible to connect it with all 3 functions and why is it not possible to write a flash block once connected with the esptool-js?