Jaguar enables live reloading when developing for the ESP32. Develop, update, and restart your code in less than two seconds via WiFi. Use the really fast development cycle to iterate quickly and learn fast!

Jaguar is a small Toit application that runs on your ESP32. It uses the capabilities of the Toit virtual machine to let you update and restart your ESP32 code written in Toit over WiFi. Change your code in your editor, update it on your device, and restart it all within seconds. No need to flash over serial, reboot your device, or wait for it to reconnect to your network.

Watch a short video that shows how you can experience Jaguar on your ESP32 in two minutes:

Jaguar runs a small HTTP server that listens for incoming requests. The requests contain compiled Toit programs that are relocated and installed in flash on the device. Before installing a program, we stop any old version of the program and free the resources it has consumed. The new version of the program gets to start again from main.

Unless you want to build Jaguar from source, start by downloading and installing the jag binary for your host platform:

• Download Jaguar for Windows (or as an archive)
• Download Jaguar for macOS (or as an archive)
• Download Jaguar for Linux (only as an archive)

On macOS, you can also use Homebrew to mange the installation of jag:

brew install toitlang/toit/jag

If you download an archive, you should unpack it and put the embedded jag or jag.exe binary somewhere on your PATH. The same applies when you extract the jag binary from the macOS jag.dmg file.

Next step is to let jag download and configure the Toit SDK and the associated tools for flashing the Jaguar application onto your ESP32:

jag setup

Now it is time to connect your ESP32 with a serial cable to your computer and put the Jaguar application onto it. This will ask you for the serial port to use and the WiFi credentials:

jag flash

NOTE

To flash you will need to access the device /dev/ttyUSB0. On Linux that means you probably need to be a member of some group, normally either uucp or dialout. To see which groups you are a member of and which group owns the device, plug in an ESP32 to the USB port and try:

groups
ls -g /dev/ttyUSB0

If you lack a group membership, you can add it with

sudo usermod -aG dialout $USER

You will have to log out and log back in for this to take effect.

Now it is possible to monitor the serial output from the device:

jag monitor

Once the serial output shows that your ESP32 runs the Jaguar application, it will start announcing its presence to the network using UDP broadcast. You can find a device by scanning, but this requires you to be on the same local network as your ESP32:

jag scan

With the scanning complete, you're ready to run your first Toit program on your Jaguar-enabled ESP32 device. Download hello.toit and store it in your file system and then run:

jag run hello.toit

It is even possible to ask Jaguar to keep watching your Toit code on disk and to live reload it when it changes. Simply write:

jag watch hello.toit

and edit hello.toit or any of the files it depends on in your favorite editor.

The Toit SDK used by Jaguar comes with support for Visual Studio Code. Once installed, you can add the Toit language extension and get full language support for Toit, including syntax highlighting, integrated static analysis, and code completions. Jaguar already comes with everything you need, so if you can run jag from your PATH, the extension will automatically find the Toit SDK downloaded by Jaguar and use that.

If you have not opted-out of Jaguar's crash reporting and usage analytics, the jag binary will gather crash reports and usage statistics and forward them to Segment. We use the statistics to improve Jaguar and the gathered data may include:

• Basic information: The version of Jaguar and the name and version of your host operating system.
• Command line usage: Data on which commands were run, not including the actual command lines.
• Stack traces: The stack trace generated by a crash, which only contains references to jag's own code.
• Anonymous ID: A constant and unique number generated for the host where Jaguar is installed.

The gathering of analytics is controlled by $HOME/.cache/jaguar/config.yaml or %USERPROFILE%\.cache\jaguar\config.yaml and you can opt out of the data gathering by running:

jag config analytics disable

If you opt out of analytics, an opt-out event will be sent, and then no further information will be sent by that installation of Jaguar. The crash reporting component is work in progress.

You can also install using go install. First you'll need to have a Go development environment properly set up (1.16+) and remember to add $HOME/go/bin or %USERPROFILE%\go\bin to your PATH. Using that you can install the jag command line tool through:

go install github.com/toitlang/jaguar/cmd/jag@latest

You've read this far and you want to know how to build Jaguar and the underlying Toit language implementation yourself? Great! You will need to follow the instructions for building Toit and make sure you can flash a simple example onto your device.

We assume all the commands are executed from this directory (the checkout of the Jaguar repository).

Start by setting the JAG_TOIT_REPO_PATH. Typically, this would be the path to the third_party directory:

export JAG_TOIT_REPO_PATH=$PWD/third_party/toit

Alternatively, JAG_TOIT_REPO_PATH could point to a different checkout of Toit.

Setup the ESP-IDF environment variables and PATHs, which will allow to compile ESP32 programs. The easiest is to just use the export.sh that comes with the ESP-IDF repository:

source $JAG_TOIT_REPO_PATH/third_party/esp-idf/export.sh

Note that Toit's ESP-IDF is patched. Don't use use a plain ESP-IDF checkout instead.

Compile everything.

make

This will build the SDK from the JAG_TOIT_REPO_PATH, then use it to download the Toit dependencies (using toit.pkg) and finally build Jaguar; both the host executable, as well as the Toit program that runs on the device.

You can now use Jaguar as usual:

build/jag flash
sleep 3        # Give the device time to connect to the WiFi.
build/jag scan # Select the new device.
build/jag run $JAG_TOIT_REPO_PATH/examples/hello.toit
build/jag monitor

We welcome and value your open source contributions to Jaguar.