ESP32: TRIAC phase-dimming module #3023

jpeletier · 2020-01-29T23:04:31Z

This PR is for the dev-esp32 branch rather than for master.
This PR is compliant with the other contributing guidelines as well (if not, please describe why).
I have thoroughly tested my contribution.
The code changes are reflected in the documentation at docs/*.

This module implements phase-dimming for TRIAC-based mains dimmers.

How phase-dimming works

Find here a brief description on how TRIAC-based dimming works.

In essence, phase dimming implies generating a square-wave PWM signal, with the special characteristic that it must be perfectly synchronized with mains, modulating it, and thus delivering more or less effective power to the load depending on the PWM signal duty cycle.

In order to do this, a dimmer module or circuit must be used to a) detect when the mains signal crosses 0V, to use it as a synchronization point and b) modulate mains. The module must isolate mains from the microcontroller.

Some reference hardware:

These modules come with a TRIAC whose gate is intended to be driven by a GPIO pin, isolated from mains by an optocoupler. These modules also come with a zero-crossing detector, also isolated, that raises a pin voltage when the AC mains sine wave signal crosses 0V.

Architecture of this nodemcu module

The above scheme is implemented in this module by dedicating ESP32's CPU1 entirely to this purpose... Phase dimming requires very accurate timing. Configuring timer interrupts in the "busy" CPU0 does not work properly, with FreeRTOS scheduler, WiFi and so on demanding their share of the CPU at random intervals, which would make dimmed lamps flicker.

Once the dimmer module is started, by means of dimmer.setup(), a busy loop is launched on CPU1 that monitors zero-crossing signals from the dimmer and turns on/off the TRIAC at the appropriate time, with nanosecond precision.

Required SDK `menuconfig` changes

To use this module, change the following in menuconfig (make menuconfig):

Enable FreeRTOS in both cores by unselecting "Component Config/FreeRTOS/Run FreeRTOS only on first core". This will allow the module to use CPU1.
Unselect "Component Config/ESP32-specific/Also watch CPU1 tick interrupt"
Unselect "Component Config/ESP32-specific/Watch CPU1 idle task"

The last two settings disable the reset watchdog for CPU1. This is necessary since CPU1 is purposefully going to be running an infinite loop.

Example

dimmer.setup(14)     -- configure pin 14 as zero-crossing detector
dimmer.add(22)       -- TRIAC gate controlling lightbulb is connected to GPIO pin 22
dimmer.setLevel(300) -- set brightness to 300‰ (30%)

dimmer.setup()

Initializes the dimmer module. This will start a task that continuously monitors for signal zero crossing and turns on/off the different dimmed pins at the right time.

Syntax

dimmer.setup(zc_pin, [transition_speed])

Parameters

zc_pin: GPIO pin number where the zero crossing detector is connected. dimmer.setup() will configure this pin as input.
transition_speed: integer. Specifies a transition time or fade to be applied every time a brightness level is changed. It is defined as a per mille (‰) brightness delta per half mains cycle (10ms if 50Hz). For example, if set to 20, a light would go from zero to full brightness in 1000 / 20 * 10ms = 500ms
- Value must be between 1 and 1000 (instant change).
- Defaults to a quick ~100ms fade.

Returns

Throws errors if CPU1 task cannot be started or zc_pin cannot be configured as input.

Integer with the measured mains frequency, in cHz. 0 if mains is not detected.

Example

dimmer.setup(14) -- Zero crossing detector connected to GPIO14
tmr.create():alarm(1000, tmr.ALARM_AUTO, function()
    print("Mains frequency is %d Hz", dimmer.mainsFrequency() / 100)
end)

marcelstoer · 2020-03-29T20:57:10Z

docs/modules/dimmer.md

+
+These modules come with a TRIAC whose gate is intended to be driven by a GPIO pin, isolated from mains by an optocoupler. These modules also come with a zero-crossing detector, also isolated, that raises a pin voltage when the AC mains sine wave signal crosses 0V.
+
+## Architecture of this nodemcu module


Suggested change

## Architecture of this nodemcu module

## Architecture of this NodeMCU module

marcelstoer · 2020-03-29T21:02:10Z

I'm currently compiling the firmware to start testing.

🥇 The documentation is fantastic. Thank you.

What is the reason you do not allow setting the dimmer pins in setup()? It's certainly nice that I can dynamically add and remove pins for dimming. However, intuitively I expected to have to define those pins during setup. Also, how about making the pin in setLevel() optional?

marcelstoer · 2020-03-30T19:08:47Z

docs/modules/dimmer.md

+```lua
+dimmer.setup(14)     -- configure pin 14 as zero-crossing detector
+dimmer.add(22)       -- TRIAC gate controlling lightbulb is connected to GPIO pin 22
+dimmer.setLevel(300) -- set brightness to 300‰ (30%)


Suggested change

dimmer.setLevel(300) -- set brightness to 300‰ (30%)

dimmer.setLevel(22, 300) -- set brightness to 300‰ (30%)

marcelstoer · 2020-03-30T19:14:40Z

docs/modules/dimmer.md

+* Enable *FreeRTOS in both cores* by unselecting *"Component Config/FreeRTOS/Run FreeRTOS only on first core"*. This will allow the module to use CPU1.
+* Unselect  *"Component Config/ESP32-specific/Also watch CPU1 tick interrupt"*
+* Unselect  *"Component Config/ESP32-specific/Watch CPU1 idle task"*


Suggested change

* Enable *FreeRTOS in both cores* by unselecting *"Component Config/FreeRTOS/Run FreeRTOS only on first core"*. This will allow the module to use CPU1.

* Unselect *"Component Config/ESP32-specific/Also watch CPU1 tick interrupt"*

* Unselect *"Component Config/ESP32-specific/Watch CPU1 idle task"*

* Enable FreeRTOS in both cores by **deselecting** `Component Config` > `FreeRTOS` > `Run FreeRTOS only on first core`. This will allow the module to also use CPU1 (besides CPU0).

* **Deselect** `Component Config` > `ESP32-specific` > `Also watch CPU1 tick interrupt`

* **Deselect** `Component Config` > `ESP32-specific` > `Watch CPU1 idle task`

marcelstoer · 2020-03-30T19:34:50Z

docs/modules/dimmer.md

+```lua
+dimmer.setup(14) -- Zero crossing detector connected to GPIO14
+tmr.create():alarm(1000, tmr.ALARM_AUTO, function()
+    print("Mains frequency is %d Hz", dimmer.mainsFrequency() / 100)


Prints Mains frequency is %d Hz 49.95 here.

marcelstoer · 2020-03-30T19:57:03Z

docs/modules/dimmer.md

+
+## dimmer.remove()
+
+Removes the given pin from the dimmer module


Is it intentional that this does not set the level back to 0 i.e. the light remains on? Intuitively I was expecting it to get turned off.

stale · 2021-08-28T17:22:37Z

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

jpeletier added 13 commits January 29, 2020 00:30

Added dimmer module skeleton + add/remove

116df37

first working implementation

5290f7d

change to pulldown + some docs

0b80c6b

messages

3a6f44c

check_setup and cleanup

24cbb89

cleanup includes

ecd55b8

adjust task stack size

14a256e

added intro and some comments

154db42

more comments

8dda8f3

Added brightness transition

5809b25

with linked list

3e5fda2

comments

c3bb3fe

documentation

5d569aa

marcelstoer added ESP32 new module labels Jan 31, 2020

add missing reference in documentation

e20b879

marcelstoer reviewed Mar 29, 2020

View reviewed changes

marcelstoer reviewed Mar 30, 2020

View reviewed changes

jpeletier mentioned this pull request May 10, 2020

ESP32: External modules #3100

Merged

4 tasks

jpeletier mentioned this pull request May 18, 2020

Introduce NodeMCU Lua module directory #3034

Open

marcelstoer mentioned this pull request May 21, 2020

ESP32: ledc.channel:reset() only working once #3120

Closed

Merge branch 'dev-esp32' into dimmers

552b322

stale bot added the stale label Aug 28, 2021

stale bot closed this Apr 16, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ESP32: TRIAC phase-dimming module #3023

ESP32: TRIAC phase-dimming module #3023

jpeletier commented Jan 29, 2020 •

edited

Loading

marcelstoer Mar 29, 2020

marcelstoer commented Mar 29, 2020 •

edited

Loading

marcelstoer Mar 30, 2020 •

edited

Loading

marcelstoer Mar 30, 2020

marcelstoer Mar 30, 2020

marcelstoer Mar 30, 2020 •

edited

Loading

stale bot commented Aug 28, 2021


		These modules come with a TRIAC whose gate is intended to be driven by a GPIO pin, isolated from mains by an optocoupler. These modules also come with a zero-crossing detector, also isolated, that raises a pin voltage when the AC mains sine wave signal crosses 0V.

		## Architecture of this nodemcu module

	dimmer.setLevel(300) -- set brightness to 300‰ (30%)
	dimmer.setLevel(22, 300) -- set brightness to 300‰ (30%)


		## dimmer.remove()

		Removes the given pin from the dimmer module

ESP32: TRIAC phase-dimming module #3023

ESP32: TRIAC phase-dimming module #3023

Conversation

jpeletier commented Jan 29, 2020 • edited Loading

How phase-dimming works

Architecture of this nodemcu module

Required SDK menuconfig changes

Example

dimmer.setup()

Syntax

Parameters

Returns

dimmer.add()

Syntax

Parameters

Returns

dimmer.remove()

Syntax

Parameters

Returns

dimmer.setLevel()

Syntax

Parameters

Returns

dimmer.mainsFrequency()

Syntax

Returns

Example

marcelstoer Mar 29, 2020

Choose a reason for hiding this comment

marcelstoer commented Mar 29, 2020 • edited Loading

marcelstoer Mar 30, 2020 • edited Loading

Choose a reason for hiding this comment

marcelstoer Mar 30, 2020

Choose a reason for hiding this comment

marcelstoer Mar 30, 2020

Choose a reason for hiding this comment

marcelstoer Mar 30, 2020 • edited Loading

Choose a reason for hiding this comment

stale bot commented Aug 28, 2021

jpeletier commented Jan 29, 2020 •

edited

Loading

Required SDK `menuconfig` changes

marcelstoer commented Mar 29, 2020 •

edited

Loading

marcelstoer Mar 30, 2020 •

edited

Loading

marcelstoer Mar 30, 2020 •

edited

Loading