This section is mandatory. It contains an array of HomeKit accessories that are available on your device.

Each accessory has a HomeKit service with a number of keys defined to describe it and how it should behave. The list of keys that can be used in any service are contained below. Also check each specific service for details of other keys available for that specific service type.

Each element of the array is made of a service type definition, a set of Actions to perform when binary inputs change state and the binary inputs that cause the actions to occur. Multiple accessories can be defined for the same physical device. A configuration file should have the following layout e.g.

{
  "c": { ... },        <-- Configuration definition
  "a": [
    {                  <-- First accessory
      "t": 2,          <-- Service Type definition
      "0": { ... },    <-- Action definition
      "1": { ... },    <-- Action definition
      "b": [[ ... ]]   <-- Binary I/O input definitions
      "l": [{ ... }]   <-- ICMP Ping input definitions
      "s": 5           <-- Initial State definition
      "f0": [[ ... ]]  <-- State Inputs definitions
      "g0": [[ ... ]]  <-- Status Inputs definitions
      "q0": [{ ... }]  <-- ICMP Ping status definitions
      "p0": [{ ... }]  <-- ICMP Ping state definitions
      "y0": { ... }  <-- Wildcard action definitions
    },
    { ... },           <-- Second accessory
    { ... }            <-- Third accessory
  ]
}

The above outline example shows the layout for the configuration settings. The first accessory has been expanded to show the different objects that can be defined for an accessory. The documentation below details the generic information. Refer to each specific device type to understand the actions, binary inputs and notifications available for it.

Every accessory needs to have the type "t" option set. This defines the type of HomeKit service that the hardware supports e.g. switch, sensor, thermostat etc.

Refer to the list of service types to determine the value to use for the "t" option.

Optionally, each accessory can have extra services, adding more features to same accessory. Some advantages declaring more services into an accessory instead creating a different one is to save RAM, to group services in Apple Home App, to create some special accessories that work with group of services (Power strips, irrigation systems...).

It is possible to create any combination of any HomeKit Service into same accessory. Each extra service will can have same options that accessory main service, but Serial Number Prefix.

Since extra services are related only to HomeKit accessories, those services declared with "h":0 to not add them to HomeKit can not be into "es": array and must be declared as stand-alone accessories.

Main recommendation is to add all services into same accessory that stays at same HomeKit room.

This is an example of a Power Strip, created with 3 outlets into same accessory (2 of them are extra services):

{
  "c": { ... },        <-- Configuration definition
  "a": [
    {                  <-- First accessory
      "t": 2,          <-- Service Type definition
      "es": [          <-- Array of extra services
        {              <-- Second service
          "t": 2       <-- Service Type definition
        },
        {              <-- Third service
          "t": 2       <-- Service Type definition
        }
      ]
    }
  ]
}

Binary inputs array e.g. buttons, are defined by the "b" key within an service object.

This is an array of objects defining the GPIOs the inputs use, configuration of the GPIO e.g. whether or not it needs a pull up resistor, and the state of the input e.g. normal or inverted signal.

Remember to declare used GPIOs as Input only with binary input (button/switch) support into "io":[...] array. See GPIOs Configuration

A binary input is a GPIO pin (or pins) that causes service action "0" then service action "1" to be triggered each time the defined state in key "b" is met e.g. the first time the input state occurs service action "0" will be triggered. The second time the input state occurs service action "1" will triggered. The third time the input state occurs service action "0" will be triggered etc.

Binary input key "b" is an array object. Multiple GPIO inputs can be defined to cause service actions "0" & "1" to be triggered.

Each object must be an array [ gpio, type ]

type is optional, and default value of 1 will be used if it is missed.

{
  "c": {
    "io": [ [ [ 0 ], 6 ], [ [ 12 ], 2 ] ]
  },
  "a": [{
    "t": 1,
    "0": { "r": [ [ 12, 0 ] ] },
    "1": { "r": [ [ 12, 1 ] ] },
    "b": [ [ 0, 1 ] ]
  }]
}

In the above example a button is attached to GPIO 0 and the button is activated by a single press.

NOTE: The example above has entries for the default values. It is recommended these are omitted in an actual configuration to reduce memory usage.

These options are explained in more detail below.

This option is mandatory for each binary input definition and must contain the GPIO number the input is connected to. If you want to use ESP8266 ADC as binary input, declare it as GPIO 17.

This option defines the type of press required on an input to initiate an action.

You can have the same binary input / GPIO with different press types attached to different services or functions.

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

In this example we have created a toggle switch by declaring two binary input types with the same GPIO 14 one of press type 1 and one of press type 0. When you press the button down type 0 is triggered and on button up type 1 is triggered (the default type)

ICMP Ping inputs were introduced in firmware version 1.4.0

ICMP ping inputs can be action or state oriented, depending on whether you are trying to update the state of your service or perform an action, based on the ping response.

The "l" and "p[n]" objects are action objects and follow the same rules as Binary Inputs and State Inputs. With an "l" key replacing the binary input key "b" and "p[n]" objects replacing "f[n]" objects.

The "q[n]" key is a status key and is used to update the service status based on the result of the ping, but not perform the action.

Specific states are defined using the "p[n]" & "q[n]" options (where [n] is an action number e.g. "p0", "q0"). Each device has its own set of actions and these are mapped to the state inputs. Check the device page for details of the specific states.

Ping inputs are triggered only on a response change. If you have set up to listen for a specific state "p0": [{ "h":"iMac-de-Jose","r":0 }] then this state is triggered on the first occurrence of the target host not responding to the ping. If the host remains unresponsive then no further triggers occur until the host becomes responsive and then unresponsive again.

The ping interval is fixed at 5 seconds and 3 failed responses need to occur consecutively before a response type of 0 occurs.

The following options are available as part of the "p[n]" and "q[n]" objects:

This option defines how the ping state action should behave based on the target response. The default value of 0 indicates that the action should be relative to the ping response. A ping response changing from non-response to response will cause the action to occur only when change occurs (assuming "r":1) e.g. If the action is to turn the lights off when the TV responds to a ping then the lights will go off the first time the TV ping responds. If the lights are subsequently turned back on while the TV is still on then no further actions will occur unless the TV ping response status changes.

A value of 1 indicates the action should be absolute to the ping response. A ping response changing from non-response to response will always cause the action to occur (assuming "r":1) e.g. If the action is to turn the lights off when the TV responds to a ping then the lights will go out the first time the TV ping responds. If the lights are subsequently turned back on while the TV is still on then the next ping response from the TV will cause the action to re-occur and the lights to go back off.

This option is mandatory and must contain the IP address or host name of the device to be targeted with a ping.

NOTE: When using a DNS name ensure that the DNS server allocated in the DHCP server response to the device can resolve the name. There is no mDNS support.

This option defines the expected response in order to trigger the defined action.

This option defines if the ping action should occur if there is no WiFi connectivity. By default the ping action is disabled and no action will take place if the WiFi connection is lost.

In this example we want a power switch to turn on whenever a laptop appears on the local network in order to ensure it gets charged while we are using it.

The switch can be configured to ping the laptop DNS name and when a successful response occurs the power is turned on. Similarly, when the laptop is powered down the ping no longer gets a response and the switch can turn off the power.

{
  "c":{ "io": [ [ [ 12, 13 ], 2 ] ], "l":13 },
  "a":[{
    "t": 1,
    "0": { "r": [ [ 12 ] ] },
    "1": { "r": [ [ 12, 1 ] ] },
    "p0": [{ "h":"iMac-de-Jose","r":0 }],
    "p1": [{ "h":"iMac-de-Jose" }]
  }]
}

In this example we have a Sonoff S20 that uses ping to turn on/off the lounge light when ever the TV is turned on and responds to a ping request. The lights will always follow the inverse state of the TV even if changed by an external action ("i":1).

{
  "c":{ "io": [ [ [ 12, 13 ], 2 ], [ [ 0 ], 6 ] ], "l":13, "b":[ [ 0, 5 ] ] },
  "a":[{
    "t": 2,
    "0": { "r": [ [ 12 ] ] },
    "1": { "r": [ [ 12, 1 ] ]},
    "b": [ [ 0 ] ],
    "p0": [{ "h":"my-tv", "i":1 }],
    "p1": [{ "h":"my-tv", "i":1, "r":0 }]
  }]
}

In this example we use ping actions to reflect the current on/off state of the TV e.g. If the TV responds to a ping the HomeKit service shows as on in the HomeKit application.

{
  "c":{ "io": [ [ [ 13 ], 2 ], [ [ 0 ], 6 ] ], "l":13, "b":[ [ 0, 5 ] ] },
  "a":[{
    "t": 2,
    "q0": [{ "h":"my-tv" }],
    "q1": [{ "h":"my-tv", "r":0 }]
  }]
}

The Inching Time is an accessory option that defines a time period for a service to return to the previous state e.g. If the inching time is set to 10 seconds a switch would turn off 10 seconds after turning on.

Inching time is started when action "1" of the service is triggered. After the inching time has elapsed action "0" will be triggered. NOTE: the lock mechanism is the opposite of this.

Inching time is a float, so fractions of seconds can be specified e.g. "i":3.5

A typical example of using inching time would be to reset a lock after it has been unlocked.

NOTE: Inching Time is not supported by all services, so check before using it.

Initial state is defined by the "s" key contained within the service object.

The initial state that a service enters on boot can be set using the "s" option.

Check each service for details on whether Initial State is supported.

This option was implemented in firmware version 1.10.0

The Execution of Actions on Boot is defined by the "xa" key within the service object.

By default actions are enabled on boot, but some circumstances require no actions to be performed during the boot of an accessory. When this is the case the actions can be disabled by setting the "xa" key to 0.

See the TV device for an example on why disabling actions is necessary.

This option was implemented in firmware version 2.4.5

The Delay after creation option is defined by the "cd" key within the service object.

By default a service is created within HAA and then the next service is immediately created. There are times when a delay is required after a service has been created in order to exec and free memory before the next service is created.

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 service has been created.

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

REMOVED. See: https://github.com/RavenSystem/esp-homekit-devices/releases/tag/HAA_2.5.0

Wildcard actions are defined by the "y[n]" key within a service object.

Wildcard actions were introduced in firmware version 1.7.0

Wildcard actions are used to trigger state changes when a minimum value criteria has been met e.g. when a window cover is opened 68%, when the brightness of a lightbulb is set to 20%, when the fan speed reaches 40% or step 3 etc.

Wildcard actions are defined by "y[n]". Where "y[n]" is normally "y0", but in the case of a device that has a humidity sensor service (e.g. "t":24 & "t":25) then "y1" refers to the humidity sensor.

The Target Value "v" is a mandatory key for the wildcard action. It defines the minimum target value required in order to trigger the defined action.

If multiple minimum target values are defined then the action associated with the highest minimum value that satisfies the condition will be performed e.g. in the example below two minimum values are defined; 35ºC & 20ºC. At 36ºC, only the action defined by the 35ºC object will be performed.

The Repeat "r" is used to cause the associated action to be performed each time the target value is assessed e.g. In a temperature sensor, if "r":1 then the action will be performed each time the temperature is read and the target value is met.

The default ("r":0) triggers the action only the first time the target value is met.

The Action "0" is an array and contains the list of actions to perform when the target value is met. Any, or multiple service actions can be contained within the array.

In this temperature sensor example wildcard actions have been defined to perform actions when the temperature sensor reaches a temperature of 35ºC or 20ºC. Switching GPIO 12 on or off.

Each time the temperature sensor returns a reading above 35ºC the action will be repeated.

NOTE: In the case where the temperature sensor jumps from 18ºC to 35ºC between readings then only the 35ºC action will be performed.

{
  "c": { "io": [ [ [ 12, 13 ], 2 ] ], "l": 13 },
  "a": [{
    "t": 22,
    "g": 14,
    "n": 4,
    "j": 30,
    "y0": [{
      "v": 35,
      "r": 1,
      "0": { "r": [ [ 12, 1 ] ] }
    }, {
      "v": 20,
      "0": { "r": [ [ 12 ] ] }
    }]
  }]
}

State Inputs manage the state of a service. They monitor GPIO inputs and set the state of the service when conditions are met e.g. In a lock mechanism two separate GPIO inputs could be linked to buttons. One button will unlock the mechanism and one will lock it. Using state inputs linked to each of the buttons the mechanism can be locked or unlocked from each button (see below for an example).

State inputs are defined by an "f[n]" key contained within the service object. Where [n] is the unique identifier for the state input.

Each service can have its own set of state inputs and in most cases these are mapped to some of the Service Actions the service can perform. They can also be mapped to internal states the service monitors e.g. "f3" in a thermostat is used to change the target temperature.

Check the device page for details of the specific states.

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

In this example of a lock mechanism input action "f0" is defined as a single press on the button connected to GPIO 14. When the button is pressed service action "0" will be triggered and the mechanism is unlocked. When the button connected to GPIO 0 is pressed the mechanism will lock.

{
  "c": { "io": [ [ [ 12, 13 ], 2 ], [ [ 14 ], 6 ] ], "l": 13 },
  "a": [{
    "t": 40,
    "d":18,
    "0": { "r": [ [ 12, 1, 0.5 ] ] },
    "1": { "a": 0 },
    "2": { "r": [ [ 12, 0, 1.5 ], [ 12, 1, 0.5 ], [ 12, 1, 2 ] ] },
    "3": { "a": 2 },
    "f3": [ [ 14 ] ],
    "f4": [ [ 14, 0 ] ]
  }]
}

In this example of a garage door state input "f3" is defined for a garage door as being when the button/sensor connected to GPIO 14 is released (goes high) and "f4" is defined as being when the button/sensor is pressed (goes low) press. Either a door is closing and receives opening order service action is triggered ("3") or a garage door is closed service action is triggered "4"'.

See Binary Inputs for details on how to define this option.

Status Inputs were introduced in firmware version 1.8.0

Status Inputs are very similar to State Inputs, but differ in that they only set the internal state of a service. They do not trigger any actions. e.g. Staying with the lock mechanism example. A Status Input can be used to set the state of the service when a key is used in the mechanism and it is manually locked or unlocked. See below for an example of how this might be done.

Status Inputs are defined by an "g[n]" key contained within the service object. Where [n] is the unique identifier for the Status Input.

Each service can have its own set of Status Inputs and in most cases these are mapped to some of the Service Actions the service can perform, but can also be mapped to internal states the service monitors.

Additionally a service can have button(s) or binary input(s) associated with a Status Input. When a specific state occurs then the Service Action status is set.

Check the device page for details of the specific states.

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

In a modification to the State Inputs lock mechanism example. This service has no buttons associated with it, but does have an input to indicate the mechanism is locked or unlocked by a physical key turning the mechanism. When GPIO 14 goes high the mechanism is unlocked and the service status is set to unlocked: "g0". When GPIO 14 goes low the mechanism is locked and the service status is set to locked: "g1".

Action keys define what the service should do when state changes occur due to changes in inputs, or when specific triggers occur. Actions can take the form of changes to GPIO lines, system actions (reboot), Network requests, ICMP Ping requests and IR transmissions etc. Multiple actions can be defined for each accessory. Actions are specified by using one or more of the action types listed below.

Depending on the service type a range of different actions may be possible. See each service type for the list of actions. Refer to the Actions section in each service page.

Available Action Types are:

NOTE: Within an action the copy action type "a" is mutually exclusive to all other actions and can only be used on its own. All other action types can be combined.

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

In this example we have defined an service of type Switch with two actions; action "0" sets GPIO 12 to a value of 0 and action "1" sets GPIO 12 to a value of 1. These actions are performed when the button "b" attached to GPIO 0 is pressed with a single press.

For the example the device type "t": 1, the value "v": 0 and the button press type "t": 1 are included for clarity, but as they are the default values they can be omitted from the config to save device memory.

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

In this example we have added a couple of extra accessories with switch and outlet services and service notifications to the second action "1" of the first service. A notification is sent with value 1 to the third service, causing the switch to turn on.

NOTE: For simplicity of the example the details of the 2nd & 3rd accessories have not been shown

{
  "c": { "io": [ [ [ 12 ], 2 ], [ [ 0 ], 6 ] ] },
  "a": [{
    "t": 21,
    "0": { "r": [ [ 12 ] ] },
    "1": { "r": [ [ 12, 1 ] ] },
    "2": { "a": 0 },
    "b": [ [ 0 ] ]
  }]
}

In this example the third action "2" is the same as the second action "0". Using the "a" shortcut to copy an action reduces the size of the MEPLHAA script.

{
  "c": { "io": [ [ [ 12 ], 2 ], [ [ 0 ], 6 ] ] },
  "a": [{
    "t": 21,
    "0": { "r": [ [ 12 ] ] },
    "1": { "r": [ [ 12, 1 ] ], "s": [ 1 ] },
    "b": [ [ 0 ] ]
  }]
}

In this example the second action "1" sets GPIO 12 high and performs a system action "s" to enter the device setup mode (1).

Every service type has a defined set of service actions "[n]". A service action is represented by an integer e.g. "0", "1" etc.

A service action is specific to the service e.g. turn the switch or outlet on ("1") or off ("0"), turn on a lightbulb ("1"), turn on the heating ("3") in a thermostat device.

Almost all services have a minimum of two service actions; "0" & "1". Exceptions are service types such as a temperature sensor or a humidity sensor.

Service actions have other actions embedded within them to effect the action state they represent e.g. a switch On service action "1" may set a GPIO to cause the on condition to occur e.g. "1": { "r": [ [ 12, 0 ] ] }

See above examples of service actions.

The copy action is defined by the "a" key array within a service object.

The copy action is mutually exclusive with all other action types i.e. if a copy action is present within an service definition then no other action types can be present.

If you have two or more service actions that do the same thing then a copy action can be used as a shortcut to reduce memory for the MEPLHAA script. The value defined in the key is a reference to another action to copy e.g. "3": { "a": 0} is a shortcut for action "3" to copy action "0".

See Action Example 3 for an example.

The binary output array is defined by the "r" key within a service object.

Each object must be an array [ gpio, value, inching ]

value and inching are optional, and default will be used if any is missed.

The binary output array contains a list of GPIO level changes to perform when an action is invoked e.g. Set GPIO 12 low [ 12, 0 ] or set GPIO 12 high for 2 seconds [ 12, 1, 2 ]

Sometimes multiple actions need to be performed when an action is invoked. In this case the binary output array will have multiple entries in its list e.g. "r": [ [ 12, 0, 1.5 ], [ 12, 1, 2] ]

Each defined action has an array of binary outputs "r" e.g. relays, LEDs etc. These outputs have a number of different configuration options defined below.

This option is mandatory for each action defined. The gpio specifies a GPIO to use as the binary output for the action performed e.g. [ 12 ] specifies GPIO 12 to be used as the binary output.

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

This option specifies the level to drive the GPIO output pin. Driving the pin low normally results in an "off" state and a high normally results in an "on" state.

This option can be used to trigger an automatic return of the output to its previous state after a preset period of time has elapsed. The inching value is a floating point number specifying the number of seconds e.g. [ 12, 1, 1.34 ] will result in a period of 1.34 seconds elapsing before the output pin is returned to its previous state. The time can be specified in hundredths of seconds. NOTE: Positive values only are allowed

Service notifications are defined by the "m" key array contained within an service object.

Service notifications are notifications sent to another service within the same device. Check each device type's Service Notifications section to see what notifications can be sent to it and the values that can be sent e.g. assuming a device has two services; a switch ("t":1) & a lock mechanism ("t":4) respectively. The following can be added to the switch service to request the lock service to unlock when the switch is pressed: {"m": [[ 2, 0 ]]}

The service notification object is a list object and can contain multiple accessory notifications.

If more than one notification is contained in the list then the notifications will be sent in the order they appear in the list.

See Actions Example 2 for an example.

The target service number is the index into the list of services of accessories in the "a" object. The target service index number begins with 1 i.e. the first service in the top level accessories key "a".

If n services are defined in the "a" and "es" objects, then a value of 1 specifies the first service and a value of n specifies the last service.

Since HAA v7.5.0, relative index can be used:

• 0: Target Service will be own service.
• -N: Target Service will be own service index -N services.
• 7000 + N: Target Service will be own service index +N services.

The target service value is the value to send as part of the notification.

In the case of a service notification the value of the "v" option is determined by the service type and is defined in the details of each accessory, in the "Service Notifications" section. Check this section in each service to determine the valid values that can be used for services.

There are some values common across all services used to control the internal state of a service:

These internal values replace a feature present in pre 2.5.0 releases called Kill Switches. Each service can be disabled by setting its internal state to -10000. In this state no automations will work.

A service can also have its physical controls disabled by setting its internal state to -20000. In this state no physical button/switches will work. However, it can always be managed with a HomeKit client and automations will work.

{
  "c": { "io": [ [ [ 12 ], 2 ], [ [ 0 ], 6 ] ] },
  "a": [{
    "t": 2,
    "0": { "r": [ [ 12 ] ] },
    "1": { "r": [ [ 12, 1 ] ] },
    "b": [ [ 0 ] ]
  },{
    "s":1,
    "0":{"m":[ [ 1, -10000 ] ] },
    "1":{"m":[ [ 1, -10001 ] ] }
  }]
}

In the above example a HomeKit switch has been added that can change the internal state of the the first service to be enabled "0" or disable "1". Thus the outlet switch connected to GPIO 0 can be disabled using the HomeKit client.

REMOVED. See: https://github.com/RavenSystem/esp-homekit-devices/releases/tag/HAA_2.5.0

System actions are defined by the "s" key array within a service object.

The array must have all needed system actions.

"s": [ action0, action1, ... ]

See Actions Example 4 for an example.

The system actions array is used to define system actions to perform when a service action is invoked.

Send Network Request Actions were first introduced in firmware version 1.3.0

Send Network request actions are defined by the "h" key array within a service object.

Send Network request actions can be used to initiate a TCP or UDP request to a specified target host and URL when an action occurs. They might be used to communicate to non-HomeKit devices from a HAA device e.g. turn on a WiFI lightbulb when a HAA device button is pressed, enter a record into a time series database etc.

The Host "h" is any valid IP address or a fully qualified domain name e.g. "192.168.22.45" or "lounge-light.lan".

NOTE: If you are using a fully qualified domain name then make sure you have a DNS server on your network capable of resolving the name.

The Port "p" is any valid TCP port number.

The Method "m" is the communication method to use and can be one of:

When using the HTTP methods; 0, 1 or 2. The HTTP request is made up using the specified options to create a request and then sending it via the specified Method to the specified URL e.g. http://<host>:<port>/<url>

When using TCP RAW or UDP RAW the Content is sent as-is, without any header or other information. This method is useful when communicating to websockets or any other protocol outside of HTTP. When using TCP RAW method 4 or UDP RAW method 14 the Content must be in HEX format e.g. { "c":"01b364007aff04" }. When using either of the TCP methods the URL is ignored.

The URL "u" is any valid URL e.g. {"u": "cm?cmnd=Power%20OFF"}

The content "c" is a string and can be any valid content.

When using Wake on LAN method 12 the Content must be a valid MAC address in HEX format e.g. { "c":"0a1b2c3d4e5f" }.

Complete WOL example action:

"h":[{"m":12,"h":"255.255.255.255","p":9,"c":"a1b2c3d4e5f6"}]

NOTE: Any content returned by a Network Send Request is ignored by the device.

When using Wait for response with "w":N value, device will wait N seconds for a response from target host, but received data will not be processed unless Free Monitor service is used.

"w":N value is a float, but only one decimal can be used. Default value is "w":0 (disabled) in normal actions, and "w":1 in Free Monitor Service.

This feature is needed for some devices that needs to send any kind of acknowledgment to work properly (Eg. Philips HUE Bridge).

First introduced in firmware version 2.5.1

If the string contains the magic expression #HAA@aacc then the expression will be replaced by the characteristic cc value from the service aa e.g. #HAA@0100 will be replaced with the value held by characteristic 0 from service 1.

If the service value 00 is used then the characteristic value is read from the actual service containing the HTTP Request Action.

The magic expression can be used as many times as needed in the same content string.

The actual characteristic value entered in to the content string is dependent on its type:

You want to send a power command to a device at IP address 192.168.2.15 using the GET method: http://192.168.2.15/cm?cmnd=Power%20ON

{
  "c": { "io": [ [ [ 13 ], 2 ], [ [ 0 ], 6 ] ], "l": 13 },
  "a": [{
    "t": 1,
    "0": { "h": [{ "h": "192.168.2.15", "u": "cm?cmnd=Power%20OFF"}]},
    "1": { "h": [{ "h": "192.168.2.15", "u": "cm?cmnd=Power%20ON"}]},
    "b": [ [ 0 ] ]
  }]
}

In this example we are using the default method of GET "m":0 and the default port of 80 "p":80. No content is required "c" as we are using a GET.

In this example you want to send a time series event to an influxDB database to record the current temperature and humidity readings every time the sensor values are read e.g.

curl -X POST 'http://influxdb.lan:8086/write?db=haadb' --data-binary 'sensor,location=office temperature=20.230,humidity=38.000'

{
  "c": { "io": [ [ [ 13 ], 2 ] ], "l": 13 },
  "a": [{
    "t":24,
    "g":14,
    "n":4,
    "j":30,
    "y0": [{
      "v": 0,
      "r": 1,
      "0": { "h": [{ "h": "dixnas1.lan", "p": 8086, "m": 2, "u": "write?db=testdb", "c": "sensor,location=office temperature=#HAA@0000,humidity=#HAA@0001" }] }
    }]
  }]
}

In this example you want to send a time series event to ThingSpeak Internet server, to record the current temperature and humidity readings every time the sensor values are read e.g.

{
    "a": [{
        "t": 24,
        "g": 5,
        "y0": [{
            "v": -100,
            "r": 1,
            "0": {
                "h": [{
                    "h": "api.thingspeak.com",
                    "m": 2,
                    "e": "X-THINGSPEAKAPIKEY: GHAXXXXXXXXXX\r\nContent-type: application/x-www-form-urlencoded\r\n",
                    "u": "update",
                    "c": "field1=#HAA@0000"
                }]
            }
        }],
        "y1": [{
            "v": 0,
            "r": 1,
            "0": {
                "h": [{
                    "h": "api.thingspeak.com",
                    "m": 2,
                    "e": "X-THINGSPEAKAPIKEY: GHAXXXXXXXXXX\r\nContent-type: application/x-www-form-urlencoded\r\n",
                    "u": "update",
                    "c": "field2=#HAA@0001"
                }]
            }
        }]
    }]
}

Send IR Code Actions were introduced in firmware version 1.5.0

Send IR Code actions are defined by the "i" key array within an accessory object.

The Frequency "x" used in an action to override the global setting defined in the General Configuration for this action only.

The Protocol "p" defines the IR protocol to use. When used in a service it overrides the General Configuration setting for actions within the service. When used in an action it overrides the setting defined in the General Configuration setting for the action only.

The Repeats "r" defines the number of times the IR command will be transmitted. IR command codes are often sent multiple times in a row to ensure the receiving device is able to capture the code e.g. to turn on some Panasonic TVs, the same code must be sent 5 times.

The Inter-Repeat-Delay "d" defines the delay between repeats in milliseconds when Repeats are greater than 1. Valid values are from 10 to 65535. If none is declared, default value will be 100 milliseconds.

The Command "c" defines the actual command code to be transmitted. At least one definition of the Protocol ("p") must exist, either in the General Configuration section, in the accessory ("a") object, in any extra service, or in the action ("p") object.

The Raw Code "w" defines the IR code to be transmitted. The Raw Code does not use any protocol (it is raw data) and does not require a "p" key in either the General Configuration section, accessory object or within the action object. NOTE: If "w" and "c" options are defined for the same action then the "c" option will take precedence and the "w" definition will be ignored.

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

Example of a HomeKit Switch that can turn on and off a Panasonic TV using an IR TX LED connected to GPIO 2

{
  "c": { "io": [ [ [ 2 ], 2 ] ], "t": 2, "p": "HtDCAQ0?AQCAAK" },
  "a": [{
    "0": { "i": [{ "c": "aAkAiAhAaDbAaDaA" }]},
    "1": { "i": [{ "r": 5, "c": "aAkAiAhAaDbAaDaA" }]},
    "t": 1
  }]
}

UART Actions were introduced in firmware version 2.1.1

UART Actions are defined by the "u" key array within an accessory object.

The UART Number defines the UART port to use.

• UART2 is only available in ESP32 chips.

See UART Configuration for details and settings.

The Command string in HEX or TEXT format, defining the command to send to the attached service e.g. "41424344"

The Inter-command Delay is the time in milliseconds to delay before transmitting subsequent commands to the same UART when multiple commands are contained in the same "u" array.

{
  "c":{"io":[[[13],2],[[0],6]],"l":13,"b":[[0,5]],"r":[{"n":0, "s":9600, "p":0, "b":0}]},
  "a": [{
    "t": 1,
    "0": { "u":[{"n":0, "v": "48656c6c6f20576f726c64" }]},
    "1": { "u":[
      {"n":0, "d":100, "v": "537769746368204f6666" },
      {"n":10, "v": "ACK" }
    ]}
  }]
}

This is a general example of using a UART attached service. The external accessory is connected to the switch on UART0 ("n":0) and used 9600 baud, no parity bits and 0 stop bits ("s":9600,"p":0,"b":0). To turn off the device the string "48656c6c6f20576f726c64" must be sent to it. To turn on the device the string "537769746368204f6666", followed by "4e6f77" 100ms later.

Set Characteristic Actions were introduced in firmware version 11.1.0 Peregrine

Read value from a source service characteristic and write it in a target service characteristic, even if types are different.

Set a PWM duty, frequency or dithering value to a GPIO declared as PWM.

"q" : [ [ PWM Action 1 ], [ PWM Action 2 ], ... ]

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

GPIO is mandatory.

If you only want to change software PWM frequency, set GPIO to -1.

To change hardware PWM frequency and duty, set Dithering to 1.

If you want to change Dithering (available only for software PWM) without changing Frequency, set Frequency to 0.

https://youtu.be/XodmGL_dHRw

{
  "c":{
    "z": 0, "q": 1, "io": [ [ [ 4 ], 7 ] ]
  },
  "a":[{
    "i": 0.5, "1": { "q": [ [ 4, 0, 1 ] ] },
    "es":[
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 262 ] ] }},
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 294 ] ] }},
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 330 ] ] }},
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 349 ] ] }},
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 392 ] ] }},
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 440 ] ] }},
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 494 ] ] }},
      { "i": 0.5, "1": { "q": [ [ 4, 32768, 523 ] ] }}
    ]
  }]
}

If this option is set to 0 the service will become outside from HomeKit, using very low DRAM and CPU resources, but will still function as a service. Its hardware will be fully functional, as well as its status. All actions will function as normal too.

This option is applicable to all services.

Now you know all about Accessory Configuration it is time to discover Service Types