Skip to content

Make it easier to build and flash with jag #3025

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
addshore wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Make it easier to build and flash with jag #3025

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ compile_commands.json
*_mock.go
tedi_test.go
/third_party/benchmarks/java/*.class
wifi.json

**/node_modules/
/tools/lsp/client/npm-debug.log
Expand Down
51 changes: 42 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -314,18 +314,18 @@ in `build/esp32/firmware.envelope`:
make esp32
```

For other chip variants use the corresponding make target. For example, for the ESP32-C6 which would generate in `build/esp32c6/firmware.envelope`:

``` sh
make esp32c6
```

If you want to flash the generated firmware on your device, you can use the `firmware`
too. Internally, the `firmware` tool calls out to
[esptool](https://github.com/espressif/esptool)
so you need to install that one first.
You can also set the environment variable `ESPTOOL_PATH` to point
to a valid esptool (for example the one in the shipped esp-idf:
`export ESPTOOL_PATH=$PWD/third_party/esp-idf/components/esptool_py/esptool/esptool.py`).
Assuming your device is connected through `/dev/ttyUSB0`
you can then flash a device as follows:
tool. Internally it calls the bundled esptool from the esp-idf submodule.
Copy link
Copy Markdown
Member

@floitsch floitsch Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That only works if one has sourced the export.sh. Otherwise it doesn't. (I didn't know that until today...)

You can override this with the `ESPTOOL_PATH` environment variable if you want to use a different version of esptool.

``` sh
build/host/sdk/lib/toit/tool firmware -e build/esp32/firmware.envelope \
build/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \
Copy link
Copy Markdown
Member

@floitsch floitsch Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good change. thanks.

flash --port /dev/ttyUSB0 --baud 921600
```

Expand All @@ -340,6 +340,39 @@ build/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \
flash --port /dev/ttyUSB0 --baud 921600
```

### Flashing with Jaguar (live reloading)

To run Jaguar on your locally built firmware, compile the Jaguar service snapshot
Copy link
Copy Markdown
Member

@floitsch floitsch Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Normally I use JAG_TOIT_REPO_PATH from the Jaguar directory. When would you use the approach here instead of the env-variable one?

using your SDK (so the versions match) and install it as a container before flashing.
The Jaguar source lives in [toitlang/jaguar](https://github.com/toitlang/jaguar).
Set `JAG_PATH` to its location, or leave it unset to default to `../jaguar`
(i.e. checked out alongside this repo):

``` sh
JAG_PATH=${JAG_PATH:-../jaguar}

# Install jaguar's dependencies and compile its service snapshot
build/host/sdk/bin/toit pkg --project-root="$JAG_PATH" install
build/host/sdk/bin/toit compile -O2 --snapshot \
-o /tmp/jaguar.snapshot "$JAG_PATH/src/jaguar.toit"

# Add jaguar to the firmware envelope
build/host/sdk/bin/toit tool firmware \
-e build/esp32c6/firmware.envelope \
container install -o /tmp/firmware-jaguar.envelope \
jaguar /tmp/jaguar.snapshot

# Flash with WiFi credentials
# echo '{ "wifi": { "wifi.ssid": "YourSSID", "wifi.password": "YourPassword" } }' > wifi.json
build/host/sdk/bin/toit tool firmware \
-e /tmp/firmware-jaguar.envelope \
flash --config wifi.json --port /dev/ttyACM0 --baud 921600
```

> **Note:** The jaguar snapshot must be compiled with the same SDK version as the
> firmware envelope. `jag flash` alone uses jag's pre-built snapshot which is pinned
> to a release tag and will not match a local dev build's version suffix.

### Adding multiple containers

You can add more containers before you flash, so you firmware
Expand Down
14 changes: 1 addition & 13 deletions tools/firmware.toit
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1116,29 +1116,17 @@ flash invocation/cli.Invocation -> none:

esptool := find-esptool_

// The new esptool has deprecated underscores in some arguments.
Copy link
Copy Markdown
Member

@floitsch floitsch Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a fan of unconditionally removing the replacements.
Arch users have the latest esptool installed and that would yield errors. The 5.2 esptool version which is shipped with Toit handles the '-' just fine.

Compromise:
until we update the esp-idf we can make these replacements on whether JAG_TOIT_REPO_PATH is not set.

// TODO(floitsch): remove these replacements when the esp-idf has been updated
// to a version that uses the new arguments.
before-args := flashing["extra_esptool_args"]["before"]
after-args := flashing["extra_esptool_args"]["after"]
write-flash-args := flashing["write_flash_args"]
before-args = before-args.replace --all "default_reset" "default-reset"
before-args = before-args.replace --all "no_reset" "no-reset"
after-args = after-args.replace --all "hard_reset" "hard-reset"
after-args = after-args.replace --all "no_reset" "no-reset"
write-flash-args.map --in-place:
if it == "--flash_mode": "--flash-mode"
else if it == "--flash_size": "--flash-size"
else if it == "--flash_freq": "--flash-freq"
else: it

code := pipe.run-program esptool + [
"--port", port,
"--baud", "$baud",
"--chip", chip,
"--before", before-args,
"--after", after-args
] + [ "write-flash" ] + write-flash-args + partition-args
] + [ "write_flash" ] + write-flash-args + partition-args
if code != 0: exit 1
finally:
directory.rmdir --recursive tmp
Expand Down