Important: This service is in a BETA stage, and its configuration can change between versions.

A special HomeKit Custom Service, able to obtain data from different sources, like analog pin, GPIO pulses, network, I2C devices, UART and even other services.

Obtained final data must be a number, with or without decimals.

Free Monitor was introduced in firmware version 10.0 Kestrel

The following configuration is available:

This service can get data from different source types. This key indicates that type:

Default type. This does not read values from any source. Raw values are sent from other services using Service Notifications.

Raw value is the frequency, in Hertz, that selected GPIO changes the defined state. That change can be from LOW to HIGH, from HIGH to LOW, or both. See GPIO.

Raw value is the duration, in microseconds, of a received pulse, direct or inverted. An optional GPIO can be declared to send a pulse of 20us before read raw value. See GPIO.

Example of a Occupancy Sensor service with Free Monitor reading values from a HC-SR04 Ultrasonic sensor using trigger with GPIO 4 and Echo with GPIO 5 and a threshold of 300cm:

{"c":{"io": [ [ [ 5 ], 1 ], [ [ 4 ], 2 ] ] }
 "a":[{
  "t": 6,
  "es": [{
    "t": 80,
    "n": 3,
    "g": [ 5, 3, 4 ],
    "j": 1,
    "ff": 0.01718213058,
    "y0": [{
        "v": 0,
        "0": {"m": [[-1, 1]]}
      },
      {
        "v": 300,
        "0": {"m": [[-1]]}
      }
    ]}
  ]}
]}

Raw value is the PWM duty cycle (from 0 to 100%) detected in the declared GPIO. Resolution of reads is in microseconds.

Remember to declare GPIO as INPUT into "io":[...] array. See GPIOs Configuration, and declare it into "g":[ GPIO ] Free Monitor service key.

Example of a Occupancy Sensor service with Free Monitor reading values from a PWM signal connected to GPIO 5:

{"c":{"io": [ [ [ 5 ], 1 ] ] }
 "a":[{
  "t": 6,
  "es": [{
    "t": 80,
    "n": 4,
    "g": [ 5 ],
    "j": 1,
    "y0": [{
        "v": 0,
        "0": {"m": [[-1]]}
      },
      {
        "v": 60,
        "0": {"m": [[-1, 1]]}
      }
    ]}
  ]}
]}

This type is able to read data from other characteristics from other services, and to do different math operations with all data. It can read values from current date and time, and it can generate random numbers too.

Math Operations was introduced in firmware version 11.0 Peregrine

All operations must be defined with a "dt":[...] array. Each operation always uses 3 datas, then "dt" array will have always a multiple of 3 elements.

Structure for N operations: "dt" : [ x1, y1, z1, x2, y2, z2, x3, y3, z3, ..., xN, yN, zN]

Service number is the index of the service where is the source characteristic to read value. It must be an absolute index, meaning that negative values or 7000 + index relative values can not be used.

Characteristic number is the index of the source characteristic from the selected service to read value.

If Service number is 0 or a negative value, it is a Special Data Source, and this table will be used:

If Source Number doesn't need a Characteristic number, use a value of 0. Anyways, this value is useless and it will be ignored.

Raw values come from Analog Pin (ADC). Those raw values are from 0 to 1023.

Inverted ADC means that raw value will be 1023 - ADC.

For ESP32 chips, remember to declare GPIO as ADC into "io":[...] array. See GPIOs Configuration, and declare it into "g":[ GPIO ] Free Monitor service key.

Example of a Free Monitor reading a MQ-135 sensor connected to ADC pin of ESP8266 and setting the state of an Air Quality Service:

{
  "a":[
    {
      "t" : 15
    }, {
      "t" : 80,
      "h" : 0,
      "n" : 10,
      "y0" : [
        {
          "v" : 0,
          "0" : { "m" : [ [ -1, 1 ] ] }
        }, {
          "v" : 500,
          "0" : { "m" : [ [ -1, 2 ] ] }
        }, {
          "v" : 600,
          "0" : { "m" : [ [ -1, 3 ] ] }
        }, {
          "v" : 700,
          "0" : { "m" : [ [ -1, 4 ] ] }
        }, {
          "v" : 800,
          "0" : { "m" : [ [ -1, 5] ] }
        }
      ]
    }
  ]
}

This service can send a network request and read the network response. To request, action 0 must be used with an array of Network Request Actions.

Response of types 15 and 16 will be processed as text, allowing signed and decimals values. Read raw value will begin at first numeric character found into the received payload.

Response of type 17 will be processed as bytes, and Data Format is mandatory.

When patterns filter is used, value will be search after filter.

When several network requests are declared, raw value will be last valid value read from all network requests.

It is possible to get raw values from I2C devices. It is necessary to know how I2C device works and what register addresses are needed.

Declaration of Free Monitor Type is not necessary when this type is used.

Requirements are:

• I2C Bus declaration in General Configuration.
• I2C Data
• Data Format

Optional:

• I2C Initial Commands
• I2C Value Offset

I2C with Trigger: This mode will send the specified I2C command to device, and will wait specified time, before read value from I2C bus. It needs additional declarations:

• I2C Trigger Command

If several Free Monitor services use same I2C and address (Accessing same I2C device), tasks overlapping can occur. Check HAA logs for tasks overlapping, and use Service delay to avoid tasks concurrences.

Read data from selected UART. Data is defined by Data Format array.

In ESP8266 chips, only UART0 is available (UART1 has not RX).

In ESP32 chips, used UART must be selected with "u": key. Default is "u":0.

In order to work with these types, UART Configuration is required; and UART Receiver Lengths is available.

Final value can be copied to any characteristic of any service declared before this Free Monitor Service.

"tg" : [ Service, Characteristic ]

• Service is the target service index. Absolute index or relative index (negative) can be used.
• Characteristic is the target Data History Charateristic.

Value of target characteristic will be overwritten, but no actions will be triggered. Only HeaterCooler, Humidifier and Battery will be evaluated. To use actions with other target services, you must use directly Free Monitor Wildcard Actions.

Array that contains GPIO and pulse type, used by Free Monitor Pulse Type. GPIO 16 can NOT be used because it does not support hardware interrupts.

"g" : [ GPIO, Type ]

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

Optionally, an extra GPIO can be declared to send a trigger pulse when Pulse Width is used. If trigger GPIO is inverted, a value of 100 must be added to GPIO number. Example: Inverted GPIO 4 will be 104.

"g" : [ GPIO, Type, Trigger GPIO ]

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

It is an array to declare information about I2C communication. This information is available in datasheet of I2C device.

All values must be in numeric decimal format:

"ic" : [ bus, device address, register byte 1, register byte 2, ... ]

• bus: HAA I2C bus. Can be 0 or 1. See I2C Bus declaration in General Configuration.
• device address: I2C address used by device, from 0 to 127. Many I2C devices have options to customize it.
• register bytes: These are the register bytes used to read the target value. Each register byte is a number from 0 to 255. If there is not register bytes needed, declare only bus and device address.

Typically, I2C devices need an initial setup in order to be configured and work. With this array of arrays, it is possible to declare all information that I2C device needs.

"in" : [ [ length, register byte 1, register byte 2, ..., value byte 1, value byte 2, ... ], [...], ... ]

• length: Number of register bytes to write. If none is used, set it to 0.
• register bytes: Register bytes to write values. Each must be a decimal number from 0 to 255. They are optional.
• value bytes: Value bytes to be written. Each must be a decimal number from 0 to 255.

Commands will be sent to I2C device in same order as declared in "in" array.

If an I2C device is accessed from several Free Monitor Services, "in" array must be placed at first of them in MEPLHAA script.

It is needed when I2C Trigger Command is used.

"it" : [ delay, length, register byte 1, register byte 2, ..., value byte 1, value byte 2, ... ]

• delay: Seconds to wait after send trigger command and before read new value.
• length: Number of register bytes to write. If none is used, set it to 0.
• register bytes: Register bytes to write values. Each must be a decimal number from 0 to 255. They are optional.
• value bytes: Value bytes to be written. Each must be a decimal number from 0 to 255.

Number of bytes to forward before read raw value bytes.

Raw value, declared in Data Format, will begin before offset is applied to read I2C bus data.

It is an optional array to define limits to received data when Network request or UART are used. If the received data length is out of declared limits, data will be dropped.

There are no limits by default.

"bl" : [ min, max ]

Array used by those Free Monitor Types that need patterns filter:

"pt" : [ [ "Pattern 1", Offset 1 ], [ "Patter 2", Offset 2 ], ... ]

Pattern is, in text or hexadecimal format (depending of Free Monitor Type), the string to search into received response.

• Type 16 and 25: Text.
• Types 17 and 24: Hexadecimal.

When pattern is found, its offset is applied to forward that value, and keep searching for next pattern.

After all patterns are matched, value is read. If a pattern is not found, none value will be read. Patterns are processed in same order as declaration into "pt" array.

If only offset is needed, without any pattern, you can use "" as pattern.

Offset is optional; if offset is not declared, a value of 0 will be used as offset.

It applies to Network with hex patterns, I2C and UART (Types 7, 8, 9 and 10). It is an array that determines length and byte format:

"dt" : [ Length, Format ]

Length is the number of bytes to process, from 1 to 4.

Format determines endian and sign, as follow:

• Big Endian (Most common): from MSB (Most Significant Byte) to LSB (Less Significant Byte).
• Little Endian: from LSB to MSB.

Sometimes, read value needs to be recalculated in order to obtain the final value. Factor and offset values are values applied as:

Final Value = (Raw Value * Factor) + Offset

By default, there is not any limit that final value can take, but it is possible to add a lower and a upper limit to final value with "l": key:

"l" : [ Lower Limit, Upper Limit ]

Final values outside these limits will be ignored.

For example, if final value must be a number between 5 and 24, declaration will be:

"l" : [ 5, 24 ]

Polling time is defined by the "j" key contained within the service object.

Value is polled on a regular basis to read the latest values. These values are then posted to HomeKit. If this option is not specified then the value will be polled once every 30 seconds.

The list of Service Notifications "m" values supported are:

When Free Monitor Accumulative is used, new value will be added to current value.

The Initial Lock State about Service.

Wildcard Actions "y[n]" are supported by this service. The supported list is:

Refer to Wildcard Actions for more detail.