A Comprehensive Guide to Using the Loxone API Connector

Learn how to unlock the full potential of your Loxone Smart Home with the powerful API Connector. This guide covers everything from basic setup to advanced automation scripts.

What is the Loxone API Connector?

The API Connector is a powerful interface that bridges Loxone devices (Touch Pure Flex, NFC Code Touch) with your smart home's function blocks. Through HTTP commands, it enables external systems like PLCs, servers, and custom applications to communicate with your Loxone installation. This makes it the perfect tool for both internal device communication and external automation integrations.

Why Use the API Connector?

• Device Integration: Connect Loxone devices like Touch Pure Flex and NFC Code Touch seamlessly
• External Control: Enable communication with PLCs, servers, and custom applications
• Automation: Create custom scripts and integrations using simple HTTP commands
• Flexibility: Implement both internal and external communication pathways

Prerequisites

• Loxone Config software (version 13 or later)
• Loxone Miniserver (Gen 1 or Gen 2)
• Access to your Miniserver's IP address (local network or cloud DNS)

Step-by-Step Setup Guide

Step 1: Create a Virtual Text Input

The API Connector relies on a Virtual Text Input (VTI) to receive commands:

1. Open Loxone Config
2. Navigate to Peripherals Virtual Inputs
3. Right-click and select Add Virtual Text Input
4. Name it appropriately (e.g., Example VTI)

Step 2: Create a User with Permissions

1. Go to Users & Permissions
2. Click on Add New User

1. Enter a username (e.g., test) and a strong password
2. Under Permissions, check Web Interface and App

1. In the Functions section, grant access to your Virtual Text Input

Using API Commands

Understanding the command structure is crucial for effective use of the API Connector.

Command Syntax

# Base URL Structure
http://<Miniserver_IP>/dev/sps/io/<Virtual_Text_Input>

# Command Format
SET(FunctionBlock;Input;Value)

# URL Encoding Note
# For VTI names with spaces (e.g., "Example VTI"), use %20: Example%20VTI
# For VTI names without spaces (e.g., "ExampleVTI"), use as is: ExampleVTI

# Example with Authentication
username:password@<miniserver-ip>/dev/sps/io/<Virtual_Text_Input>/SET(FunctionBlock;Input;Value)

Command Structure Breakdown

Let's break down the command structure piece by piece:

• Basic Authentication:
  username:password@
  Used when basic authentication is required. This is the standard way to authenticate your requests.
• Miniserver Address:
  <miniserver-ip or hostname>
  Your Miniserver's local IP address or hostname (e.g., 192.168.1.100).
• API Endpoint:
  /dev/sps/io
  The standard endpoint for accessing inputs and outputs in the Loxone system.
• Virtual Text Input:
  <Virtual_Text_Input>
  The name or UUID of your Virtual Text Input. Remember to use %20 for spaces in names.
• Command Structure:
  SET(FunctionBlock;Input;Value)
  The actual command being sent to the API connector.

Command Parameters Explained

• FunctionBlock:
  The short name of the function block (found under the i icon). Examples:
  

  

  • Lico - Lighting Controller
  • SW - Switch
  • IR - Intelligent Room Controller
• Input:
  The specific input name or abbreviation for the function block. Common examples:
  • On - Turn On
  • Off - Turn Off
  • Tg - Toggle
  • Mood - Target the Light Mood
• Value:
  The value to send, which can be:
  • 1 or 0 for binary inputs
  • pulse for momentary triggers
  • Float values (e.g., 22.5 for temperature)

Example Commands

# Turn On Lights
http://<Miniserver_IP>/dev/sps/io/Example%20VTI/SET(Lico;On;pulse)

# Turn Off Lights
http://<Miniserver_IP>/dev/sps/io/Example%20VTI/SET(Lico;Off;pulse)

# Toggle Switch
http://<Miniserver_IP>/dev/sps/io/Example%20VTI/SET(SW;TG;pulse)

Advanced Usage: Python Automation

Automate your Loxone commands using Python scripts. Here's a simple example to get you started:

import requests
from requests.auth import HTTPBasicAuth
import time

# Miniserver configuration
local_url = "http://192.168.0.69/"
serial_number = "504F94A1242E"
username = "Test"
password = "Test123"
virtual_text_input = "ExampleVTI"

basic = HTTPBasicAuth(username, password)

# For remote access
external_url = f"http://dns.loxonecloud.com/{serial_number}"
resolved_external_url = (requests.get(external_url)).url

# Command structure
command_base = f"dev/sps/io/{virtual_text_input}/"
lights_on = "SET(Lico;On;Pulse)"
lights_off = "SET(Lico;Off;Pulse)"
toggle_switch = "SET(Sw;Tg;Pulse)"

# Execute a command on the local network
def execute_local_command(command):
    command = local_url + command_base + command
    return print(requests.get(command, auth=basic))

# Example usage
execute_local_command(toggle_switch)

For a complete Python implementation, check out theLoxone Templates repositorywhich includes additional examples and functionality.

Remote Access

To control your Miniserver remotely, use the Remote Connect address:

# Step 1: First resolve your Miniserver's cloud address
https://dns.loxonecloud.com/<Miniserver_Serial_Number>
# This will redirect to something like: https://195-201-222-243.504f94aXXXXX.dyndns.loxonecloud.com:48284/

# Step 2: Use the resolved address to send commands
# Example Command (using the resolved address)
https://195-201-222-243.504f94aXXXXX.dyndns.loxonecloud.com:48284/dev/sps/io/Example%20VTI/SET(SW;TG;pulse)

# Note: Ensure Remote Connect is enabled on your Miniserver

Additional Resources

• Loxone API Documentation

Video Tutorial

If you prefer to learn through video, check out our detailed walkthrough of the Loxone API Connector setup and usage:

In this video, we demonstrate the complete process of setting up and using the API Connector, including practical examples and common troubleshooting tips.