App 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.

To benefit from the modularity of Toit, we recommend writing and deploying separate apps for the different sensors. This ensures that a failure to access one sensor does not prevent the other apps from collecting data generated by the other sensors for example. It is also easier and safer to update apps independently from each other.

This section describes content of an app specification.

# Example of an app specification file.

name: <App name>
entrypoint: <toit entrypoint>
  on_boot: <bool>
  on_install: <bool>
  on_interval: "<duration>"
    - "*/5 7 * * *"
    - "0 */2 * * *"
    - "<type:name>"

  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.toitToit 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.

    • 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).

  • pubsub:

    The PubSub subscriptions.

    • subscriptions:

      Subscribes to the topic. A topic is a <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.