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.
On Windows 10+ you can use the Windows package manager:
winget install --id=toit.jaguar -e
On macOS, you can use Homebrew to manage the installation of jag
:
brew install toitlang/toit/jag
For Archlinux you can install the AUR package jaguar-bin:
yay install jaguar-bin
If you see errors when upgrading with yay
make sure to pick "cleanBuild" for the package.
As alternative to these package managers, we also offer precompiled binaries for download:
- Download Jaguar for Windows (or as an archive)
- Download Jaguar for macOS (or as an archive)
- Download Jaguar for Linux (only as an archive)
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. You can also try
newgrp dialout
to avoid the need to log out and log back in.
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.