See #2097
Timings are now less than a msec per iteration and interrupt driven.
Also settings are no longer saved every time the plugin gets initialized. (flash wear out)
A number of functions was given a String parameter as a deepcopy instead of a (const) reference.
This will use a lot more memory and time, where it isn't needed.
Also those deepcopy actions may fail silently and thus lead to crashes.
Since the `ESPEasyRules.ino` file is newly introduced in this branch, now is the best moment to tidy up the source code.
Also included the used Uncrustify.cfg file.
- Parsed commands or IR codes now only use amount of memory needed, no fixed allocation on the stack.
- Strings passed to functions via const reference instead of deepcopy
- Massive checks for brand name is now done on lower case, to improve speed.
See #2057
Currently this version works with P001 and P019.
Main changes:
Added a new command to SWITCH 001: unmonitor,pcf,port#
Added two new commands to PCF 019: monitor,pcf,port# and unmonitor,pcf,port#
Added two new http commands: monitor and unmonitor
Added a new rules command: logPortStatus that will print the port status
Added the "SafeButton" functionality to 001 and 019 that will avoid false positives
Added more checks to all commands in WRITE function to avoid possible overflows
Added two more PIN STATUS: OFFLINE and INPUT_PULLUP
Modified SendStatus function so that it will be called only when needed (#1593)
Redesign of the pinstate page
Optimized the WRITE function, changing the serie of 'if' with 'else if'
Split the plugin related substitutions into separate files (per 10) to speed-up building docs.
Please note the use of indirect paths used in includes, needed to link those replacements from other directories.
Sonoff POW build now is usable for both POW and POW r2.
Use the Reset Factory default to select proper pre-defined setup for keys and relay.
Both power sensors are included as plugin.
Problem appeared to be a stack overflow.
There were a lot of large arrays allocated on the stack to parse commands or their arguments.
These are now only temporary allocated and de-allocated as soon as possible.
Writing data to the serial port while it is not being read may cause all kinds of issues and maybe even Watchdog Resets.
All `Serial.print` and `Serial.println` calls in our own code is now sent to a dynamic buffer.
This buffer will try to only send data to the serial port when its buffer permits it.
After a while, unread data will be dropped.
- Replaced all <TH> with functions
- Optimized CSS (removed some errors too)
- Uniform rendering of pages (TH, width first column)
- Added some metadata to timing stats page
- Reduction in used flash strings.
Saving the settings file may sometimes take a few 100 msec.
Added a `delay(0)` per page written to make sure background tasks are dealt with.
These system background tasks should not perform writes to SPIFFS, so this delay should be fine.
For all other plugins not setting the GPIO labels, all are now added.
Also reverted the decision about RX/TX, since these are the only ones to be crossed, the rest is always describing the data on the sensor side.
"GPIO <-- TX" is rather descriptive. The GPIO is on the ESP side, TX is on the sensor side.
So the function to format the label is called `formatGpioName_RX` and it will write "GPIO <- TX"
At least it is clear where it is going to be used, it is the RX channel on the ESP side. (for example SoftwareSerial describes the pins with function on ESP side)
All custom GPIO labels (set using `PLUGIN_GET_DEVICEGPIONAMES` ) now use the same format.
It is now uniform to describe GPIO functions on ESP side.
It was quite a mixup of sensor pin descriptions and ESP side descriptions (e.g. mixup of RX and TX)
Now all descriptions show the ESP side description.
Make sure disconnects will not be missed.
Give background tasks more time when not connected to WiFi.
This may help lowering power consumption and improve chance of getting connected.
Add a System#NoSleep event which returns the amount of seconds fow which the unit will be awake (at least). However this time can change within the delay or even disabled (by rules, commands, etc.)
Amend system command "nosleep" to accept a parameter that sets the awake time (eg. nosleep for <time>).
like this it's possible to send a "nosleep" command to the unit immediately after it awakes, do whatever needed and then reset the awake time with "nosleep,<time>" instead of having to go via web-page.
- Fix for bug #1977 for serial and web sources
- Fix for Publish command not evaluating Formulas
- Fixed addlog commands only when needed
- Fixed logEntry command not showing command line
Fixed nit value of pinstate in P001, P009 and P019
Got rid of a few kB in the binary image by removing F-macro from numerous 1 or 2 character flash strings.
These very short strings take more space in flash and memory when using the F-macro.
Also appending to a string using a `'a'` character definition takes less resources compared to a one-character string `"a"`.
The (large) template string was reduced over and over again while parsing for strings to replace.
Now it is using one big string in memory which is not reduced. (and thus taking twice the amount of memory)
- ESP32 could not select GPIO-0 in plugins.
- Only usable pins will be selectable
- Arrow icon will show if GPIO is input or output only
- Added warning sign for pins affecting boot.
- Added RX0/TX0 indicator for GPIO-1 and -3 when serial is enabled.
- Added GPIO-1 and -3 to boot pin state setup, but only selectable when Serial disabled.
- Reduce number of flash strings.
Using 128k SPIFFS and 2-step OTA image, it is possible to perform an OTA update on 1 MB nodes.
This 2-step image does not have the ArduinoOTA service running, but does allow for manual upload using web interface.
ArduinoOTA needs 8 kB more, which will not work at the moment.
Define `GPIO_KEY1` containing GPIO number to get a pre-configured button input on factory reset.
Define `GPIO_REL1` containing GPIO number to get a pre-configured relay on factory reset.
When couple of `GPIO_KEY1` and `GPIO_REL1` is defined, a rule matching both will be added.
This is defined for 1...4
`delay(0)` is a special case of delay, which also calls the system scheduler, `yield()` does not call.
It may interrupt a bit more than `yield()`
See #1950
See #1910
Added a lot more of these changes and changed the input fields of the Notification Settings to be the same as all input fields in other places.
These char arrays were rather large, so allocate on heap instead of char[240] on the stack.
Also re-order elements in not stored structs to reduce memory usage
4 new system variables:
%iswifi% (=1 if wifi is connected)
%isntp% (=1 if NTP has been initialized)
%ismqtt% (=1 if mqtt is connected)
%ismqttimp% (=1 if mqtt import is connected)
Example:
if %isntp%=1 and %systime%>%sunset% do
....
endif
Lately a lot of new issues were non-descriptive and the same basic questions were to be asked over and over again.
These are now included in this template.
Started with this issue:
"Framed Oled Display mixing up multiple values in different lines" #1904
Now almost all calls to `strncpy` are replaced with this safe variant which does some checking and zero-ing the buffer.
Removed some unneeded stack allocations of 240 bytes in the rules processing.
Also gave the `process_system_event_queue()` a bit more priority to make sure it will be looked at at least once every 500 msec.
Add escaping of wifi network names that can be discovered using the search
functionality of for instantce the /setup page. As these names are also used
inside an html tag, a stronger html encoding variant has been added.
PlatformIO `espressif8266@1.7.3` instead of `espressif8266@1.8.0`
2.4.2 has a lot of improvements like 4k of extra free memory.
But also the number of hardware watchdog reboots has increased a lot and the PWM related code no longer seems to work on 2.4.2
So for now, back to 2.4.1 library.
Added DEBUG_LOG define to reduce info log messages and prevent serial log flooding.
Added SendStatus() to post log message on browser to acknowledge HTTP write.
Added reserve() to minimize string memory allocations.
Measuring unit can be changed bewtween metric/imperial
Filtertype can none or median. If median a filtersize can be set.
Meauring value time to distance conversion now as float division, resulting in a higher resolution output.
Apparently the settings are allocated on the system stack and not on the Arduino stack.
This means it takes a lot of ram when allocated on the heap. So move it back to the system stack.
Originally the Arduino stack was placed on top of the system stack.
But since the system stack is mostly empty, it was decided to shift the Arduino stack to overlap the system stack to save an extra 4k of memory.
However, since a lot of Watchdog timer reboots are reported lately, this optimisation will now be reverted to see if it will improve stability.
This will use about 4k more RAM.
there were several errors that all resulted in a distance value reading of 0. Added an errorState that is printed to the log and helps troubleshooting.
Max. Distance checking can be turned off by setting max distance to 0 cm. If max. distance is used, exceeding the range will return a distance of 0 cm and print this to the log.
the P_013_sensordef object was created on the stack and the destructor was called after leaving the PLUGIN_INIT. That deleted the included NewPingESP8266 object and using this object failed.
Enable RTOS flag in advanced settings (and reboot) to create separate threads on the 2nd ESP32 core, which will handle the scheduler.
This lowers stack usage and CPU load.
Also the ESP will no longer crash when saving large settings like for the Framed OLED plugin.
The last update to > 0.12 increased the binary size a lot. This is mainly due to the added BLE support.
This makes it almost impossible to use the default partition table layout.
This changes the app partitions to 1.8 MB and reduces the SPIFFS to 320 k.
Changing the partition table will clear all settings, so make a backup of the settings.
Also added all plugins that would compile (not tested) for ESP32.
Known issue:
ESP32 might crash due to stack overflow when saving settings of plugins. (e.g. OLED framed plugin)
Maybe a fix for #1525
Meant to be a fix for #1530
It looks like the MQTT broker is refusing to accept a new connection from a specific client ID, as long as the broker thinks a client with that ID is still connected.
This work around adds the number of wifi reconnects to the clientID, to make the ID unique when a reconnect has to be made.
MCP and PCF devices should be of type SWNSOR_TYPE_SWITCH instead of SENSOR_TYPE_SINGLE so that the controllers can identify them correctly as switches (for GPIO related functions)
The plugin still had some delay and an active polling to see if the reading was ready.
This took more than 1.5 sec per reading, which could trigger a Watchdog reset.
In addFormPinSelect move local variables from the stack to the heap
because when it is called from the P1WifiGateway there is not enough
stack space resulting in a stack overflow.
hi,
added 2 new operators for calculations:
!: Logical NOT:
returns 1 if operand is = 0
returns 0 if operand is != 0
%: MOD:
converts operands in integers and calculates the remainder of the division
When the node gets locked in a boot loop, the only recovery is to erase it and start all over.
This fix will count the number of failed boots and above a certain threshold it will start disabling plugin, then controller and then notification.
Only one will be disabled at once, so the user can see which one is giving issues.
The disabled state will not be saved, so make sure to save the failing part when it is accessible again.
Hi,
adding the possibility to have 3 parameters when calling an event:
event,eventname=p1,p2,p3
The variable name are:
param 1: %eventvalue% or %eventvalue1%
param 2: %eventvalue2%
param 3: %eventvalue3%
Added three new commands to toggle the pins from 0 to 1 or viceversa and to toggle the task value:
Command: taskvaluetoggle
P001: gpiotoggle
P019:pcfgpiotoggle
Hi,
here is a PR for using parameters when calling commands from inside the rules.
The scope is to be able to use formulas instead of an integer when calling a command inside the rules.
Example:
taskvalueset,1,%eventvalue%+65,[Relay1#r1]+1
Usage could be:
Assuming you have a PCF8574 with ports from 65 to 72.
You can write a rule:
on turnOnRelay do
pcfgpio,%eventvalue%+64,0
endon
And to turn on port65, the rule can be called like this:
event,turnOn=1
Write the log lines to a std::deque and write that buffer to the serial port without overflow of the Serial buffer.
This flushing is done during background task.
Depending on the type of controller, the queued messages can be quite big.
This means the queue limit set can cause the memory to fill up.
This commit adds another check. If the free memory is less than 5000 bytes, it will consider the queue being full.
It will then also log the actual memory usage of the queue.
`bla@bla.com` will be set as `nodename <bla@bla.com>` in the mail header as from part.
`John Doe <bla@bla.com>` will now be used like that in the mail header.
N.B. `<` is actually the separator, so as long as that character is being used to separate the name and mail address, it will work. (see #1714 )
Make sure only enabled devices are used for checking. (see #1702)
Do a full erase of the task settings when deleting a plugin. Just to make sure no obsolete settings may corrupt behaviour of new settings.
It looks like the check for `client->connected()` may return false positives.
This means the MQTT client may assume the connection is still active, while it isn't.
These structs to keep track of available plugins and controllers were fixed in size and also the member variables were not ordered in the most optimum way.
Also the name of the nodes always used 26 Bytes and would impose a memory leak when deleted.
As suggested here: https://github.com/letscontrolit/ESPEasy/pull/1669#issuecomment-414434578
This plugin is not using the Queue yet, but only had some duplicate code moved to a helper class.
I now removed the port number from the HTTP header, since I am not really sure if the standard demands it or only for the connect part.
Also changed the HTTP command to use the code that has the port in the header, just to check if that will break now compared to older builds.
Added some simplifications to the code by creating one big macro in `_CPlugin_Helper.h` that does all the work and defines.
This will reduce the chance of typo errors a lot.
MQTT messages are queued and processed at set pace to not overload the broker.
N.B. other controllers still need a similar queue to process. Current interval for those is now probably too low.
Also initial queue parameters must still be corrected when set to 0.
For example `%syshour%` to `%syshour_0%`
Both variables are now supported.
The ones without leading zero can be used in rules.
The ones with leading zero will probably be used on displays.
At this moment it is just using the same static configuration as P150 from the playground.
It is not yet using the settings. This will have to be changed later on.
As a NTP client, you don't need to send requests from port 123. Some internet providers even block ports below 1024. So try to use a random port for outgoing requests.
Also added some checks and increased buffer on the receiving end of UDP packets.
When using C013, the size of infoStruct is copied from that buffer and the size is about 137 bytes, which may lead to Exception crashes.
Add a duplicate call for changing the address. This is required by the new sensor firmware version 2.6. This is to avoid a stry address change command that happens during hotplugging of the sensor
also see here: https://github.com/Apollon77/I2CSoilMoistureSensor/pull/17
Scheduled commands are blocking when run all after another at highest priority.
This removes the scheduled commands from the scheduler and the scheduler will now process the next queued command when no other scheduled task has to run.
Also made some optimizations to reduce memory usage.
Controller C011 (Advanced HTTP) uses all of the available `ExtraControllerSettings`.
Now the last byte of those arrays is set to 0, just to make sure they will not read beyond the range of those arrays when using as a string.
The controller still causes crashes, bit it is a start.
New timing was only allowed after MessageDelay seconds. (default was 1000, which is about 20 minutes)
It should use `TaskDeviceTimer`.
BME280 can now schedule itself to perform a read-update as soon as a measurement has completed.
Then it schedules itself to perform a new measurement at set interval time.
When sending command request from the Tools tab in the web interface, the command will be executed immediately.
In other situations it will use the scheduler to run commands async.
Commands will now be buffered and processed in order.
This will also speed-up rules which do a publish.
- Save RAM, move constants to flash (CharTableTM1637, CharTableMAX7219)
- Remove unnecessary parameter passing (the interface pins do not change during operation for one instance)
The existing implementation was a bit sparse in returned info.
Now each command can return a useful string to display in the command output window in the webinterface. (or whatever the source of the command is)
Servo Motors by default forcefully hold the desired position. This consumes power. In some cases for example to turn a value or open a latch once the position is set there may be no need to hold the new position. With this update users can pass a special case value above >9000 which is out of normal range 0-180 or 365. when this value is passed the servo is detached and is free to move.
We need to find the xth command, so we need to find the position of the (X-1)th separator.
Too bad the rest of the world (other than programmers) do not start counting at 0 :(
Apparently it is called 1.4 million times in 30 seconds and takes 8.5 CPU cycles on average (about 50'000 calls per second)
So maybe this function can benefit from some optimisation?
All enabled plugins have their own timer added to the scheduler.
The `PLUGIN_INIT` function call is used to reschedule when it was added, or enabled.
The set interval for the plugin will be used to set the new entry in the scheduler.
And fix longpulse command
With other plugins active, like the OLED Framed, the set period of `longpulse_ms` may fluctuate and durations below 100 msec are quite useless.
However, when running just a few sensors, the set pulse width is quite accurate.
Must still check a few other plugins.
`%sunrise%` and `%sunset%` were already available.
Now it is also possible to get some time before or after those times.
For example `%sunrise+10m%` or `%sunset-1h%`
The offset must be an integer (including + or -) and can have a postfix of "m" or "h".
Default is "s", for seconds.
some code rearrangements and improvements:
- fix a rare buffer overflow
- only update variables when new (correct) values are received
- little speed-up
- correct code indentations...
`ParseString` and `getParamStartPos` made (lots of) copies of the strings.
Also the result of `getParamStartPos` was not checked, which can result in crashes.
As being described a few times and a screenshot shown here: https://github.com/letscontrolit/ESPEasy/issues/1302#issuecomment-393631572
It looks like a DHCP request may fail resulting in a cleared IP setup. The web server then still replies to requests, but no new connections can be made then.
This patch should detect such a situation and then reset the wifi and make a new connection.
- [ ] The title of this issue is "to the point" and descriptive.
- [ ] This issue describes what is happening.
- [ ] This issue describes what components are affected (e.g. name of plugin/controller)
- [ ] This issue describes how to reproduce it.
- [ ] This issue describes when it was introduced (when known) and what version is now showing the problem.
### I have...
- [ ] searched the [issue tracker](https://github.com/letscontrolit/ESPEasy/issues) or the [forum](https://www.letscontrolit.com/forum/viewforum.php?f=1) for a similar issue. (include links when applicable)
- [ ] entered a system description using "Copy info to clipboard" on the sysinfo page. (when possible)
- [ ] entered the full filename of the used version (e.g. `ESP_Easy_mega-20181001_test_ESP8266_4096_VCC.bin` )
- [ ] given a list of active plugins or controllers when applicable.
- [ ] filled out all applicable fields below.
### Steps already tried...
- [ ] Tried a clean install (empty `.bin` files are included in the ZIP)
- [ ] Tested previous/other build (mention which one already tested)
- [ ] Tested on other node to make sure hardware isn't defective.
- [ ] Verified if the problem is limited to a single plugin/controller
### If you self compile, please state this and PLEASE try to ONLY REPORT ISSUES WITH OFFICIAL BUILDS! ###
<!--- If you self compile, please state this and PLEASE try to ONLY REPORT ISSUES WITH OFFICIAL BUILDS! --->
<!--- NOTE: This is not a support forum! For questions and support go here: --->
For ways to *support* us, see [this announcement on the forum](https://www.letscontrolit.com/forum/viewtopic.php?f=14&t=5787), or have a look at the [Patreon](https://www.patreon.com/GrovkillenTDer), [Ko-Fi](https://ko-fi.com/grovkillentder) or [PayPal](https://www.paypal.me/espeasy) links above.
# ESPEasy (development branch)
Badge | Info |
-------|-------|
[](https://travis-ci.org/letscontrolit/ESPEasy) | build status |
- normal_IR => "Normal" + IR receiver/transmitter plugins and library
- hard_xxxxx => Special builds for some off-the-shelf hardware.
- normal_core_241 => "Normal" using core 2.4.1, since 2.4.2 has issues with PWM
- minimal_ESP82xx_1024_OTA => Minimum number of plugins and a limited set of controllers included to be able to perform a 2-step OTA on 1 MB flash nodes.
Chip can be:
- ESP8266 => Most likely option
- ESP8285 => Used in some Sonoff modules
- ESP32 => Experimental support at this moment
MemorySize can be:
- 1024 => 1 MB flash modules (e.g. almost all Sonoff modules)
Implementation of secure communication and check for valid data.
..versionadded:: 1.0
...
|added|
Initial release version.
Description
-----------
ESPEasy is able to communicate between nodes itself.
It is an IANA registered service: `espeasy-p2p <https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=8266#ESPeasy>`_
* Service Name: espeasy-p2p
* Port Number: 8266
* Transport Protocol: UDP
* Description: ESPeasy peer-2-peer communication
* Registration date: 2018-11-28
This protocol is targeted specific for use by ESPeasy to let ESPeasy nodes
communicate with each other to create a big swarm of nodes working together
without the need for a hosted service like MQTT, which needs a central broker.
It is currently used for:
* Discovery of nodes
* Sharing sensor data among nodes
Later updates may add:
* Distribution of settings
* Sending commands
Sending & Known Nodes
---------------------
ESPEasy keeps track of all nodes advertising themselves via Sysinfo messages.
This knowledge is kept in a ``NodeStruct`` for at least 10 minutes.
If a node is not sending a Sysinfo message in this period, it will be removed from the list.
Data Format Versions
--------------------
During the IANA port assignment assessment, a number of issues were pointed out by their experts.
* Versioning
* Security
* Data validation
* Traffic limiting and congestion handling
There are now 2 versions available:
* Version "0" - No security, no data validation.
* Version "1" - Introduced in ESPeasy build <???>
Data Format Version 0
---------------------
Sending and receiving is causing issues when the swarm of nodes increases.
* All nodes with this service enabled will advertise their presence every 30 seconds via broadcast
* Nodes can not subscribe to receiving sensor data updates
* Non broadcast messages are sent to each individual known node, regardless if the receiving node will use the data
* Sensor Data messages are sent to each individual known node
* Sensor Info updates are sent to each individual known node when a plugin coupled to this plugin is saved.
Of each known node the following data is kept:
..code-block::C++
structNodeStruct
{
StringnodeName;
byteip[4];
uint16_tbuild;
byteage;
bytenodeType;
};
The key to index this ``NodeStruct`` is the nodes unit number.
ASCII Data
~~~~~~~~~~
Command Message
***************
First byte is not 0xFF.
The entire message processed as a command like this:
RTTTL (Ring Tone [Text] Transfer Language) was developed by Nokia to play more "easy on the ear" melodies as ringtones for mobile phones. The tunes over all characteristics are created by using three different commands:
**d** - duration
**o** - octave
**b** - tempo (beat)
After that the actual tune is then created using standard notes (a, b, c, d, e, f, and g), before the note the duration is set, after the note the octave is set:
..code-block::html
<duration><note><octave>
To compose a jingle you separate the notes with a comma.
Specifications:
* Output sound
Wiring
------
..code-block::html
ESP Buzzer
GPIO <--> I/O
Power
3.3V <--> VCC
GND <--> GND
Setup
-----
No device is needed, generally you use rules to activate different notifications, or you send commands to activate them. Below you find more information on how to do this.
Rules examples
--------------
From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language#Technical_specification>`_ (don't forget to remove the spaces and replace # with -, this might be fixed in future releases):
Level-converters, aka level-shifters, aka voltage dividers, are used to adapt between a 3.3V device like the ESP8266 and devices using 5V or more internally.
The ESP8266 runs with 3.3V - many devices need 5V or more, for example a LCD display or a Wiegand card reader. It is said that the ESP8266 can
take 5V at its inputs. Basically this is correct and confirmand by Espressif, the manufacturer. Anyways this as always has some limitations.
**First**, overcurrent. If you use a GPIO as input and the output of the connected device has 5V it should work. But if the internal resistance
of the device is low the current might exceed the limits of the ESP8266. With some specific settings of the ESP8266 the GPIO can not take 5V,
who checks every plugin or never made a setting mistake? So for making sure no GPIO is blown accidentally or by a bug some measurements should be taken.
**Second**, some devices need higher voltage if GPIO used as output. For example the PCF8574 or the MCP23017, port multiplexer. This chips use
3.3V or 5V as you choose. For some purpose higher voltage is useful. If using 5V there is a point you have to take care for:
The High and Low levels depend on the voltage!
With the PCF8574 the minimum "High" level Vih = 0.7 × Vdd, with 5V as Vdd it is 3.5V. With the MCP23017 the Vih = 0.8 × Vdd, with 5V as Vdd it is 4V.
(Vdd is the supplied voltage) So with 3.3V max from the ESP we are too low. It might work, it might fail. Worse, it might work with one chip
and fail with another one due to tolerances. In this case a level-converter is needed.
Specifications:
* Level shifter, aka logic converter. Used to turn logics of higher voltage (5V) down to ESP friendly voltage (3.3V).
..note::
**Troubleshooting**:
If your level converter does not work, please check cabling first. As said cabling mistakes and slack joints with the usual cheap breadboard cables are the most likely reason.
If you use breakout board type level converters have a second one at hand. We've seen some "dead on arrival", other died by electrostatic discharge.
And again, breadboards are somewhat unreliable. Use a digital multi-meter to check contacts and wires.
Wiring
------
..warning::
Be careful with wiring. A wrong connection from 5V to the 3.3V rail can cause damages of the ESP and/or the power supply.
A direct connection by mistake from 5V to a GPIO may fry your ESP! Handle level-shifters with some care.
The used FET transistors are somewhat sensible against electrostatic discharge. Use a anti-static mat.
..code-block::html
ESP Level converter Connected hardware
GPIO (X) <--> 3A, LV1, A1 etc. <--> 5A, HV1, B2 etc.
GPIO (Y) <--> 3B, LV2, A2 etc. <--> 5B, HV2, B2 etc.
Power
3.3V <--> 3V3, LV, VA, 3V etc.
5.0V <--> VIN, HV, VB, +5V etc.
GND <--> GND
Different ways of level converting
----------------------------------
Other than using a level converter it is possible to do it "manually" through resistors.
Just Input - simple unidirectional
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As an example we will use a HC-SR04 ultrasonic distance metering module. The HC-SR04 needs 5V, it will not work with 3.3V.
It works like bat ears, sending ultrasonic pulses and waiting for the echo. It has an input "Trigger" for sending ultrasonic pulses and an output "Echo" for the received signals.
The "trigger" input is no problem as it can take 3.3V for "High". Just connect it to the desired GPIO. But the "Echo" pin sends back 5V signals!
As this signaling is working just in one direction ("unidirectional") from the HC-SR04 to the ESP8266, a simple voltage divider does the job. Look at the schematic:
..image:: P000_Level_converter_2.jpg
Note the two resistors R1 and R2, configured as a voltage divider. The divider gives 2.2/(1.2+2.2) = 0.65 so with 5V you get 5V × 0.65 = 3.25V at the GPIO pin.
Just Input - precise unidirectional
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The simple circuit with two resistors has one disadvantage. It is calculated for 5V. For other voltages you have to calculate another pair of resistor values. And worse,
spikes, short spikes of high voltage from unstable power supply or other reasons) pass through the divider. A better and more precise way is using a Zener diode.
A Zener diode simplified is a semiconductor that gets conductive at a specific voltage.
..image:: P000_Level_converter_3.jpg
Here a Zener diode is used as voltage limiter. The resistor must not be omitted, it is necessary to limit the current. If a 5V signal comes the diode gets conductive - it would
short circuit the device output without the resistor. This circuit is dimensioned for input voltages from 5V to 9V (resistor should have 0.25W!). It can be used nicely for Wiegand
card readers for example. You may use even higher voltages, for example if you want to check a 24V pump. You need an adapted resistor value for that.
Input and Output - Bidirectional Level Converter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For devices that use one wire for input and output ("bidirectional") or devices that need higher voltage on an input an active level converter is necessary.
This applies mainly to I²C devices as SCL (the clock signal) comes with 3.3V from the ESP and the SDA (data signal) goes in both directions. There are
specialized chips for this purpose. Most of them have 8 channels - bit of an overkill for an ESP. There is a much simpler way you can buy as a cheap
breakout board or solder together yourself.
..image:: P000_Level_converter_4.jpg
A little FET and two resistors do the job. This is the circuit most level shifters you can buy at the market use.
How does it work? Lets have a simplified look in a nutshell. A FET gets conductive if the voltage at the gate (pin 1) is higher then the voltage at
the source (pin 2). So if the ESP gives 3.3V (High), gate and source have same voltage - the FET isolates both sides (pin 2 & 3) from each other.
If the ESP goes to 0.3V (Low), the gate still has 3.3V - now the FET gets conductive pulling the 5V-side down. If the 5V-side goes to zero (low)
because your device sends data, the diode inside the FET gets conductive and pulls the 3.3V side down to nearly zero (Low).
Use of a dedicated level converter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Quite an easy job. The pins on a level shifter are usually divided in a LV (Low Voltage) and a HV (High Voltage) side. Sometimes it is just called 3V and 5V.
Connect the 3V pin to 3.3V from ESP and the 5V pin to 5V from your device, for example a LCD display. Don't forget ground, some breakouts have some additional
capacitors which need it. Then connect the GPIOs from the ESP to the LV side, the equivalent pins from your 5V device to the HV side. That's all.
RTTTL (Ring Tone [Text] Transfer Language) was developed by Nokia to play more "easy on the ear" melodies as ringtones for mobile phones. The tunes over all characteristics are created by using three different commands:
**d** - duration
**o** - octave
**b** - tempo (beat)
After that the actual tune is then created using standard notes (a, b, c, d, e, f, and g), before the note the duration is set, after the note the octave is set:
..code-block::html
<duration><note><octave>
To compose a jingle you separate the notes with a comma.
Specifications:
* Output sound
Wiring
------
..code-block::html
ESP Piezo
GPIO <--> Positive (red)
GND <--> Negative (black)
Setup
-----
No device is needed, generally you use rules to activate different notifications, or you send commands to activate them. Below you find more information on how to do this.
Rules examples
--------------
From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language#Technical_specification>`_ (don't forget to remove the spaces and replace # with -, this might be fixed in future releases):
The ESP8266 can't switch high currents or voltages and no AC at all. But it can switch a relay that can switch high load, isolating high
voltage from the ESP circuit. There are several relay types in the wild.
The ESP can control a relay using one of it's GPIO pins. All relay boards that work with Arduino should also work with the ESP module.
Note this is only a possible application of the ESPs ability to send a logic 1/0 (TTL at 3.3V) on a GPIO. These relay are usually available
as 1,2,4,8,16 Relay modules and work electromagnetically. They can switch both AC/DC(or imitate a button press of a remote for example)
as they are "power operated mechanical switches". Each relay has the screw terminal. The middle one is usually "always connected" terminal.
The NC contact will be connected to the middle terminal when the relay is not powered. The NO is connected when the relay is powered
and activated. Note that there are "active high" and "active low" versions of these relays.
There are mainly two relay types in the wild: The good old mechanical relay with the nice "click-clack" sound and the electronic relays, so called
"Solid State Relays" (SSR) which are completely silent.
Specifications:
* Opto coupler (mechanical)
* Solid state (SSR)
Relays are the most used actuators in home automation. Most people use breakout boards with a relay on it. Sadly there is no "standard" relay board.
It seems every small manufacturing garage in china has it's own layout and schematic. Some use 5V, some use 12V, some do with opto couplers, some without...
the perfect chaos. Several problems result from this chaos. Relays keeping switched on no mater what your ESP says. Relays not switching at all.
And last but not least - sometimes they work. Let's get some order into that chaos.
..note::
You have just got your brand new relay board and it does not work. What to do?
At first you should check the switching level. Is it switching on with "high" or with "low"?
* Connect the board to power only (5V or 12V usually).
* Plug a jumper cable to one of the inputs.
* With the other end of the cable touch GND and +Vcc (5V or 12V).
On one of these touches the relay should switch. If it switches when connecting to GND the board uses "low" as active (relay on) signal.
In this case diodes or a transistor / FET as described above might help.
Connect the board to the ESP carefully. Check voltages, the power supply should be able to deliver enough current for the relays!
Check the connection cables. Jumper cables are well known for slack joints.
Mechanical relay
----------------
The mechanical relay is a simple construction.
It consist of a coil, one or more contacts and a spring. The spring keeps the contact in the "open" position. If the coil gets current, the magnetic
field pulls the contact into the second position, the contact closes. As soon as the current is switched off the spring pulls the contact back.
Mechanical relays may just have one contact switching to closed if the coil works (Normally open or NO). The contact might be a changeover contact which
has a "common" connector and a NO (open without coil current, "normally open") and a NC (closed without coil current, "normally closed") connection.
There might even be several contacts in one relay.
There are several special types of mechanical relay
One current pulse switches on and keeps on when current goes off, a second pulse switches off.
Polarized relay:
..image:: P000_Relay_3.jpg
These relays have a defined + and - pin for the coil that must be followed.
..warning:: These micro relays can not switch mains voltage! Use them for low voltage door openers or similar.
Pros and cons of mechanical relays
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:green:`+` Several contacts in one relay available.
:green:`+` NO/NC available.
:green:`+` Limited resistance to overload and overvoltage.
:red:`-` Noisy, might disturb in a living room or bedroom.
:red:`-` Mechanical, moving parts that might wear out over time.
:red:`-` Contact bumping when switching.
:red:`-` High current for the coil, needs a transistor or FET for driving and generates peaks on power supply.
:red:`-` The coil induces high voltage when switching off.
Solid state relay
-----------------
The solid state relay, SSR for short, is a complex electronic circuit. It uses an opto coupler for input, this isolating the driving circuit from the load voltage.
Isolation voltage is usually 2000V, 4000V or more. The switching element usually is a triac for AC switching types. For DC there are types with a MOSFET as switching element.
There are several special types of SSR relay
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
..image:: P000_Relay_4.jpg
As with the mechanical relays there are specialized types of SSR's.
**AC Type** : Can only (!!) switch AC. AC with zero crossing circuit. This type switches on and off if the AC voltage is at the zero point. **Expensive** and necessary only for special applications.
**DC Type** : Can only (!!) switch DC! And a lot more that are reserved for special cases.
Pros and cons of SSR relays
^^^^^^^^^^^^^^^^^^^^^^^^^^^
:green:`+` Completely noiseless
:green:`+` Low driving current and voltage available. Some types can be driven directly from the ESP.
:green:`+` No mechanical parts, no wearing out.
:green:`+` No contact bumping.
:green:`+` No voltage peaks on the low voltage side.
:green:`+` Available for very high current for an affordable price.
:red:`-` Very sensitive to overvoltage and overcurrent.
:red:`-` No NC available usually.
:red:`-` Usually with only one or sometimes three "normally open" circuits.
:red:`-` Needs cooling! Smaller relays up to 5A must be mounted with at least 1cm distance to other parts.
:red:`-` Bigger relays usually need a heat sink. Watch out:Heat sink may carry mains voltage with some types!
:red:`-` Leak current! These relays leak some current even if switched off.
Leak currents
~~~~~~~~~~~~~
Leak Current from SSR's might lead into problems under certain circumstances.
The both types shown above ("Hoymk D3805KH" and "Mager GJ-6-L", 5A AC) were tested here.
The Mager GJ-5-L showed a low leaking current and is useable for most purposes.
The D3805HK showed a really high leaking current, enough for a 10W LED to glow and a small solenoid valve to keep open!
This is not recommended for normal use.
Meanwhile a third sample arrived: The SSR-D32A380/5 sold by Pollin.
Similar to the D3805HK it shows a leaking current, as the test LED is slightly glowing in the dark when off.
It seems to be a lower leaking then with the D3805HK, this is subject to some further investigation.
The advantage of the Pollin SSR: It contains a small LED on the top indicating if the relay is on.
This SSR is a bit bigger then the other two types tested, it just fits the case. So holes for the LEDs
can be drilled on the top side of the case.
..danger::
Always remember that a switched-off SSR is not completely switched off!
Even a small leaking current is enough to give a shock. Nice surprise if you're on the ladder changing bulbs....
Choosing your relay
~~~~~~~~~~~~~~~~~~~
Which relay should be used?
Well, this depends on what you want to switch. If you control a heavy motor or pump, I'd always prefer a mechanical relay.
The resistance against short overcurrent is a good point here.
For experimenting we prefer mechanical relays too - we just love the "click" sound, i.e. we don't have to connect a load to see if it works.
If noise counts or if you place the relay in a dusty or humid environment a SSR is the better choice. It's completely encapsulated so dust
and humidity can't damage it. As it has no mechanical parts it is completely noise-free. So it's the perfect choice to switch lighting in a living room or sleeping room.
Of course you have to chose a relay that fits your parameters.
Which voltage you want to switch? AC or DC? Which current?
If you want to use a SSR for high current you have to calculate the space for a heat sink and you have to use a vented case. All these parameters
have to be figured into your project. It is also possible to use a small SSR to drive a really heavy external relay for a heavy machine for example.
Wiring
------
..code-block::html
ESP Relay (board)
GPIO (X) <--> IN1
GPIO (Y) <--> IN2
Power
5.0V <--> VCC
GND <--> GND
Setup
-----
No device is needed, generally you use rules to activate relays, or you send commands to activate them. Below you
find more information on how to do this.
..note::
If you want to monitor and have the GPIO state published you do this by adding as a |P001_typename| ,
it will not be a switch per say but you will get the state published automatically.
Rules examples
--------------
..code-block::html
On Switch#State Do
if [Switch#State]=1
GPIO,12,1
else
GPIO,12,0
endif
EndOn
This rule will turn the relay ON when the button is pressed, and OFF when released.
Indicators (recommended settings)
---------------------------------
No device is needed.
Commands
--------
..include:: P001_commands_GPIO.rst
How to connect your relay
-------------------------
You can connect the relay in multiple ways, we explain them all below.
Basic ESP circuit: mechanical relays
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The basic circuit is simple.
As the relay usually consumes more current as the ESP can handle it needs a transistor or FET to drive the relay.
To suppress the voltage peak when switching off the coil a free-wheeling diode is needed. This can be a standard silicium diode, a 1N4148 for example.
..image:: P000_Relay_5.jpg
Well, there is another way to switch the relay. In the above example we used a NPN transistor or a N-channel FET. A PNP transistor or P-Channel FET can be used too.
Some board manufacturers do this and now we run into problems promptly. The relays usually need some higher voltage then the ESP, 5V or 12 V in most cases.
The PNP transistor in the example is connected to +5V. It will switch the relay to "on" if the voltage at the input is at least 0.7V below the Vcc of 5V.
The ESP delivers a maximum of 3.3V if the GPIO is "high", around 0.5V if it is "low". Both voltages are far below the 5V-0.7V = 4.3V threshhold of the relay board.
The relay is permanently on, no matter what your ESP says. We can get this to work in a simple way with a 5V relay board. A standard diode has a loss of around 0.7V.
We can use this to get a higher output level from the ESP. We simply use two diodes in the connection between relay board and ESP. This raises the voltage from the
ESP up to 3.3v + 1.4V = 4.7V. This is above the threshhold of 4.3V. If the board uses a FET it might be necessary to use three diodes. That usually will work.
On top: This circuit switches the relay off if the GPIO is "high", this leading to irritations sometimes.
The picture shows the basic circuit with a PNP transistor, and the " 2 Diodes " solution:
..image:: P000_Relay_6.jpg
More complex: using an opto coupler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many widespread relay boards use opto couplers. Honestly we don't know the reason besides it looks good in advertising.
In theory the opto coupler isolates the relay coil from the ESP circuit. Well, that's nice theory. In real world we use the same power supply for relays and ESP.
This bridges the opto coupler as the circuits are connected via power supply making the opto coupler completely useless. Anyways the relay isolates the load from
the ESP anyways. It might be useful only if relay switching interferes with the ESP. In this case you might try a separate power supply for relay coils.
This isolates the ESP completely from the coil circuits. Note that a jumper has to be set for that on some boards.
Again there are two possible ways to use this circuit. The opto coupler input has one pin to the ESP and one to ground - this works without any problem but it is not widespread.
..image:: P000_Relay_7.jpg
Most boards we've seen connect the opto coupler to 5V or 12V and the other input pin to the ESP.
..image:: P000_Relay_8.jpg
This runs into same issues as with the PNP transistor above. The high voltage of 3.3V from ESP is far below 5V, this keeping the relay permanently active.
The solution is same as with the transistor board above. Use some diodes between ESP and relay board usually does the job with relay boards using 5V.
Depending on the circuit you will have to experiment how many diodes are necessary.
Boards with 12V
~~~~~~~~~~~~~~~
If your relay board uses 12V and needs "Low" to switch the relay on it gets somewhat more complex. Basically it is possible to use a lot of diodes but
it's not very handy. You may try a Zener diode of around 8.5.. 8.7 V. Honestly we don't recommend it. In this case it is better to use an additional
transistor or FET to get it to work. This has one advantage: It inverts the switching signal so a "low" output says the relay is off.
..image:: P000_Relay_9.jpg
Special designed boards
~~~~~~~~~~~~~~~~~~~~~~~
There are some boards in the wild which can be configured if "low" or "high" should switch the relay on.
With this boards you will have to experiment a bit with your ESP and the board, there should be a combination that works.
..image:: P000_Relay_10.jpg
Note the jumpers down left - that's the configuration for switching on high or low level.
Basic ESP circuit: SSR
~~~~~~~~~~~~~~~~~~~~~~
This is more simple. If you got a SSR that has an input of "3...12V" or "3...30V" it usually can be driven directly from the ESP.
The only thing you should keep in mind: Do not omit the varistor (RVx in the schematics). It protects the SSR from voltage peaks that
may kill it within some milliseconds. Instead of the varistor a TVS diode can be used, for example a P6K400CA.
Be careful, you have to use a bidirectional type!
..image:: P000_Relay_11.jpg
It is possible to direct drive a SSR from the ESP but we won't recommend this. We prefer the same circuit as with the mechanical relay.
It makes the relay circuit more universal and reduces load on the ESP.
..image:: P000_Relay_12.jpg
Instead of the 2N2222/BC547 you may use a small FET, a BSS138 or 2N7000 / 7002. Omit the 22K resistor if useing a FET.
R2 is needed if your relay can't take the Vcc directly. If you use a "3...30V" input SSR it's not necessary.
Any opto coupler is completely needless if you use a SSR. The SSR has an opto coupler built in to isolate the load from the ESP.
At this time there are not that much relay boards with SSR in the market, this will change over time as they get more popular.
From what is on the market be careful what you buy. Most boards we've seen nowadays on AliExpress and Ebay have a DC relay installed - they can switch DC only! They can't switch mains voltage.
Some words about DIY relay boards
---------------------------------
All in all it's no problem to build your own relay board fitting your needs exactly. But watch out if you want to switch
mains voltage. There is a reason why in some countries the policies specify a minimum distance between the parts with high
voltage and the low voltage circuits. Do not use experimental PCB's with copper pads or stripes!
Good breakout boards are milled out, there is a gap in the PCB for isolating mains from low voltage.
Prefer these boards over others without milling.
..danger::
Be very careful - mains voltage can burn your home or kill you. In case of doubt ask an expert!
RTTTL (Ring Tone [Text] Transfer Language) was developed by Nokia to play more "easy on the ear" melodies as ringtones for mobile phones. The tunes over all characteristics are created by using three different commands:
**d** - duration
**o** - octave
**b** - tempo (beat)
After that the actual tune is then created using standard notes (a, b, c, d, e, f, and g), before the note the duration is set, after the note the octave is set:
..code-block::html
<duration><note><octave>
To compose a jingle you separate the notes with a comma.
Specifications:
* Output sound
Wiring
------
..code-block::html
ESP Speaker
GPIO <--> Positive (red)
GND <--> Negative (black)
Setup
-----
No device is needed, generally you use rules to activate different notifications, or you send commands to activate them. Below you find more information on how to do this.
Rules examples
--------------
From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language#Technical_specification>`_ (don't forget to remove the spaces and replace # with -, this might be fixed in future releases):
You should try to use GPIO 12...16 since these generally aren't used. The recommended tone range is 20...13000 but you could try tones outside this range. Duration is set in ms.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
ESPEasy release bot
Gijs NoorlanderandGitHub
Saverio CisterninoandGijs Noorlander
Plebs
GrovkillenandGitHub
clumsy-stefanandGitHub
papperoneandGitHub
Stephen Houser
Bartlomiej Zimon
jimmys01
stefan
kpalczewski
Bartłomiej ZimońandGitHub
svmac
KurairaitoandGitHub
Max
ThomasandGitHub
JojoS62
David ConranandGitHub
Gilad Raz
sakinit
Benno Eigenmann
Markus Gloede
henfriandTD-er
TungstenE2andTD-er
feuerreiter
krikkandGitHub
Gerald Hollweger
James TuttonandGitHub
denisfrench
