Improve docs on how to flash ESP32 board first time

[Honza Pobořil (iBobik)]

Hi,
I just started with Devicescript, trying to run Hello world to the ESP32-based board.

Created board config because it was not in the list:

{
    "$schema": "https://raw.githubusercontent.com/microsoft/devicescript-esp32/main/boards/esp32deviceconfig.schema.json",
    "devName": "Seeed Studio WT32-SC01",
    "productId": "0x35f9b6ef",
    "$description": "ESP32 Development board with a 3.5-inch 320x480 color capacitive multi-touch screen.",
    "archId": "esp32",
    "url": "https://www.seeedstudio.com/ESP32-Development-board-WT32-SC01-p-4735.html",
    "pins": {
      …
    }
}

Connected the board to the usb and clicked Connect Device in the VSCode, but it end up like this:

DeviceScript Development Server

using devs: v2.16.4, runtime: v2.16.4, node: v20.16.0 from .../node_modules/@devicescript/cli/built
devs: v2.16.4, runtime: v2.16.4, node: v20.16.0 running in ...
   dashboard  : http://127.0.0.1:8081/
   connection : http://127.0.0.1:8081/connect
   websocket  : ws://127.0.0.1:8081
   tcpsocket  : tcp://127.0.0.1:8082
   dbgserver  : tcp://127.0.0.1:8083
webclient: connected (ws1, 1 clients)
adding serial transport (requires "serialport" package)
serial error: JDUSB: can't connect, no HF2 nor JDUSB; port=/dev/tty.usbserial-02A9DD30, vendor: 10c4, product: ea60

I see the board have not been booted to the flash mode, it just immediately printed the error.

Do I guess correctly it requires Devicescript runtime flashed on the board first? I see no mention about it in the Getting started guide.

Aha, found mention about this process in the Troubleshouting. Maybe write this essential information in the fisrt steps?

Ok, so I used Clean flash form the UI, but then it cannot select the device:

$ node ./node_modules/.bin/devicescript flash --board seed_wt32_sc01 --install --clea
n --python /usr/bin/python3
using devs: v2.16.4, runtime: v2.16.4, node: v20.16.0 from /Users/Bobik/Applications/fiat-hell-atm/node_modules/@devicescript/cli/built
Viable serial ports:
/dev/cu.usbserial-02A9DD30: Silicon Labs 10c4:ea60
/dev/cu.SLAB_USBtoUART: Silicon Labs 10c4:ea60

fatal error: more than one port viable; use '--port /dev/cu.usbserial-02A9DD30' or similar

My device is visible on the multiple ports, does not know why… Ok, so select it:

$ node ./node_modules/.bin/devicescript flash --board seed_wt32_sc01 --install --clean --python /usr/bin/python3 --port /dev/cu.usbserial-02A9DD30
error: unknown option '--port'
$ node ./node_modules/.bin/devicescript --port /dev/cu.usbserial-02A9DD30 flash --board seed_wt32_sc01 --install --clean --python /usr/bin/python3
error: unknown option '--port'
$ node ./node_modules/.bin/devicescript flash --port /dev/cu.usbserial-02A9DD30 --board seed_wt32_sc01 --install --clean --python /usr/bin/python3
error: unknown option '--port'

So I checked sources if there is some bug and see there should be multiple flash command variants. Luckily I does not have to use my brain today to figure out how to call it correctly:

$ node ./node_modules/.bin/devicescript flash esp32 --board seed_wt32_sc01 --install  --python /usr/bin/python3 --port /dev/cu.usbserial-02A9DD30 

Then I clashed it similarly and wow, device is connected.