Primary Purpose:
Jaguar is a live reloading tool designed to streamline the development process for ESP32 microcontrollers using the Toit programming language. It enables developers to update and restart code over WiFi in mere seconds, eliminating the need for serial flashing or manual reboots.
Key Features:
Live Reloading: Instantly deploy updates to your ESP32 via WiFi, reducing iteration time.
Container Support: Install and manage multiple named containers for services and drivers, enhancing system extensibility.
VS Code Integration: Leverage Visual Studio Code with Toit language support for enhanced development体验, including syntax highlighting and code completions.
Runtime Definitions: Define custom parameters to configure applications dynamically.
Firmware Updates: Easily update the ESP32 firmware and Jaguar application over WiFi without manual intervention.
Audience & Benefit:
Ideal for developers working on ESP32 projects using Toit, Jaguar accelerates development by enabling rapid testing and iteration. It transforms the development cycle by significantly reducing time spent on updates and deployments, allowing developers to focus on innovation.
Installation:
Jaguar can be installed via winget on Windows 10+ with the command: winget install --id=Toit.Jaguar -e.
This tool is a must-have for anyone looking to enhance productivity in ESP32 development with Toit.
README
Jaguar: Live reloading for your ESP32
Jaguar enables live reloading of Toit code when developing for the
ESP32, a popular microcontroller.
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!
What is it?
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:
How does it work?
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.
Community
Use this invite to join our Discord server, and follow the development and get help.
We're eager to hear of your experience building with Toit. The Discord
chat is publicly accessible through our Linen.
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.
Setup associated tools
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
Flashing via serial
Now it is time to connect your ESP32 with a serial cable to your computer and put the Jaguar
application onto it. Running jag flash will ask you for the serial port to use and the WiFi
credentials, but be aware that the tooling requires
permission to access your serial port.
jag flash
If you want to avoid typing the WiFi credentials every time you flash, you can store
them in Jaguar's config file with:
jag config wifi set --wifi-ssid SSID --wifi-password PASSWORD
After flashing 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
Running code via WiFi
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
Be aware that you can configure the way your applications run by providing options
to jag run. Also, Jaguar is fast enough that it is 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.
Installing services and drivers
Jaguar supports installing named containers that are automatically run when the system boots. They can be used
to provide services and implement drivers for peripherals. The services and drivers can be used by
applications and as such they form an instrumental part of the extensibility of a Jaguar based system.
You can list the currently installed containers on a device through:
jag container list
This results in a list that shows the container image ids and the associated names.
$ jag container list
85c64060-ffbd-5e04-a0dd-252d5bbf4a32: print-service
4e9a12bc-7f07-5118-9f04-8ad2bbe476d1: jaguar
You install a new, or update an existing, container through:
jag container install print-service service.toit
and you can uninstall said container again using:
jag container uninstall print-service
Updating Jaguar via WiFi
If you upgrade Jaguar, you will need to update the system software and the Jaguar application on your
device. You can do this via WiFi simply by invoking:
jag firmware update
Updating the firmware will uninstall all containers and stop running applications, so those have to
be transfered to the device again after the update.
Visual Studio Code
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.
Options for jag run
It is possible to provide options for jag run that control how your applications behave on your device. This section
lists the options and provides an explanation for when they might come in handy.
Limiting application run time
You can control how much time Jaguar gives your application to run through the -D jag.timeout setting. It takes a value
like 10s, 5m, or 1h to indicate how many seconds, minutes, or hours the app can run before being shut down by Jaguar.
jag run -D jag.timeout=10s service.toit
Defines
Jaguar supports defining values that can be used in your Toit code. This is done through
the -D option. Its primary use is to configure Jaguar (see below for temporarily disabling
Jaguar), but it can also be used to pass values to your Toit code.
All defined values that are available in the jag.defines assets, where they are stored as
Tison. The encoding.tison library has functions to extract these values from the assets.
jag run -D my-define=499 defines.toit
// defines.toit
import encoding.tison
import system.assets
main:
defines := assets.decode.get "jag.defines"
--if-present=: tison.decode it
--if-absent=: {:}
if defines is not Map:
throw "defines are malformed"
print defines["my-define"]
Temporarily disabling Jaguar's WiFi
You can disable Jaguar's WiFi while your application runs using -D jag.wifi=false. This is useful if Jaguar otherwise
interferes with your application. As an example, consider an application that uses the WiFi to setup a
software-enabled access point ("Soft AP"). This would normally conflict with Jaguar's use of the WiFi, so your
application and Jaguar cannot run at the same time. By temporarily disabling Jaguar, it is possible to test and tinker with
the Soft AP based service.
jag run -D jag.wifi=false softap.toit
By default this runs with a 10 seconds timeout to avoid making the device inaccessible by Jaguar. You can configure
the timeout by passing a separate -D jag.timeout option:
jag run -D jag.wifi=false -D jag.timeout=5m softap.toit
This also works for installed containers. Containers that run with -D jag.wifi=false start when the device boots and
runs to completion before Jaguar tries to connect to WiFi. This allows them to control the WiFi and to prevent
Jaguar from taking over before they are ready for it:
jag container install -D jag.wifi=false softap softap.toit
You can also set the timeout for them to make sure they cannot block enabling Jaguar forever:
jag container install -D jag.wifi=false -D jag.timeout=20s softap softap.toit
Permission to access serial port
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.
Installing via Go
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
Building it yourself
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:
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
