# Special

Special blocks provide essential control over program execution and event handling. These blocks let you create the main program loop, handle MQTT events, and build event-driven device behaviors.

## task

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-a25d5a0cc877d865c18723f843586eff3fadef16%2Fspecial_main.png?alt=media" alt=""><figcaption></figcaption></figure></div>

The main execution loop for your script. This block repeatedly executes the code inside it at a specified interval. Every script requires exactly one task block - it serves as your program's entry point and controls when your device logic runs.

**Parameters:**

* **Iterations** (Number): How many times to run. Set to `0` for infinite execution (most common)
* **Interval** (Number): Time between executions in milliseconds

**Example:**

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-c94a909d743851afd2e2d4af14b94c0d1088afb7%2Fspecial_task_example.png?alt=media" alt=""><figcaption><p>Read temperature every 5 seconds and send an event with the value</p></figcaption></figure></div>

## task pass

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-c3a0dd7f44fd44d209e911f210824b345aee0994%2Fspecial_iterator.png?alt=media" alt=""><figcaption></figcaption></figure></div>

Returns the current iteration counter for the task. Useful for creating behaviors that change over time or execute only on specific iterations.

**Returns:**

* **Number**: `-1` for infinite tasks (iterations = 0), otherwise counts down from `n-1` to `0`

{% hint style="warning" %}
This block only works inside a task block. Using it elsewhere will cause an error.

<img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-6bc387cd8599cf36c450890030befb26d4dcce20%2Fspecial_iterator_outside.png?alt=media" alt="" data-size="original">
{% endhint %}

**Example:**

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-26ba30c1c48988ce8c50ec0bf3a662f332c9d362%2Fspecial_task_pass_example.png?alt=media" alt=""><figcaption><p>Create LED patterns based on iteration</p></figcaption></figure></div>

{% hint style="info" %}
Custom iterator implementation using variables to count up instead of down.

<img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-bf93e79f4ef941f8850e072075294bb5c3a9b2ab%2Fspecial_iterator_custom.png?alt=media" alt="" data-size="original">
{% endhint %}

## is event

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-0168e9b470c21347010e24b30f63f25761a3019c%2Fspecial_is_event.png?alt=media" alt=""><figcaption></figcaption></figure></div>

Checks whether a specific MQTT event is waiting in the queue. Use this to conditionally process events when they arrive.

**Parameters:**

* **Event Name** (String): The name of the event to check for

**Returns:**

* **Boolean**: `#t` (true) if the event exists in the queue, `()` (false) if not

{% hint style="warning" %}
This block returns true as long as the event remains in the queue. To remove the event, use the **pop event** block.
{% endhint %}

**Example:**

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-a1ed535c6784262b11e07049797d8098a159ccbb%2Fspecial_is_event_example.png?alt=media" alt=""><figcaption><p>Check and retrieve an event</p></figcaption></figure></div>

## pop event

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-4a3647b911254011d2ce35fa6dabd192f201a75e%2Fspecial_pop_event.png?alt=media" alt=""><figcaption></figcaption></figure></div>

Retrieves and removes the oldest event of the specified type from the queue. Use this to access event data sent via MQTT.

**Parameters:**

* **Event Name** (String): The name of the event to retrieve

**Returns:**

* **Number**: The event payload value, or `()` (empty) if no event exists

{% hint style="warning" %}
Event payloads are always of type **Number**. If you need to send other data types, encode them as numbers.
{% endhint %}

**Example:**

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-a1ed535c6784262b11e07049797d8098a159ccbb%2Fspecial_is_event_example.png?alt=media" alt=""><figcaption><p>Check and retrieve an event</p></figcaption></figure></div>

## push event

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-c1150be5ce541136e9a52e1d81d4234330e4c3d7%2Fspecial_push_event.png?alt=media" alt=""><figcaption></figcaption></figure></div>

Sends an event with a value to the MQTT broker. Use this to publish sensor readings, status updates, or trigger actions on other devices or dashboards.

**Parameters:**

* **Event Name** (String): The name of the event to publish
* **Value** (Number/Boolean): The value to send

{% hint style="warning" %}
Event payloads are always sent as **Number** type. Boolean values are automatically converted: `true` → `1`, `false` → `0`.
{% endhint %}

**Example:**

<div align="left"><figure><img src="https://1776027180-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsSE1iwGRAGqUrb5YXfFa%2Fuploads%2Fgit-blob-ab4580d6701bde4f47edfdabc784f828ee7319c1%2Fspecial_push_event_example.png?alt=media" alt=""><figcaption><p>Send sensor readings</p></figcaption></figure></div>
