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.
Free Monitor was introduced in firmware version
The following configuration is available:
|Free Monitor Type||
||Type of source|
|Target HomeKit Characteristic||
||Characteristic of other service that receives Free Monitor value|
||Declarations used by Pulse Type|
||Declarations to connect to target I2C device|
|I2C Initial Commands||
||Declarations used by I2C to init connected hardware|
||Byte format of read value|
||Value factor adjustment|
||Value offset adjustment|
||Array to set lower and upper limits|
||Frequency value is read|
||Notifications received from another service|
|Initial Lock State||
||Lock state at boot|
||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:
||Network request with text response|
||Network request with text response and patterns filter|
||Network request with binary response and patterns filter|
||UART Receiver with patterns filter|
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.
3 and 4: ADC
Raw values come from Analog Pin (ADC). Those raw values are from
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
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.
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.
9 and 10: UART Receiver
Read raw values from
UART1 has not RX). Raw value is defined by Data Format array.
Target HomeKit Characteristic
Final value can be copied to any characteristic of any service declared before this Free Monitor Service.
"tg" : [ Service, Characteristic ]
Serviceis the target service index. Absolute index or relative index (negative) can be used.
Characteristicis the target Data History Charateristic.
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 ]
||LOW to HIGH|
||HIGH to LOW|
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, ... ]
bus: HAA I2C bus. Can be
1. See I2C Bus declaration in General Configuration.
device address: I2C address used by device, from
255. Most of I2C devices have options to customize it.
registers: These are the register addresses used to read the target value. Each register is an address from
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, ... ], [...], ... ]
length: Number of registers to write.
registers: Register addresses to write values. Each must be a decimal number from
values: Vales to be written. Each must be a decimal number from
Commands will be sent to I2C device in same order as declared in
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
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
10). It is an array that determines
length and byte format:
"dt" : [ Length, Format ]
Length is the number of bytes to process, from
Format determines endian and sign, as follow:
||Big endian, unsigned|
||Little endian, unsigned|
||Big endian, signed|
||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
||Set factor value|
||Set offset value|
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" : [ 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
||Value is polled every 30 seconds (default)|
||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.
The list of Service Notifications
"m" values supported are:
||Set current value to
||Set current value to
Initial Lock State
The Initial Lock State about Service.
||Service unlocked (default)|
"y[n]" are supported by this service.
The supported list is:
||Trigger action when service reaches a specific value|
Refer to Wildcard Actions for more detail.
Data History Characteristics
||* Current value|