Skip to content

Home Accessory Architect

Jump to bottom
José Antonio Jiménez edited this page Dec 9, 2019 · 118 revisions

Introduction

Home Accessory Architect (aka HAA) is an advanced firmware to bring native HomeKit to any device with an esp8266 controller, with OTA updates and fully customizable using a JSON string. It supports multiroom, that means you can put different services/accessories of same device in different HomeKit rooms.

Future features

Installation

Setup Mode

This mode is used to configure device. You can setup Wifi settings, JSON config, and reset HomeKit ID accessory.

If an invalid JSON string is detected, device will enter setup mode atomically.

Once device is in setup mode, you can access to a webGUI connecting to device IP address or hostname http://HAA-XXXXXX (in case a WiFi is configured) or connecting directly to a WiFi AP generated (HAA-XXXXXX) if configured WiFi network is not available.

http://haa-1a2b3c

If you installed it using OTA procedure, there is an option called "Auto OTA Updates" that allows to search updates every time device enters in setup mode, 90 seconds pasts, and setup web page is not loaded.

Entering Setup Mode

To enter setup mode, you must toggle quickly any action switch/button 8 times (physical or from Home App). You can secure this method declaring a timeout since device boots to perform it.

Additionally, you can declare a physical method to enter setup mode.

Emergency Setup Mode: If device is powered cut or freezes before 3 seconds since boots, next time it boots will enter in Setup Mode.

Reconnecting to Wifi network

If wifi network becomes unreachable, device will keep searching wifi automatically until it can connect again when wifi becomes available.

JSON config

To configure your device, it is necessary to create a JSON string that contains all information about accessories, GPIOs, button, relays, sensors, LEDs, displays...

See here some examples and templates

Also, you can use the tool Maximilian Beck is developing:

JSON Configurator Tool (Beta)

Not all keys are mandatories, and default values will be applied when optional keys are not present. You can use a JSON validator to check your string.

JSON can be written in multiple lines, but it is highly recommended to do in a single line because uses less memory size.

If you make changes in your JSON that involve accessory types, number of used accessories or change order of them, you must check "Reset HomeKit ID" from "Setup mode" and remove your device from HomeKit; and then you must pair it again.

JSON has 2 main sections: "c" and "a".

"c" General Config

This section is optional, and default values will be used if you don't use it.

It contains info about general setup of device. Keys are:

"o" Log output:

  • 0: Default. Disable logs.
  • 1: Enable UART log output.

"l" Status LED:

  • Default: none.
  • Set GPIO number where a status LED is connected.

"i" Inverted status LED:

  • 0: Normal.
  • 1: Default. Inverted.

"b": Array of buttons (or any binary inputs) to enter setup mode. See buttons declarations.

"f" Button filter:

  • Default: 10.
  • Set button filter parameter from 10 (soft) to 210 (hard) to avoid interferences. This is applied to all buttons.

"q" Custom PWM Frequency:

  • Set a custom PWM frequency, from 1 to 65535.

"n" Custom Hostname. It does not work in setup mode (in that case, default hostname is used):

  • Default: HAA-XXXXXX
  • Set a custom network hostname. It must be between quotes and must not use special characters or blank spaces.

"m" Time in seconds to allow to enter into Setup Mode:

  • Default: 0. There are not time limitations.

"h" Enable HomeKit Server:

  • 0: Disable.
  • 1: Default. Enable.

"u" Enable HomeKit rest API to use with third-party tools without an encrypted connection or authentication.

  • 0: Default. Disable.
  • 1: Enable.

Enabling this is not recommended for security reasons, because your accessory will be exposed without any security mechanism, but you can use this feature to manage it under other domestic systems.

You can use commands like these:

Get current accessory status:

curl -X GET http://device_ip_address:5556

Set a "turn on" status of accessory with aid 1 and iid 9:

curl -X PUT -d '{"characteristics":[{"aid":1,"iid":9,"value":true}]}' http://device_ip_address:5556/characteristic

You can download HomeKit specifications to know how to build its JSON from here: https://developer.apple.com/homekit/specification/

"a" Accessories

This section is mandatory. It contains an array of HomeKit accessories.

"t" Type:

Select accessory type:

  • 1: Default. Switch.
  • 2: Outlet.
  • 3: ...

"k": Kill Switches:

Creates simple HomeKit switches to enable or disable the attached accessory or a part of its functions.

  • 0: Default: No Kill Switches are used.
  • 1: Secure Switch: Accessory only works when this switch is turned on. Automations will not work.
  • 2: Kids Switch: Physical button/switches only works when this switch is turned on. Accessory can be managed always with a HomeKit client and automations will work.
  • 3: Secure Switch and Kids Switch.

Buttons declaration:

Each digital input (aka button) has these options:

"g": Digital input GPIO:

  • Mandatory. GPIO connected to the digital input.

"p": Internal pull-up resistor:

  • 0: Disable.
  • 1: Default. Enable.

"i": Inverted digital input:

  • 0: Default. Normal.
  • 1: Inverted.

"t": Press type:

You can have a same digital input (same GPIO) with different type attached to different accessories or functions. To create a toggle, you must declare 2 digital input types with same button/GPIO, type 0 and 1. Type 1 is the default, and it is triggered when you up button; and type 0 is triggered when you down button.

  • 0: Single press, opposite to 1.
  • 1: Default. Single press.
  • 2: Double press.
  • 3: Long press.
  • 4: Very long press.
  • 5: Hold press during 8 seconds.

"0", "1", "2", "3" ... Actions:

Actions performed on each state of the accessory. Are defined by a integer number.

Depending of selected accessory type, there will be different actions to configure.

You can copy actions from other Action declaration with "a", for example: If you have "0":{"r":[{"g":12,"v":1}]}, you can declare "3":{"a":0} and action "3" will do same actions of "0".

"r": Array of digital outputs (relays/LEDs) attached to an action.

Each digital output has these options:

"g": Digital output GPIO:

  • Mandatory. GPIO used.

"v": Value:

Value assigned to digital output:

  • 0: Default. Low, usually off.
  • 1: High, usually on.

"i": Inching:

Optional. Value in seconds to trigger digital output automatically to its previous state. You can use 2 decimals if you need.

  • Min value: 0.02
  • Max value: unknown, maybe near to infinite.

"m": Accessory Manager Actions: Array of orders, attached to an action, to manage other accessories from same device:

Each has these options:

"g": Target Accessory number: Accessories are defined in the same order of JSON, first is 1:

"v": Value: Target status that target accessory receives. See "Orders to be received" from each Accessory Type to know what values are valid.

Type 1: SWITCH

A standard HomeKit switch.

Actions:

  • "0": OFF.
  • "1": ON.

Orders to be received:

  • 0: Default. OFF.
  • 1: ON.

"s": Initial state:

  • 0: Default. OFF.
  • 1: ON.
  • 4: Defined by fixed inputs.
  • 5: Last state.
  • 6: Opposite to last state.

"b": Array of buttons (or any binary inputs) attached to the switch. See buttons declarations.

"f0", "f1" ...: Arrays of buttons (or any binary inputs) attached to a specific status. See buttons declarations.

  • "f0": Turns off switch.
  • "f1": Turns on switch.

"i": Inching:

Value in seconds to turn off HomeKit switch automatically. You can use 2 decimals if you need.

  • Min value: 0.02
  • Max value: unknown, maybe near to infinite.

"d" Maximum time in seconds to use with the switch (Timer is only accessible with third-party HomeKit clients). Don't use decimals:

  • Default: 0. It means disabled timer.
  • Max value: unknown, maybe near to infinite.

Type 2: OUTLET

A standard HomeKit outlet/plug. Options are same of Type 1

Type 3: STATELESS BUTTON

A stateless HomeKit button.

"f0": Array of buttons (or any binary inputs) attached to the stateless button single press event. See buttons declarations.

"f1": Array of buttons (or any binary inputs) attached to the stateless button double press event. See buttons declarations.

"f2": Array of buttons (or any binary inputs) attached to the stateless button long press event. See buttons declarations.

Actions:

  • "0": Stateless button single press event.
  • "1": Stateless button double press event.
  • "2": Stateless button long press event.

Orders to be received:

  • 0: Default. Single press event.
  • 1: Double press event.
  • 2: Long press even.

Type 4: LOCK MECHANISM

A HomeKit Lock Mechanism.

Actions:

  • "0": UNLOCK.
  • "1": LOCK.

Orders to be received:

  • 0: Default. UNLOCK.
  • 1: LOCK.

"f0", "f1" ...: Arrays of buttons (or any binary inputs) attached to a specific status. See buttons declarations.

  • "f0": Unlocked.
  • "f1": Locked.

"s": Initial state:

  • 0: Unlocked.
  • 1: Default. Locked.
  • 4: Defined by fixed inputs.
  • 5: Last state.
  • 6: Opposite to last state.

"b": Array of buttons (or any binary inputs) attached to the lock. See buttons declarations.

"i": Inching:

Value in seconds to lock it automatically. You can use 2 decimals if you need.

  • Min value: 0.02
  • Max value: unknown, maybe near to infinite.

Type 5: CONTACT SENSOR

A HomeKit Contact Sensor.

Actions:

  • "0": Sensor deactivated.
  • "1": Sensor activated.

Orders to be received:

  • 0: Default. Sensor deactivated.
  • 1: Sensor activated.

"f0", "f1" ...: Arrays of buttons (or any binary inputs) attached to a specific status. See buttons declarations.

  • "f0": Sensor deactivated.
  • "f1": Sensor activated.

"i": Inching:

Value in seconds to deactivate it automatically. You can use 2 decimals if you need.

  • Min value: 0.02
  • Max value: unknown, maybe near to infinite.

Type 6: OCCUPANCY SENSOR

A HomeKit Occupancy Sensor. Options are same of Type 5

Type 7: LEAK SENSOR

A HomeKit Water Leak Sensor. Options are same of Type 5

Type 8: SMOKE SENSOR

A HomeKit Smoke Sensor. Options are same of Type 5

Type 9: CARBON MONOXIDE SENSOR

A HomeKit Carbon Monoxide Sensor. Options are same of Type 5

Type 10: CARBON DIOXIDE SENSOR

A HomeKit Carbon Dioxide Sensor. Options are same of Type 5

Type 11: FILTER CHANGE SENSOR

A HomeKit Filter Change Sensor. Options are same of Type 5

Type 12: MOTION SENSOR

A HomeKit Motion Sensor. Options are same of Type 5

Type 20: WATER VALVE

A HomeKit Water Valve or Irrigation System.

Actions:

  • "0": OFF.
  • "1": ON.

Orders to be received:

  • 0: Default. OFF.
  • 1: ON.

"w" Valve Type:

  • 0: Default. Water Valve.
  • 1: Sprinkler.
  • 2: Shower.
  • 3: Tap.

"d" Maximum time in seconds to use with the valve. Don't use decimals:

  • Min value: 0. It means disabled timer.
  • Default: 3600.
  • Max value: unknown, maybe near to infinite.

"f0", "f1" ...: Arrays of buttons (or any binary inputs) attached to a specific status. See buttons declarations.

  • "f0": Off.
  • "f1": On.

"s": Initial state:

  • 0: Default. Off.
  • 1: On.
  • 4: Defined by fixed inputs.
  • 5: Last state.
  • 6: Opposite to last state.

"b": Array of buttons (or any binary inputs) attached to the water valve. See buttons declarations.

"i": Inching:

Value in seconds to turn off it automatically. You can use 2 decimals if you need.

  • Min value: 0.02
  • Max value: unknown, maybe near to infinite.

Type 21: THERMOSTAT

A HomeKit Thermostat. It requires a compatible sensor.

Actions:

  • "0": Total OFF.
  • "1": Thermostat ON, but heating OFF.
  • "2": Thermostat ON, cooling OFF.
  • "3": Heating ON.
  • "4": Cooling ON.
  • "5": Sensor error.

Orders to be received:

  • 0.01: OFF.
  • 0.02: ON.
  • 0.03: Heater mode.
  • 0.04: Cooler mode.
  • 0.05: Auto mode.
  • XX.Y0: Set heater temperature to XX.Yº.
  • XX.Y1: Set cooler temperature to XX.Yº.

"g": Sensor GPIO connected to device. It is Mandatory. Only, One-Wire sensors are supported.

"n": Sensor type:

  1. DHT11.
  2. Default. DHT22 Type 1.
  3. DS18B20.
  4. Si7021 and DHT22 Type 2.

"z": Temperature offset. You can use 2 decimals if you need:

  • Default: 0.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"w": Thermostat type:

  1. Default. Heater.
  2. Cooler.
  3. Heater and cooler.

"m": Minimum temperature in ºC you can set. You can use 2 decimals if you need:

  • Default: 10.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"x": Maximum temperature in ºC you can set. You can use 2 decimals if you need:

  • Default: 38.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"d": Temperature deadband to adjust how thermostat works. You can use 2 decimals if you need:

  • Default: 0.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"j": Sensor poll period, in seconds:

  • Default: 30
  • Min value: 3.
  • Max value: 65535.

"b": Array of buttons (or any binary inputs) attached to the thermostat to cycling current mode. See buttons declarations.

"f0", "f1" ...: Arrays of buttons (or any binary inputs) attached to a specific status. See buttons declarations.

  • "f0": OFF.
  • "f1": ON.
  • "f3": Change target temperature by +0.5º.
  • "f4": Change target temperature by -0.5º.

Use these fixed input instead "f1" when you select "w":3 as thermostat type:

  • "f5": ON. Mode Heater.
  • "f6": ON. Mode Cooler.
  • "f7": ON. Mode Auto.

"s": Initial state:

  • 0: Default. Off.
  • 1: Heating.
  • 2: Cooling.
  • 4: Defined by fixed inputs.
  • 5: Last state.

Type 22: TEMPERATURE SENSOR

A HomeKit Temperature sensor. It requires a compatible sensor.

Actions:

  • "5": Sensor error.

"g": Sensor GPIO connected to device. It is Mandatory. Only, One-Wire sensors are supported.

"n": Sensor type:

  1. DHT11.
  2. Default. DHT22 Type 1.
  3. DS18B20.
  4. Si7021 and DHT22 Type 2.

"z": Temperature offset. You can use 2 decimals if you need:

  • Default: 0.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"j": Sensor poll period, in seconds:

  • Default: 30
  • Min value: 3.
  • Max value: 65535.

Type 23: HUMIDITY SENSOR

A HomeKit Humidity sensor. It requires a compatible sensor.

Actions:

  • "5": Sensor error.

"g": Sensor GPIO connected to device. It is Mandatory. Only, One-Wire sensors are supported.

"n": Sensor type:

  1. DHT11.
  2. Default. DHT22 Type 1.
  3. None.
  4. Si7021 and DHT22 Type 2.

"h": Humidity offset. You can use 2 decimals if you need:

  • Default: 0.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"j": Sensor poll period, in seconds:

  • Default: 30
  • Min value: 3.
  • Max value: 65535.

Type 24: TEMPERATURE AND HUMIDITY SENSOR

A HomeKit Temperature and Humidity sensor. It requires a compatible sensor.

Actions:

  • "5": Sensor error.

"g": Sensor GPIO connected to device. It is Mandatory. Only, One-Wire sensors are supported.

"n": Sensor type:

  1. DHT11.
  2. Default. DHT22 Type 1.
  3. None.
  4. Si7021 and DHT22 Type 2.

"z": Temperature offset. You can use 2 decimals if you need:

  • Default: 0.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"h": Humidity offset. You can use 2 decimals if you need:

  • Default: 0.0
  • Min value: unknown, maybe near to -infinite
  • Max value: unknown, maybe near to infinite.

"j": Sensor poll period, in seconds:

  • Default: 30
  • Min value: 3.
  • Max value: 65535.

Type 30: LIGHTBULB

A HomeKit Dimmable Lightbulb with auto-dimmer managed by external switches/buttons. It can be Single Color, 2-channels selectable temperature color, RGB or RGBW. Hardware must be PWM controlled. Max total channels are 8.

Auto Dimmer

To activate it, ensure that light is on. Then, toggle twice switch or double press button. To stop, press it again once.

GPIO Channels: You must define them based on lightbulb type you want:

  • "r": Red channel.

  • "g": Green channel.

  • "v": Blue channel.

  • "w": White channel.

  • Single color: declare only "w".

  • 2-channels selectable temperature color: declare "v" for cool white and "w" for warm white.

  • RGB: declare "r", "g" and "v" for Red, Green and Blue colors.

  • RGBW: declare "r", "g", "v" and "w" for Red, Green, Blue and White colors.

RGBW Factor: Define the factor to be applied to the color target value. You can use 2 decimals if you need:

  • Default: 1

  • Min value: 0.01

  • Max value: unknown, maybe near to infinite.

  • "fr": Red factor.

  • "fg": Green factor.

  • "fv": Blue factor.

  • "fw": White factor.

"p": Step value applied to color transitions:

  • Default: 1024.
  • Min value: 1.
  • Max value: 65535.

"d": Autodimmer delay between each step, in seconds. You can use 2 decimals if you need:

  • Default: 1.0
  • Min value: 0.01
  • Max value: 65.5

"e": Autodimmer step percentage:

Setting it to 0 will disable autodimmer.

  • Default: 10.
  • Min value: 0.
  • Max value: 50.

Actions:

  • "0": OFF.
  • "1": ON.

Orders to be received:

  • 0: Default. OFF.
  • 1: ON.

"s": Initial state:

  • 0: Default. OFF.
  • 1: ON.
  • 4: Defined by fixed inputs.
  • 5: Last state.
  • 6: Opposite to last state.

"b": Array of buttons (or any binary inputs) attached to the lightbulb. See buttons declarations.

"f0", "f1" ...: Arrays of buttons (or any binary inputs) attached to a specific status. See buttons declarations.

  • "f0": Turns off lightbulb.
  • "f1": Turns on lightbulb.
  • "f2": Increase brightness by 10%.
  • "f3": Decrease brightness by 10%.

Type 40: GARAGE DOOR

A HomeKit Garage Door accessory. This can be used to manage your actual garage door driver, or be a stand-alone fully working driver.

If you don't use any sensor, or use only one, working time will be used to determine door state. If you use both sensors (for open and close: "f2" to "f5"), working time will be used as security measure alerting like a obstruction is detected if door does not complete operation before working time.

When an obstruction is detected, door stops and can not be operated until obstruction is removed.

"d" Working time needed by door to complete a fully opening. Don't use decimals:

  • Default: 30.
  • Min: 1.
  • Max value: unknown, maybe near to infinite.

Actions:

  • "0": Door is opened and receives closing order.
  • "1": Door is closed and receives opening order.
  • "2": Door is opening and receives closing order.
  • "3": Door is closing and receives opening order.
  • "4": Sensor detects opened door.
  • "5": Sensor detects closed door.
  • "6": Sensor detects opening door.
  • "7": Sensor detects closing door.
  • "8": Obstruction not detected.
  • "9": Obstruction detected.
  • "10": Emergency stop.

Orders to be received:

  • 0: Default. Open.
  • 1: Close.
  • 2: Emergency stop.
  • 3: Obstruction removed.
  • 4: Obstruction detected.

"s": Initial state:

  • 0: Opened.
  • 1: Default. Closed.
  • 5: Last state.
  • 6: Opposite to last state.

"f0", "f1" ...: Arrays of buttons, sensors or any binary inputs attached to a specific status. See buttons declarations.

  • "f0": Set garage door to open.
  • "f1": Set garage door to close.
  • "f2": Indicates that garage door is opened.
  • "f3": Indicates that garage door is closed.
  • "f4": Indicates that garage door is opening.
  • "f5": Indicates that garage door is closing.
  • "f6": Indicates that there is not obstruction.
  • "f7": Indicates that there is obstruction.
  • "f8": Emergency stop.

"b": Array of buttons (or any binary inputs) attached to the garage door to open and close it. See buttons declarations.

Releases | Installation | Configuration | Device Types | Devices Database | Examples

Home

Home Accessory Architect
Home Accessory
Installation
Setup Mode
HAA Home Manager App

Configuration
About
General
| GPIOs Configuration
Accessory
| Actions

Service Types
Air Quality
Battery
Data History
Fan
Free Monitor
Garage Door
HAA iAirZoning
Heater Cooler
Humidifier
Light Sensor
Lightbulb
Lock Mechanism
Sensors
Power Monitor
Security System
Stateless Button & Doorbell
Switch & Outlet
Temperature & Humidity
TV
Water Valve
Window Covering

Other
Devices Database
Infra-red
Migration HAA V12 Merlin

Examples
RavenCore v1
TODO List

Clone this wiki locally