Free Monitor - RavenSystem/esp-homekit-devices Wiki

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.

Type Service Type
80 Free Monitor

Free Monitor was introduced in firmware version 10.0 Kestrel

The following configuration is available:

Section Key Description
Free Monitor Type "n" Type of source
Target HomeKit Characteristic "tg" Characteristic of other service that receives Free Monitor value
GPIO "g" Declarations used by Pulse Type
I2C Data "ic" Declarations to connect to target I2C device
I2C Initial Commands "in" Declarations used by I2C to init connected hardware
Patterns "pt" Pattern filters
Data Format "dt" Byte format of read value
Value Factor "ff" Value factor adjustment
Value Offset "fo" Value offset adjustment
Value Limits "l" Array to set lower and upper limits
Polling Time "j" Frequency value is read
Service Notifications "m" Notifications received from another service
Initial Lock State "ks" Lock state at boot
Wildcard Actions "y[n]" Perform an action when service reaches a target value
Data History Characteristics

Free Monitor Type

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

Key Value Description
"n" 1 Free (default)
2 Pulse
4 Inverted ADC
5 Network request with text response
6 Network request with text response and patterns filter
7 Network request with binary response and patterns filter
8 I2C
9 UART Receiver
10 UART Receiver with patterns filter

1: Free

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

2: Pulse

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.

3 and 4: ADC

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.

5, 6 and 7: Network Requests

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 5 and 6 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 7 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.

8: I2C

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.

Requirements are:

9 and 10: UART Receiver

Read raw values from UART0 (UART1 has not RX). Raw value is defined by Data Format array.

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

Target HomeKit Characteristic

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

"tg" : [ Service, Characteristic ]

Value of target characteristic will be overwritten, but no actions will be triggered. Only HeaterCooler and Humidifier 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 ]
Type Description
3 Both

I2C Data

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 1, register 2, ... ]

I2C Initial Commands

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 1, register 2, ..., value 1, value 2, ... ], [...], ... ]

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 JSON declaration.


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.

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.

Data Format

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:

Format Description
0 Big endian, unsigned
1 Little endian, unsigned
2 Big endian, signed
3 Little endian, signed

Factor and Offset

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
Key Default Value Description
"ff" 1 Set factor value
"fo" 0 Set offset value

Value Limits

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

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

Key Value Description
"j" 30 Value is polled every 30 seconds (default)
0.1 to 65535 Float specifying the number of seconds between polls

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.

Service Notifications

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

Key Value Notification
"v" 0 Set current value to 0 (default)
N Set current value to N

Initial Lock State

The Initial Lock State about Service.

Key Value Notification
"ks" 0 Service locked
1 Service unlocked (default)

Wildcard Actions

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

Key Action
"y0" Trigger action when service reaches a specific value

Refer to Wildcard Actions for more detail.

Data History Characteristics

Characteristic Description
0 * Current value