Toit language implementation

This repository contains the Toit language implementation. It is fully open source and consists of the compiler, virtual machine, and standard libraries that together enable Toit programs to run on an ESP32.

We use GitHub Discussions to discuss and learn and we follow a code of conduct in all our community interactions.

References

The Toit language is the foundation for the Toit platform that brings robust serviceability to your ESP32-based devices. You can read more about the language and the standard libraries in the platform documentation:

Contributing

We welcome and value your open source contributions to the language implementation and the broader ecosystem. Building or porting drivers to the Toit language is a great place to start. Read about how to get started building I2C-based drivers and get ready to publish your new driver to the package registry.

Licenses

The Toit compiler, the virtual machine, and all the supporting infrastructure is licensed under the LGPL-2.1 license. The standard libraries contained in the lib/ directory are licensed under the MIT license. The examples contained in the examples/ directory are licensed under the 0BSD license.

Certain subdirectories are under their own open source licenses, detailed in those directories. These subdirectories are:

• Every subdirectory under src/third_party
• Every subdirectory under src/compiler/third_party
• Every subdirectory under lib/font/x11_100dpi
• The subdirectory lib/font/matthew_welch

Building

Dependencies

ESP-IDF

The VM has a requirement to ESP-IDF, both for Linux and ESP32 builds (for Linux it's for the MBedTLS implementation).

We recommend you use Toitware's ESP-IDF fork that comes with a few changes:

• Custom malloc implementation.
• Allocation-fixes for UART, etc.
• LWIP fixes.

git clone https://github.com/toitware/esp-idf.git
pushd esp-idf/
git checkout patch-head-4.3-3
git submodule update --init --recursive
popd

Remember to add it to your ENV as IDF_PATH:

export IDF_PATH=...

ESP32 tools

Install the ESP32 tools, if you want to build an image for an ESP32.

On Linux:

$IDF_PATH/install.sh

For other platforms, see Espressif's documentation.

Remember to update your environment variables:

. $IDF_PATH/export.sh

The build system will automatically use a 32-bit build of the Toit compiler to produce the correct executable image for the ESP32. Your build might fail if you're on a 64-bit Linux machine and you don't have the support for compiling 32-bit executables installed. You can install this support on most Linux distributions by installing the gcc-multilib and g++-multilib packages. If you use apt-get, you can use the following command:

sudo apt-get install gcc-multilib g++-multilib

Build for Linux and Mac

Make sure IDF_PATH is set, as described above.

Then run the following commands at the root of your checkout.

make tools

This builds the Toit VM, the compiler, the language server and the package manager.

You should then be able to execute a toit file:

build/host/bin/toitvm examples/hello.toit

The package manager is found at build/tpkg:

build/tpkg pkg init --project-root=<some-directory>
build/tpkg pkg install --project-root=<some-directory> <package-id>

The language server can be started with:

build/toitlsp --toitc=build/host/bin/toitc

See the instructions of your IDE on how to integrate the language server.

For VSCode you can also use the published extension.

Notes for Mac

The support for building for Mac is still work in progress. For now, it isn't possible to build firmware images for the ESP32 on a Mac, because it requires compiling and running 32-bit executables. We are working on addressing this.

Build for ESP32

Make sure the environment variables for the ESP32 tools are set, as described in the dependencies section.

Build an image for your ESP32 device that can be flashed using esptool.py.

make esp32

By default, the image boots up and runs examples/hello.toit. You can use your own entry point and specify it through the ESP32_ENTRY make variable:

make esp32 ESP32_ENTRY=examples/mandelbrot.toit

Configuring WiFi for the ESP32

You can easily configure the ESP32's builtin WiFi by setting the ESP32_WIFI_SSID and ESP32_WIFI_PASSWORD make variables:

make esp32 ESP32_ENTRY=examples/http.toit ESP32_WIFI_SSID=myssid ESP32_WIFI_PASSWORD=mypassword

This allows the WiFi to automatically start up when a network interface is opened.