{"id":13338135,"url":"https://github.com/toitlang/jaguar","last_synced_at":"2026-02-15T22:17:55.421Z","repository":{"id":36957306,"uuid":"435810765","full_name":"toitlang/jaguar","owner":"toitlang","description":"Use live reloading over WiFI to turbo-charge developing for your ESP32.","archived":false,"fork":false,"pushed_at":"2025-04-14T08:04:57.000Z","size":1281,"stargazers_count":192,"open_issues_count":22,"forks_count":15,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-14T09:24:15.198Z","etag":null,"topics":["esp32","livereload","toit"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toitlang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-12-07T09:04:25.000Z","updated_at":"2025-04-14T08:05:00.000Z","dependencies_parsed_at":"2023-02-19T08:01:03.088Z","dependency_job_id":"a0ced67d-fff1-4e50-be50-9bda2806677e","html_url":"https://github.com/toitlang/jaguar","commit_stats":null,"previous_names":[],"tags_count":196,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Fjaguar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Fjaguar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Fjaguar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Fjaguar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toitlang","download_url":"https://codeload.github.com/toitlang/jaguar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248880920,"owners_count":21176758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","livereload","toit"],"created_at":"2024-07-29T19:15:31.714Z","updated_at":"2026-02-15T22:17:55.415Z","avatar_url":"https://github.com/toitlang.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jaguar: Live reloading for your ESP32\nJaguar enables live reloading of [Toit](https://toitlang.org/) code when developing for the\n[ESP32](https://en.wikipedia.org/wiki/ESP32), a popular microcontroller.\n\nDevelop, update, and restart your code in less than two seconds via WiFi.\nUse the really fast development cycle to iterate quickly and learn fast!\n\n## What is it?\nJaguar is a small Toit application that runs on your ESP32. It uses the capabilities of the\n[Toit virtual machine](https://github.com/toitlang/toit) to let you update and restart your ESP32\ncode written in Toit over WiFi. Change your code in your editor, update it on\nyour device, and restart it all within seconds. No need to flash over serial, reboot your device, or wait\nfor it to reconnect to your network.\n\nWatch a short video that shows how you can experience Jaguar on your ESP32 in two minutes:\n\n\u003ca href=\"https://youtu.be/cU7zr6_YBbQ\"\u003e\u003cimg width=\"543\" alt=\"Jaguar demonstration\" src=\"https://user-images.githubusercontent.com/133277/146210503-24811800-bb26-4244-817d-6422b20e6786.png\"\u003e\u003c/a\u003e\n\n## How does it work?\nJaguar runs a small HTTP server that listens for incoming requests. The requests contain compiled\nToit programs that are relocated and installed in flash on the device. Before installing a\nprogram, we stop any old version of the program and free the resources it has consumed. The new\nversion of the program gets to start again from `main`.\n\n## Community\n\nUse this [invite](https://discord.gg/Q7Y9VQ5nh2) to join our Discord server, and follow the development and get help.\nWe're eager to hear of your experience building with Toit. The Discord\nchat is publicly accessible through our [Linen](https://linen.dev/d/toit).\n\nWe also use [GitHub Discussions](https://github.com/toitlang/toit/discussions) to discuss and learn.\n\nWe follow a [code of conduct](CODE_OF_CONDUCT.md) in all our community interactions.\n\n\n## How do I use it?\n\n### Download\nUnless you want to [build Jaguar from source](#building-it-yourself), start by\ndownloading and installing the `jag` binary for your host platform.\n\nOn macOS, you can use [Homebrew](https://brew.sh/) to manage the installation of `jag`:\n``` sh\nbrew install jaguar\n```\n\nOn Windows 10+ you can use the [Windows package manager](https://docs.microsoft.com/en-us/windows/package-manager/winget/):\n```\nwinget install --id=Toit.Jaguar -e\n```\n\nRemember to run `winget upgrade --id=Toit.Jaguar -e` (or simply `winget upgrade`) from time\nto time to keep Jaguar up to date.\n\nFor Archlinux you can install the AUR package [jaguar-bin](https://aur.archlinux.org/packages/jaguar-bin):\n``` sh\nyay install jaguar-bin\n```\n\nFor Debian/Ubuntu based systems, you can download the `.deb` package from the [releases page](https://github.com/toitlang/jaguar/releases) and install it:\n``` sh\nsudo dpkg -i jaguar_*.deb\n```\n\nAs alternative to these package managers, we also offer precompiled binaries for download:\n\n- [Download Jaguar for macOS](https://github.com/toitlang/jaguar/releases/latest/download/jag.dmg)\n  (or as an [archive](https://github.com/toitlang/jaguar/releases/latest/download/jag_macos.zip))\n- [Download Jaguar for Windows](https://github.com/toitlang/jaguar/releases/latest/download/jag_installer.exe)\n  (or as an [archive](https://github.com/toitlang/jaguar/releases/latest/download/jag_windows.zip))\n- [Download Jaguar for Linux](https://github.com/toitlang/jaguar/releases/latest/download/jag_linux.tgz)\n  (only as an archive)\n\nIf you download an archive, you should unpack it and put the embedded `jag` or `jag.exe` binary\nsomewhere on your `PATH`. The same applies when you extract the `jag` binary from the macOS `jag.dmg` file.\n\n### Setup associated tools\nNext step is to let `jag` download and configure the Toit SDK and the associated tools for\nflashing the Jaguar application onto your ESP32:\n\n``` sh\njag setup\n```\n\n### Flashing via serial\nNow it is time to connect your ESP32 with a serial cable to your computer and put the Jaguar\napplication onto it. Running `jag flash` will ask you for the serial port to use and the WiFi\ncredentials, but be aware that the tooling requires\n[permission to access your serial port](#permission-to-access-serial-port).\n\n``` sh\njag flash\n```\n\nIf you want to avoid typing the WiFi credentials every time you flash, you can store\nthem in Jaguar's config file with:\n\n``` sh\njag config wifi set --wifi-ssid SSID --wifi-password PASSWORD\n```\n\nAfter flashing it is possible to monitor the serial output from the device:\n\n``` sh\njag monitor\n```\n\nOnce the serial output shows that your ESP32 runs the Jaguar application, it will start announcing\nits presence to the network using UDP broadcast. You can find a device by scanning, but this requires\nyou to be on the same local network as your ESP32:\n\n``` sh\njag scan\n```\n\n### Running code via WiFi\nWith the scanning complete, you're ready to run your first Toit program on your Jaguar-enabled\nESP32 device. Download [`hello.toit`](https://github.com/toitlang/toit/blob/master/examples/hello.toit)\nand store it in your file system and then run:\n\n``` sh\njag run hello.toit\n```\n\nBe aware that you can configure the way your applications run by [providing options](#options-for-jag-run)\nto `jag run`. Also, Jaguar is fast enough that it is possible to ask Jaguar to keep watching your Toit code\non disk and to *live reload* it when it changes. Simply write:\n\n``` sh\njag watch hello.toit\n```\n\nand edit `hello.toit` or any of the files it depends on in your favorite editor.\n\n### Installing services and drivers\nJaguar supports installing named containers that are automatically run when the system boots. They can be used\nto provide services and implement drivers for peripherals. The services and drivers can be used by\napplications and as such they form an instrumental part of the extensibility of a Jaguar based system.\n\nYou can list the currently installed containers on a device through:\n\n``` sh\njag container list\n```\n\nThis results in a list that shows the container image ids and the associated names.\n\n```\n$ jag container list\n85c64060-ffbd-5e04-a0dd-252d5bbf4a32: print-service\n4e9a12bc-7f07-5118-9f04-8ad2bbe476d1: jaguar\n```\n\nYou install a new, or update an existing, container through:\n\n``` sh\njag container install print-service service.toit\n```\n\nand you can uninstall said container again using:\n\n``` sh\njag container uninstall print-service\n```\n\n### Updating Jaguar via WiFi\nIf you upgrade Jaguar, you will need to update the system software and the Jaguar application on your\ndevice. You can do this via WiFi simply by invoking:\n\n``` sh\njag firmware update\n```\n\nUpdating the firmware will uninstall all containers and stop running applications, so those have to\nbe transferred to the device again after the update.\n\n# Visual Studio Code\nThe Toit SDK used by Jaguar comes with support for [Visual Studio Code](https://code.visualstudio.com/download).\nOnce installed, you can add the [Toit language extension](https://marketplace.visualstudio.com/items?itemName=toit.toit)\nand get full language support for Toit, including syntax highlighting, integrated static analysis, and code completions.\nJaguar already comes with everything you need, so if you can run `jag` from your `PATH`, the extension will automatically\nfind the Toit SDK downloaded by Jaguar and use that.\n\n---\n\n# Options for `jag run`\nIt is possible to provide options for `jag run` that control how your applications behave on your device. This section\nlists the options and provides an explanation for when they might come in handy.\n\n## Limiting application run time\nYou can control how much time Jaguar gives your application to run through the `-D jag.timeout` setting. It takes a value\nlike `10s`, `5m`, or `1h` to indicate how many seconds, minutes, or hours the app can run before being shut down by Jaguar.\n\n``` sh\njag run -D jag.timeout=10s service.toit\n```\n\n## Defines\nJaguar supports defining values that can be used in your Toit code. This is done through\nthe `-D` option. Its primary use is to configure Jaguar (see below for temporarily disabling\nJaguar), but it can also be used to pass values to your Toit code.\n\nAll defined values that are available in the `jag.defines` assets, where they are stored as\nTison. The `encoding.tison` library has functions to extract these values from the assets.\n\n``` sh\njag run -D my-define=499 defines.toit\n```\n\n``` toit\n// defines.toit\nimport encoding.tison\nimport system.assets\n\nmain:\n  defines := assets.decode.get \"jag.defines\"\n      --if-present=: tison.decode it\n      --if-absent=: {:}\n  if defines is not Map:\n    throw \"defines are malformed\"\n  print defines[\"my-define\"]\n```\n\n## Temporarily disabling Jaguar's WiFi\nYou can disable Jaguar's WiFi while your application runs using `-D jag.wifi=false`. This is useful if Jaguar otherwise\ninterferes with your application. As an example, consider an application that uses the WiFi to setup a\nsoftware-enabled access point (\"Soft AP\"). This would normally conflict with Jaguar's use of the WiFi, so your\napplication and Jaguar cannot run at the same time. By temporarily disabling Jaguar, it is possible to test and tinker with\nthe Soft AP based service.\n\n``` sh\njag run -D jag.wifi=false softap.toit\n```\n\nBy default this runs with a 10 seconds timeout to avoid making the device inaccessible by Jaguar. You can configure\nthe timeout by passing a separate `-D jag.timeout` option:\n\n``` sh\njag run -D jag.wifi=false -D jag.timeout=5m softap.toit\n```\n\nThis also works for installed containers. Containers that run with `-D jag.wifi=false` start when the device boots and\nruns to completion before Jaguar tries to connect to WiFi. This allows them to control the WiFi and to prevent\nJaguar from taking over before they are ready for it:\n\n``` sh\njag container install -D jag.wifi=false softap softap.toit\n```\n\nYou can also set the timeout for them to make sure they cannot block enabling Jaguar forever:\n\n``` sh\njag container install -D jag.wifi=false -D jag.timeout=20s softap softap.toit\n```\n\n---\n\n# Permission to access serial port\nTo flash you will need to access the device `/dev/ttyUSB0`.  On Linux that\nmeans you probably need to be a member of some group, normally either `uucp` or\n`dialout`.  To see which groups you are a member of and which group owns the\ndevice, plug in an ESP32 to the USB port and try:\n\n``` sh\ngroups\nls -g /dev/ttyUSB0\n```\n\nIf you lack a group membership, you can add it with\n\n``` sh\nsudo usermod -aG dialout $USER\n```\n\nYou will have to log out and log back in for this to take effect. You can also try\n`newgrp dialout` to avoid the need to log out and log back in.\n\n# Installing via Go\nYou can also install using `go install`. First you'll need to have a [Go development environment](https://go.dev)\nproperly set up (1.16+) and remember to add `$HOME/go/bin` or `%USERPROFILE%\\go\\bin` to your `PATH`. Using that\nyou can install the `jag` command line tool through:\n\n``` sh\ngo install github.com/toitlang/jaguar/cmd/jag@latest\n```\n\n# Building it yourself\nYou've read this far and you want to know how to build Jaguar and the underlying Toit language\nimplementation yourself? Great! You will need to follow the instructions for\n[building Toit](https://github.com/toitlang/toit) and make sure you can flash a\n[simple example](https://github.com/toitlang/toit/blob/master/examples/hello.toit) onto your device.\n\nWe assume all the commands are executed from this directory (the checkout of\nthe Jaguar repository).\n\nStart by setting the `JAG_TOIT_REPO_PATH`. Typically, this would  be\nthe path to the third_party directory:\n``` sh\nexport JAG_TOIT_REPO_PATH=$PWD/third_party/toit\n```\nAlternatively, `JAG_TOIT_REPO_PATH` could point to a different checkout of Toit.\n\nSetup the ESP-IDF environment variables and PATHs, which will allow to compile\nESP32 programs. The easiest is to just use the `export.sh` that comes with\nthe ESP-IDF repository:\n``` sh\nsource $JAG_TOIT_REPO_PATH/third_party/esp-idf/export.sh\n```\nNote that Toit's ESP-IDF is patched. Don't use use a plain ESP-IDF checkout instead.\n\nCompile everything.\n``` sh\nmake\n```\nThis will build the SDK from the `JAG_TOIT_REPO_PATH`, then use it to download\nthe Toit dependencies (using `toit.pkg`) and finally build Jaguar; both the\nhost executable, as well as the Toit program that runs on the device.\n\nYou can now use Jaguar as usual:\n\n``` sh\nbuild/jag flash\nsleep 3        # Give the device time to connect to the WiFi.\nbuild/jag scan # Select the new device.\nbuild/jag run $JAG_TOIT_REPO_PATH/examples/hello.toit\nbuild/jag monitor\n```\n\n## Contributing\nWe welcome and value your [open source contributions](CONTRIBUTING.md) to Jaguar.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoitlang%2Fjaguar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoitlang%2Fjaguar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoitlang%2Fjaguar/lists"}