SimpleHome API

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 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 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; See below
mode	String	Mode of the command; See below
data	Boolean	Initial state for switch mode

Supported values for icon

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

Supported values for mode

• action
• switch
• input
• none

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.