{"id":13469109,"url":"https://github.com/toitlang/toit","last_synced_at":"2025-04-13T02:00:11.377Z","repository":{"id":36957124,"uuid":"427260190","full_name":"toitlang/toit","owner":"toitlang","description":"Program your microcontrollers in a fast and robust high-level language.","archived":false,"fork":false,"pushed_at":"2025-04-07T20:42:42.000Z","size":17709,"stargazers_count":1279,"open_issues_count":63,"forks_count":86,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-13T01:59:49.684Z","etag":null,"topics":["esp32","toit"],"latest_commit_sha":null,"homepage":"https://toitlang.org/","language":"Toit","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-12T06:47:52.000Z","updated_at":"2025-04-07T11:08:50.000Z","dependencies_parsed_at":"2023-09-23T13:43:24.662Z","dependency_job_id":"b3992a89-d563-48f7-89cd-ad19c3d2eaaa","html_url":"https://github.com/toitlang/toit","commit_stats":{"total_commits":2223,"total_committers":24,"mean_commits":92.625,"dds":0.5299145299145299,"last_synced_commit":"59e154010e93781127726d1f991c1b9f8496460f"},"previous_names":[],"tags_count":199,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Ftoit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Ftoit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Ftoit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toitlang%2Ftoit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toitlang","download_url":"https://codeload.github.com/toitlang/toit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654045,"owners_count":21140235,"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","toit"],"created_at":"2024-07-31T15:01:26.685Z","updated_at":"2025-04-13T02:00:11.325Z","avatar_url":"https://github.com/toitlang.png","language":"Toit","funding_links":[],"categories":["Toit","C++","others"],"sub_categories":[],"readme":"# Toit programming language\n\nThis repository contains the Toit language implementation. It consists of the compiler,\nvirtual machine, and standard libraries that together enable Toit programs to run on an ESP32.\n\n## Jaguar: Live reloading for the ESP32\n\nYou can use Toit to develop, update, and restart your ESP32 applications in less than two seconds through\n[Jaguar](https://github.com/toitlang/jaguar). Jaguar is a small Toit program that runs on your ESP32.\nIt uses the capabilities of the Toit virtual machine to let you update and restart your ESP32\napplications written in Toit over WiFi whenever your source files change. Once set up, it is as easy as:\n\n``` sh\njag watch examples/hello.toit\n```\n\nIt is also straightforward to install extra drivers and services that can extend the core functionality\nof your device. Add automatic [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)-based time\nsynchronization without having to write a single line of code:\n\n``` sh\njag container install ntp examples/ntp/ntp.toit\n```\n\nYou can watch a short video that shows how you can experience Jaguar on your ESP32 in less 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## 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## References\n\nThe Toit language is the foundation for the [Toit platform](https://toit.io/) that brings robust serviceability\nto your ESP32-based devices. You can read more about the language and the standard libraries in the platform\ndocumentation:\n\n* [Language basics](https://docs.toit.io/language)\n* [Standard libraries](https://libs.toit.io/)\n\n## Contributing\n\nWe welcome and value your [open source contributions](CONTRIBUTING.md) to the language implementation\nand the broader ecosystem. Building or porting drivers to the Toit language is a great place to start.\nRead about [how to get started building I2C-based drivers](https://github.com/toitlang/toit/discussions/22) and\nget ready to publish your new driver to the [package registry](https://pkg.toit.io).\n\nIf you're interested in pitching in, we could use your help with\n[these drivers](https://github.com/toitlang/toit/issues?q=is%3Aissue+is%3Aopen+label%3Adriver+label%3A%22help+wanted%22)\nand more!\n\n## Licenses\n\nThe Toit compiler, the virtual machine, and all the supporting infrastructure is licensed under\nthe [LGPL-2.1](LICENSE) license. The standard libraries contained in the `lib/` directory\nare licensed under the [MIT](lib/LICENSE) license. The examples contained in the `examples/`\ndirectory are licensed under the [0BSD](examples/LICENSE) license.\n\nCertain subdirectories are under their own open source licenses, detailed\nin those directories and the files they contain. These subdirectories are:\n\n* The subdirectory `lib/font/matthew_welch/`\n* Every subdirectory under `packages/`\n* Every subdirectory under `lib/font/x11_100dpi/`\n* Every subdirectory under `src/compiler/third_party/`\n* Every subdirectory under `src/third_party/`\n* Every subdirectory under `third_party/`\n\n# Installation\nThe instructions in this section don't cover the IDE integration. Follow the instructions\n[below](#ide-integration) to set up Toit support for your editor.\n\n## Arch Linux\nFor [Arch Linux](https://archlinux.org/) (or variants such as [Manjaro](https://manjaro.org/))\nuse your favorite [AUR helper](https://wiki.archlinux.org/title/AUR_helpers) to\ninstall the [toit](https://aur.archlinux.org/packages/toit/) or\n[toit-git](https://aur.archlinux.org/packages/toit-git/) package.\n\nFor example:\n```\nyay -S toit\n```\n\n## Other platforms\nWe're actively working on simple installation steps for other platforms. For now, please use the build instructions below or download the `.tar.gz` files from the\n[release](https://github.com/toitlang/toit/releases) page.\n\n\n# Building\n\n## Dependencies\n\n### Build system\n\n#### Linux and Mac\nTo build Toit and its dependencies the build host requires:\n\n* [GNU Make](https://www.gnu.org/software/make/)\n* [CMake \u003e= 3.13.3](https://cmake.org/)\n* [Ninja](https://ninja-build.org/)\n* [GCC](https://gcc.gnu.org/)\n* [Go \u003e= 1.19](https://go.dev/)\n* python-is-python3: on Ubuntu machines\n* glibc-tools: optional and only available on newer Ubuntus\n\nIf you are using a Linux distribution with `apt` capabilities, you can\nissue the following command to install these:\n\n``` sh\nsudo apt install build-essential cmake ninja-build golang\n```\n\nYou can then build Toit by running the following commands in a checkout of this repository:\n\n``` bash\ngit submodule update --init --recursive\nmake\n```\n\nFor builds targeting ESP32 hardware additional requirements might be in effect\ndepending on the build host's architecture, see paragraph [ESP32 tools](#esp32-tools).\n\nFor builds targeting RISC-V, ARM32, or ARM64 hardware, see the [Other platforms README](README_OTHERPLATFORMS.md).\n\n#### Windows\n\nIf you are using Windows you can use Chocolatey to install the required dependencies.\n\nAfter [installing Chocolatey](https://docs.chocolatey.org/en-us/choco/setup), you can\ninstall the required dependencies by running the following command in an elevated shell\n(usually the same you just used to install Chocolatey):\n\n``` powershell\nchoco install git ninja mingw make golang ccache\nchoco install cmake.install --installargs '\"ADD_CMAKE_TO_PATH=System\"'\n```\n\nAfter that you can use the bash that comes with Git ('git-bash') and compile Toit\nin a checkout of this repository by running the following commands:\n\n``` bash\ngit submodule update --init --recursive\nmake\n```\n\n### ESP-IDF\n\nThe Toit VM has a requirement for the [Espressif IoT Development Framework](https://idf.espressif.com/), both for Linux and ESP32 builds (for Linux it's for the [Mbed TLS](https://www.trustedfirmware.org/projects/mbed-tls/) implementation).\n\nWe recommend you use Toitware's [ESP-IDF fork](https://github.com/toitware/esp-idf) that comes with a few changes:\n\n* Custom malloc implementation\n* Allocation-fixes for UART, etc.\n* LWIP fixes\n\nThe fork's repository has been added as a submodule reference to this repository, so doing a recursive submodule init \u0026 update will establish everything nedded:\n\n``` sh\ngit submodule update --init --recursive\n\n```\n\nIf the `submodule update` step fails with:\n\n```\nSubmodule path 'esp-idf/components/coap/libcoap': checked out '98954eb30a2e728e172a6cd29430ae5bc999b585'\nfatal: remote error: want 7f8c86e501e690301630029fa9bae22424adf618 not valid\nFetched in submodule path 'esp-idf/components/coap/libcoap/ext/tinydtls', but it did not contain 7f8c86e501e690301630029fa9bae22424adf618. Direct fetching of that commit failed.\n```\n\ntry following the steps outlined [here](https://github.com/toitlang/toit/issues/88). It is an issue in the upstream ESP-IDF repository\ncaused by the `tinydtls` component having changed its remote URL.\n\nTo use the [offical ESP-IDF](https://github.com/espressif/esp-idf), or [any other variation](https://github.com/espressif/esp-idf/network/members), you need to add the Toit specific patches first.\n\nThen make sure it is available in your file system and point IDF_PATH to its path instead before building.\n\n``` sh\nexport IDF_PATH=\u003cA_DIFFERENT_ESP_IDF\u003e\n```\n\n### ESP32 tools\n\nIf you want to build an image for the ESP32, install the ESP32 tools.\n\nOn Linux:\n``` sh\n$IDF_PATH/install.sh\n```\n\nThe default location of $IDF_PATH is under ```./third_party/esp-idf```\n\nFor other platforms, see [Espressif's documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#step-3-set-up-the-tools).\n\nRemember to update your environment variables:\n\n``` sh\nsource $IDF_PATH/export.sh\n```\n\n## Build for host machine\n\nMake sure the required build tools are installed as described in dependency sections [ESP-IDF](#esp-idf) and [Build system](#build-system) above.\n\nThen run the following commands at the root of your checkout.\n\n``` sh\nmake all\n```\n\n---\n*NOTE*\n\nThese instructions have been tested on Linux and macOS.\n\nWindows support is still [preliminary](https://github.com/toitlang/toit/discussions/33), and\nthe build instructions may differ for Windows. Let us know on the\n[discussions forum](https://github.com/toitlang/toit/discussions) how we can improve\nthis README.\n\n---\n\nThis builds the Toit VM, the compiler, the language server and the package manager.\n\nYou should then be able to execute a toit file:\n\n``` sh\nbuild/host/sdk/bin/toit examples/hello.toit\n```\n\nThe package manager is found at `build/host/sdk/bin/toit.pkg`:\n\n``` sh\nbuild/host/sdk/bin/toit pkg init --project-root=\u003csome-directory\u003e\nbuild/host/sdk/bin/toit pkg install --project-root=\u003csome-directory\u003e \u003cpackage-id\u003e\n```\n\n### Debugging\nSee https://github.com/toitlang/toit/wiki/Debugging.\n\n## IDE integration\n\nToit has a [VS Code](https://code.visualstudio.com/) extension. You can either use the\n[published extension](https://marketplace.visualstudio.com/items?itemName=toit.toit) or\nbuild it yourself from the\n[sources](https://github.com/toitware/ide-tools).\n\nIn the VS Code extension (version 1.3.7+) set the `toitLanguageServer.command` setting to\n`[\"PATH_TO_SDK/bin/toit\", \"tool\", \"lsp\"]`, where\n`PATH_TO_SDK` is the path to your `build/host/sdk/` folder in the Toit repository.\n\nThis makes the extension use the language server that was compiled in the [build step](#build-for-host-machine).\n\n### Other IDEs\n\nThe Toit language server is independent of VSCode and can be used with other IDEs.\nIt can be started with:\n\n``` sh\nbuild/host/sdk/bin/toit.lsp --toitc=build/host/sdk/bin/toit.compile\n```\n\nSee the instructions of your IDE on how to integrate the language server.\n\nThere are syntax highlighters for VIM and CodeMirror in the\n[ide-tools repository](https://github.com/toitware/ide-tools).\n\n## Build for ESP32\n\nMake sure the environment variables for the ESP32 tools are set, as\ndescribed in the [dependencies](#dependencies) section. Typically this\nconsists of running the following command:\n\n``` bash\n# On Linux and Mac OS X:\nthird_party/esp-idf/install.sh\n```\n``` powershell\n# On Windows:\nthird_party\\esp-idf\\install.bat\n```\n\nBuild firmware that can be flashed onto your ESP32 device. The firmware is generated\nin `build/esp32/firmware.envelope`:\n\n``` sh\nmake esp32\n```\n\nIf you want to flash the generated firmware on your device, you can use the `firmware`\ntoo. Internally, the `firmware` tool calls out to\n[esptool](https://github.com/espressif/esptool)\nso you need to install that one first.\nYou can also set the environment variable `ESPTOOL_PATH` to point\nto a valid esptool (for example the one in the shipped esp-idf:\n`export ESPTOOL_PATH=$PWD/third_party/esp-idf/components/esptool_py/esptool/esptool.py`).\nAssuming your device is connected through `/dev/ttyUSB0`\nyou can then flash a device as follows:\n\n``` sh\nbuild/host/sdk/tools/firmware -e build/esp32/firmware.envelope \\\n    flash --port /dev/ttyUSB0 --baud 921600\n```\n\nBy default, the image boots up but does not run any application code. You can use your\nown entry point by installing it into the firmware envelope before flashing:\n\n``` sh\nbuild/host/sdk/bin/toit compile --snapshot -o hello.snapshot examples/hello.toit\nbuild/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \\\n    container install hello hello.snapshot\nbuild/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \\\n    flash --port /dev/ttyUSB0 --baud 921600\n```\n\n### Adding multiple containers\n\nYou can add more containers before you flash, so you firmware\nenvelope can have any number of containers. Be aware that adding the NTP\nexample below requires you to [configure the WiFi on the ESP32](#configuring-wifi-for-the-esp32) when you\nflash.\n\n``` sh\nbuild/host/sdk/bin/toit compile --snapshot -o hello.snapshot examples/hello.toit\nbuild/host/sdk/bin/toit compile --snapshot -o ntp.snapshot examples/ntp/ntp.toit\n\n# Typically we set the output envelope the first time we change it.\nbuild/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \\\n    -o custom.envelope \\\n    container install hello hello.snapshot\nbuild/host/sdk/bin/toit tool firmware -e custom.envelope \\\n    container install ntp ntp.snapshot\n```\n\nYou can list the containers in a given firmware envelope:\n\n``` sh\nbuild/host/sdk/bin/toit tool firmware -e custom.envelope container list\n```\n\nThe listing shows the containers that are installed.\n\n```\nsystem:\n  Kind: snapshot\n  Id: bf14aa94-4b7e-3ddd-94a9-a22f5d1ec92c\n  Size: 242104\n  Flags:\n    - trigger=boot\n    - critical\nhello:\n  Kind: snapshot\n  Id: adc2babc-d89a-2301-98a1-3a1dfe34f144\n  Size: 141852\n  Flags:\n    - trigger=boot\nntp:\n  Kind: snapshot\n  Id: 8d8ff2f0-3c51-13e8-6876-84a70fa359b5\n  Size: 187330\n  Flags:\n    - trigger=boot\n```\n\nYou can use the `--output-format=json` flag to get the output in JSON format.\n\n### Adding container assets\n\nContainers have associated assets that they can access at runtime. Add the\nfollowing code to a file named `assets.toit`:\n\n```\nimport system.assets\n\nmain:\n  print assets.decode\n```\n\nIf you run this on an ESP32, you'll get an empty map printed becase you\nhaven't associated any assets with the container that holds the code.\n\nTo associate assets with the container, we first construct an encoded\nassets file and add this `README.md` file to it.\n\n``` sh\nbuild/host/sdk/bin/toit tool assets -e encoded.assets create\nbuild/host/sdk/bin/toit tool assets -e encoded.assets add readme README.md\n```\n\nNow we can add the `encoded.assets` to the `assets` container at\ninstall time:\n\n``` sh\nbuild/host/sdk/bin/toit compile --snapshot -o assets.snapshot assets.toit\nbuild/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \\\n    container install assets assets.snapshot \\\n    --assets=encoded.assets\n```\n\nIf you update the source code in `assets.toit` slightly, the\nprinted information will be more digestible:\n\n```\nimport system.assets\n\nmain:\n  readme := assets.decode[\"readme\"]\n  // Guard against splitting a unicode character by\n  // making this non-throwing.\n  print readme[0..80].to_string_non_throwing\n```\n\nYou'll need to reinstall the container after this by recompiling\nthe `assets.toit` file to `assets.snapshot` and re-running:\n\n``` sh\nbuild/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \\\n    container install assets assets.snapshot \\\n    --assets=encoded.assets\n```\n\n### Configuring WiFi for the ESP32\n\nYou can easily configure the ESP32's builtin WiFi passing it as configuration\nwhen you flash:\n\n``` sh\necho '{ \"wifi\": { \"wifi.ssid\": \"myssid\", \"wifi.password\": \"mypassword\" } }' \u003e wifi.json\nbuild/host/sdk/bin/toit tool firmware -e build/esp32/firmware.envelope \\\n    flash --config wifi.json \\\n    --port /dev/ttyUSB0 --baud 921600\n```\n\nThis allows the WiFi to automatically start up when a network interface is opened.\n\n---\n*NOTE*\n\nTo access the device `/dev/ttyUSB0` on Linux you probably need to be a member\nof some group, normally either `uucp` or `dialout`.  To see which groups you are\na member of and which group owns the device, plug in an ESP32 to the USB port\nand 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoitlang%2Ftoit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoitlang%2Ftoit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoitlang%2Ftoit/lists"}