I/O Device Control

Controls I/O devices connected to the controller, such as LEDs, sensors, LCDs, and motors. See Part 7 for the device categories, the full device list, and the commands of each device.

Device

Select the I/O device to control. Devices are registered in Settings > I/O Device.

Command

Select the command to run on the selected device. The command list depends on the device type, and a description of the selected command is shown below the field.

Values

Set the input or output values of the selected command in the table.

Set Variable

Writes a value to the selected variable. The write mode and the value field change with the variable type.

Variable

Select the variable to write to. Variables of every type can be selected.

Write Mode

Select the operation applied when writing. The default is None, and the available options depend on the variable type.

Insert Position

Select whether to append the input value Before or After (default) the current value. Displayed only when Write Mode is Append.

Value

Enter the value to write. The field changes to the input format of the variable type (digital, number, text, date, time, duration, byte array, or color).

Shell Command

Runs a command in the default shell of the controller's operating system. Use it to run system commands or to launch external programs and scripts.

Command

Enter the shell command to run (for example, ls -al /home or python /path/script.py). The command runs in the default shell of the controller's operating system.

Wait for Completion

Select whether the action waits until the command finishes. The default is off. When it is on, the execution result can be stored in a variable.

Execution Result

Select a Text variable to store the output of the command. Displayed only when Wait for Completion is on.

Duplicate Handling

Select what happens when a process with the same name is already running.

• Allow Duplicate (default): Starts a new process even if one with the same name exists.
• No Duplicate: Skips execution if a process with the same name is already running.
• Kill Previous Process: Forcibly terminates the existing process with the same name and then starts a new one.

Read/Write File

Reads text or binary data from a file, or writes data to a file. File editors are registered in Settings > File Editor.

File Editor

Select the file editor to use.

Commands

• Read (default): Reads the file and stores its content in a variable.
• Read Line: Reads one line from the file and stores it in a variable. After reading, the cursor moves to the next line automatically.
• Write: Writes text or binary data to the file. Creates the file if it does not exist.
• Append: Appends data after the existing content of the file. Creates the file if it does not exist.
• Clear All: Deletes all content of the file.
• Close File: Closes the open file.
• Is End of File: Stores in a variable whether the cursor has reached the end of the file.

Fields

File Path

For Read and Read Line, select the file to read from the files uploaded to the project. For Write and Append, enter the path of the file to write, or pick it in the file browser (for example, C:\Users\me\file or /home/me/file); both slashes and backslashes are accepted, and surrounding spaces and quotes are removed automatically. The field is not displayed for Clear All, Close File, and Is End of File.

File Mode

Select the data format, Text (default) or Binary (byte array). Displayed only when Command is Read, Write, or Append.

Clear Content

Select whether the existing content is deleted before writing. The default is on. Displayed only when Command is Write.

Cursor Position

Select where to read or write from: Current Position, Beginning (default), or Set Position. Displayed when Command is Read, Read Line, or Write with Clear Content off. When Set Position is selected, enter the byte position (0 to 4294967295) in Cursor Position Input.

Size to Read

Select To End (default) or Set Size. When Set Size is selected, enter the number of bytes (1 to 4294967295, default 10) in Input Size to Read. Displayed only when Command is Read.

Write Content

Enter the data to write: text in Text mode or a byte array in Binary mode. Displayed only when Command is Write or Append.

Auto Line Break

Select whether a line break is inserted after the existing content before appending. The default is off. Displayed only when the file mode is Text and Command is Append.

Output variables

• Read Content: The variable that receives the data read. Select a Text variable in Text mode or a Byte Array variable in Binary mode. Displayed when Command is Read or Read Line.
• End of File (EOF): A Digital variable that receives whether the cursor has reached the end of the file. Displayed only when Command is Is End of File.

File System

Creates, copies, moves, and deletes local files and folders on the controller, or queries their information. Paths can be written in either Windows or Linux form (for example, C:\Users\me\file or /home/me/file). Both slashes and backslashes are accepted, and surrounding spaces and quotes are removed automatically.

Commands

Fields

Path

Enter the path of the target file or folder, or pick it in the browser. Create Directory and Is Directory open a folder browser; the other commands open a file browser.

Source Path, Target Path

Enter the path of the source file or folder and the path of the target folder. Displayed only when Command is Copy or Move.

Duplicate Handling

What happens when a file or folder with the same name already exists at the target path. Displayed only when Command is Copy or Move.

• None (default): Cancels the operation and raises an error.
• Overwrite: Overwrites with the source.
• Skip: Skips without overwriting.
• Update if Newer: Overwrites only when the source is newer.

New Name

Enter the new name. Displayed only when Command is Rename.

Output variables

The output variables in the table are displayed only when their command is selected, and each takes a variable of the type given in the table.

Delay

Waits for the set time and then continues to the next action.

Mode

• Normal (default): Delay in milliseconds.
• Precision: Precise delay in microseconds, in the range 0 to 999 μs.

Delay Time

Enter the time to wait (duration). The default is 5 seconds. Displayed only when Mode is Normal.

Delay Time (μs)

Enter the time to wait in microseconds (0 to 999, default 10). Displayed only when Mode is Precision.

Timer

Measures the time elapsed from a base time. It can be set to count up or down, so it serves as a timer or a stopwatch. Timers are registered in Settings > Timer.

Timer

Select the timer to control.

Commands

• Start (default): Starts the timer. Select the increase or decrease mode with it.
• Stop: Stops the timer.
• Reset: Stops the timer and resets the current time to the set time.
• Set Time: Changes the timer's current time to the set time.
• Get Time: Reads the timer's current time into a variable.

Fields

Mode

Increase (default) counts up and Decrease counts down; the minimum in decrease mode is 0 seconds. Displayed only when Command is Start.

Set Time

Enter the time (duration) used by Reset and Set Time. Displayed only when Command is Reset or Set Time.

Current Time

Select a Duration variable to store the current time. Displayed only when Command is Get Time.

Collection

Adds, retrieves, and removes values in a collection. A collection is a store for many values and comes in two types, list and map. The collection type and its key and value types are set when the collection is created in Settings > Collection (Part 6).

• List: Stores values in order. Each value has an index (position number) starting from 0, and values are found, added, changed, and removed by index.
• Map: Stores values as key-value pairs. The key is a unique identifier, and values are found, added, changed, and removed by key.

An example list (a shopping list) looks like this.

An example map (a phone book) looks like this.

Collection

Select the collection to use. The list commands or the map commands below are shown according to the type of the selected collection, and the value and key fields take the input format of the value type and key type set for the collection.

List commands

Position is a 0-based index (0 to 4294967295), and the default of the List Size input is 10. The Value input and the Value output variable follow the value type of the collection.

Map commands

The Key input follows the key type of the collection, and the Value input and output variable follow its value type.

Database

Queries, inserts, updates, and deletes data in a database. SQL databases (MySQL, PostgreSQL, SQLite, ODBC) and the Firebase Realtime Database are supported, and connections are registered in Settings > Database (Part 6). See Appendix B for preparing Firebase.

Database

Select the database to use. The SQL fields or the Firebase fields below are shown according to the type of the selected database.

SQL databases

Command

• Login (default): Logs in to the database.
• Execute Query: Runs an SQL query to query, insert, update, or delete data.
• Logout: Logs out of the database.

Query

Enter the SQL query to run (for example, SELECT * FROM users WHERE id = 1). Variable values can be composed with expressions in the block editor. Displayed only when Command is Execute Query.

Response

Select a Text variable to store the query response. Displayed only when Command is Execute Query.

Firebase database

Command

• Read (default): Reads the data at the path into a variable.
• Write: Writes data to the path.
• Delete: Deletes the data at the path.

Path

Enter the path of a node (key) inside the database (for example, /users/123/status). The root is /; this is not a file path.

Value

For Read, select the variable that receives the data; variables of every type can be selected. For Write, enter the data in the format of the Value Type. Not displayed when Command is Delete.

Value Type

Select the type of the data to write: Digital (default), Number, Text, Date, Time, Duration, Byte Array, or Color. Displayed only when Command is Write.

Statistics

Calculates statistics such as the minimum, maximum, and average of a number variable. For example, a statistic on a temperature sensor reading gives the highest, lowest, and average temperature directly. Statistics and their target variable are registered in Settings > Statistics.

Statistics

Select the statistic to use.

Commands

• Compute (default): Computes the statistics in real time.
• Clear: Resets all computed values.

Output variables

Select a Number variable for each of the following ten items. Only the items needed have to be set. Displayed only when Command is Compute.

Data Logging

Records one sample to the specified data logging channel. One row of the channel's variable values is appended at the moment the action runs, so it is used for trigger-based logging at the moment an event occurs, independently of the channel's Auto Logging. Channels are created in Settings > Data Logging (Part 6).

Data Logging Channel

Select the data logging channel to record to.

Play Media

Plays audio and video. Most file formats such as mp3 and mp4 and web streaming are supported; see the VLC supported formats for the playable formats. Media players are registered in Settings > Media Player, and video output requires a desktop session on the controller (Appendix B). See Appendix A for playback errors.

Media Player

Select the media player to use.

Commands

• Play (default): Plays a file or a stream.
• Pause: Pauses playback.
• Resume: Resumes paused media.
• Stop: Stops playback.
• Set Volume: Adjusts the volume.
• Set Speed: Adjusts the playback speed.
• Seek: Moves the playback position.
• Get Status: Reads the current state into a variable.

Fields

Media Type

File (default) plays a file uploaded to the project, and Streaming plays media at a URL. Displayed only when Command is Play.

Media File

Select the file to play from the files uploaded to the project. A sample audio file (sample.mp3) is set by default. Displayed only when Command is Play and Media Type is File.

Stream URL

Enter the URL of the streaming media (for example, https://example.com/video.mp4 or rtsp://192.168.0.10:554/stream). If the scheme is omitted, http:// is added automatically. A sample video address is set by default. Displayed only when Command is Play and Media Type is Streaming.

Wait for Completion

Select whether the action stays running until playback ends. The default is on. Displayed only when Command is Play (see Wait Until Finished in Part 4).

Volume (%)

Enter the volume from 0 to 100%. The default is 50. Displayed only when Command is Set Volume.

Playback Speed

Select 0.25x, 0.5x, 0.75x, 1.0x (default), 1.25x, 1.5x, 2.0x, 3.0x, or 4.0x, or select Manual Input and enter 0.01 to 100 in Playback Rate (x). Displayed only when Command is Set Speed.

Playback Position

Enter the position (duration) to move to. Displayed only when Command is Seek.

Status

Select a Number variable to store the current state: 0 initial, 1 playing, 2 paused, 3 stopped, 4 playback complete, 5 error. Displayed only when Command is Get Status.

Display Image

Displays an image on the display connected to the controller. Files uploaded to the project and web images can be shown, and image viewers are registered in Settings > Image Viewer. Screen output requires a desktop session on the controller (Appendix B).

Image Viewer

Select the image viewer to use.

Commands

• Display (default): Displays the image.
• Close: Closes the displayed image.

Fields

Image Type

File (default) displays an image uploaded to the project, and Web displays an image at a URL. Displayed only when Command is Display.

Image File

Select the image from the files uploaded to the project. A sample image (sample.jpg) is set by default. Displayed only when Command is Display and Image Type is File.

Web URL

Enter the URL of the image (for example, https://example.com/image.jpg). http:// may be omitted. Displayed only when Command is Display and Image Type is Web.

Synthesizer

Plays instrument sounds and sound effects, or plays MIDI files. The synthesizer is implemented in software and uses a SoundFont (sf2, sf3) file as its sound source. Instruments are registered in Settings > Synthesizer, and Appendix B explains how to find bank and preset numbers in a SoundFont.

Synthesizer

Select the synthesizer to use.

Commands

• Set Instrument (default): Sets the instrument played on a channel by bank and preset number.
• Note On: Plays a note. A note already playing on the same channel is stopped.
• Note Off: Stops the playing note. It does not need to be run if the note has already ended.
• MIDI Play: Plays a MIDI file.
• MIDI Pause: Pauses MIDI playback.
• MIDI Resume: Resumes paused MIDI playback.
• MIDI Stop: Stops MIDI playback.
• MIDI Seek: Moves the MIDI playback position.
• MIDI Status: Reads the current MIDI state into a variable.
• Set Volume: Adjusts the output volume.

Fields

Channel

Enter the channel to play on, from 0 to 15. A channel is a path for MIDI events, and each channel can hold a different instrument, so up to 16 instruments can play at the same time. Displayed only when Command is Note On, Note Off, or Set Instrument.

Bank, Preset

A bank is a group of instrument sounds in the SoundFont, and a preset is one instrument in the bank. Enter the bank number and preset number of the instrument, each from 0 to 255. Displayed only when Command is Set Instrument.

Enter Note Number

When on, the note is entered as a MIDI note number; when off (default), the note is selected from a list. Displayed only when Command is Note On or Note Off.

Note

Select the note to play from the list, from C-1 (0) to G9 (127). The default is C4 (60). Displayed when Enter Note Number is off.

MIDI Note Number

Enter the note to play as a MIDI note number from 0 to 127. The default is 60 (C4). Displayed when Enter Note Number is on. The note numbers by octave and note name are as follows.

Velocity (%)

Enter the MIDI velocity, how hard the key is struck, from 0 to 100%. The default is 100. Displayed only when Command is Note On.

MIDI File

Select the MIDI file to play from the files uploaded to the project. A sample MIDI file (sample.mid) is set by default. Displayed only when Command is MIDI Play.

Wait for Completion

Select whether the action stays running until MIDI playback ends. The default is on. Displayed only when Command is MIDI Play.

Position (%)

Enter the MIDI playback position to move to, from 0 to 100%. The position can be moved only after the MIDI file has been played at least once. Displayed only when Command is MIDI Seek.

Volume (%)

Enter the output volume from 0 to 100%. The default is 50. Displayed only when Command is Set Volume.

Status

Select a Number variable to store the current MIDI state: 0 initial, 1 playing, 2 paused, 3 stopped, 4 playback complete. Displayed only when Command is MIDI Status.

Camera

Starts or stops camera capture and streaming, and saves the current frame to a file. Cameras are registered in Settings > Camera (Part 6). Video AI analysis starts only after the camera has been started with this action (Part 4).

Camera

Select the camera to control.

Commands

• Start (default): Starts video capture and streaming.
• Stop: Stops video capture and streaming.
• Capture: Saves the current frame to an image file.
• Get Status: Reads the camera's status code and status message into variables.

Fields

Save Path

Enter the path of the image file to save, or pick it in the file browser. The default is /tmp/capture.jpg. Displayed only when Command is Capture.

Region of Interest (ROI)

Select the region to capture from the regions of interest defined in the camera settings. Leave it empty to capture the full frame. Displayed only when Command is Capture.

Output variables

• Status Code: A Number variable for the status code: -2 not initialized, -1 error, 0 idle, 1 running.
• Status Message: A Text variable for the status message.

Both are displayed only when Command is Get Status.

Audio Analysis

Analyzes the level and frequency distribution of audio in real time using FFT (Fast Fourier Transform). Audio analyzers and their source (microphone or speaker) are registered in Settings > Audio Analyzer.

Audio Analyzer

Select the audio analyzer to use.

Commands

• Start Analysis (default): Starts audio analysis.
• Stop Analysis: Stops audio analysis.
• Add Analysis: Adds an analysis to the analyzer. Several analyses can be added to one analyzer.
• Clear All Analyses: Removes all analyses from the analyzer.

Fields

All of the following fields are displayed only when Command is Add Analysis.

Data Type

• Overall RMS (default): The RMS (root mean square) of all channels, representing the overall sound level.
• Channel RMS: The RMS of the given channel, representing the sound level of that channel.
• Frequency Amplitude: The intensity of a given frequency on the given channel.
• Peak Intensity Frequency: The frequency with the highest intensity on the given channel, and that intensity.
• Centroid Frequency: The center frequency where the energy is concentrated on the given channel. It represents the brightness of the sound: higher is bright and sharp, lower is dark and dull.

Channel

Enter the index of the channel to analyze, from 0 to 31. The channel layout depends on the audio source; typical numbers are as follows. Not displayed when Data Type is Overall RMS.

• Mono: 0
• Stereo: 0 left, 1 right
• 5.1 channels: 0 front left, 1 front right, 2 center, 3 subwoofer, 4 rear left, 5 rear right

Frequency (Hz)

Enter the frequency to analyze, from 0 to 50000 Hz. The default is 1000; the audible range is roughly 20 to 20000 Hz. Displayed only when Data Type is Frequency Amplitude.

Output variables

All take a Number variable.

• Intensity (dBFS): Stores the intensity. dBFS is relative to the full-scale level (0 dB) of digital audio, so values are negative and closer to 0 means louder. Displayed when Data Type is Overall RMS, Channel RMS, or Frequency Amplitude.
• Peak Frequency (Hz), Peak Intensity (dBFS): Store the frequency with the highest intensity and that intensity. Displayed when Data Type is Peak Intensity Frequency.
• Centroid Frequency (Hz): Stores the centroid frequency. Displayed when Data Type is Centroid Frequency.

Record Audio

Records sound from the microphone and saves it as a file. The mp3, ogg, flac, and wav formats are supported, and recorders are registered in Settings > Audio Recorder.

Audio Recorder

Select the audio recorder to use.

Commands

• Start Recording (default): Starts recording.
• Stop Recording: Stops recording.

Fields

All of the following fields are displayed only when Command is Start Recording.

File Format

• mp3 (default): A lossy compressed format with a good balance of quality and file size.
• ogg: An open-source compressed format with high quality.
• flac: A lossless compressed format with CD-quality audio.
• wav: An uncompressed raw format with large files.

Bit Rate (kbps)

Select 64, 96, 128, 192 (default), 256, or 320 kbps. Higher bit rates improve quality but increase file size; 128 kbps or higher generally gives good quality.

File Path

Enter the path to save the recording, or pick it in the file browser (for example, C:\Users\me\file or /home/me/file). Both slashes and backslashes are accepted, and surrounding spaces and quotes are removed automatically.

Transform Audio

Changes the tempo, pitch, and playback speed of a source audio file, saves the result as a new file, and plays it if required. Transformers are registered in Settings > Audio Transform. This action has no command field.

Audio Transform

Select the audio transform to use.

Source File

Select the source file from the files uploaded to the project. Only the WAV format can be used, and a sample file (sample.wav) is set by default.

Source Type

Select whether the source audio is Speech (default) or Music. Choosing the matching type improves the transform quality.

Tempo Change (%)

Changes the tempo (beat) in the range -95 to 5000%. 0 is the original speed; positive values are faster and negative values slower (for example, 100 is twice as fast and -50 is half speed). The pitch is preserved.

Pitch Change (semitones)

Changes the pitch in the range -60 to 60 semitones. A semitone is the pitch difference between a white key and the adjacent black key on a piano.

Speed Change (%)

Changes the playback speed in the range -95 to 5000%. Unlike tempo, the pitch changes with it, like changing the rotation speed of an LP record (for example, 100 plays twice as fast and one octave higher).

Output File Path

Enter the path to save the transformed WAV file, or pick it in the file browser.

Auto Play

Select whether the transformed audio is played immediately. The default is on.

Wait for Completion

Select whether the action stays running until playback ends. The default is on. Displayed only when Auto Play is on.

LLM AI Query

Sends a query text and an optional attachment to an LLM (large language model) provider and stores the response in a variable. Providers and models are registered in Settings > LLM AI (Part 6); see Appendix B for preparing API keys.

LLM AI

Select the LLM AI configuration to use.

Query Text

Enter the query text (prompt) to send to the LLM. Type it directly, or build a dynamic prompt that includes variable values with the block editor.

Attachment

Select a file to send with the query from the files uploaded to the project. Images (JPEG, PNG, WebP) are supported by all providers; PDFs are supported only by OpenAI and Anthropic. The attachment is optional.

Output variables

• Response Variable: A Text variable for the response text.
• Success Flag: A Digital variable that receives true on success and false on failure.

Text-to-Speech (TTS)

Converts text to speech and plays it. The service type (On Device, Google Cloud, OpenAI, or ElevenLabs) is set when the service is registered in Settings > Text-to-Speech (Part 6), and the field that selects the voice depends on the type. See Appendix B for obtaining API keys for the online services and the ElevenLabs Voice ID.

Text-to-Speech

Select the text-to-speech service to use.

Commands

• Play (default): Converts the text to speech and plays it.
• Stop: Stops the speech being played.

Fields

Speaker ID, Voice ID

When the type is On Device, enter the model's speaker ID as a number. IDs are defined per model and start from 0; an invalid value selects the first voice. The speaker IDs of each model are listed in the sherpa-onnx model list. When the type is ElevenLabs, enter the Voice ID of the voice to use; this field is displayed only when Command is Play.

Voice Name

When the type is Google Cloud, enter the voice name. The default is en-US-Standard-C, and the voices are listed in the Google Cloud documentation. When the type is OpenAI, select alloy (default), echo, fable, onyx, nova, or shimmer; the voices are described in the OpenAI documentation. In both cases the field is displayed only when Command is Play.

Output Text

Enter the text to convert to speech. Displayed only when Command is Play.

Wait for Completion

Select whether the action stays running until the speech ends. The default is on. Displayed only when Command is Play.

Playback Speed

Select 0.25x, 0.5x, 0.75x, 1.0x (default), 1.25x, 1.5x, 2.0x, 3.0x, or 4.0x, or select Manual Input and enter 0.1 to 10 in Playback Rate (x). Displayed when Command is Play, and not displayed when the type is ElevenLabs.

Speech-to-Text (STT)

Converts human speech to text in real time. VAD (voice activity detection) detects the speech segments automatically; the service and the detection threshold are registered in Settings > Speech-to-Text (Part 6).

Speech-to-Text

Select the speech-to-text service to use.

Commands

• Listen (default): Starts speech recognition. It waits until speech is heard, then detects only the speech segments and converts them to text.
• Stop: Stops the speech recognition in progress.
• Get Status: Reads the current state into a variable.

Output variables

• Converted Text: A Text variable for the converted text. Displayed only when Command is Listen.
• Status: A Number variable for the state: 0 idle, 1 listening, 2 processing, 3 complete, 4 error. Displayed only when Command is Get Status.

Telegram Message

Exchanges messages or files with users through a Telegram bot. Bots are registered in Settings > Telegram Bot; see Appendix B for obtaining the bot token and the Chat ID.

Telegram Bot

Select the Telegram bot to use.

Commands

• Send Message (default): Sends a message to the recipient.
• Send File: Sends a file to the recipient.
• Receive Message: Receives a message sent to the bot.

Fields

Chat ID

Enter the Chat ID of the recipient (a user, group, or channel). A Chat ID is a number such as 123456789. Displayed only when Command is Send Message or Send File.

Message to Send

Enter the message to send. Displayed only when Command is Send Message.

File to Send, File Caption

Select the file to send from the files uploaded to the project and, if required, enter a caption shown with the file. The caption may be left empty. Displayed only when Command is Send File.

Output variables

• Receive Complete: A Digital variable that becomes true when a new message is received and false otherwise.
• Received Message: A Text variable for the received message.

Both are displayed only when Command is Receive Message.

Send Email

Sends an email through an SMTP client. The body can be text or HTML, files can be attached, and any mail server that supports SMTP, such as Naver or Google, can be used. Clients are registered in Settings > Email Client (Part 6). This action has no command field.

Email Client

Select the email client to use.

Recipients, CC, BCC

Enter the addresses. Separate several addresses with a comma (,), a semicolon (;), or a line break (for example, a@x.com, b@y.com); surrounding spaces are trimmed automatically. Recipients is required; CC and BCC may be left empty.

Subject

Enter the subject of the email.

Body Type

Select whether the body is sent as Text (default) or HTML.

Body

Enter the body to send. Enter HTML code when the body type is HTML.

Attachments

Enter the local paths on the controller of the files to attach. Separate several paths with commas.

Push Notification

Sends a push notification to the user's mobile app. The title and message are free text, and dynamic messages that include variable values can be built. This action has no resource selection and no command field.

Title

Enter the title of the notification. If it is left empty, a default title is used.

Message

Enter the message of the notification. Type it directly, or build a dynamic message that includes variable values with the block editor.

Attachment

Select a file to attach from the files uploaded to the project. The attachment is optional.

Zigbee Device Control

Reads sensor values from, or controls, a Zigbee device registered in Settings. Every property the device exposes can be accessed: light brightness, switch on and off, temperature and humidity readings, and more. Devices are paired and registered in Settings > Zigbee Device (Part 6).

Zigbee Device

Select the device to communicate with.

Commands

• Read (default): Reads the device's sensor values into variables.
• Write: Sends values to the device to control it.

Property Mapping

The table lists the properties supported by the selected device. For Read, the values of the checked properties are stored in the assigned variables; for Write, values are sent to the checked properties. The list is generated from the device's Exposes information, so it varies by device model.

Home Assistant Integration

Integrates with the Home Assistant server registered in Settings. Home Assistant entities can be read or controlled, and Grablo variables can be exposed to Home Assistant as new entities. Server connections are registered in Settings > Home Assistant (Part 6).

HA Server

Select the Home Assistant server to communicate with.

Commands

• Read (default): Reads the state and attribute values of an entity into variables.
• Write: Sends values to an entity to control it (for example, turn a light on, switch off, set a temperature).
• Expose Variables: Exposes Grablo variables to Home Assistant as new entities (sensor or binary_sensor).

Fields

HA Entity

Select the entity to read or control. Once the server is connected, the registered entities are listed with domain filtering (lights, switches, sensors, and so on), and entity search and a current-state preview are supported. Displayed only when Command is Read or Write.

Property Mapping

The table lists the properties generated from the state and attributes of the selected entity. For Read, the values of the checked properties are stored in variables; for Write, values are sent to the checked properties. Displayed only when Command is Read or Write.

Expose Items

A table of the variables exposed to Home Assistant. Displayed only when Command is Expose Variables. Each item has the following settings.

• Variable: The Grablo variable to expose. Digital variables are exposed as binary_sensor and all other variables as sensor.
• Unit: The unit of the value (for example, °C, %, W, kWh).
• Device Class: Determines the icon and presentation in the Home Assistant UI. Digital variables choose from 28 classes such as door, motion, and smoke; other variables choose from 60 classes such as temperature, humidity, and power. none can also be selected.

MQTT Communication

Publishes messages to an MQTT broker, or subscribes to a topic and receives messages. MQTT is a lightweight messaging protocol optimized for low-power, low-bandwidth environments and widely used in IoT. The broker connection (host, port, authentication, TLS) is registered in Settings > MQTT Client (Part 6).

MQTT Client

Select the MQTT client to use.

Commands

• Publish (default): Sends a message to the topic.
• Subscribe: Subscribes to the topic and requests the messages that arrive. If the topic is already subscribed, only the messages are requested.

Fields

Topic

Enter the topic to publish to or subscribe to (for example, home/sensor/temperature). A topic is the path a message is delivered through, with levels separated by slashes (/).

QoS

Select the quality-of-service level of the message. The default is QoS 1; a higher number gives more reliability but uses more network resources.

• QoS 0: Sends the message without checking for a response. The message may not be delivered.
• QoS 1: Resends the message until a response arrives. The message may be delivered more than once.
• QoS 2: Guarantees exactly-once delivery with a four-way handshake.

Message

Enter the message to publish. Displayed only when Command is Publish.

Retain Message

When on, the last message sent is stored on the broker so that newly connecting subscribers receive it immediately. The default is off. Displayed only when Command is Publish.

Max Wait Time

Enter how long (duration) to wait for a message. The default is 1 second; when the time is exceeded, no message is considered received. Displayed only when Command is Subscribe.

Output variables

• Receive Complete: A Digital variable that becomes true the moment a new message is received and false otherwise.
• Received Topic: A Text variable for the topic of the received message.
• Received Message: A Text variable for the received message.

All three are displayed only when Command is Subscribe.

Modbus Communication

Exchanges data with industrial equipment such as PLCs and sensors using the Modbus protocol. Modbus is an industrial protocol developed in 1979 for communication between automation devices; it is simple and reliable and is widely used across industries. Modbus items (RTU Master, RTU Slave, TCP Master, TCP Slave) are registered in Settings > Modbus (Part 6).

Modbus

Select the Modbus item to use. The fields below are displayed when the selected item is an RTU Master or TCP Master. A Slave has no settings of its own; it serves the Master's requests each time the action runs.

Master fields

Unit ID

Enter the Unit ID of the Slave to communicate with, from 1 to 247. The default is 1.

Response Timeout

Enter how long (duration) to wait for the Slave's response to a request. The default is 3 seconds; when the time is exceeded, the connection to the Slave is considered lost.

Function Code

Select the function code of the request. The default is FC1.

Read Offset, Read Length

Enter the start address of the Slave memory area to read (0 to 65535, default 0) and the number of items to read (1 to 256, default 8). Displayed only when Function Code is FC1, FC2, FC3, FC4, or FC23.

Read Mapping

Assign in the table the variables that receive the values read. The number of rows follows Read Length; FC1 and FC2 show a bit (digital) table, and FC3, FC4, and FC23 show a register table.

Write Offset, Write Length

Enter the start address of the Slave memory area to write (0 to 65535, default 0) and the number of items to write (1 to 256, default 8). Displayed only when Function Code is FC5, FC6, FC15, FC16, or FC23.

Write Mapping

Assign in the table the variables that hold the values to write. The number of rows follows Write Length; FC5 and FC15 show a bit (digital) table, and FC6, FC16, and FC23 show a register table.

OPC UA Communication

Reads or writes nodes on an OPC UA server. OPC UA is an industrial standard protocol for exchanging data in a standardized way between equipment that uses different communication methods; it is used for integrating PLC-based systems, smart factories, building automation, energy management, and more. Server connections are registered in Settings > OPC UA Client (Part 6).

OPC UA Client

Select the OPC UA client to use.

Commands

• Read (default): Reads the value of a node on the server.
• Write: Writes a value to a node on the server.

Fields

Node ID

Enter the ID of the node to read or write in the standard OPC UA NodeId format: the namespace number and the identifier joined by a semicolon, with s for a string identifier or i for a numeric one (for example, ns=2;s=Temperature or ns=3;i=1001).

Read Value

Select the variable that receives the value read. Variables of every type can be selected. Displayed only when Command is Read.

Value Type, Write Value

Select the type of the value to write, Digital, Number (default), Text, or Byte Array, and enter a value of that type in Write Value. Displayed only when Command is Write.

HTTP Communication

Sends an HTTP request to a web server or REST API and receives the response. This action has no resource selection and no command field, and no field for request headers is provided. See Appendix B for an example that calls a weather API.

URL

Enter the URL to send the request to (for example, https://api.example.com/data or api.example.com/data). If http:// is omitted, it is added automatically.

Connection Timeout

Enter how long (duration) to wait for the server connection. The default is 5 seconds; when the time is exceeded, the connection is considered failed.

Method

Select the HTTP request method. The default is GET.

Content Type

Select the format (MIME type) of the request body. The default is text/plain, and 29 types are available, including application/json, application/x-www-form-urlencoded, and multipart/form-data. Displayed only when Method is POST, PUT, PATCH, CONNECT, or OPTIONS.

Request Body

Enter the request body. Displayed only when Method is POST, PUT, PATCH, CONNECT, or OPTIONS.

Output variables

• Response Code: A Number variable for the server's response code (for example, 200 or 404).
• Response Body: A Text variable for the server's response body. Values in a JSON response are extracted with the JSON blocks of the block editor (Part 8).

User Defined Communication

Communicates with external devices using frames that you define yourself. Serial, TCP, UDP, WebSocket, Bluetooth, and shared memory connections can be used, and connections are registered in Settings > User Defined Communication (Part 6).

User Defined Communication

Select the connection to use.

Commands

• Send (default): Sends the data composed in the frame.
• Receive: Receives data and interprets it according to the frame.

Receive Complete

Select a Digital variable that becomes true the moment new data is received and false otherwise. Displayed only when Command is Receive.

Frame

The data frame to send or receive is composed as a sequence of items added to the table. The frame works as follows.

• When sending: The data is composed from the items in order. Constants, variables, and integrity check items can be included; a variable contributes its value at the time of sending, and an integrity check item contributes its calculated result.
• When receiving: The received data is compared with the frame to check that it matches. A variable item parses the received data into the variable, and an integrity check item verifies that the calculated result of the received data matches.

Frame items

Name

Enter the name of the item. Any name can be used.

Type

• Digital (default): A true or false constant.
• Number: A numeric constant. The number format sets the byte size and whether it is an integer or a floating-point value.
• Text: A text constant.
• Byte Array: A byte array constant.
• Variable: Sends the value of a variable, or stores the received value in a variable. Only Digital, Number, Text, and Byte Array variables can be selected.
• Integrity Check: Calculates a check value over a range of the data and inserts it into the frame, or compares it with the received check value.

Value

Enter the constant value. Displayed only when Type is Digital, Number, Text, or Byte Array.

Variable

Select the variable to send or receive. Displayed only when Type is Variable.

Number Format

Select how the number is converted to bytes: 1-byte Integer (default), 1-byte Unsigned Integer, 2-byte Integer, 2-byte Unsigned Integer, 4-byte Integer, 4-byte Unsigned Integer, 4-byte Float, or 8-byte Double. Displayed only when Type is Number, or Variable with a Number variable selected.

Unknown Byte Size

Turn this on when the byte size of the data to receive is not known in advance. A frame can contain only one item of unknown size. Displayed only when Command is Receive and Type is Variable with a Text or Byte Array variable selected.

Byte Size

Enter the byte size of the data to receive, from 1 to 65535. That many bytes are parsed into the variable. Displayed only for Text or Byte Array variable items with Unknown Byte Size off.

Reverse Byte Order

Reverses the byte order of the data sent or received. Turn it on when the other device handles byte order (endianness) differently. Displayed only when the constant or variable type is Number, Text, or Byte Array.

Validation Method

Select the calculation used for the integrity check. The items from Start Data to End Data are the calculation range. Displayed only when Type is Integrity Check.

Start Data, End Data

Select the first and last frame items of the range over which the integrity check is calculated. Displayed only when Type is Integrity Check.

Convert to ASCII

When on, the calculated check value is inserted as a hexadecimal string (for example, 0x9C becomes the string "9C"). Displayed only when Type is Integrity Check.

PID Control

Calculates PID feedback control. PID stands for Proportional, Integral, and Derivative; the three terms are combined to minimize the error between the setpoint and the measured value. Controllers and their control direction (direct or reverse) are registered in Settings > PID Control (Part 6).

PID Control

Select the PID controller to use.

Commands

• Compute (default): Performs one PID calculation. This command must be repeated at a regular interval.
• Stop: Stops the PID calculation.

Fields

All of the following fields are displayed only when Command is Compute.

Proportional Gain (Kp), Integral Gain (Ki), Derivative Gain (Kd)

Enter the three gains. The default of each is 0.

Setpoint (SP)

Enter the target value the system should reach (for example, the set temperature in temperature control).

Process Variable (PV)

Select the Number variable that holds the measured value (for example, the measured temperature in temperature control).

Control Output (CV)

Select a Number variable to store the calculated control value, the quantity the system must adjust to reach the setpoint (for example, the opening of a boiler valve in temperature control).

Custom Action

Writes the action to run yourself with block coding. See Part 8 for using the block editor and the block categories, and Appendix E for the meaning of each block.

Action

Click Edit Block to open the block editor and write the action to run. The block has no return value, so it can be written freely.