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

Each of the above configuration options are described below, along with their default values.

Additional to the above list of configuration options a set of Device Actions can be configured to be taken when specific device events occur.

The new Advanced Logger Library was implemented in HAA v2.4.0. This library provides additional options for outputting log information and supports the new UART configurations added in v2.1.0. You can now choose to disable logs, output them to serial ports, the network, or both.

If you are not intending to view or capture logs then it is recommended to leave the option as the default ("o":0) i.e. disable log output.

Enabling log output is only useful if you need to see what the firmware is doing.

When enabling serial port logging ensure that you have a terminal attached to the UART output. In order to view the output.

Remember to configure used UART when enabling serial port logging.

If network logging is enabled then the log output can be captured and viewed using the following command on macOS or GNU/Linux:

nc -kulnw0 45678

NOTE: Network logs can impact system stability. If you want to use network logs for a long time, buffered options are recommended (8, 9, 10 and 11), but they take more RAM memory.

Use "ot":"<server>:<port>" option to specify destination address for network logs, and port. A FQDN hostname can be used.

Set the GPIO pin used for LED status information. If you are using Sonoff devices, the LED is usually connected to GPIO 13 e.g. {"l": 13}

Remember to declare used GPIO as Output into "io":[...] array. See GPIOs Configuration

Set the activation level for the LED GPIO output. On a Sonoff device the LED GPIO is usually active low, so you will need to invert the output of the GPIO in order to ensure the LED lights when enabling the output e.g. {"i": 1}, but since the default is 1 this option can be omitted from the string to save device memory.

If your device has one or more buttons and you want to use any of them to have a physical means of invoking the setup mode then you will need to define "b" to contain a list of those buttons and the action that will cause setup mode to be entered e.g.

{
  "c": {
    "io": [ [ [ 13 ], 2 ], [ [ 0 ], 6 ] ],
    "l": 13,
    "b": [ [ 0, 5 ] ]
  }
}

In this example the binary input "b" key contains a single definition of a button connected to GPIO 0 and configured with a press type 5, of Hold for 8 seconds.

See here for more examples of different press types.

To understand more about defining binary inputs refer to binary input declarations.

The binary software input filter "f" can be set to any integer value between 10 (soft) and 2550 (hard) to avoid interference such as debounce from the input when a button pressed.

NOTE: The binary software input filter value is used for all binary inputs defined in the MEPLHAA script.

Only available in ESP32-C6.

Chip provides 8 hardware flexible input filters, whose duration is configurable. Each of them can be applied to any input GPIO. However, applying multiple filters to the same GPIO does not make difference from one.

• GPIO: Number of GPIO to apply filter.
• Threshold: Threshold time in nanoseconds (Integer).
• Width: Width time in nanoseconds (Integer).

During window Width, any pulse whose width is shorter than window Threshold will be discarded. Please note that you can not set Threshold time bigger than Width time.

Please note, the glitch filter and flex filter are independent. You can enable both of them for the same GPIO.

By default, Binary Input Continuous Mode is not used because HAA uses ISRs (Hardware interruptions) to detect changes in input GPIOs. But there are some GPIOs that don't allow hardware interruptions, like GPIO 16 of ESP8266. Use of I/O expanders as input are incompatible with interruptions too, and GPIOs using pulse mode. In these cases, it is needed to enable Continuous Mode to avoid use of hardware interruptions.

To summarize, Binary Input Continuous Mode must be enable for any of these cases:

• Using a GPIO as input button/switch that doesn't allow ISR, like GPIO 16 of ESP8266.
• Using a GPIO as input button/switch with pulse mode.
• Using an expansion interface as inputs buttons/switches.

This option enables you to change the hostname of a device. By default the hostname is set to HAA-XXXXXX where "XXXXXX" are the last 6 characters of the Ethernet MAC address of the device.

If you want to use a friendly name to identify your device in your router's DHCP list etc. then put it in this option.

{
  "c": {
    "io": [ [ [ 13 ], 2 ], [ [ 0 ], 6 ] ],
    "l": 13,
    "b": [ [ 0, 5 ] ],
    "n": "sonoff-laptop"
  }
}

In the above example the device hostname has been set to a friendly name of "sonoff-laptop". The custom hostname must be in quotes and and must not use special characters or blank spaces. Refer to Hostnames to get more details on valid hostnames.

NOTE: During initial device setup i.e. after factory reset or very first boot, the name will be HAA-XXXXXX.

HAA sends a Gratuitous ARP packet (GARP) each 285 seconds, by default, to prevent ARP spoofing attacks and keep WiFi connectivity. Normally, switches and routers have an ARP TTL of 300 seconds. Using a very low value, like "e":3, could help to keep WiFi connectivity and avoid disconnections in noise environments.

This option enables the setting of a custom software PWM frequency in Hz. The value can be set from 1 to 2000. The default is 305 Hz.

A custom PWM frequency is predominantly used when controlling lighting. Setting "q" to lower values may result in lights blinking very fast.

Only for ESP32 models.

This option enables the setting of custom hardware PWM frequencies in Hz for each PWM timer. The value can be set from 1Hz to 29KHz. The default is 5KHz.

A custom PWM frequency is predominantly used when controlling lighting. Setting "y" to lower values may result in lights blinking very fast.

Enables Software PWM to be used by Zero-Cross detection. PWM Frequency should be double of AC frequency, and even a bit more (Double + 10%). For example, for AC 50Hz, a right value of PWM Frequency could be "q" : 110.

• GPIO: Number of GPIO where Zero-Cross pin is connected.

Remember to declare used GPIO as Input into "io":[...] array. See GPIOs Configuration

• Interrupt type: Depending of how Zero-Cross hardware works, it is necessary to select correct interrupt. Normally, HIGH to LOW is the recommended value.

Determines Accessory number (not Service) where HAA Setup Service will be placed. This service is only compatible with HAA Home Manager App, to update, enable setup mode, reboot...

By default, service is placed at first accessory. But in some cases it is useful to put it in other accessory, for example, when first accessory has a TV Service, that is not showed in HomeKit third-party Apps.

A value of 0 will disable HAA Setup Service. Useful to save DRAM when HAA Home Manager App is not used.

You can declare up to 2 different I2C buses. To declare them, you must use "ic" key in configuration section. It contains an array of I2C buses.

Each bus must have these settings:

[ SCL, SDA, Frequency, SCL pull-up,  SDA pull-up ]

• SCL: SCL GPIO.
• SDA: SDA GPIO.
• Frequency: Bus frequency in KiloHertz.
• SCL pull-up: Internal SCL GPIO pull-up resistor. 0 disable, 1 enable.
• SDA pull-up: Internal SDA GPIO pull-up resistor. 0 disable, 1 enable.

SCL pull-up and SDA pull-up are optional. Default value is 0 for both.

First declared bus will be bus 0, and second will be bus 1.

Example:

"ic" : [ [ 3, 2, 80, 1, 1 ], [ 13, 14, 500 ] ]

IO Expansion interfaces are used to add extra GPIOs for inputs and outputs. They must declare in configuration section using "mc" key. It is an array that contains all connected expansion interfaces.

MCP23017 and Shift Registers are supported:

You can connect up to 16 MCP23017 interfaces (8 per I2C bus), having up to 256 extra GPIOs for binary inputs and outputs. I2C bus must be declared to use these interfaces.

Each MCP23017 interface must be declared with an array:

[ Bus, Address, Channel A, Channel B ]

Example of 2 MCPs declaration (first for inputs and second for outputs):

"mc" : [ [ 0, 32, 256, 256 ], [ 0, 33, 0, 0 ] ]

Channel A and B are optional. If they are missed, default value is 258.

• Bus: I2C Bus.
• Address: Access address. First MCP23017 begins at 32. MCP address is configured using A2, A1 and A0 pines. FInal address will be 32 + (A2, A1, A0); where A2, A1 and A0 represent a binary number of 3 bits, and each bit is 0 or 1 depending is pin is connected to GND or VCC.
• Channel A: from 0 to 259. Mode and initial state of all channel A GPIOs.
• Channel B: from 0 to 259. Mode and initial state of all channel B GPIOs.

Channel config values (Default 0):

• 0 - 255 : OUTPUT. Values are the result of convert 8 bits binary string to decimal.

For example, to set all channel A GPIOs to LOW, but second GPIO to HIGH, you must use 00000010 in decimal: 2.

• 256 - 259 : INPUTs
  • 256 : INPUT with internal pull-up resistor.
  • 257 : INPUT with internal pull-up resistor, inverted logic.
  • 258 : INPUT without internal pull-up resistor. Use this if channel is not used.
  • 259 : INPUT without internal pull-up resistor, inverted logic.

Remember to activate Binary Input Continuous Mode in order to work with INPUTs.

You can connect one shift register, or a daisy-chained group of them, for each 3 GPIOs (or 2 if shift register does not use latch pin). Each shift register can manage up to 100 OUTPUTs (from 0 to 99).

To declare a shift register as OUTPUT, declare it as:

[ Clock GPIO + 100, Data GPIO, Latch GPIO, Length, Initial values 1, Initial values 2, ... ]

• Clock GPIO + 100: Signal clock. If you want to use GPIO 5, this will be 105. By default, it is declared as OUTPUT.
• Data GPIO: Pin to send bit states to shift register. By default, it is declared as OUTPUT.
• Latch GPIO: Pin to send order to activate sent data. If Latch GPIO is not needed, set this as -1. By default, it is declared as OUTPUT.
• Length: Numbers of bits/outputs of shift register of daisy-chained group. Maximum value is 100 (from 0 to 99).
• Initial values: Each default value is a 8 bits number that correspondes to initial output states. Default value is 0.

You can connect one shift register, or a daisy-chained group of them, for each 2 GPIOs. Each shift register can manage up to 100 INPUTs (from 0 to 99).

Remember to activate Binary Input Continuous Mode in order to work with INPUTs.

To declare a shift register as INPUT, declare it as:

[ Clock GPIO + 100, Data GPIO, -2, Length ]

• Clock GPIO + 100: Signal clock. If you want to use GPIO 5, this will be 105. By default, it is declared as OUTPUT.
• Data GPIO: Pin to read bit states to shift register. By default, it is declared as INPUT, floating.
• Length: Numbers of bits/outputs of shift register of daisy-chained group. Maximum value is 100 (from 0 to 99).

It is possible to override shift registers default GPIOs type declarations in "io":[ ... ] GPIOs Configuration Array.

Use "r":[ pin, value ] with I/O expander index and GPIO number. For example: GPIO 12 of first declared IO expander will be 112.

To call a GPIO from a expansion interface, you must use normal "r":[ pin, value ] array. ESP8266 GPIOs are from 0 to 16, but expander GPIOs are used in this format: XYY

• X: is the index of expansion interface in MEPLHAA script.
• YY: is the number of GPIO. (For MCP23017, Channel A GPIOs are from 00 to 07; and channel B, from 08 to 15).

For example, to set to HIGH GPIO 4 of third declared expansion interface:

"r" : [ [ 304 , 1 ] ]

Since HAA V12 Merlin, used GPIOs must be declared into an array with needed options, initial values, and behaviors.

See GPIOs Configuration page to know details.

HAA has an internal software clock to write a timestamp in logs and to perform timedate based actions. Because ESP8266 has not a RTC with a battery, it is needed to get date and time information from a NTP server.

Example:

"ntp" : "time.apple.com"

If configured or default NTP server fails twice, HAA will use pool.ntp.org as fallback server.

Timezone for Europe/Paris with daylight saving time:

"tz" : "CET-1CEST-2,M3.5.0/2,M10.5.0/3"

These actions will occur only if there is a working NTP server to get current date and time.

If action must occur in all units, value of -1 must be used.

There is not needed to declare all timedate units. Missing units will take default value of -1.

Setup mode toggle count was introduced in firmware version 0.8.7

One way to enter setup mode is to toggle the I/O line of one of the buttons defined for entering setup mode.

This option allows the configuration of the number of times to toggle the I/O. A value of 0 will disable this method of entering setup mode.

This option specifies the time in seconds that the user has to enter setup mode after a device boot. Any value between 0 (disable) and 65535 can be set. See Setup Mode for details on how to enter the mode.

If this option is set then once the time has passed after a reset the user will not be able to enter setup mode without rebooting the device.

{
  "c": {
    "io": [ [ [ 13 ], 2 ], [ [ 0 ], 6 ] ],
    "l": 13,
    "b": [ [ 0, 5 ] ],
    "m": 10
  }
}

In this example the Setup Mode Timer has been set to 10 seconds ("m": 10). Beware not to set it to a value to less than 8 if you are using option "b" with a long press button of 8 seconds ("t": 5)...

The Delay at boot option, before any hardware configuration or GPIO setup has been done, is defined by the "v" key.

Useful when peripherals and external hardware need more time to boot than ESP chip.

The Delay before services creation option is defined by the "cd" key.

By default accessories are created within HAA immediately after boot. There are times when a delay is required to allow some hardware to be ready.

When this is required the "cd" option can be used. Set it to a positive value in seconds and a delay of that time will occur once the device has booted.

The option only needs to be added if a delay is required. If it is not present then no delay will be executed.

The "h" option allows you to change maximum number of simultaneous HomeKit clients that can connect to device, or completely disable the HomeKit server component.

HomeKit clients are iPhones, iPads, Macs, HomePods, AppleTVs and AppleWatches.

By default, up to 20 concurrent clients can be connected; and allowing to connect new clients while dropping others. Then, there is not limit of clients to connect, but new clients access will be a bit slower than connected clients. If there are many HomeKit clients, it is possible to increase this limit to let more clients to connect before dropping others, but this will use more DRAM.

This option enables the use of HomeKit third-party tools without an encrypted connection or authentication.

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/

Only ESP32 models. ESP8266 has not wifi sleep DTIM mode.

Option to enable or disable WiFi Modem sleep. By default, WiFi driver will use router DTIM beacon to transmit and receive data; but some networks can be incompatible with this, and disable WiFi sleep modem is needed.

Only ESP32 models. ESP8266 has not wifi bandwidth 40MHz.

By default, wifi bandwidth is 20MHz. It is enough for all HAA network traffic, and to mitigate interferences.

It is possible to select 40MHz, but only for HAA Main firmware running in normal mode.

Installer firmwares and setup modes will use only 20MHz to maximize compatibility and minimize interferences.

Configurable option to set the TTL value of the mDNS entry held for the device.

This option was implemented in firmware version 2.2.0

Default: "ttl" : [ 4500, 2250 ]

If period is not given, it will be same value as TTL.

Setting period to a very low value such as "ttl" : [ 4500, 120 ] could be used as a workaround for networks without a good mDNS support.

This option was implemented in firmware version 3.5.0

This option enables you to add a prefix to the serial number supplied to HomeKit when pairing a device.

Prior to release 3.5.0 the serial number provided for each accessory when pairing a device was of the format HAA-XXXXXX where the XXXXXX part consists of the last 6 characters of the devices MAC address e.g. HAA-669CD4. From 3.5.0 onwards the serial number provided is of the format XXXXXX-<Acc#>. Where <Acc#> is the configured accessory number e.g. 669CD4-1. This change enables applications such as Home Assistant to recognise the multiple accessories within a device (NOTE: the Apple Home App has always been lenient on the serial number, but recommends a unique serial number for each device/accessory).

The user also has the option to prefix the serial number provided with their own string e.g. { "sn": "ABC" }. This would result in a serial number of ABC-669CD4-1

Additionally, if you specify a prefix of { "sn": "cn" } the HomeKit config number will be used as the prefix. The config number will be incremented each time the Save button is pressed in the Setup page and after the device's firmware is updated e.g. 1-669CD4-1, 2-669CD4-1

Setting this option in the General Configuration section will apply it to all accessories.

NOTE This option can also be placed in an accessory's configuration section. If used in the Accessory Configuration section then it will override any value that has been set as part of the General Configuration.

This option was implemented in firmware version 2.2.0

This option enables you to configure the period between pings being transmitted by an accessory that determine actions to take or statuses to set.

The value is a float and so fractions of a second can be specified e.g. "pt": 0.5

This option was implemented in firmware version 2.5.0

When this option is added to the general configuration the device will monitor the network by performing an ICMP ping to the gateway every second. If the configurable number of consecutive ping failures occur then the device will start the connection process again.

This feature is disabled by default. If enable, default Gratuitous ARP will be disabled. To enable Gratuitous ARP, it must be declare explicitly.

NOTE: If a value of 0 is used ("w":0) then the device will attempt to reconnect after the first ping failure.

When using your device to transmit infra-red commands to control other devices you need to, as a minimum, set the "t" option to define the GPIO pin that the infra-red transmitter is connected to.

Remember to declare used GPIO as Output into "io":[...] array. See GPIOs Configuration

The "j" option is used to invert the state of the IR Tx LED GPIO pin and configure open-drain HIGH output.

The "x" option allows you to define the frequency in Kilohertz (KHz) that the IR LED flashes. The default is 38KHz. This frequency is used by the majority of infra-red controllers on the market today.

The "p" option allows you to define the default IR protocol. This protocol will be used by any IR Code Actions unless the action specifies an alternate protocol using the "p" option in the action object.

Refer to the IR Code Actions section in the Accessory Configuration details for information on defining IR code actions.

Refer to the Using Infra-red in HAA for details on defining the protocol and protocol codes.

Your device can use up to two UART ports to control accessories. To use UART ports you must configure them within the General Configuration and then use UART Actions to send commands, but can not get status from your attached accessory.

{
  "c":{
    "io": [ [ [ 13 ], 2 ], [ [ 0 ], 6 ] ],
    "l": 13,
    "b": [ [ 0, 5 ] ],
    "r": [
      { "n":0, "s":9600, "p":0, "b":0 }
    ]
  }
}

In this example UART0 has been set up to communicate at 9600 baud, no parity and 0 stop bits.

In esp8266, the UART will use GPIO lines 1 & 3 for communication.

This option was implemented in firmware version 2.1.0

The "n" key is used to define up to two UARTs can be configured and used to control accessories. In ESP8266, there are 2 UARTs. UART0 supports both receive and transmit, UART1 supports only transmit.

In ESP32 models, there are 3 UARTs with receive and transmit support.

ESP32 can use any combination of GPIOs with UARTs. There is not default GPIOs, then it is mandatory to declare used GPIOs into an array "g": for each UART port.

"g" : [ TX, RX, RTS, CTS ]

Pins that are not used must be declared with -1, or don't declare them, using a shorter array.

For example, if you only want to use UART TX pin with GPIO 1, because it will be only used for output, you can declare array as:

"g" : [1]

Or if only RX pin will be used at GPIO 3:

"g" : [ -1, 3]

UART supports different modes.

The "s" key is used to set the baudrate of the UART. The following baudrates are supported:

The "p" key is used to set the parity of the UART. The following options are supported:

The "b" key is used to set the stop bits of the UART. The following options are supported:

Option to configure minimum and maximum length of received UART commands when UART Receiver is used.

"l" : [ min , max ]

Values must be between 1 and 255. And min value can not be greater than max value.

This option was implemented in firmware version 3.3.0

Certain actions can occur when specific events happen within the device. These actions are called Device Actions and are documented below.

Available Device events are:

See Actions for details on the actions that can be defined for each of the above events.

Additional device actions can be declared to use with Timetable Actions, up to action "50".

In this example the device is configured to turn on an LED (GPIO 14) when the device has WiFi connectivity and turn it off when connectivity is lost.

{
  "c": {
    "io": [ [ [ 13, 12, 14 ], 2 ], [ [ 0 ], 6 ] ],
    "l": 13,
    "2": {  "r": [ [ 14, 1 ] ] },
    "3": {  "r": [ [ 14, 1 ] ] },
    "4": {  "r": [ [ 14, 0 ] ] },
    "5": {  "r": [ [ 14, 0 ] ] }
  },
  "a": [{
    "t": 1,
    "0": { "r": [ [ 12, 0 ] ] },
    "1": { "r": [ [ 12, 1 ] ] },
    "b": [ [ 0, 1 ] ]
  }]
}

This option was implemented in firmware version 3.2.0

The "ct" option enables the HomeKit device category to be overwritten or customised. If this option is not specified then the device category that is presented to HomeKit when a device is added is taken from the first accessory in the accessory definitions list.

Device categories available are: