DOCSEARCHbyAlgolia
Submit Docs

Jaguar for Toit

repository·main·Indexed 42 days ago

https://github.com/toitlang/jaguar

A live-reloading development tool for the ESP32 microcontroller using the Toit language. Jaguar enables developers to update and restart Toit code over WiFi or via a UART proxy in seconds, speeding up the development cycle compared to traditional serial flashing. It includes a CLI (`jag`) for flashing firmware, managing containers for system services and drivers, monitoring serial output, and compiling Toit source code into snapshot files.

Tokens
14.7K
Snippets
67
Records
87
Agent score
50%

What's inside Jaguar

  1. Build Jaguar from source

    main

    To build Jaguar and the underlying Toit implementation manually, follow these steps. This assumes you are in the root of the Jaguar repository.

    1. Set the Toit repository path:
      export JAG_TOIT_REPO_PATH=$PWD/third_party/toit
    2. Setup ESP-IDF environment: Use the patched ESP-IDF provided within the Jaguar repository to ensure compatibility:
      source $JAG_TOIT_REPO_PATH/third_party/esp-idf/export.sh
    3. Compile: Run make to build the SDK, download Toit dependencies, and build both the host executable and the device-side Toit program.
    4. Usage: After building, use the binary in the build/ directory.
    export JAG_TOIT_REPO_PATH=$PWD/third_party/toit
source $JAG_TOIT_REPO_PATH/third_party/esp-idf/export.sh
make

# Using the built binary
build/jag flash
sleep 3
build/jag scan
build/jag run $JAG_TOIT_REPO_PATH/examples/hello.toit
build/jag monitor

  2. Install the Jaguar CLI

    main

    Install the jag binary using your platform's package manager or by downloading precompiled binaries.

    macOS (Homebrew):

    brew install jaguar

    Windows (winget):

    winget install --id=Toit.Jaguar -e

    Arch Linux (AUR):

    yay install jaguar-bin

    Debian/Ubuntu: Download the .deb package from the releases page and run:

    sudo dpkg -i jaguar_*.deb

    If using precompiled archives (zip, dmg, tgz), unpack them and ensure the jag or jag.exe binary is in your PATH.

    brew install jaguar

  3. Configure Linux serial port permissions for flashing

    main

    To flash devices via serial, you must have permission to access the device (e.g., /dev/ttyUSB0). On Linux, this typically requires being a member of the uucp or dialout group.

    1. Check your current groups and the device owner:
      groups
ls -g /dev/ttyUSB0
    2. If you lack permission, add your user to the dialout group:
      sudo usermod -aG dialout $USER
    3. Apply changes by logging out and back in, or use newgrp dialout to apply them to the current session.
    sudo usermod -aG dialout $USER
newgrp dialout

  4. Install the Jaguar CLI via Go

    main

    You can install the jag command line tool using go install.

    Prerequisites:

    • Go development environment (version 1.16+).
    • $HOME/go/bin or %USERPROFILE%\go\bin must be in your PATH.
    go install github.com/toitlang/jaguar/cmd/jag@latest

  5. Disable Jaguar's WiFi for application compatibility

    main

    If your Toit application needs to control the WiFi (e.g., setting up a Soft AP), Jaguar's own WiFi usage may cause conflicts. You can temporarily disable Jaguar's WiFi using the -D jag.wifi=false flag.

    When using this flag, Jaguar defaults to a 10-second timeout to prevent the device from becoming permanently inaccessible. You can customize this timeout using -D jag.timeout.

    Note on Timeouts:

    • Timeouts have no effect if a UART proxy is active (because Jaguar remains accessible via the proxy).
    • Timeouts have no effect in UART-only mode.
    • For installed containers, the container starts when the device boots and runs to completion before Jaguar attempts to connect to WiFi, allowing the container to control the WiFi first.
    # Run a script without Jaguar using WiFi
jag run -D jag.wifi=false softap.toit

# Run a script with a specific timeout (e.g., 5 minutes)
jag run -D jag.wifi=false -D jag.timeout=5m

# Install a container that controls WiFi first
jag container install -D jag.wifi=false -D jag.timeout=20s softap softap.toit

  6. Flash Jaguar to ESP32 via Serial

    main

    Connect your ESP32 via a serial cable and run jag flash. The command will prompt you for the serial port and WiFi credentials.

    Options:

    • --disable-udp: Keeps the HTTP endpoint enabled but stops broadcasting UDP device-discovery advertisements. Use this with jag firmware update as well.
    • --uart-only: Skips WiFi configuration and enables the UART endpoint instead (see Using the UART proxy).
    • --uart-endpoint-baud=<baud>: Sets the baud rate for the UART endpoint (e.g., 921600).
    jag flash

  7. Use the UART proxy for Jaguar commands

    main

    The UART proxy allows you to send Jaguar commands (like run or container install) through the ESP32's console UART instead of WiFi. This is useful if you don't want to use WiFi or want to avoid using extra pins.

    1. Enable the proxy during flashing: Set a baud rate using --uart-endpoint-baud. For example, to use 921600 baud:

      jag flash --uart-endpoint-baud=921600

      Or to use only the proxy (no WiFi/HTTP endpoint):

      jag flash --uart-only --uart-endpoint-baud=921600

    2. Start the proxy monitor: Keep the device connected via serial and run:

      jag monitor --proxy

      If you used a custom baud rate during flashing, specify it here:

      jag monitor --proxy --baud=921600

    While the monitor is running, you can execute commands like jag run or jag container install in a separate terminal.

    jag monitor --proxy

  8. Run and live-reload Toit code via WiFi

    main

    Once Jaguar is running on your device and you have scanned for it using jag scan, you can execute Toit programs over WiFi.

    Run a program once:

    jag run hello.toit

    Live reload (Watch mode): Jaguar can watch your file for changes and automatically reload the code on the device:

    jag watch hello.toit
    jag watch hello.toit

  9. Update Jaguar firmware via WiFi

    main

    To upgrade the Jaguar system software and the Jaguar application itself over WiFi, run:

    jag firmware update

    Warning: Updating the firmware will uninstall all currently installed containers and stop all running applications. You will need to reinstall them after the update.

    jag firmware update

  11. Use the Jaguar CLI

    main

    The jag command is the primary entrypoint for Jaguar, a tool designed for fast development on ESP32 devices using the Toit virtual machine. It allows for updating and restarting Toit applications over WiFi, significantly speeding up the development cycle by avoiding serial flashing and device reboots.

    To use Jaguar, you will interact with various subcommands for tasks such as flashing, monitoring, compiling, and configuring your environment.

    # General usage pattern
$ jag [command] [flags]

  12. Locate Jaguar configuration files

    main

    Jaguar uses standard XDG directory structures for configuration. If the XDG_CONFIG_HOME environment variable is set, Jaguar will use that directory. Otherwise, it defaults to ~/.config/ on most systems.

    User Configuration

    • Default Path: $XDG_CONFIG_HOME/jaguar/config.yaml (or ~/.config/jaguar/config.yaml)
    • Override: Set JAG_USER_CONFIG_PATH to specify a custom file.

    Device Configuration

    • Default Path: $XDG_CONFIG_HOME/jaguar/device.yaml (or ~/.config/jaguar/device.yaml)
    • Override: Set JAG_DEVICE_CONFIG_PATH to specify a custom file.

    Toit Configuration

    • Default Path: $XDG_CONFIG_HOME/toit/config.yaml (or ~/.config/toit/config.yaml)
    • Override: Set TOIT_CONFIG_FILE to specify a custom file.