GPIOs Configuration

Since HAA V12 Merlin, GPIOs behavior must be configured in an array to determine how hardware will work.

This array is declared by the key "io":[...] and contains other arrays. Each other array is a group of GPIOs declaration.

By default, GPIOs are disabled, but they must be configured as INPUT, OUTPUT, OPEN-DRAIN... with different options, like pull-up resistors, modes, PWM...

Structure of "io":[...] array is:

"io" : [ 
  [ [ gpio 1, gpio 2, gpio N, ...], mode, pull-up/down, options... ], 
  [ [ gpio 1, gpio 2, gpio N, ...], mode, pull-up/down, options... ], 
  [ [ gpio 1, gpio 2, gpio N, ...], mode, pull-up/down, options... ], 
  ...
]

• [ gpio 1, gpio 2, gpio N, ...] is a GPIO array, according to hardware. All GPIO numbers into this array will have same configuration as follow.
• mode is the main operation mode for these [ gpios ].

Depending of selected mode, different options are available.

ADC pin of ESP8266 doesn't need any declaration here.

- Options with * are available only for ESP32 models. They are incompatible with ESP8266 models.

Mode	Description
0	Disable (default)
1	Input only
2	Output only
3	Output only with open-drain
4	* Output and input with open-drain
5	* Output and input
6	Input only with binary input (button/switch) support
7	Software PWM, only output
8	Software PWM, only output with open-drain
9	* Hardware PWM, only output
10	* ADC Input

Depending on the hardware attached to a GPIO there may be a need for enabling an internal pull-up or pull-down resistor.

Pull-up/down	Description
-1	Don't apply any pull-up/down setting to GPIO and leave it as SDK init.
0	Floating. Disable internal pull-up and pull-down resistors. (default)
1	Enable internal pull-up resistor
2	* Enable internal pull-down resistor
3	* Enable internal pull-up and pull-down resistors

Mode 0. Disable:

[ [ gpios ], mode, pull-up/down ]

Used to set a GPIO disable. This sets GPIO in a high impedance state without any function.

In ESP8266, all user GPIOs (except 9 an 10) are set in this state.

In ESP32 chips, disabled GPIOs must be declared explicitly.

Mode 1. Input:

[ [ gpios ], mode, pull-up/down ]

Used to set a GPIO as input, needed for some drivers. This mode is not the proper to use with buttons, switches, or any other binary sensor. For those, use mode 6.

Modes 2, 3, 4 and 5. Output options:

[ [ gpios ], mode, pull-up/down, initial value ]

Initial value	Description
0	Set GPIO output to LOW value (default)
1	Set GPIO output to HIGH value

Mode 6. Input only with binary input (button/switch) support

If MCP23017 interfaces are used, remember to use hundreds to select MCP23017 of GPIO. For example, GPIO 6 of first MCP23017 will be 106.

[ [ gpios ], mode, pull-up/down, button mode, button filter ]

With some peripherals and hardware the actual GPIO signal may need to be inverted to ensure the correct action is performed when the GPIO changes state. This is normal for binary inputs that are active low.

Other peripherals send a pulse instead setting GPIO signal high constantly. For example, an AC@50Hz signal from mains, that will do GPIO signal to trigger low and high 50 times per second. In this cases, input with pulse detection is needed.

Button mode	Description
0	Normal input (default)
1	Inverted input
2	Normal input with pulse detection. Not available with MCP23017
3	Inverted with pulse detection. Not available with MCP23017

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

Button filter	Description
5	Default GPIO filter value (default)
1 to 255	Set filter value to avoid bounces and interferences. 1 is the softer value.

Note: pulse detection, inputs from MCP23017 and GPIOs without ISR (hardware interruption), like GPIO 16 from ESP8266, need Binary Input Continuous Mode enabled with "c":1 key into General Configuration.

Modes 7 and 8. Software PWM options

[ [ gpios ], mode, pull-up/down, initial value, PWM mode, PWM dithering ]

Initial value	Description
0	Set initial PWM output value to 0 (default)
0 to 65535	Initial PWM output value

By default, trailing mode is used. But some hardware may require to use leading, like TRIACs. This array will specify which channels must be leading:

PWM Mode	Description
0	Normal Trailing (default)
1	Inverted Trailing
2	Normal Leading
3	Inverted Leading

PWM Dithering	Description
0	No PWM Dithering (default)
0 to 32768	Deformation of PWM to avoid noises and armonic interferences.

Mode 9. Hardware PWM options (Only ESP32)

[ [ gpios ], mode, pull-up/down, initial value, PWM mode, timer ]

Initial value	Description
0	Set initial PWM output value to 0 (default)
0 to 65535	Initial PWM output value

By default, trailing mode is used. But some hardware may require to use leading, like TRIACs. This array will specify which channels must be leading:

PWM Mode	Description
0	Normal Trailing (default)
1	Inverted Trailing
2	Normal Leading
3	Inverted Leading

Timer	Description
0	Timer 0 (default)
0 to 3	LEDC Timer used by selected GPIO. Each timer can have a different frequency.

Mode 10. ADC (Only ESP32)

Configure GPIOs to use as ADC Inputs. It has a 12 bits width, getting raw values from 0 to 4095.

Check which GPIOs are ADC available, because only ADC unit 1 is supported. ADC unit 2 from some ESP32 chips can not be used because it is attached to WiFi and both are self-exclusive.

ESP8266 has only one ADC pin with 10 bits width (0 to 1023) and it doesn't need any configuration.

[ [ gpios ], mode, pull-up/down, attenuation ]

Attenuation	Description
0	No input attenuation, ADC can measure up to approx (default)
1	The input voltage of ADC will be attenuated extending the range of measurement by about 2.5 dB (1.33 x)
2	The input voltage of ADC will be attenuated extending the range of measurement by about 6 dB (2 x)
3	The input voltage of ADC will be attenuated extending the range of measurement by about 11 dB (3.55 x)