Draft diagram on startup details - feedback

[Josverl]

I was triggered by reading a comment from @robert-hh that main.py is not executed when running machine.reset()in raw-REPL
and I had various other tidbits drifting around on boot.mpy main.mpy not being executed from the filesystem.

To me a picture helps clarify matters , so that is what I coded (in Mermaid) .
but because I cannot test everything on all board, and there appear to be a few inconsistencies in the docs

I'm looking for:

• feedback on errors , incorrect interpretation
• readability / layout (currently using a flowchart , limited options on routing lines etc)
• things to add / omit (port specifics, dual core , dual VMs , .... ?)
• if this would be useful in the documentation ( or Wiki)

P.S. If you want to see the mermaid code, just use the copy button and paste somewhere

MicroPython reset and boot flow

This diagram summarizes reset entry points and the startup sequence described in
the reset/boot reference.

flowchart TD

    COLD["Cold start (power on)"]
    RESET["Reset button"]
    M_RESET["machine.reset()"]


    %% order of the main stages 
    HW --> VM
    HARD --> VM_INIT
    BOOT --> APPSTAGE --> REPLSTAGE
    %% SOFT_RESET --> VM_RESET


    COLD --> HARD
    RESET --> HARD
    M_RESET --> HARD

    subgraph HW["Hardware stage"]
        HARD["full MCU reset and hardware re-init"]
    end
    VM_INIT --> VM_RESET
    VM_RESET--> SAFE_MODE


%%-------------------------------------------------------------------
    subgraph VM["MicroPyton VM"]

        VM_INIT@{ shape: start, label: "VM init" }
        VM_RESET
        SAFE_MODE@{ shape: card, label: "Safe mode ? STM32 and renesas-ra only" }

        SAFE_MODE -- NORMAL --> BOOT
        SAFE_MODE -- SAFE --> REPL  
%%-------------------------------------------------------------------
        subgraph BOOT["Boot stage"]
            %%HAS_PBOOT(["_boot.py ?"])
            RUN_PBOOT@{ shape: card, label: "if exist: exec _boot.py" }
            %%HAS_BOOT(["boot.py ?"])
            RUN_BOOT@{ shape: card, label: "if exist: exec boot.py" }
        end
        RUN_PBOOT --> RUN_BOOT --> HAS_MAIN

%%-------------------------------------------------------------------
        subgraph APPSTAGE["Application stage"]
            HAS_MAIN@{ shape: card, label: "if exist: main.py, AND NOT in raw REPL"}
            subgraph YOURAPP["YOURAPP"]
                RUNMAIN["exec main.py"]
                A@{ shape: processes, label: "imported modules" }

            end
        end
        %% SOFT_RESET --> VM_RESET
        %%HAS_PBOOT -- Yes --> RUN_PBOOT --> HAS_BOOT
        %%HAS_PBOOT -- No --> HAS_BOOT
        %%HAS_BOOT -- Yes --> RUN_BOOT  --> HAS_MAIN
        %%HAS_BOOT -- No --> HAS_MAIN
        HAS_MAIN -- No --> REPL
        HAS_MAIN -- Yes --> RUNMAIN --> REPL
%%-------------------------------------------------------------------
        subgraph REPLSTAGE["REPL"]
            TO_RESET@{ shape: start }
            REPL["Interactive REPL"]
            RAWREPL["RAW REPL"]
            %% PASTEMODE["Paste mode"]
            
        end


        %% REPL 

        REPL -- CTRL-A -->  RAWREPL
        %%REPL -- CTRL-B --> CTRL_B
        %%REPL -- CTRL-C --> CTRL_C
        REPL -- CTRL-D --> TO_RESET


        RAWREPL -- CTRL-B --> REPL
        RAWREPL -- CTRL-D --> TO_RESET
    
        TO_RESET --> VM_RESET

    
        %% Paste mode not relevant for boot flow, but included for completeness
        %% REPL -- CTRL-E --> PASTEMODE
        %% PASTEMODE -- CTRL-D --> REPL
        %% PASTEMODE -- CTRL-C --> REPL
    end

Loading

Notes

• Hard reset entry points include cold power-on, reset button, and
  machine.reset().
• Soft reset entry points include machine.soft_reset() and Ctrl-D at REPL.
• _boot.py runs first (frozen in firmware), then boot.py, then main.py.
• If main.py is missing, or it exits, the REPL starts.
• A soft reset triggered from raw REPL mode skips main.py startup.
• Startup entry points on the filesystem are boot.py and main.py.
• If a frozen module named main.py exists, it is run first and cannot be
  overridden by filesystem main.py or main.mpy.
• For regular imports, frozen modules are usually overrideable by filesystem
  modules because filesystem paths are searched before .frozen by default
  sys.path order.
• boot.mpy/main.mpy on the filesystem are not auto-executed as startup
  entry points.
• To use .mpy at startup, import pre-compiled modules from boot.py or
  main.py, or freeze modules named boot.py/main.py into firmware.

port specifics

• Port-specific startup-script selection hooks:
  pyb.main(filename) is supported on stm32 and renesas-ra, and
  machine.main(filename) is supported on cc3200/WiPy. These are intended to
  be called from boot.py to choose which script is run in the main stage.

• Built-in safe-boot mode (skip boot.py/main.py) is implemented only on:
  stm32/pyboard, renesas-ra, and wipy/cc3200.

[davefes]

After several discussions about machine.reset() and a current search on AI doing machine.reset() is not the same as pressing the reset button.

machine.reset() on ESP32 MicroPython triggers a hard reset (equivalent to pressing the physical EN/RST button). It restarts the CPU, re-initializes most peripherals, and clears the RAM, functioning as a "cold boot". However, it may not clear all internal hardware states to their original power-on state.

[robert-hh]

Some ports set the watchdog timer to the shortest possible time and let the watchdog force a reset. That isost of the time identical to pull the reset pin. External circuitry of a board is of course not affected.

[Josverl]

the watchdog force a reset.

Did not think of that, would indeed be good to add

External circuitry of a board is not affected

Might indeed be good to mention that , or add it to the diagram, but that might get to crowded.

[Josverl]

machine.reset() is not the same as pressing the reset button.

Good point. I'll need to add that to the diagram.