Let's start at the basics, what everything is called, follow that link to the visual glossary for Blockly. Alternatively we'll cover the essentials here.
First off, the Blockly area of the browser window is called a workspace, the Blockly workspace.
When you create a new action, you'll start with just the root block on the workspace, called the Action Root block, or just root block.
Notice the blue triangular exclamation-mark icon on the root block. It shows there is a problem with the block, and clicking it will tell you more.
In this case, it's telling you the root block must have a Trigger block, and also an Action block before it is complete.
Lastly in the bottom right of the workspace are the Zoom and Trashcan controls. The top option zooms to fit all blocks in view. The crosshairs with a dot inside resets the view to default zoom, and the plus and minus zoom in and out.
Next the grey panel to the left side of the workspace is called the Category Toolbox.
When you click on a category, a flyout toolbox menu appears. The toolbox contains all the blocks in that category.
Each block has a brief description, hovering your mouse pointer over a block will bring up a helpful note for using the block.
Moving Blocks in the Workspace
The basic idea is to select a block and drag it into place, also known as drag and drop.
If you just click on it then it'll be placed randomly on the workspace as a disabled Block (a semi-transparent silhouetted version of the block). This means it's not a complete block yet and simply dragging it into place (with the jigsaw peg nested into the root block's jigsaw hole) will lock it into being a normal Block.
You'll still possibly have other attached pieces of the block that are also shadow blocks. For example, the feed names and operators, until you select appropriate values or replace the shadow blocks with other blocks. If a shadow block is showing an acceptable value, then you may leave it and continue as long as the block is attached to the root (directly or indirectly).
Block Menus
Finally you'll want to know is that there is a context-menu. That is the name for the menu that appears when you right-click with the mouse (or Control key + click on Mac), and the menu varies according to where the mouse is (contextual menu).
Here I've right clicked on a Reactive action block, placed from the Triggers category toolbox. You can see options for collapse blocks, inline inputs, disable and enable blocks, and finally delete them.
Do try it out as you may find some very helpful.
Inline? Yes, the compact form of the block, allowing you to read it in a single line rather than large multi-line blocks.
Here's an example with collapsed (top), and inline versions of both Trigger and Action blocks:
Block Types
Now on to learning the details of the blocks specific to Adafruit IO.
Please note that these may change in the future as we try to break down the complexity into smaller more useful chunks. But, the same functionality will remain so check back here if you need a refresher.
Triggers Category
The input blocks for our Blockly workspace.
Here you select from: a reactive trigger (that trigger based on a new feed value), scheduled trigger (based on a simple repeating time schedule), or a delay timer trigger (where the trigger fires based on a new feed value, but the trigger is delayed before starting by a chosen delay value)
-
Reactive - This is the base block for a reactive action, it has two comparators, and an operator (the condition), along with a repetition time limit. Notify on reset will email you when the condition is no longer true.
- Timer - Identical to reactive for evaluating a condition, except in addition to verifying the condition has been met, it is also delayed before flowing through from the Trigger to the Action.
You choose the delay after the condition is met, before the resulting Action is fired, and whether a new value matching the condition should extend the timer.
- Scheduled - This makes use of the Schedules category toolbox, and you can select various different timing schemes, like hourly, daily, weekly, annually etc.
Schedules Category
This category has all the different scheduling blocks that can be used to complete the "When" option of the Scheduled Trigger Block.
With options for hourly, daily, weekly, monthly, annually, and possibly more coming soon (sunrise anybody?), there is a lot of possibility in these blocks!
Make sure to use the mouse-over tooltips as there are a few intricacies left over from the old system, allowing more complex triggering that you might first expect.
An example is the hourly block, which can trigger more than once per hour, as we used to allow it to be used in a more advanced way a bit like Cron if you've ever heard of that (a Linux job scheduler).
Actions Category
The outputs category for our Blockly workspace, one Action block is required and also only one is allowed, similarly to the Trigger blocks.
This is where you select what happens next. Do you send an email or SMS, publish a new value to another feed, or use a webhook to trigger a process on another server? Let's find out more...
- Publish to a Feed - this sends a new value to a feed, currently, this is a fixed value (a number or string) that you define in advance.
If you need more than one output, then consider chaining actions by publishing to an intermediate feed or webserver (using webhooks), then have additional actions triggered by that intermediate feed or webhook.
-
Email - Comes with a suggested template, where you can use the placeholders in double curly braces like
{{value}}, to insert the value from a feed, along withfeed_name,timeand other useful fields.
- SMS - Same sort of thing as email, but you must have the number registered for Adafruit IO, which is under your Adafruit Account -> Services -> IO+ SMS settings. It's currently an IO+ powerup (like our Weather service), US/CA numbers only and 25 SMS per day.
-
Webhook - This sends a templated message to a web server. It is used to call out to existing external services, for example, a discord bot, automation services, or some other JSON-loving device. (Does not need to be JSON, you control the message that is sent).
There is also the option to use Form Encoding instead.
Values Category
The blocks in the Values category are used as comparators (things to compare against), and for template related blocks (like email/SMS/webhooks) to allow the placeholders to be correctly populated. This means it's technically possible to publish the value of a different feed in an email to the feed that was triggering our action.
First is the most frequently used block, the Feed block, and then different value types required in some conditional / logic operations. If you don't know the term, a boolean is only ever either true or false.
Most things on Adafruit IO accept strings or numbers interchangeably, effectively everything is treated as a string when being evaluated, but that cannot and should not be relied upon. For one thing, machines do care about the difference, so it's best to stick to one data type and use the specific one you need for the output.
Operators
Operators aren't a toolbox category, but they're just as important as the other blocks!
An operator is used to specify the type of comparison, or check, that is done against the comparators (things being checked).
These are the conditional operators, the noble equals, the infinitely useful any, and many more:
- any - when any value arrives, it is said to match and the conditional check is true.
- greater than
- greater than or equal to
- less than
- less than or equal to
- equals
- not equal to
- includes - search within an incoming feed/value for another feed/value.
Here's a simple run-through of recreating my burnt toast reactive action, and on the next page(s) you'll go through some other more useful "real" examples to help you learn how to use each trigger type.
Text editor powered by tinymce.
