Skip to content

SimpleHome API

Jump to bottom
Dominik edited this page Jun 14, 2023 · 13 revisions

What is that?

The SimpleHome API is an easy to use API for devices like Arduinos or Raspberry Pis.

Communication between the devices uses HTTP GET requests and JSON strings. After the commanding device has send a HTTP request to the smart home device, the smart home device sends back a JSON string containing the information the app needs.

Device Discovery

UPnP (SSDP)

If implemented by the developer, it is possible to discover a compatible device using the Simple Service Discovery Protocol (SSDP), which is part of UPnP.
If the responses contain SimpleHome, it is considered to be a compatible device. Take a look at the Arduino Example to see how it can be implemented.

mDNS (Zeroconf/Bonjour)

HomeApp finds devices that announce the _simplehome._tcp mDNS service type.

The optional url TXT record parameter can be used to configure a custom URL for the service. Specifying the url lets you announce multiple services on the same host.

Example configuration

You can use the avahi daemon to announce a SimpleHome service for autodiscovery with the following configuration file:

<?xml version="1.0"?>
<service-group>
  <name>Lamps for HomeApp</name>
  <service protocol="ipv4">
    <type>_simplehome._tcp</type>
    <port>80</port>
    <txt-record>url=http://simpleapi-homeapp.example.org/</txt-record>
  </service>
</service-group>

HomeApp will create a new device with title "Lamp for HomeApp" and URL http://simpleapi-homeapp.example.org/. If the service has no TXT record, it will use the IP address of the device: http://192.168.23.42/.

List of Commands

On your smart home device, you have to respond to HTTP requests for path /commands with a string as follows:

{
  "commands": {
    "example": {
      "title": "Title of the command",
      "summary": "Summary of the command",
      "icon": "display",
      "mode": "action"
    }
  }
}

The list entry will be generated with the title Title of the command and the summary Summary of the command. If you click on it, a HTTP GET request for URL example will be sent.

Parameters

All parameters are optional.

Key Type Description
title String Title of the command
summary String Summary of the command
icon String Icon of the command
mode String Mode of the command
data Boolean Initial state for switch mode

Supported values for icon

  • christmas tree
  • clock
  • display
  • display alt
  • electricity
  • gauge
  • hygrometer
  • lamp
  • raspberry pi
  • router
  • socket
  • schwibbogen
  • speaker
  • stack
  • thermometer
  • webcam

Supported values for mode

Key Description
action General type without parameters (default)
switch Type for providing switch actions
input Type for handling string inputs
none Read-only type for providing information

Command Execution

This second request should be answered with a string like this:

{
  "toast": "This is the feedback!"
}

This will show the user a toast with the message This is the feedback!.

You can also add the optional parameter refresh, to refresh the command list after execution as seen with the example below.

{
  "toast": "This is the feedback!",
  "refresh": true
}

User Input

When using the modes switch or input the user input is sent as the GET parameter Input to the specified URL.

# For switches:
http://127.0.0.1/example?input=0 
http://127.0.0.1/example?input=1 

# For inputs:
http://127.0.0.1/example?input=your%20input

Version

This documentation corresponds to version 1.8.1 or later.

Clone this wiki locally