General Configuration - WizBangCrash/esp-homekit-devices GitHub Wiki

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

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.

If network logging is enabled then the log output can be captured and viewed using the following command on a macOS PC nc -kulnw0 45678.

NOTE: If you are using firmware versions earlier than 2.4.0 only options "o":0 & "o":1 are available.

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}

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": {
    "l": 13,
    "b": [{ "g": 0, "t": 5 }]
  }
}

In this example the digital input "b" key contains a single definition of a button connected to GPIO 0 ("g": 0) and configured with a press type of Hold for 8 seconds ("t": 5).

See here for more examples of different press types.

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

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

NOTE: The digital input filter value is used for all inputs defined in the JSON configuration.

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": {
    "l": 13,
    "b": [{ "g": 0, "t": 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.

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

A custom PWM frequency is predominantly used when controlling lighting. If you see sporadic flashes the you it may help to reduce the PWM frequency to 500 or 600 Hz. Setting "q" to lower values may result in lights blinking very fast.

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": {
    "l": 13,
    "b": [{ "g": 0, "t": 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 "h" option allows you to completely disable the HomeKit server component of the device. Doing this will stop all HomeKit notifications and state changes being processed. You device will also no longer be seen and accessible from the HomeApp.

This option enables the use of 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/

This option was implemented in firmware version 2.2.0

Configurable option to set the TTL value of the mDNS entry held for the device. Setting this to a very low value such as "ttl":5 could be used as a workaround for networks without mDNS support.

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

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.

The "j" option is used to invert the state of the IR Tx LED GPIO pin. A value of 1 inverts the GPIO and 0 (default) is non-inverting.

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.

When UART0 is used, logs will be redirect to UART1 unless that is use also.

{
  "c":{
    "l":13,
    "b":[{"g":0,"t":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. 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. UART0 supports both receive and transmit, UART1 supports only transmit.

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: