Specification

A Toit application is made of:

• a toit file containing the code that will be executed.

• a YAML file containing the app specification that describes when and how often the application must run.

The specification file

This section describes the content of an app specification file.

# Description of an app specification file using YAML syntax.

name: <App name>
entrypoint: <toit file entrypoint>
triggers:
  on_boot: <bool>
  on_install: <bool>
  on_interval: "<duration>"
  cron:
    - "*/5 7 * * *"
    - "0 */2 * * *"
  on_pubsub_topic:
    - "<type>:<name>"
  gpios:
    - pin: <pin>

pubsub:
  subscriptions:
    - "<type>:<name>"

• name:

  The app name. This name is the primary human identifier of an app.

• entrypoint:

  The Toit file where the main function of the program is located. The entrypoint can be the name of the Toit file, such as hello.toit, if it is saved in the same folder as its configuration file, or a relative path to the Toit file including the Toit file, such as myproject/hello.toit.

• triggers:

  The events triggering the execution of the application. Programs can query which trigger started them by using the job library.

  Without any trigger, the application is always running. In case the application terminates, it is immediately restarted.

  • on_boot:

    Runs the application every time the device boots. This includes reboots, or when the device wakes up from a scheduled deep sleep.

  • on_install:

    Runs the application when it is installed.

  • on_interval:

    Runs the application every duration. If the application is already running when the trigger fires the event is ignored and the program is not run again.

    The input is an interval of time in either hours, minutes, or seconds such as: 1h, 10m or 2s.

  • cron:

    Is a list of crons, each defining a schedule on when the application should start. In the example above, the application will be triggered every 5 minutes of the 7th hour, as well as every 2 hours on minute 00. Note that the time on devices is in UTC. Timezones are not supported.

    If the application is already running when the trigger fires, the event is ignored.

  • on_pubsub_topic:

    Runs the application when a message from the defined pubsub topic <type>:<name> is received on the device. The on_pubsub_topic can only trigger on topics that the device is subscribed to (see below for subscribing to a topic).

  • gpios:

    Runs the application when any of the specified GPIO pins are high. This GPIOs trigger is level-triggered, so it'll continue running the application while the GPIO pin is high. This will also wake up the device from deep-sleep to run the app and go back to deep sleep.

• pubsub:

  The PubSub subscriptions.

  • subscriptions:

    Subscribes to topics. Each topic is of the form <type>:<name>, with type being either cloud or device. The name is defined by the user. See PubSub and Tutorials for additional information and an example of an app specification file with a PubSub subscription.

Example

# An example of an app specification file.

name: My App Name
entrypoint: hello.toit
triggers:
  on_boot: true
  on_install: true
  on_interval: "10m"
  cron:
    - "*/5 7 * * *"
    - "0 */2 * * *"
  on_pubsub_topic:
    - "cloud:hello-world"
  gpios:
    - pin: 21

pubsub:
  subscriptions:
    - "cloud:hello-world"