Getting started with Toit on your ESP32

[kasperl]

1. Set up your development environment

Install Jaguar

Start by downloading and installing the jag binary for your host platform:

• Download Jaguar for Windows (or as an archive)
• Download Jaguar for macOS (or as an archive)
• Download Jaguar for Linux (only as an archive)

On macOS, you can also use Homebrew to mange the installation of jag:

brew install toitlang/toit/jag

If you download the 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

If the jag setup completes successfully, you have the tools you need to work with Toit code installed.

Install Visual Studio Code

Visual Studio Code is the preferred editing experience for Toit. If you don't already have VS Code installed, go ahead and download and install it. Then start it:

You're now ready to install the Toit extension. Choose View > Extension from the menu and search for Toit. Click the Install button next to the Toit extension in the list. You should now have the extension installed:

Create a new folder and open it in Visual Studio Code. In the new folder, create a new file called hello.toit and put some basic Toit code in it:

main:
  print "Hello, World!"

The Toit extension provides syntax highlighting, static analysis, and autocompletions, so you now have a great editing environment for tinkering with Toit code.

---

2. Run code on your ESP32

Start a terminal in Visual Studio Code and make sure you can run jag version from within there. If that works, you're ready to connect your ESP32 to your host machine using a serial link and flash the initial firmware onto it through jag flash:

Your host machine must be on the same network as your ESP32. Jaguar uses UDP broadcast from the ESP32 to support scanning for devices and you can find yours by running:

jag scan

and select your device from the list:

Now run jag monitor from your terminal. This will give you access to the serial logs from the device:

We're almost there. The final step is to start a new terminal using the Terminal > New Terminal menu. In the new terminal, start watching the hello.toit file for changes using:

jag watch hello.toit

You can switch back and forth between the jag monitor and jag watch outputs, but the most interesting information will be in the monitor output:

INFO: program 1 starting from flash @ [0,24576]
Hello, World!
INFO: program 1 terminated with exit code 0

If you change the hello.toit file and save the changes, Jaguar will reload the app on your ESP32 and you will see the new output within a few seconds:

---

3. Using packages

Toit comes with a package manager that allows you to easily pull down additional functionality from an online repository of published packages. To install your first package, you use jag pkg like this:

jag pkg install mqtt

You must install the mqtt package in the folder your hello.toit file resides in, because this is where the Toit compiler will look for packages.

With the installed package in place, you can replace the content of hello.toit with a more involved example that uses MQTT to publish and subscribe. You can download the example from here or you can go to the code and simply copy and paste it in VS Code.

Once you save your edits and thus the new example in hello.toit the jag watch functionality (assuming you left it running from step 2) will kick in and you will start seeing output like:

INFO: program 9 starting from flash @ [196608,245760]
Connected to MQTT Broker @ test.mosquitto.org:1883
Subscribed to topic 'my/sensor/data'
Published message `42.0` on 'my/sensor/data'
Received message '42.0' on 'my/sensor/data'
INFO: program 9 terminated with exit code 0

Drivers are one of the most common kind of packages, so take a look at the list of available packages and start contributing your own.