Michel2/ESPEasy
1
0
Fork 0
mirror of https://github.com/letscontrolit/ESPEasy.git synced 2026-07-27 19:57:38 +00:00
Code Issues Releases Activity

Merge branch 'mega' into httpResponseParser

Browse Source
This commit is contained in:
chromoxdor
2026-03-18 21:37:15 +01:00
committed by GitHub
parent 2a49df0439 ed8bc322ca
commit cf95367a7d
527 changed files with 15225 additions and 6422 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/build.yml
+5 -5
View File
@@ -5,7 +5,7 @@ name: Build
on:
push:
branches: [mega]
tags-ignore: '**'
tags-ignore: ['**']
paths-ignore:
- 'dist/Release_notes.txt'
- 'docs/**'
@@ -37,7 +37,7 @@ jobs:
make html
cd ..
zip -r -qq ESPEasy_docs.zip docs/build/*
- uses: actions/upload-artifact@v6
- uses: actions/upload-artifact@v7
with:
name: Documentation
path: ESPEasy_docs.zip
@@ -88,7 +88,7 @@ jobs:
uses: Entepotenz/change-string-case-action-min-dependencies@v1
with:
string: ${{ matrix.chip }}
- uses: actions/upload-artifact@v6
- uses: actions/upload-artifact@v7
with:
# FIXME Workaround to (temporarily) not use # in the artifact name, see https://github.com/actions/upload-artifact/issues/473
name: Bin-${{ steps.string.outputs.uppercase }}-${{ matrix.env }}-${{ steps.date.outputs.builddate }}_PR_${{ github.event.number }}_${{ github.run_id }} # Sort by ESP type
@@ -110,7 +110,7 @@ jobs:
run: |
echo "builddate=$(date +'%Y%m%d')" >> $GITHUB_OUTPUT
- name: Download all artifacts
uses: actions/download-artifact@v7
uses: actions/download-artifact@v8
with:
path: artifacts/Binaries/bin/
pattern: Bin-*
@@ -119,7 +119,7 @@ jobs:
run: |
cd artifacts/Binaries/
ls -R
- uses: actions/upload-artifact@v6
- uses: actions/upload-artifact@v7
with:
# FIXME Workaround to (temporarily) not use # in the artifact name, see https://github.com/actions/upload-artifact/issues/473
name: ESPEasy-all-Binaries-${{ steps.date.outputs.builddate }}_PR_${{ github.event.number }}_${{ github.run_id }}
.github/workflows/release.yml
+6 -6
View File
@@ -9,8 +9,8 @@ name: Release
on:
push:
branches-ignore: '**'
tags: 'mega-*'
branches-ignore: ['**']
tags: ['mega-*']
permissions:
contents: read
@@ -58,7 +58,7 @@ jobs:
uses: Entepotenz/change-string-case-action-min-dependencies@v1
with:
string: ${{ matrix.chip }}
- uses: actions/upload-artifact@v6
- uses: actions/upload-artifact@v7
with:
name: Bin-${{ steps.string.outputs.uppercase }}-${{ matrix.env }}
path: |
@@ -87,7 +87,7 @@ jobs:
cd dist
zip -r -qq ../ESPEasy_dist.zip *
cd ..
- uses: actions/upload-artifact@v6
- uses: actions/upload-artifact@v7
with:
name: Distribution
path: |
@@ -131,13 +131,13 @@ jobs:
run: |
echo "builddate=$(date +'%Y%m%d')" >> $GITHUB_OUTPUT
- name: Download all successfully compiled artifacts
uses: actions/download-artifact@v7
uses: actions/download-artifact@v8
with:
path: artifacts/bin/
pattern: Bin-*
merge-multiple: true
- name: Download dist and docs zip files
uses: actions/download-artifact@v7
uses: actions/download-artifact@v8
with:
path: distribution/
name: Distribution
.gitignore
+2
View File
@@ -91,3 +91,5 @@ src/src/CustomBuild/CompiletimeDefines_generated.h
sdkconfig.normal_ESP32solo1_4M316k
src/Custom_.h
README.md
+14
View File
@@ -4,6 +4,20 @@
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, Automate (using) Common Sense, No AI.
The main objective for ESPEasy is to make people realize they can easily control appliances and act on sensor data.
Anyone can use it and you don't need AI.
Only requirement is common sense and appreciate the satisfaction of seeing things just work.
If you can't build it yourself, you don't 'own' it.
So let's make sure YOU control it.
We are more than willing to assist via our [forum](https://www.letscontrolit.com/forum).
# ESPEasy (development branch)
boards/esp32c3cdc-16M.json
+1 -1
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c3_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DESP32_16M -DESP32C3 -DUSE_USB_CDC_CONSOLE -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DESP32_16M -DESP32C3 -DUSE_USB_CDC_CONSOLE -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "dio",
boards/esp32c3cdc.json
+1 -2
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c3_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DESP32_4M -DESP32C3 -DUSE_USB_CDC_CONSOLE -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DESP32_4M -DESP32C3 -DUSE_USB_CDC_CONSOLE -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "dio",
@@ -29,7 +29,6 @@
"maximum_ram_size": 327680,
"maximum_size": 4194304,
"require_upload_port": true,
"before_reset": "usb_reset",
"speed": 460800
},
"url": "https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/hw-reference/esp32c3/user-guide-devkitm-1.html",
boards/esp32c5cdc-8M.json
+1 -1
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c5_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32C5 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32C5 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32c5cdc.json
+1 -1
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c5_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32C5 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32C5 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32c61cdc-8M.json
+1 -1
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c61_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32C61 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32C61 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32c6cdc-16M.json
+1 -1
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c6_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_16M -DESP32C6 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_16M -DESP32C6 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32c6cdc-8M.json
+1 -1
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c6_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32C6 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32C6 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32c6cdc.json
+1 -1
View File
@@ -4,7 +4,7 @@
"ldscript": "esp32c6_out.ld"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32C6 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32C6 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "160000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32s3cdc-qio_opi-16M.json
+1 -1
View File
@@ -9,7 +9,7 @@
"f_flash": "80000000L",
"boot": "opi",
"flash_mode": "qio",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_16M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_16M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=0",
"hwids": [
[
"0x303A",
boards/esp32s3cdc-qio_opi-8M.json
+1 -1
View File
@@ -5,7 +5,7 @@
"memory_type": "qio_opi"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "240000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32s3cdc-qio_opi.json
+1 -1
View File
@@ -5,7 +5,7 @@
"memory_type": "qio_opi"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "240000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32s3cdc-qio_qspi-16M.json
+1 -1
View File
@@ -5,7 +5,7 @@
"memory_type": "qio_qspi"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_16M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_16M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "240000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32s3cdc-qio_qspi-8M.json
+1 -1
View File
@@ -5,7 +5,7 @@
"memory_type": "qio_qspi"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_8M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "240000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
boards/esp32s3cdc-qio_qspi.json
+1 -1
View File
@@ -5,7 +5,7 @@
"memory_type": "qio_qspi"
},
"core": "esp32",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=1",
"extra_flags": "-DARDUINO_TASMOTA -DBOARD_HAS_PSRAM -DARDUINO_USB_MODE=1 -DUSE_USB_CDC_CONSOLE -DESP32_4M -DESP32S3 -DARDUINO_USB_CDC_ON_BOOT=0",
"f_cpu": "240000000L",
"f_flash": "80000000L",
"flash_mode": "qio",
docs/builds_overview.py
+25 -15
View File
@@ -4,14 +4,15 @@
#
#############################################################################################################
# This script parses all documentation substitution files to determine in what builds a plugin is available
# Collection A..G, Display, Energy and Neopixel, IR and IRext get Normal plugins injected
# Collection, Notify and Network plugins are also injected into Collection A..G
# Collection A..H, Display A..B, Climate A..B, Energy and Neopixel, IR and IRext get Normal plugins injected
# Collection, Notify and Network plugins are also injected into Collection A..H
# All plugins get injected into MAX build set
# Some build sets have exceptions for plugins not available
# The output generation order is determined by how they are ordered in list 'buildColors'
# When adding or removing a build set, this script may need adjustments!
# Changelog:
# 2026-03-12 tonhuisman: Separate status for ESP32 and ESP8266 (_lb suffix)
# 2025-10-05 tonhuisman: Adjustments for Display A and Display B split
# 2025-10-01 tonhuisman: Include Notify and Network plugins, ignore not available files, parse NWxxx also
# 2024-05-04 tonhuisman: Working and documented
@@ -26,6 +27,7 @@ basePath = "source/_templates/"
# Gather data
allBuilds = {}
allBuilds_lb = {}
# Not mentioned as a build in documentation, implicit
appendBuilds = {'MAX'}
@@ -46,9 +48,10 @@ excludePlugins = {
'CLIMATE A': {'P007', 'P008', 'P009', 'P017', 'P022', 'P027', 'P030', 'P035', 'P040', 'P041', 'P042', 'P045'},
'CLIMATE B': {'P007', 'P008', 'P009', 'P017', 'P022', 'P027', 'P030', 'P035', 'P040', 'P041', 'P042', 'P045'},
'DISPLAY A': {'P038', 'P041', 'P042', 'P070'},
'DISPLAY B': {'P038', 'P041', 'P042', 'P057', 'P070', 'P075', 'P104'},
'DISPLAY B': {'P012', 'P023', 'P038', 'P041', 'P042', 'P057', 'P070', 'P075', 'P104'},
# 'MAX': {''},
# 'NEOPIXEL': {''},
# 'ENERGY': {''},
'NORMAL': {'P016', 'P035'},
}
@@ -75,13 +78,17 @@ buildColors = {
}
# Add/update a single plugin in the list
def addOnePlugin(build, plugin, pluginName):
def addOnePlugin(build, plugin, pluginName, with_lb = False):
if not build in allBuilds:
allBuilds[build] = {}
allBuilds[build].update({plugin: pluginName})
if not build in allBuilds_lb:
allBuilds_lb[build] = {}
if with_lb:
allBuilds_lb[build].update({plugin: pluginName})
# Add a plugin to all builds it should go in
def addToAllBuilds(plugin, pluginName, builds:dict):
def addToAllBuilds(plugin, pluginName, builds:dict, builds_lb:dict):
for b in appendBuilds:
if not b in builds:
builds += {b}
@@ -96,7 +103,7 @@ def addToAllBuilds(plugin, pluginName, builds:dict):
if plugin in excludePlugins[b]:
includeIt = False
if includeIt:
addOnePlugin(b, plugin, pluginName)
addOnePlugin(b, plugin, pluginName, b in builds_lb)
# Add in other builds too?
if b in appendAlso:
for n in appendAlso[b]:
@@ -105,7 +112,7 @@ def addToAllBuilds(plugin, pluginName, builds:dict):
includeIt = False
# Except when not to be included
if includeIt:
addOnePlugin(n, plugin, pluginName)
addOnePlugin(n, plugin, pluginName, b in builds_lb)
# Parse a single substitution file
def parseSingleSubstitutionFile(fileName):
@@ -118,25 +125,28 @@ def parseSingleSubstitutionFile(fileName):
plugin = ""
pluginName = ""
builds = []
builds_lb = []
while True:
line = pfile.readline()
if not line:
break
# Parse into label, plugin ID, description and up to 4 separate builds (current max.),
# Parse into label, plugin ID, description and up to 5 separate builds (current max.),
# append "(?:[^`]+`([^`]+)`)?" to regex for an extra build, if needed
m = re.search(r"[^|]\|((?:NW|[PCN])(\d{3}))([^\|]+)\|[^`]+`([^`]+)`(?:[^`]+`([^`]+)`)?(?:[^`]+`([^`]+)`)?(?:[^`]+`([^`]+)`)?", line)
m = re.search(r"[^|]\|((?:NW|[PCN])(\d{3}))([^\|]+)\|[^`]+`([^`]+)`(?:[^`]+`([^`]+)`)?(?:[^`]+`([^`]+)`)?(?:[^`]+`([^`]+)`)?(?:[^`]+`([^`]+)`)?", line)
if m:
if m.group(3) == "_typename": # the typename substitution should be before _status...
if plugin != "" and plugin != m.group(1): # Changed plugin ID, store current
addToAllBuilds(plugin, pluginName, builds)
addToAllBuilds(plugin, pluginName, builds, builds_lb)
plugin = m.group(1)
pluginName = m.group(4)
if m.group(3) == "_status":
builds = [m.group(4), m.group(5), m.group(6), m.group(7)]
builds = [m.group(4), m.group(5), m.group(6), m.group(7), m.group(8)]
if m.group(3) == "_status_lb":
builds_lb = [m.group(4), m.group(5), m.group(6), m.group(7), m.group(8)]
pfile.close()
if plugin != "": # Store last one too
addToAllBuilds(plugin, pluginName, builds)
addToAllBuilds(plugin, pluginName, builds, builds_lb)
# Parse all .. include :: files
def parseSubstitutionFiles(rootFile):
@@ -175,11 +185,11 @@ def generateBuildOverview(fileName):
output.write('.. collapse:: Details...\n')
output.write('\n')
output.write(' .. csv-table::\n')
output.write(' :header: "Plugin name", "Plugin number"\n')
output.write(' :widths: 10, 5\n')
output.write(' :header: "Plugin name", "ESP32", "ESP8266", "Plugin number"\n')
output.write(' :widths: 10, 3, 3, 3\n')
output.write('\n')
for p in sorted(allBuilds[b], key=sortPluginsBeforeControllers):
output.write(' ":ref:`' + p + '_page`","' + p + '"\n')
output.write(' ":ref:`' + p + '_page`", "✓", "' + ('✓' if p in allBuilds_lb[b] else '') + '", "' + p + '"\n')
output.write('\n')
output.close()
docs/source/Controller/C001.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C001_type|
Name: |C001_name|
Status: |C001_status|
Status ESP32: |C001_status|
Status ESP8266: |C001_status_lb|
GitHub: |C001_github|_
docs/source/Controller/C002.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C002_type|
Name: |C002_name|
Status: |C002_status|
Status ESP32: |C002_status|
Status ESP8266: |C002_status_lb|
GitHub: |C002_github|_
docs/source/Controller/C003.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C003_type|
Name: |C003_name|
Status: |C003_status|
Status ESP32: |C003_status|
Status ESP8266: |C003_status_lb|
GitHub: |C003_github|_
docs/source/Controller/C004.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C004_type|
Name: |C004_name|
Status: |C004_status|
Status ESP32: |C004_status|
Status ESP8266: |C004_status_lb|
GitHub: |C004_github|_
docs/source/Controller/C005.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C005_type|
Name: |C005_name|
Status: |C005_status|
Status ESP32: |C005_status|
Status ESP8266: |C005_status_lb|
GitHub: |C005_github|_
docs/source/Controller/C006.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C006_type|
Name: |C006_name|
Status: |C006_status|
Status ESP32: |C006_status|
Status ESP8266: |C006_status_lb|
GitHub: |C006_github|_
docs/source/Controller/C007.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C007_type|
Name: |C007_name|
Status: |C007_status|
Status ESP32: |C007_status|
Status ESP8266: |C007_status_lb|
GitHub: |C007_github|_
docs/source/Controller/C008.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C008_type|
Name: |C008_name|
Status: |C008_status|
Status ESP32: |C008_status|
Status ESP8266: |C008_status_lb|
GitHub: |C008_github|_
docs/source/Controller/C009.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C009_type|
Name: |C009_name|
Status: |C009_status|
Status ESP32: |C009_status|
Status ESP8266: |C009_status_lb|
GitHub: |C009_github|_
docs/source/Controller/C010.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C010_type|
Name: |C010_name|
Status: |C010_status|
Status ESP32: |C010_status|
Status ESP8266: |C010_status_lb|
GitHub: |C010_github|_
docs/source/Controller/C011.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C011_type|
Name: |C011_name|
Status: |C011_status|
Status ESP32: |C011_status|
Status ESP8266: |C011_status_lb|
GitHub: |C011_github|_
docs/source/Controller/C012.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C012_type|
Name: |C012_name|
Status: |C012_status|
Status ESP32: |C012_status|
Status ESP8266: |C012_status_lb|
GitHub: |C012_github|_
docs/source/Controller/C013.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C013_type|
Name: |C013_name|
Status: |C013_status|
Status ESP32: |C013_status|
Status ESP8266: |C013_status_lb|
GitHub: |C013_github|_
docs/source/Controller/C014.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C014_type|
Name: |C014_name|
Status: |C014_status|
Status ESP32: |C014_status|
Status ESP8266: |C014_status_lb|
GitHub: |C014_github|_
docs/source/Controller/C016.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C016_type|
Name: |C016_name|
Status: |C016_status|
Status ESP32: |C016_status|
Status ESP8266: |C016_status_lb|
GitHub: |C016_github|_
docs/source/Controller/C017.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C017_type|
Name: |C017_name|
Status: |C017_status|
Status ESP32: |C017_status|
Status ESP8266: |C017_status_lb|
GitHub: |C017_github|_
docs/source/Controller/C018.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |C018_type|
Name: |C018_name|
Status: |C018_status|
Status ESP32: |C018_status|
Status ESP8266: |C018_status_lb|
GitHub: |C018_github|_
docs/source/Controller/_Controller.rst
+19 -19
View File
@@ -18,26 +18,26 @@ Controller Plugins
==================
.. csv-table::
:header: "Plugin name", "Plugin status", "Plugin number"
:widths: 10, 8, 5
:header: "Plugin name", "ESP32 Plugin status", "ESP8266 Plugin status", "Plugin number"
:widths: 9, 6, 6, 3
":ref:`C001_page`","|C001_status|","C001"
":ref:`C002_page`","|C002_status|","C002"
":ref:`C003_page`","|C003_status|","C003"
":ref:`C004_page`","|C004_status|","C004"
":ref:`C005_page`","|C005_status|","C005"
":ref:`C006_page`","|C006_status|","C006"
":ref:`C007_page`","|C007_status|","C007"
":ref:`C008_page`","|C008_status|","C008"
":ref:`C009_page`","|C009_status|","C009"
":ref:`C010_page`","|C010_status|","C010"
":ref:`C011_page`","|C011_status|","C011"
":ref:`C012_page`","|C012_status|","C012"
":ref:`C013_page`","|C013_status|","C013"
":ref:`C014_page`","|C014_status|","C014"
":ref:`C016_page`","|C016_status|","C016"
":ref:`C017_page`","|C017_status|","C017"
":ref:`C018_page`","|C018_status|","C018"
":ref:`C001_page`","|C001_status|","|C001_status_lb|","C001"
":ref:`C002_page`","|C002_status|","|C002_status_lb|","C002"
":ref:`C003_page`","|C003_status|","|C003_status_lb|","C003"
":ref:`C004_page`","|C004_status|","|C004_status_lb|","C004"
":ref:`C005_page`","|C005_status|","|C005_status_lb|","C005"
":ref:`C006_page`","|C006_status|","|C006_status_lb|","C006"
":ref:`C007_page`","|C007_status|","|C007_status_lb|","C007"
":ref:`C008_page`","|C008_status|","|C008_status_lb|","C008"
":ref:`C009_page`","|C009_status|","|C009_status_lb|","C009"
":ref:`C010_page`","|C010_status|","|C010_status_lb|","C010"
":ref:`C011_page`","|C011_status|","|C011_status_lb|","C011"
":ref:`C012_page`","|C012_status|","|C012_status_lb|","C012"
":ref:`C013_page`","|C013_status|","|C013_status_lb|","C013"
":ref:`C014_page`","|C014_status|","|C014_status_lb|","C014"
":ref:`C016_page`","|C016_status|","|C016_status_lb|","C016"
":ref:`C017_page`","|C017_status|","|C017_status_lb|","C017"
":ref:`C018_page`","|C018_status|","|C018_status_lb|","C018"
Controller Parameters
docs/source/Controller/_controller_substitutions.repl
+18 -1
View File
@@ -5,6 +5,7 @@
.. |C001_type| replace:: :cyan:`Controller`
.. |C001_typename| replace:: :cyan:`Controller - Domoticz HTTP`
.. |C001_status| replace:: :green:`NORMAL`
.. |C001_status_lb| replace:: :green:`NORMAL`
.. |C001_github| replace:: C001.cpp
.. _C001_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C001.cpp
.. |C001_usedby| replace:: `.`
@@ -16,6 +17,7 @@
.. |C002_type| replace:: :cyan:`Controller`
.. |C002_typename| replace:: :cyan:`Controller - Domoticz MQTT`
.. |C002_status| replace:: :green:`NORMAL`
.. |C002_status_lb| replace:: :green:`NORMAL`
.. |C002_github| replace:: C002.cpp
.. _C002_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C002.cpp
.. |C002_usedby| replace:: `.`
@@ -27,6 +29,7 @@
.. |C003_type| replace:: :cyan:`Controller`
.. |C003_typename| replace:: :cyan:`Controller - Nodo Telnet`
.. |C003_status| replace:: :green:`NORMAL`
.. |C003_status_lb| replace:: :green:`NORMAL`
.. |C003_github| replace:: C003.cpp
.. _C003_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C003.cpp
.. |C003_usedby| replace:: `.`
@@ -38,6 +41,7 @@
.. |C004_type| replace:: :cyan:`Controller`
.. |C004_typename| replace:: :cyan:`Controller - ThingSpeak`
.. |C004_status| replace:: :green:`NORMAL`
.. |C004_status_lb| replace:: :green:`NORMAL`
.. |C004_github| replace:: C004.cpp
.. _C004_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C004.cpp
.. |C004_usedby| replace:: `.`
@@ -49,6 +53,7 @@
.. |C005_type| replace:: :cyan:`Controller`
.. |C005_typename| replace:: :cyan:`Controller - Home Assistant (openHAB) MQTT`
.. |C005_status| replace:: :green:`NORMAL`
.. |C005_status_lb| replace:: :green:`NORMAL`
.. |C005_github| replace:: C005.cpp
.. _C005_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C005.cpp
.. |C005_usedby| replace:: `.`
@@ -60,6 +65,7 @@
.. |C006_type| replace:: :cyan:`Controller`
.. |C006_typename| replace:: :cyan:`Controller - PiDome MQTT`
.. |C006_status| replace:: :green:`NORMAL`
.. |C006_status_lb| replace:: :green:`NORMAL`
.. |C006_github| replace:: C006.cpp
.. _C006_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C006.cpp
.. |C006_usedby| replace:: `.`
@@ -71,6 +77,7 @@
.. |C007_type| replace:: :cyan:`Controller`
.. |C007_typename| replace:: :cyan:`Controller - Emoncms`
.. |C007_status| replace:: :green:`NORMAL`
.. |C007_status_lb| replace:: :green:`NORMAL`
.. |C007_github| replace:: C007.cpp
.. _C007_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C007.cpp
.. |C007_usedby| replace:: `.`
@@ -82,6 +89,7 @@
.. |C008_type| replace:: :cyan:`Controller`
.. |C008_typename| replace:: :cyan:`Controller - Generic HTTP`
.. |C008_status| replace:: :green:`NORMAL`
.. |C008_status_lb| replace:: :green:`NORMAL`
.. |C008_github| replace:: C008.cpp
.. _C008_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C008.cpp
.. |C008_usedby| replace:: `.`
@@ -93,6 +101,7 @@
.. |C009_type| replace:: :cyan:`Controller`
.. |C009_typename| replace:: :cyan:`Controller - FHEM HTTP`
.. |C009_status| replace:: :green:`NORMAL`
.. |C009_status_lb| replace:: :green:`NORMAL`
.. |C009_github| replace:: C009.cpp
.. _C009_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C009.cpp
.. |C009_usedby| replace:: `.`
@@ -104,6 +113,7 @@
.. |C010_type| replace:: :cyan:`Controller`
.. |C010_typename| replace:: :cyan:`Controller - Generic UDP`
.. |C010_status| replace:: :green:`NORMAL`
.. |C010_status_lb| replace:: :green:`NORMAL`
.. |C010_github| replace:: C010.cpp
.. _C010_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C010.cpp
.. |C010_usedby| replace:: `.`
@@ -115,6 +125,7 @@
.. |C011_type| replace:: :cyan:`Controller`
.. |C011_typename| replace:: :cyan:`Controller - Generic HTTP Advanced`
.. |C011_status| replace:: :yellow:`COLLECTION` :yellow:`CLIMATE`
.. |C011_status_lb| replace:: :yellow:`COLLECTION` :yellow:`CLIMATE`
.. |C011_github| replace:: C011.cpp
.. _C011_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C011.cpp
.. |C011_usedby| replace:: `.`
@@ -126,6 +137,7 @@
.. |C012_type| replace:: :cyan:`Controller`
.. |C012_typename| replace:: :cyan:`Controller - Blynk`
.. |C012_status| replace:: :yellow:`COLLECTION`
.. |C012_status_lb| replace:: :yellow:`COLLECTION`
.. |C012_github| replace:: C012.cpp
.. _C012_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C012.cpp
.. |C012_usedby| replace:: `.`
@@ -137,6 +149,7 @@
.. |C013_type| replace:: :cyan:`Controller`
.. |C013_typename| replace:: :cyan:`Controller - ESPEasy P2P Networking`
.. |C013_status| replace:: :green:`NORMAL`
.. |C013_status_lb| replace:: :green:`NORMAL`
.. |C013_github| replace:: C013.cpp
.. _C013_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C013.cpp
.. |C013_usedby| replace:: `.`
@@ -148,6 +161,7 @@
.. |C014_type| replace:: :cyan:`Controller`
.. |C014_typename| replace:: :cyan:`Controller - Homie MQTT convention`
.. |C014_status| replace:: :yellow:`COLLECTION`
.. |C014_status_lb| replace:: :yellow:`COLLECTION`
.. |C014_github| replace:: C014.cpp
.. _C014_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C014.cpp
.. |C014_usedby| replace:: `.`
@@ -158,7 +172,8 @@
.. |C016_name| replace:: :cyan:`Cache`
.. |C016_type| replace:: :cyan:`Controller`
.. |C016_typename| replace:: :cyan:`Controller - Cache`
.. |C016_status| replace:: :red:`DEVELOPMENT`
.. |C016_status| replace:: :yellow:`MAX`
.. |C016_status_lb| replace:: `.`
.. |C016_github| replace:: C016.cpp
.. _C016_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C016.cpp
.. |C016_usedby| replace:: `.`
@@ -170,6 +185,7 @@
.. |C017_type| replace:: :cyan:`Controller`
.. |C017_typename| replace:: :cyan:`Controller - Zabbix`
.. |C017_status| replace:: :yellow:`COLLECTION`
.. |C017_status_lb| replace:: :yellow:`COLLECTION`
.. |C017_github| replace:: C017.cpp
.. _C017_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C017.cpp
.. |C017_usedby| replace:: `.`
@@ -181,6 +197,7 @@
.. |C018_type| replace:: :cyan:`Controller`
.. |C018_typename| replace:: :cyan:`Controller - LoRa TTN - RN2483/RN2903`
.. |C018_status| replace:: :yellow:`COLLECTION`
.. |C018_status_lb| replace:: :yellow:`COLLECTION`
.. |C018_github| replace:: C018.cpp
.. _C018_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C018.cpp
.. |C018_usedby| replace:: `.`
docs/source/ESPEasy/ESPchips.rst
+16 -12
View File
@@ -34,10 +34,14 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
* **ESP32-S3** Support added: 2023-05-03
* **ESP32-C2 / ESP8684** Support added: 2023-11-10
* **ESP32-C3 / ESP8685** Support added: 2023-05-03
* **ESP32-C5** Not yet supported
* **ESP32-C5** Preliminary support added: 2026-01-09
* **ESP32-C6** Support added: 2023-11-10
* **ESP32-C61** Preliminary support added: 2026-01-09
* **ESP32-E22** Not yet supported
* **ESP32-H2** Not yet supported
* **ESP32-P4** Not yet supported
* **ESP32-H21** Not yet supported
* **ESP32-H4** Not yet supported
* **ESP32-P4** Support added: 2026-01-08
.. list-table:: Espressif platforms
@@ -92,7 +96,7 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
- 160
- 120
- 96
- 400
- 360 (v1.x) / 400 (v3.x)
* - Voltage (V)
- 2.5 ~ 3.6
- 3.0 ~ 3.6
@@ -115,8 +119,8 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
-
- Nov-23
-
-
-
- n/a
- Jan-26
* - Introduction
- 2014
- 2016
@@ -124,23 +128,23 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
- 2021
- 2022
- 2020
-
- 2022
- 2021
-
- 2024
- 2021
-
* - Status (2024/12)
- 2023
* - Status (2026/03)
- End-Of-Life
- Mass Production (solo1: NRND)
- NRND
- Mass Production
- Mass Production
- Mass Production
- Sample
- Mass Production
- Sample
- Mass Production
- Sample
- Mass Production
- Mass Production
- Mass Production
* - Wi-Fi
- IEEE 802.11 b/g/n; 2.4 GHz; HT20; up to 72 Mbps
- IEEE 802.11 b/g/n; 2.4 GHz; HT20/40; up to 150 Mbps
docs/source/Hardware/Hardware.rst
-378
View File
@@ -33,153 +33,6 @@ This feature can be useful in a development/laboratory environment, for when the
.. image:: Hardware_Resetpin.png
-------------
I2C Bus
-------------
When using devices that use the I2C bus (Inter-integrated circuit, also known as IIC, and mostly compatible with SM Bus) (`Wikipedia: I2C <https://en.wikipedia.org/wiki/I%C2%B2C>`_) some pins have to be configured, and initialized during boot, for the SDA and SCL connections. This can be any unused pair of pins on the ESP board.
The pins can be configured here, and will have default values initially (ESP8266: SDA: GPIO-4 (D2), SCL: GPIO-5 (D3), ESP32: No defaults). When I2C is not used, these can be set to `- None -`, so the pins are available for other purposes.
When having an I2C Priority task configured, the I2C GPIO pins (for that bus, when multiple buses are available) can no longer be changed, as that could disable the hardware, thus blocking the device. The configured GPIO pins will be display-only.
The default bus clock speed can also be set here. If only devices supporting 100 kHz are connected (Old/Slow devices), then the value can be set to 100 kHz, by default 400 kHz is configured, that is supported by newer devices, though there are many devices supporting higher frequencies. ESP8266 is able to achieve ca. 400 kHz, while ESP32 allows higher speeds.
ESPEasy has a separate setting for Slow I2C devices, and per I2C device this slow clock speed can be selected in the Device configuration page. This value is by default set to 100 kHz, but can be set lower or higher if desired.
*I2C ClockStretchLimit*
- `I2C-bus.org - Clock Stretching <https://www.i2c-bus.org/clock-stretching/>`_
- `ESPeasy wiki - Basics: The I2C Bus <https://www.letscontrolit.com/wiki/index.php/Basics:_The_I%C2%B2C_Bus>`_
This setting is only available for the first I2C Bus, as not many devices (should) need this set, and the devices that do need this should then be connected to I2C Bus 0.
.. image:: Hardware_I2CBus.png
*Device specific Force Slow I2C speed selection:*
.. image:: Device_I2COptionsShort.png
Added: 2023-11-23
A device flag has been added for specific devices to have **Force Slow I2C speed** set by default. After adding the device this option will be checked, but can still be unchecked to use (try) Fast I2C speed (400 kHz).
Added: 2025-02-02
Multiple I2C Buses can be configured on ESP32 builds. This aids in connecting all on-board sensors and devices when multiple GPIO pin-pairs are used for I2C devices. By default, 2 I2C Buses are made available, but via compile-time options, a 3rd I2C Bus can be enabled, if required.
.. image:: Hardware_I2CBus2.png
The available options are the same as for the first I2C Bus.
If a second (or third) I2C Bus are not needed, then leave the GPIO settings on ``- None -``, and the interface won't be initialized, and not shown in the configuration options.
NB: The I2C Buses should of course not be configured for the same GPIO pins as any other I2C Bus.
NB2: Some boards require that in the Serial Console Settings (Tools/Advanced), the ``Fall-back to Serial 0`` option is disabled, to free the GPIO pins for I2C use.
When multiple I2C Buses are configured (so, ``SDA`` and ``SCL`` GPIO-pins configured), each task configured with an I2C device will show a selection for the I2C Bus to use. As expected, the first I2C Bus is selected by default, and another interface can be selected as required.
*Device specific I2C Bus selection:*
.. image:: Device_I2CBusSelection.png
NB: If a multiplexer is configured for 1 of the I2C Buses (but *not* for all interfaces), the I2C Bus selector will save & reload the page to show/hide the multiplexer options, below.
.. image:: Device_I2CBusSelectionReload.png
This screenshot shows the reload icon, to indicate that changing the selection will reload the page.
.. image:: Device_I2CBusSelection3.png
And an example for when 3 I2C Buses are available (compile-time option!) and configured.
---------------
I2C Multiplexer
---------------
Since build 20110, there is the option of using an I2C multiplexer. This option is not available in all builds, because of the size of the code. It is usually available in the normal, testing and custom builds, but ommitted from minimal, IR and hardware-specific builds.
Possible use-cases for an I2C multiplexer are:
* Connect multiple devices that have fixed or limited I2C addresses (For example, some OLED devices have a single fixed address but you need to connect 2 or more, or connect more than 3 TLS2561 devices, that support only 3 different addresses).
* Connect different devices that have the same I2C address (For example connecting a TSL2561 light/lux sensor and an APDS9960 proximity sensor).
* Connect slow and fast devices, where the speed of the fast device prohibits proper working of the slow device.
.. |br| raw:: html
<br>
.. note::
If devices with conflicting I2C addresses are to be used, then *none* of them can be connected to the ESP main I2C bus, but they should each be connected to a separate channel of the multiplexer. |br|
Devices that do not conflict with other devices *can* be connected to the ESP main I2C bus, this might improve the performance/responsiveness of these devices.
.. note::
When using an I2C Multiplexer, make sure there is no address conflict with any of the devices you intend to connect, f.e. when connecting BME280 sensors, don't set the address of the multiplexer to 0x76 or 0x77.
There are a couple of I2C multiplexer chips available, currently there is support for:
* TCA9548a (8 channels, multiple channel-connections, 8 I2C addresses, with reset)
* TCA9546a (4 channels, multiple channel-connections, 8 I2C addresses, with reset, also TCA9545a can be used, but no support for the Interrupt function though)
* TCA9543a (2 channels, multiple channel-connections, 4 I2C addresses, with reset)
* PCA9540 (2 channels, fixed I2C address, no reset, experimental support)
The TCA9548a, TCA9546a and TCA9543a support connecting multiple channels to the main I2C channel. This can be configured on the Device edit page for I2C devices, once the I2C Multiplexer configuration is enabled by selecting a multiplexer type and an I2C address for the multiplexer.
Also, the TCA9548a, TCA9546a and TCA9543a chips have a connection for a reset signal available. This allows the chip to be reset if it gets stuck by some 'less compatible' or 'badly behaving' devices. Once connected and configured, the multiplexer can be reset from the software, if desired or required. This feature is not yet used in any I2C device plugin.
A TCA9543a board has the advantage of being quite a bit smaller than either TCA9546a or TCA9548a, while being digitally compatible. (But with less channels and only 4 I2C addresses).
All these chips/boards can be found at Adafruit, Aliexpress, Banggood, EBay, etc.
.. image:: Hardware_I2CMultiplexerNone.png
*Available multiplexer types:*
.. image:: Hardware_I2CMultiplexer_Type.png
*Select the I2C Address for the multiplexer:*
.. image:: Hardware_I2CMultiplexer_Address.png
Added: 2025-02-02
With the introduction of multiple I2C Buses, it is also plausible to configure an I2C Multiplexer on the second (or third, when included in the build) I2C Bus.
.. image:: Hardware_I2CMultiplexer2.png
This allows the same configuration options as shown above for the first I2C Bus, as all I2C Buses are completely independent from each other.
Device configuration
^^^^^^^^^^^^^^^^^^^^
If an I2C multiplexer is configured for the selected I2C Bus, the Device edit page for I2C devices will show extra options to select the multiplexer channel the device is connected on.
There is the default option of Single channel, or, when a TCA9548a, TCA9546a or TCA9543a is configured, Multiple channels.
*Example: A multiplexer is configured, but the device is connected directly on the ESP board I2C channel:*
.. image:: Device_I2COptionsMultiplexerNone.png
*Configure a (single) multiplexer channel the device is connected on:*
.. image:: Device_I2COptionsMultiplexerSelectSingleChannel.png
NB: Only acceptable channels (0-7/0-3/0-1) will be available in the dropdown list, depending on the Multiplexer type configured.
*Select Single channel or Multiple channels:*
.. image:: Device_I2COptionsMultiplexerSelect.png
*Configure multiple channels for a device, 8 channel multiplexer configured*
.. image:: Device_I2COptionsMultiplexerMultipleSelect.png
Above configuration results in channels 0, 4, 5, 6 and 7 being connected to the ESP board I2C bus when this sensor is active via I2C.
NB: Only acceptable channel checkboxes (0-7/0-3/0-1) will be shown, depending on the Multiplexer type configured.
--------------------
PCF & MCP Direct I/O
@@ -198,41 +51,6 @@ When using multiple PCF and/or MCP GPIO extenders, they must all be connected to
NB: If only 1 I2C Bus is configured, this section isn't shown.
-------------
SPI Interface
-------------
When using devices that are connected via the SPI interface (`Wikipedia: SPI <https://en.wikipedia.org/wiki/Serial_Peripheral_Interface>`_), the interface must be initialized during boot. This can be enabled here. For ESP32 there is the option to select the HSPI (often called Hardware SPI) interface, the VSPI (often called Virtual SPI) interface, or select User-defined GPIO pins for the ``SCLK``, ``MISO`` and ``MOSI`` signals.
The common SPI pins are shown here.
Other SPI pins to be used are device specific, and need to be configured from the corresponding Device edit page.
*For ESP8266:*
.. image:: Hardware_SPIInterfaceESP8266.png
*For ESP32, disabled:*
.. image:: Hardware_SPIInterfaceESP32.png
*For ESP32, select the desired configuration:*
.. image:: Hardware_SPIInterfaceESP32_Select.png
NB: When using the VSPI configuration and also the I2C interface is used, another pin has to be selected for I2C GPIO -> SCL, as its configuration is fixed for the VSPI setting.
When selecting the *User-defined* options, 3 extra input fields are displayed, where the ``SCLK``, ``MISO`` and ``MOSI`` GPIO pins have to be selected. Nearly all pins can be used, but for the output signals ``SCLK`` and ``MOSI`` **no** *input-only* pins should be selected!
.. image:: Hardware_SPIInterfaceESP32_UserDefined.png
.. warning::
When changing the setting for **Init SPI**, or changing any of the User-defined GPIO pins, the ESP32 unit needs a hardware reset. This can be achieved by pressing the reset button (when available, sometimes labelled ``EN`` or ``RST``), or by completely removing the power for ~30 seconds. Also take into account here that units with a backup battery (f.e. some LilyGo and Waveshare ESP32 models) may keep power on the unit, so specific measures may have to be taken!
NB: When selecting the *User-defined* option, **all 3 GPIO pins should be set**, or an error message will be displayed when the page is saved, and the SPI interface will not be enabled at the next boot.
.. image:: Hardware_SPIpinsError.png
-------
SD Card
-------
@@ -241,202 +59,6 @@ When the compile-time option for SD-card support is enabled, the ``CS`` pin for
.. image:: Hardware_SDCard.png
--------
Ethernet
--------
On builds including ``_eth`` in their build name, it is also possible to use ethernet instead of WiFi.
Currently this is only present for ESP32 builds and no plans currently exist to support it for ESP82xx.
N.B. This is still in testing phase, so not all kinds of network communications work right now.
Preferred network medium
^^^^^^^^^^^^^^^^^^^^^^^^
Allows to switch between:
* WiFi (default)
* Ethernet
To activate a new configuration, a reboot is needed.
Ethernet PHY type
^^^^^^^^^^^^^^^^^
ESP boards can be equiped with Ethernet.
This is more stable and reliable compared to WiFi and allows for better responsiveness.
Actual transfer speed (at least when using RMII) is also higher than can be achieved via WiFi, but this is less of a concern for typical use cases where ESPEasy is used.
Ethernet chips/boards for ESP32-variant boards exist with 2 types of interfaces to the ESP.
* RMII interface - Faster actual transfer speeds possible, uses more GPIO pins, only supported on ESP32-classic (and upcoming ESP32-P4).
* SPI interface - (Added: 2024/02) Supported on all ESP32-variants (not all tested) on builds based on ESP-IDF 5.1
SPI Ethernet adapters do obviously require the SPI interface to be configured.
N.B. Only ESP32-variant builds with LittleFS support SPI Ethernet. (starting February 2024)
Supported Ethernet chips:
* RMII Interface:
* LAN8710 (LAN8720 is also supported, but none of the newer features are supported)
* TLK110
* RTL8201 (since ESP32 IDF 4.4)
* JL1101 (since ESP32 IDF 4.4)
* DP83848 (since ESP32 IDF 4.4)
* KSZ8041 (since ESP32 IDF 4.4)
* KSZ8081 (since ESP32 IDF 4.4)
* SPI Interface: (since ESP32 IDF 5.1)
* DM9051
* W5500
* KSZ8851
.. note:: The LAN8710 and LAN8720 are also available with an "A" suffix.
These are the same chips, only produced after the brand SMSC was taken over by Microchip Technology.
Ethernet PHY Address
^^^^^^^^^^^^^^^^^^^^
The PHY address depends on the hardware and the PHY configuration.
On some chips, like the LAN8720, the board designer may set this address by pulling some pins either high or low at power on.
In theory, one could use multiple PHY adapters on the same RMII/SPI bus, but this is (currently) not supported by ESPEasy.
* Espressif's Ethernet board with TLK110 PHY use PHY address 31.
* Common Waveshare LAN8720 PHY breakout board (and clones) use PHY address 1.
* Olimex ESP32 EVB REV B IoT LAN8710 PHY Board with CAN use PHY address 0.
* Other LAN8720 breakouts often use PHY address 0.
* ETH01-EVO (ESP32-C3 based board) uses PHY address 1.
If the PHY address is incorrect then the EMAC will initialise but all attempts to read/write configuration registers on the PHY will fail.
N.B. There is support for an auto detect of this PHY address, by setting it to -1, but at least on the LAN8720 this does not seem to work.
RMII Ethernet
^^^^^^^^^^^^^
As mentioned above, the RMII interface is only present on ESP32-classic (and is mentioned on the announced ESP32-P4).
RMII PHY SMI Wiring
"""""""""""""""""""
Most PHY boards have documented their *RMII PHY SMI Wiring* pins:
* **MDC** Output to PHY, usually pin 23
* **MDIO** Bidirectional, usually pin 18
Clock sync
""""""""""
The PHY and the ESP need to keep a clock in sync.
This can either be done via an external crystal, which is connected to a GPIO pin.
Another option is to let the ESP provide the clock to the PHY.
* External crystal oscillator
* 50MHz APLL Output on GPIO0
* 50MHz APLL Output on GPIO16
* 50MHz APLL Inverted Output on GPIO17
.. note:: When using an external crystal oscillator, this is connected to GPIO-0. Make sure this crystal is not active, or connected to GPIO-0, during boot or else the ESP32 may boot into flash mode.
Power pin
"""""""""
On almost all PHY boards, or ESP boards equiped with an ethernet PHY, it is possible to turn the PHY on or off.
Either to save energy, or to make sure the external clock is not affecting the ESP boot mode when it restarts.
For example the Olimex ESP32-EVB does have the *external crystal oscillator* connected to GPIO-0, which could boot the ESP32 randomly into UART flash mode.
Most boards use a specific GPIO pin to control the power to the PHY.
The Olimex ESP32-EVB does have a specific delay circuit to only allow power to the PHY after boot and therefore does not need to control the PHY power.
For other boards, the default is often GPIO-17, but this may change per board.
(Changed: 2022-01-20)
If the power pin is defined, ESPEasy will toggle the ethernet module off and on at boot.
Some Ethernet modules, like the LAN8720, may sometimes get stuck and need to be reset to get it to work again.
RMII PHY Wiring
"""""""""""""""
Apart from these GPIO pins, there is a number of other pins reserved on the ESP32 for RMII PHY Wiring.
Since these GPIO pin assignments cannot be changed, it is also not needed to configure them.
However, they also cannot be used when *RMII PHY* is used.
.. include:: ../Reference/RMII_Ethernet_PHY_ESP32.rst
RMII Ethernet ESP32 Boards
""""""""""""""""""""""""""
.. include:: ../Reference/RMII_Ethernet_ESP32_boards.rst
SPI Ethernet
^^^^^^^^^^^^
(Added: 2024/02)
As mentioned above, these SPI based Ethernet interfaces require the SPI interface to be configured.
The SPI bus can be shared, but the SPI Ethernet chips are a bit specific about the used frequency.
Currently the default SPI frequency of 20 MHz is used, so not all other SPI devices may work together with SPI Ethernet.
Some boards like the ETH01-EVO (ESP32-C3 based) do not even have the SPI bus pins made accesible.
.. note:: Switching to ECO mode can sometimes result in an unreachable node when using SPI Ethernet. After a reboot the node works just fine again (in ECO mode). This is currently being investigated.
GPIO Configuration
""""""""""""""""""
* CS pin: Just as any SPI device, it needs a CS pin to tell the device it is being addressed.
* IRQ/INT pin: Allows the Ethernet chip to signal the ESP about new data. (Optional for W5500)
* RST pin: ESP will try to reset the Ethernet adapter during boot. Not all boards may have this wired.
SPI Ethernet ESP32 Boards
"""""""""""""""""""""""""
.. include:: ../Reference/SPI_Ethernet_ESP32_boards.rst
Ethernet with PoE
^^^^^^^^^^^^^^^^^
Some ethernet boards support Power over Ethernet (PoE), so only a single (ethernet) cable to the ESP is needed, and the ESP (and any sensors) will be powered via an onboard converter.
For Olimex boards in the ESP32-POE range, the supplier has documented this warning:
.. warning::
**Important notice**: Olimex ESP32-PoE has **no galvanic isolation** from Ethernet's power supply, when you program the board via the micro USB connector the Ethernet cable should be disconnected (if you have power over the Ethernet cable)!
Consider using Olimex USB-ISO to protect your computer and board from accidental short circuit. Also consider instead using Olimex ESP32-PoE-ISO board, which *is* insulated.
Most likely, this warning is applicable to other brands as well.
Ethernet Isolation
^^^^^^^^^^^^^^^^^^
Most Ethernet RJ45 phy (the connector on the PCB) have isolation transformers in them.
This does isolate the TX/RX pins to make sure there is no direct connection between the long cables and the Ethernet controller chip.
The isolation does protect the Ethernet chip from picked up high voltage spikes and ESD surges when inserting the Ethernet cable.
However not all ESP boards with Ethernet have these installed.
Apart from the isolation of the TX/RX pins the metallic enclosure of the phy should also be isolated from the rest of the circuit of the ESP board.
Typically this is done by connecting the metal enclosure of the phy via a capacitor to GND of the rest of the circuit.
A lot of boards with Ethernet have these directly connected to GND, which may impose a problem when connecting the ESP board to your PC.
.. warning::
**Important notice**: For ESP boards with Ethernet which need debugging, never use Ethernet cables with metal shielding on the Ethernet connector.
Using shielded Ethernet cable will connect the metal shield of the RJ45 phy to the ground of the switch and this may be connected to other appliances which may be badly grounded.
This will add a significant voltage offset between the ESP board and your PC while debugging.
Such a high voltage is very likely to destroy electronics.
-------------------
GPIO boot states
docs/source/Hardware/Device_I2CBusSelection.png → docs/source/Interfaces/Device_I2CBusSelection.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

docs/source/Hardware/Device_I2CBusSelection3.png → docs/source/Interfaces/Device_I2CBusSelection3.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

docs/source/Hardware/Device_I2CBusSelectionReload.png → docs/source/Interfaces/Device_I2CBusSelectionReload.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

docs/source/Hardware/Device_I2COptionsMultiplexerMultipleSelect.png → docs/source/Interfaces/Device_I2COptionsMultiplexerMultipleSelect.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

docs/source/Hardware/Device_I2COptionsMultiplexerNone.png → docs/source/Interfaces/Device_I2COptionsMultiplexerNone.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.7 KiB

After

Width:  |  Height:  |  Size: 7.7 KiB

docs/source/Hardware/Device_I2COptionsMultiplexerSelect.png → docs/source/Interfaces/Device_I2COptionsMultiplexerSelect.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.9 KiB

After

Width:  |  Height:  |  Size: 8.9 KiB

docs/source/Hardware/Device_I2COptionsMultiplexerSelectSingleChannel.png → docs/source/Interfaces/Device_I2COptionsMultiplexerSelectSingleChannel.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 23 KiB

docs/source/Hardware/Device_I2COptionsShort.png → docs/source/Interfaces/Device_I2COptionsShort.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 3.3 KiB

docs/source/Hardware/Hardware_I2CBus.png → docs/source/Interfaces/Hardware_I2CBus.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

docs/source/Hardware/Hardware_I2CBus2.png → docs/source/Interfaces/Hardware_I2CBus2.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

docs/source/Hardware/Hardware_I2CMultiplexer2.png → docs/source/Interfaces/Hardware_I2CMultiplexer2.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

docs/source/Hardware/Hardware_I2CMultiplexerNone.png → docs/source/Interfaces/Hardware_I2CMultiplexerNone.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.7 KiB

After

Width:  |  Height:  |  Size: 9.7 KiB

docs/source/Hardware/Hardware_I2CMultiplexer_Address.png → docs/source/Interfaces/Hardware_I2CMultiplexer_Address.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 24 KiB

docs/source/Hardware/Hardware_I2CMultiplexer_Type.png → docs/source/Interfaces/Hardware_I2CMultiplexer_Type.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

docs/source/Hardware/Hardware_SPIInterfaceESP32.png → docs/source/Interfaces/Hardware_SPIInterfaceESP32.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.3 KiB

After

Width:  |  Height:  |  Size: 8.3 KiB

docs/source/Hardware/Hardware_SPIInterfaceESP32_Select.png → docs/source/Interfaces/Hardware_SPIInterfaceESP32_Select.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

docs/source/Hardware/Hardware_SPIInterfaceESP32_UserDefined.png → docs/source/Interfaces/Hardware_SPIInterfaceESP32_UserDefined.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

docs/source/Hardware/Hardware_SPIInterfaceESP8266.png → docs/source/Interfaces/Hardware_SPIInterfaceESP8266.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.6 KiB

After

Width:  |  Height:  |  Size: 7.6 KiB

docs/source/Hardware/Hardware_SPIpinsError.png → docs/source/Interfaces/Hardware_SPIpinsError.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.0 KiB

After

Width:  |  Height:  |  Size: 2.0 KiB

docs/source/Interfaces/Interfaces.rst
+209
View File
@@ -0,0 +1,209 @@
.. _Interfaces_page:
Interfaces page
***************
To configure the available (included in the build) device interfaces there are tabs for each type of interface bus. These tabs allow to set up the GPIO pins, clock speeds and other needed parameters for each interface.
* :ref:`i2c-bus`
* :ref:`spi-bus`
* :ref:`modbus`
.. _i2c-bus:
-------
I2C Bus
-------
When using devices that use the I2C bus (Inter-integrated circuit, also known as IIC, and mostly compatible with SM Bus) (`Wikipedia: I2C <https://en.wikipedia.org/wiki/I%C2%B2C>`_) some pins have to be configured, and initialized during boot, for the SDA and SCL connections. This can be any unused pair of pins on the ESP board.
The pins can be configured here, and will have default values initially (ESP8266: SDA: GPIO-4 (D2), SCL: GPIO-5 (D3), ESP32: No defaults). When I2C is not used, these can be set to `- None -`, so the pins are available for other purposes.
When having an I2C Priority task configured, the I2C GPIO pins (for that bus, when multiple buses are available) can no longer be changed, as that could disable the hardware, thus blocking the device. The configured GPIO pins will be display-only.
The default bus clock speed can also be set here. If only devices supporting 100 kHz are connected (Old/Slow devices), then the value can be set to 100 kHz, by default 400 kHz is configured, that is supported by newer devices, though there are many devices supporting higher frequencies. ESP8266 is able to achieve ca. 400 kHz, while ESP32 allows higher speeds.
ESPEasy has a separate setting for Slow I2C devices, and per I2C device this slow clock speed can be selected in the Device configuration page. This value is by default set to 100 kHz, but can be set lower or higher if desired.
*I2C ClockStretchLimit*
- `I2C-bus.org - Clock Stretching <https://www.i2c-bus.org/clock-stretching/>`_
- `ESPeasy wiki - Basics: The I2C Bus <https://www.letscontrolit.com/wiki/index.php/Basics:_The_I%C2%B2C_Bus>`_
This setting is only available for the first I2C Bus, as not many devices (should) need this set, and the devices that do need this should then be connected to I2C Bus 0.
.. image:: Hardware_I2CBus.png
*Device specific Force Slow I2C speed selection:*
.. image:: Device_I2COptionsShort.png
Added: 2023-11-23
A device flag has been added for specific devices to have **Force Slow I2C speed** set by default. After adding the device this option will be checked, but can still be unchecked to use (try) Fast I2C speed (400 kHz).
Added: 2025-02-02
Multiple I2C Buses can be configured on ESP32 builds. This aids in connecting all on-board sensors and devices when multiple GPIO pin-pairs are used for I2C devices. By default, 2 I2C Buses are made available, but via compile-time options, a 3rd I2C Bus can be enabled, if required.
.. image:: Hardware_I2CBus2.png
The available options are the same as for the first I2C Bus.
If a second (or third) I2C Bus are not needed, then leave the GPIO settings on ``- None -``, and the interface won't be initialized, and not shown in the configuration options.
NB: The I2C Buses should of course not be configured for the same GPIO pins as any other I2C Bus.
NB2: Some boards require that in the Serial Console Settings (Tools/Advanced), the ``Fall-back to Serial 0`` option is disabled, to free the GPIO pins for I2C use.
When multiple I2C Buses are configured (so, ``SDA`` and ``SCL`` GPIO-pins configured), each task configured with an I2C device will show a selection for the I2C Bus to use. As expected, the first I2C Bus is selected by default, and another interface can be selected as required.
*Device specific I2C Bus selection:*
.. image:: Device_I2CBusSelection.png
NB: If a multiplexer is configured for 1 of the I2C Buses (but *not* for all interfaces), the I2C Bus selector will save & reload the page to show/hide the multiplexer options, below.
.. image:: Device_I2CBusSelectionReload.png
This screenshot shows the reload icon, to indicate that changing the selection will reload the page.
.. image:: Device_I2CBusSelection3.png
And an example for when 3 I2C Buses are available (compile-time option!) and configured.
---------------
I2C Multiplexer
---------------
Since build 20110, there is the option of using an I2C multiplexer. This option is not available in all builds, because of the size of the code. It is usually available in the normal, testing and custom builds, but ommitted from minimal, IR and hardware-specific builds.
Possible use-cases for an I2C multiplexer are:
* Connect multiple devices that have fixed or limited I2C addresses (For example, some OLED devices have a single fixed address but you need to connect 2 or more, or connect more than 3 TLS2561 devices, that support only 3 different addresses).
* Connect different devices that have the same I2C address (For example connecting a TSL2561 light/lux sensor and an APDS9960 proximity sensor).
* Connect slow and fast devices, where the speed of the fast device prohibits proper working of the slow device.
.. |br| raw:: html
<br>
.. note::
If devices with conflicting I2C addresses are to be used, then *none* of them can be connected to the ESP main I2C bus, but they should each be connected to a separate channel of the multiplexer. |br|
Devices that do not conflict with other devices *can* be connected to the ESP main I2C bus, this might improve the performance/responsiveness of these devices.
.. note::
When using an I2C Multiplexer, make sure there is no address conflict with any of the devices you intend to connect, f.e. when connecting BME280 sensors, don't set the address of the multiplexer to 0x76 or 0x77.
There are a couple of I2C multiplexer chips available, currently there is support for:
* TCA9548a (8 channels, multiple channel-connections, 8 I2C addresses, with reset)
* TCA9546a (4 channels, multiple channel-connections, 8 I2C addresses, with reset, also TCA9545a can be used, but no support for the Interrupt function though)
* TCA9543a (2 channels, multiple channel-connections, 4 I2C addresses, with reset)
* PCA9540 (2 channels, fixed I2C address, no reset, experimental support)
The TCA9548a, TCA9546a and TCA9543a support connecting multiple channels to the main I2C channel. This can be configured on the Device edit page for I2C devices, once the I2C Multiplexer configuration is enabled by selecting a multiplexer type and an I2C address for the multiplexer.
Also, the TCA9548a, TCA9546a and TCA9543a chips have a connection for a reset signal available. This allows the chip to be reset if it gets stuck by some 'less compatible' or 'badly behaving' devices. Once connected and configured, the multiplexer can be reset from the software, if desired or required. This feature is not yet used in any I2C device plugin.
A TCA9543a board has the advantage of being quite a bit smaller than either TCA9546a or TCA9548a, while being digitally compatible. (But with less channels and only 4 I2C addresses).
All these chips/boards can be found at Adafruit, Aliexpress, Banggood, EBay, etc.
.. image:: Hardware_I2CMultiplexerNone.png
*Available multiplexer types:*
.. image:: Hardware_I2CMultiplexer_Type.png
*Select the I2C Address for the multiplexer:*
.. image:: Hardware_I2CMultiplexer_Address.png
Added: 2025-02-02
With the introduction of multiple I2C Buses, it is also plausible to configure an I2C Multiplexer on the second (or third, when included in the build) I2C Bus.
.. image:: Hardware_I2CMultiplexer2.png
This allows the same configuration options as shown above for the first I2C Bus, as all I2C Buses are completely independent from each other.
Device configuration
^^^^^^^^^^^^^^^^^^^^
If an I2C multiplexer is configured for the selected I2C Bus, the Device edit page for I2C devices will show extra options to select the multiplexer channel the device is connected on.
There is the default option of Single channel, or, when a TCA9548a, TCA9546a or TCA9543a is configured, Multiple channels.
*Example: A multiplexer is configured, but the device is connected directly on the ESP board I2C channel:*
.. image:: Device_I2COptionsMultiplexerNone.png
*Configure a (single) multiplexer channel the device is connected on:*
.. image:: Device_I2COptionsMultiplexerSelectSingleChannel.png
NB: Only acceptable channels (0-7/0-3/0-1) will be available in the dropdown list, depending on the Multiplexer type configured.
*Select Single channel or Multiple channels:*
.. image:: Device_I2COptionsMultiplexerSelect.png
*Configure multiple channels for a device, 8 channel multiplexer configured*
.. image:: Device_I2COptionsMultiplexerMultipleSelect.png
Above configuration results in channels 0, 4, 5, 6 and 7 being connected to the ESP board I2C bus when this sensor is active via I2C.
NB: Only acceptable channel checkboxes (0-7/0-3/0-1) will be shown, depending on the Multiplexer type configured.
|
.. _spi-bus:
-------
SPI Bus
-------
When using devices that are connected via the SPI interface (`Wikipedia: SPI <https://en.wikipedia.org/wiki/Serial_Peripheral_Interface>`_), the interface must be initialized during boot. This can be enabled here. For ESP32 there is the option to select the HSPI (often called Hardware SPI) interface, the VSPI (often called Virtual SPI) interface, or select User-defined GPIO pins for the ``SCLK``, ``MISO`` and ``MOSI`` signals.
The common SPI pins are shown here.
Other SPI pins to be used are device specific, and need to be configured from the corresponding Device edit page.
*For ESP8266:*
.. image:: Hardware_SPIInterfaceESP8266.png
*For ESP32, disabled:*
.. image:: Hardware_SPIInterfaceESP32.png
*For ESP32, select the desired configuration:*
.. image:: Hardware_SPIInterfaceESP32_Select.png
NB: When using the VSPI configuration and also the I2C interface is used, another pin has to be selected for I2C GPIO -> SCL, as its configuration is fixed for the VSPI setting.
When selecting the *User-defined* options, 3 extra input fields are displayed, where the ``SCLK``, ``MISO`` and ``MOSI`` GPIO pins have to be selected. Nearly all pins can be used, but for the output signals ``SCLK`` and ``MOSI`` **no** *input-only* pins should be selected!
.. image:: Hardware_SPIInterfaceESP32_UserDefined.png
.. warning::
When changing the setting for **Init SPI**, or changing any of the User-defined GPIO pins, the ESP32 unit needs a hardware reset. This can be achieved by pressing the reset button (when available, sometimes labelled ``EN`` or ``RST``), or by completely removing the power for ~30 seconds. Also take into account here that units with a backup battery (f.e. some LilyGo and Waveshare ESP32 models) may keep power on the unit, so specific measures may have to be taken!
NB: When selecting the *User-defined* option, **all 3 GPIO pins should be set**, or an error message will be displayed when the page is saved, and the SPI interface will not be enabled at the next boot.
.. image:: Hardware_SPIpinsError.png
|
.. _modbus:
------
Modbus
------
TODO Modbus configuration and documentation to be added.
docs/source/Network/Ethernet_generic.repl
+58
View File
@@ -0,0 +1,58 @@
--------
Ethernet
--------
On nearly all ESP32 builds (exception: ESP32-C2), it is also possible to use ethernet instead of WiFi.
Currently this is only present for ESP32 builds and no plans currently exist to support it for ESP82xx.
Ethernet PHY type
^^^^^^^^^^^^^^^^^
ESP boards can be equiped with Ethernet.
This is more stable and reliable compared to WiFi and allows for better responsiveness.
Actual transfer speed (at least when using RMII) is also higher than can be achieved via WiFi, but this is less of a concern for typical use cases where ESPEasy is used.
Ethernet chips/boards for ESP32-variant boards exist with 2 types of interfaces to the ESP.
* RMII interface - Faster actual transfer speeds possible, uses more GPIO pins, only supported on ESP32-classic and ESP32-P4.
* SPI interface - (Added: 2024/02) Supported on all ESP32-variants (not all tested) on builds based on ESP-IDF 5.1 and later.
SPI Ethernet adapters do obviously require the SPI interface to be configured.
Supported Ethernet chips:
* RMII Interface:
* LAN8710 (LAN8720 is also supported, but none of the newer features are supported)
* LAN867X (since ESP32 IDF 5.5)
* TLK110
* RTL8201 (since ESP32 IDF 4.4)
* JL1101 (since ESP32 IDF 4.4)
* DP83848 (since ESP32 IDF 4.4)
* KSZ8041 (since ESP32 IDF 4.4)
* KSZ8081 (since ESP32 IDF 4.4)
* SPI Interface: (since ESP32 IDF 5.1)
* DM9051
* W5500
* KSZ8851
.. note:: The LAN8710 and LAN8720 are also available with an "A" suffix.
These are the same chips, only produced after the brand SMSC was taken over by Microchip Technology.
Ethernet PHY Address
^^^^^^^^^^^^^^^^^^^^
The PHY address depends on the hardware and the PHY configuration.
On some chips, like the LAN8720, the board designer may set this address by pulling some pins either high or low at power on.
In theory, one could use multiple PHY adapters on the same RMII/SPI bus, but this is (currently) not supported by ESPEasy.
* Espressif's Ethernet board with TLK110 PHY use PHY address 31.
* Common Waveshare LAN8720 PHY breakout board (and clones) use PHY address 1.
* Olimex ESP32 EVB REV B IoT LAN8710 PHY Board with CAN use PHY address 0.
* Other LAN8720 breakouts often use PHY address 0.
* ETH01-EVO (ESP32-C3 based board) uses PHY address 1.
If the PHY address is incorrect then the EMAC will initialise but all attempts to read/write configuration registers on the PHY will fail.
N.B. There is support for an auto detect of this PHY address, by setting it to -1, but at least on the LAN8720 this does not seem to work.
docs/source/Network/Ethernet_poe_iso.repl
+35
View File
@@ -0,0 +1,35 @@
Ethernet with PoE
^^^^^^^^^^^^^^^^^
Some ethernet boards support Power over Ethernet (PoE), so only a single (ethernet) cable to the ESP is needed, and the ESP (and any sensors) will be powered via an onboard converter.
For Olimex boards in the ESP32-POE range, the supplier has documented this warning:
.. warning::
**Important notice**: Olimex ESP32-PoE has **no galvanic isolation** from Ethernet's power supply, when you program the board via the micro USB connector the Ethernet cable should be disconnected (if you have power over the Ethernet cable)!
Consider using Olimex USB-ISO to protect your computer and board from accidental short circuit. Also consider instead using Olimex ESP32-PoE-ISO board, which *is* insulated.
Most likely, this warning is applicable to other brands as well.
Ethernet Isolation
^^^^^^^^^^^^^^^^^^
Most Ethernet RJ45 phy (the connector on the PCB) have isolation transformers in them.
This does isolate the TX/RX pins to make sure there is no direct connection between the long cables and the Ethernet controller chip.
The isolation does protect the Ethernet chip from picked up high voltage spikes and ESD surges when inserting the Ethernet cable.
However not all ESP boards with Ethernet have these installed.
Apart from the isolation of the TX/RX pins the metallic enclosure of the phy should also be isolated from the rest of the circuit of the ESP board.
Typically this is done by connecting the metal enclosure of the phy via a capacitor to GND of the rest of the circuit.
A lot of boards with Ethernet have these directly connected to GND, which may impose a problem when connecting the ESP board to your PC.
.. warning::
**Important notice**: For ESP boards with Ethernet which need debugging, never use Ethernet cables with metal shielding on the Ethernet connector.
Using shielded Ethernet cable will connect the metal shield of the RJ45 phy to the ground of the switch and this may be connected to other appliances which may be badly grounded.
This will add a significant voltage offset between the ESP board and your PC while debugging.
Such a high voltage is very likely to destroy electronics.
docs/source/Network/Ethernet_rmii.repl
+60
View File
@@ -0,0 +1,60 @@
RMII Ethernet
^^^^^^^^^^^^^
As mentioned above, the RMII interface is only present on ESP32-classic and ESP32-P4.
RMII PHY SMI Wiring
"""""""""""""""""""
Most PHY boards have documented their *RMII PHY SMI Wiring* pins:
* **MDC** Output to PHY, usually pin 23
* **MDIO** Bidirectional, usually pin 18
Clock sync
""""""""""
The PHY and the ESP need to keep a clock in sync.
This can either be done via an external crystal, which is connected to a GPIO pin.
Another option is to let the ESP provide the clock to the PHY.
* External crystal oscillator
* 50MHz APLL Output on GPIO0
* 50MHz APLL Output on GPIO16
* 50MHz APLL Inverted Output on GPIO17
.. note:: When using an external crystal oscillator, this is connected to GPIO-0. Make sure this crystal is not active, or connected to GPIO-0, during boot or else the ESP32 may boot into flash mode.
Power pin
"""""""""
On almost all PHY boards, or ESP boards equiped with an ethernet PHY, it is possible to turn the PHY on or off.
Either to save energy, or to make sure the external clock is not affecting the ESP boot mode when it restarts.
For example the Olimex ESP32-EVB does have the *external crystal oscillator* connected to GPIO-0, which could boot the ESP32 randomly into UART flash mode.
Most boards use a specific GPIO pin to control the power to the PHY.
The Olimex ESP32-EVB does have a specific delay circuit to only allow power to the PHY after boot and therefore does not need to control the PHY power.
For other boards, the default is often GPIO-17, but this may change per board.
(Changed: 2022-01-20)
If the power pin is defined, ESPEasy will toggle the ethernet module off and on at boot.
Some Ethernet modules, like the LAN8720, may sometimes get stuck and need to be reset to get it to work again.
RMII PHY Wiring
"""""""""""""""
Apart from these GPIO pins, there is a number of other pins reserved on the ESP32 for RMII PHY Wiring.
Since these GPIO pin assignments cannot be changed, it is also not needed to configure them.
However, they also cannot be used when *RMII PHY* is used.
.. include:: ../Reference/RMII_Ethernet_PHY_ESP32.rst
RMII Ethernet ESP32 Boards
""""""""""""""""""""""""""
.. include:: ../Reference/RMII_Ethernet_ESP32_boards.rst
docs/source/Network/Ethernet_spi.repl
+29
View File
@@ -0,0 +1,29 @@
SPI Ethernet
^^^^^^^^^^^^
(Added: 2024/02)
As mentioned above, these SPI based Ethernet interfaces require the SPI interface to be configured.
The SPI bus can be shared, but the SPI Ethernet chips are a bit specific about the used frequency.
Currently the default SPI frequency of 20 MHz is used, so not all other SPI devices may work together with SPI Ethernet.
Some boards like the ETH01-EVO (ESP32-C3 based) do not even have the SPI bus pins made accesible.
.. note:: Switching to ECO mode can sometimes result in an unreachable node when using SPI Ethernet. After a reboot the node works just fine again (in ECO mode). This is currently being investigated.
GPIO Configuration
""""""""""""""""""
* CS pin: Just as any SPI device, it needs a CS pin to tell the device it is being addressed.
* IRQ/INT pin: Allows the Ethernet chip to signal the ESP about new data. (Optional for W5500)
* RST pin: ESP will try to reset the Ethernet adapter during boot. Not all boards may have this wired.
SPI Ethernet ESP32 Boards
"""""""""""""""""""""""""
.. include:: ../Reference/SPI_Ethernet_ESP32_boards.rst
docs/source/Network/NW001.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |NW001_type|
Name: |NW001_name|
Status: |NW001_status|
Status ESP32: |NW001_status|
Status ESP8266: |NW001_status_lb|
GitHub: |NW001_github|_
docs/source/Network/NW002.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |NW002_type|
Name: |NW002_name|
Status: |NW002_status|
Status ESP32: |NW002_status|
Status ESP8266: |NW002_status_lb|
GitHub: |NW002_github|_
docs/source/Network/NW003.rst
+9 -1
View File
@@ -14,12 +14,20 @@ Type: |NW003_type|
Name: |NW003_name|
Status: |NW003_status|
Status ESP32: |NW003_status|
Status ESP8266: |NW003_status_lb|
GitHub: |NW003_github|_
Maintainer: |NW003_maintainer|
.. include:: Ethernet_generic.repl
.. include:: Ethernet_rmii.repl
.. include:: Ethernet_poe_iso.repl
Change log
----------
docs/source/Network/NW004.rst
+9 -1
View File
@@ -14,12 +14,20 @@ Type: |NW004_type|
Name: |NW004_name|
Status: |NW004_status|
Status ESP32: |NW004_status|
Status ESP8266: |NW004_status_lb|
GitHub: |NW004_github|_
Maintainer: |NW004_maintainer|
.. include:: Ethernet_generic.repl
.. include:: Ethernet_spi.repl
.. include:: Ethernet_poe_iso.repl
Change log
----------
docs/source/Network/NW005.rst
+3 -1
View File
@@ -14,7 +14,9 @@ Type: |NW005_type|
Name: |NW005_name|
Status: |NW005_status|
Status ESP32: |NW005_status|
Status ESP8266: |NW005_status_lb|
GitHub: |NW005_github|_
docs/source/Network/_Network.rst
+96 -10
View File
@@ -3,7 +3,7 @@
Network
*******
A Network plugin is compable with a 'driver' for a network adapter.
A Network plugin is comparable with a 'driver' for a network adapter.
The first 2 entries will be the same for every ESPEasy setup and these cannot be removed.
@@ -11,21 +11,107 @@ The first 2 entries will be the same for every ESPEasy setup and these cannot be
- Wi-Fi AP: To let the ESP board act as an access point.
.. note::
The network code of ESPEasy has been rewritten in 2025/2026.
Older builds of ESPEasy do have a different organisation of network related parameters.
Most of these were accessible via the ``Tools->Advanced`` page.
.. _Network Plugins:
Network Plugins
==================
.. csv-table::
:header: "Plugin name", "Plugin status", "Plugin number"
:widths: 10, 8, 5
.. note::
ESP32 builds do have a lot more networking capabilities compared to ESP8266.
For ESP8266 we only have support for WiFi and no other network interfaces will be added for ESP8266.
":ref:`NW001_page`","|NW001_status|","NW001"
":ref:`NW002_page`","|NW002_status|","NW002"
":ref:`NW003_page`","|NW003_status|","NW003"
":ref:`NW004_page`","|NW004_status|","NW004"
":ref:`NW005_page`","|NW005_status|","NW005"
.. csv-table::
:header: "Plugin name", "ESP32 Plugin status", "ESP8266 Plugin status", "Plugin number"
:widths: 9, 6, 6, 3
":ref:`NW001_page`","|NW001_status|","|NW001_status_lb|","NW001"
":ref:`NW002_page`","|NW002_status|","|NW002_status_lb|","NW002"
":ref:`NW003_page`","|NW003_status|","|NW003_status_lb|","NW003"
":ref:`NW004_page`","|NW004_status|","|NW004_status_lb|","NW004"
":ref:`NW005_page`","|NW005_status|","|NW005_status_lb|","NW005"
Network Parameters
=====================
==================
Route Priority
--------------
(ESP32 only)
When using multiple network interfaces, like WiFi, Ethernet or PPP LTE Modem, it must be made clear which interface should be used for new connections initiated from ESPEasy to some other host.
The connected network interface with the highest Route Priority is considered to be the default route.
Default Route Priority values are:
* WiFi STA = 100
* Ethernet = 50
* PPP (LTE modem) = 20
* WiFi AP = 10
Fallback Interface
------------------
(ESP32 only)
.. note::
The concept of a Fallback Interface is available on ESP8266, but only for WiFi AP.
This is a special case, which is discussed here: :ref:`NW002_page` .
A network interface can be marked as "Fallback Interface".
A fallback interface will only be scheduled to start when:
* A non-fallback interface failed to connect.
* Route Priority changed to a value which is less than the set priority for the fallback interface.
The scheduled delay to start the fallback interface is set as "Delay Startup" (see below).
A fallback interface will be stopped when there is a default route with a route priority higher than the set Route Priority of the fallback interface.
It is possible to set multiple interfaces as Fallback Interface.
The fallback order can be tweaked using the Delay Startup and Route Priority.
N.B. Network interfaces which should be started at boot, should not be marked as Fallback Interface.
Delay Startup
-------------
For various reasons, it can be useful to not immediately start a network interface at boot.
For example to reduce the power consumption as most network interfaces may draw significant more power for a short time when starting.
Another use case can be to check some sensor value before deciding to either start the network interface or enter deep sleep again.
The set value (in msec) is the delay from boot before starting the network interface.
Delay Startup for Fallback Interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A Fallback Interface is not started at boot.
The set Delay Startup is then used as delay to schedule starting the network interface.
See "Fallback Interface" for more information.
Block Web Access
----------------
When checked, the ESPEasy web interface cannot be accessed via the IP-range of the network interface.
.. note::
The PPP Network Interface (ESP32-only) will have this checked by default, since you typically can't access devices from the network of the mobile provider.
If this is possible for some odd reason, you very likely would never want to allow this.
Enable IPv6
-----------
(ESP32 only)
Checking this checkbox, will allow the network device to use IPv6.
docs/source/Network/_network_substitutions.repl
+5
View File
@@ -5,6 +5,7 @@
.. |NW001_type| replace:: :cyan:`Network`
.. |NW001_typename| replace:: :cyan:`Network - WiFi Station`
.. |NW001_status| replace:: :green:`NORMAL`
.. |NW001_status_lb| replace:: :green:`NORMAL`
.. |NW001_github| replace:: _NW001_WiFi_STA.cpp
.. _NW001_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/ESPEasy/net/_NW001_WiFi_STA.cpp
.. |NW001_usedby| replace:: `.`
@@ -16,6 +17,7 @@
.. |NW002_type| replace:: :cyan:`Network`
.. |NW002_typename| replace:: :cyan:`Network - WiFi AP`
.. |NW002_status| replace:: :green:`NORMAL`
.. |NW002_status_lb| replace:: :green:`NORMAL`
.. |NW002_github| replace:: _NW002_WiFi_AP.cpp
.. _NW002_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/ESPEasy/net/_NW002_WiFi_AP.cpp
.. |NW002_usedby| replace:: `.`
@@ -27,6 +29,7 @@
.. |NW003_type| replace:: :cyan:`Network`
.. |NW003_typename| replace:: :cyan:`Network - Ethernet (RMII)`
.. |NW003_status| replace:: :green:`NORMAL`
.. |NW003_status_lb| replace:: `.`
.. |NW003_github| replace:: _NW003_ETH_RMII.cpp
.. _NW003_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/ESPEasy/net/_NW003_ETH_RMII.cpp
.. |NW003_usedby| replace:: `.`
@@ -38,6 +41,7 @@
.. |NW004_type| replace:: :cyan:`Network`
.. |NW004_typename| replace:: :cyan:`Network - Ethernet (SPI)`
.. |NW004_status| replace:: :green:`NORMAL`
.. |NW004_status_lb| replace:: `.`
.. |NW004_github| replace:: _NW004_ETH_SPI.cpp
.. _NW004_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/ESPEasy/net/_NW004_ETH_SPI.cpp
.. |NW004_usedby| replace:: `.`
@@ -49,6 +53,7 @@
.. |NW005_type| replace:: :cyan:`Network`
.. |NW005_typename| replace:: :cyan:`Network - PPP Modem`
.. |NW005_status| replace:: :green:`NORMAL`
.. |NW005_status_lb| replace:: `.`
.. |NW005_github| replace:: _NW005_PPP_modem.cpp
.. _NW005_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/ESPEasy/net/_NW005_PPP_modem.cpp
.. |NW005_usedby| replace:: `.`
docs/source/Notify/N001.rst
+3 -1
View File
@@ -11,7 +11,9 @@ Type: |N001_type|
Name: |N001_name|
Status: |N001_status|
Status ESP32: |N001_status|
Status ESP8266: |N001_status_lb|
GitHub: |N001_github|_
docs/source/Notify/N002.rst
+3 -1
View File
@@ -12,7 +12,9 @@ Type: |N002_type|
Name: |N002_name|
Status: |N002_status|
Status ESP32: |N002_status|
Status ESP8266: |N002_status_lb|
GitHub: |N002_github|_
docs/source/Notify/_Notifications.rst
+4 -4
View File
@@ -16,8 +16,8 @@ Notifications Plugins
======================
.. csv-table::
:header: "Name", "Status", "Notify Number"
:widths: 10, 8, 5
:header: "Plugin name", "ESP32 Plugin status", "ESP8266 Plugin status", "Plugin Number"
:widths: 9, 6, 6, 3
":ref:`N001_page`","|N001_status|","N001"
":ref:`N002_page`","|N002_status|","N002"
":ref:`N001_page`","|N001_status|","|N001_status_lb|","N001"
":ref:`N002_page`","|N002_status|","|N002_status_lb|","N002"
docs/source/Notify/_notify_substitutions_n00x.repl
+2
View File
@@ -3,6 +3,7 @@
.. |N001_typename| replace:: :cyan:`Notifications - Email (SMTP)`
.. |N001_porttype| replace:: `.`
.. |N001_status| replace:: :green:`NORMAL` :yellow:`CLIMATE` :yellow:`COLLECTION` :yellow:`SONOFF` :yellow:`SHELLY`
.. |N001_status_lb| replace:: :green:`NORMAL` :yellow:`CLIMATE` :yellow:`COLLECTION` :yellow:`SONOFF` :yellow:`SHELLY`
.. |N001_github| replace:: N001_Email.cpp
.. _N001_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_N001_Email.cpp
.. |N001_maintainer| replace:: `.`
@@ -15,6 +16,7 @@
.. |N002_typename| replace:: :cyan:`Notifications - Buzzer`
.. |N002_porttype| replace:: `.`
.. |N002_status| replace:: :green:`NORMAL` :yellow:`CLIMATE` :yellow:`COLLECTION` :yellow:`SONOFF` :yellow:`SHELLY`
.. |N002_status_lb| replace:: :green:`NORMAL` :yellow:`CLIMATE` :yellow:`COLLECTION` :yellow:`SONOFF` :yellow:`SHELLY`
.. |N002_github| replace:: N002_Buzzer.cpp
.. _N002_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_N002_Buzzer.cpp
.. |N002_maintainer| replace:: `.`
docs/source/Participate/PlatformIO.rst
+37 -32
View File
@@ -3,14 +3,14 @@
PlatformIO
**********
ESP easy can be built using the Arduino IDE or PlatformIO (PIO).
Arduino IDE is not being used during development, so it may take some more effort to get it setup for building ESPeasy.
ESP easy can be built using the PlatformIO/pioarduino IDE (PIO).
Arduino IDE is no longer supported for development though it's technically possible to be used. It may take considerable effort to get it setup for building ESPeasy.
We *strongly* advise to use PlatformIO as build environment.
We *strongly* advise to use PIO as build environment.
PlatformIO is just the build, test and upload environment for many micro controllers like the ESP8266 and ESP32 we use.
PIO is just the build, test and upload environment for many micro controllers like the ESP8266 and ESP32 we use.
On top of that you need to use an editor, or so called IDE in which PlatformIO will be used.
On top of that you need to use an editor, or so called IDE in which PIO will be used.
The current choice is:
@@ -21,10 +21,10 @@ VSCode is free to use and available for Windows, MacOS and Linux.
Apart from VSCode, there are more available, like Eclipse, MS Visual Studio (IDE) and probably more.
PlatformIO Prerequisites
========================
PlatformIO/pioarduino Prerequisites
===================================
PlatformIO does need at least the following:
PIO does need at least the following:
* Python
* Git command line tools (`download <https://git-scm.com/downloads>`_)
@@ -58,17 +58,18 @@ install Pyton in Windows for PlatformIO.
These steps have been explained in this Youtube video: https://youtu.be/ArqwMcYSMsU though you might want to use the latest version of both the Git tools and Python.
PlatformIO with VSCode
======================
PlatformIO/pioarduino with VSCode
=================================
Install
-------
For development of ESPEasy, a number of extensions has to be installed in VS-Code:
* PlatformIO IDE (by PlatformIO)
* C/C++ IntelliSense (by Microsoft)
* pioarduino IDE (by pioarduino)
* C/C++ (by Microsoft)
* C/C++ Extension Pack (by Microsoft)
* C/C++ Themes (by Microsoft)
* Uncrustify (by Zachary Flower, originally by Laurent Tréguier)
Optional, but highly recommended:
@@ -79,6 +80,7 @@ Optional, but highly recommended:
* All Autocomplete (by Atishay Jain)
* Excel Viewer (by GrapeCity)
* Esbonio - An extension for editing sphinx projects (by Swyddfa)
* reStructuredText (by LeXtudio)
* reStructuredText Syntax highlighting (by Trond Snekvik)
* Extension pack for reStructuredText (by LeXtudio Inc.)
* Markdown All in One (by Yu Zhang)
@@ -109,17 +111,19 @@ After setting it as the default formatter, the hotkey Alt-Shift-F (Cmd-Shift-F o
There used to be a reference to the Atom editor, but both Atom, and the PlatformIO plugin for Atom, are no longer maintained by their owners, so it was removed from this documentation.
Load a project using PlatformIO
-------------------------------
Load a project using PlatformIO/pioarduino
------------------------------------------
.. note:: PlatformIO has been superceded by the Community-supported **pioarduino** initiative. For simplicity, in most places the abbreviation PIO is throughout this section of the documentation.
If you have PIO installed and the source tree cloned to your hard drive, then you can open the main dir of the repository.
The main directory of the repository is the level with the file platformio.ini in it.
Then in a few moments after opening the directory, on the left there will appear an alien logo, the logo of PlatformIO.
Then in a few moments after opening the directory, on the left there will appear an chip-package logo, the logo of pioarduino.
If you click that one, you will get a tree with lots and lots of project tasks and environments.
It is important to note that PlatformIO does everything based on environments, which are defined in the platformio.ini file.
In the PlatformIO menu (on the left) everything is grouped per environment.
It is important to note that PIO does everything based on environments, which are defined in the platformio.ini file.
In the PIO menu (on the left) everything is grouped per environment.
An environment entry has several tasks, like:
@@ -130,8 +134,9 @@ An environment entry has several tasks, like:
* Clean
* ... many more.
Some of these options only are available when you have registered with PlatformIO and some are only for paid subscriptions.
At least the basic ones used for almost any user are available with the free account.
.. .. Some of these options only are available when you have registered with PlatformIO and some are only for paid subscriptions.
.. .. At least the basic ones used for almost any user are available with the free account.
The environment definitions all have at least the used micro controller in the name and the amount of flash memory used.
@@ -144,8 +149,8 @@ For example:
* ..._ESP32_16M8M_LittleFS -> ESP32 with 16 MB flash and a 4 MB partition for the sketch. (8MB LittleFS)
* ..._ESP32_16M1M_ETH -> ESP32 with 16 MB flash and a 4 MB partition for the sketch. (1MB SPIFFS, Wired ethernet support)
Make a custom build using PlatformIO
------------------------------------
Make a custom build using PIO
-----------------------------
The easiest is to go for the environment ``custom_ESP8266_4M1M`` and unfold that one.
Then select ``Build`` to see if it will start building.
@@ -213,7 +218,7 @@ Now that Linux is installed, it's strongly advised to get it up to date with the
NB: The ``sudo`` command will ask for your current account password once, (and maybe later again after some time has passed). When asked for confirmation, confirm the installation of any needed updates, or add the ``-y`` parameter to the ``upgrade`` command to continue without questions.
Additionally some tools need to be installed so PlatformIO can be properly installed later, and we can use the Uncrustify plugin in VS-Code to format the code nicely:
Additionally some tools need to be installed so PIO can be properly installed later, and we can use the Uncrustify plugin in VS-Code to format the code nicely:
.. highlight::sh
@@ -307,7 +312,7 @@ Upload to ESP
Linux
-----
For Linux, you may need to install 99-platformio-udev.rules to make PlatformIO upload tools work in vscode.
For Linux, you may need to install 99-platformio-udev.rules to make PIO upload tools work in vscode.
.. highlight::sh
@@ -317,12 +322,12 @@ Starter guide for (local) development on ESPEasy
For those with less development experience, or less experience in using Github, this chapter is intended as a **How To** guide to get started with development on ESPEasy.
It tries to help setting up Visual Studio Code (VSCode) with the PlatformIO development environment and additional VSCode plugins that aid in easier working on code and documentation.
It tries to help setting up Visual Studio Code (VSCode) with the PIO development environment and additional VSCode plugins that aid in easier working on code and documentation.
The global steps described here are:
- Creating a private copy on Github
- Getting VSCode and PlatformIO set up
- Getting VSCode and PIO set up
- Getting the source code from Github onto your system
- Compiling the source code
- Creating a branch to make your changes
@@ -366,12 +371,12 @@ After this completes, you can view the fork in your Github dashboard at https://
(You have to replace [your_github_handle] with the name you selected during the Github sign-up procedure)
Install VSCode and PlatformIO
Install VSCode and PIO
------------------------------
Earlier on this page, a complete description has been given on how to install **PlatformIO with VSCode** with the required and advised optional extensions and the git command-line tools.
Earlier on this page, a complete description has been given on how to install **PlatformIO/pioarduino with VSCode** with the required and advised optional extensions and the git command-line tools.
NB: PlatformIO is often shortened to PIO.
NB: PlatformIO/pioarduino is shortened to PIO.
Clone your forked repository to your computer
---------------------------------------------
@@ -422,7 +427,7 @@ Depending on your usual workflow, the current VSCode environment can be saved as
Compile an ESPEasy PIO environment
----------------------------------
ESPEasy supports several different configurations of ESP units, ESP8266, ESP8285 and ESP32, and also some predefined hardware configurations and sets of plugins & controllers. This has been turned into several different PlatformIO environments, to make managing the different builds as easy as possible.
ESPEasy supports several different configurations of ESP units, ESP8266, ESP8285 and ESP32, and also some predefined hardware configurations and sets of plugins & controllers. This has been turned into several different PIO environments, to make managing the different builds as easy as possible.
To compile such 'environment' (PIO terminology), select the PIO button (it looks like an alien) in VSCode:
@@ -492,10 +497,10 @@ Especially for new plugins, it is highly recommended to write documentation, as
Using external libraries
~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
Since November 2022, the PlatformIO configuration for ESPEasy was changed to *require* all libraries to be locally available, to a) prevent unexpected 'surprises' when an external library is updated, and b) greatly improve build output stability and quality.
Since November 2022, the PIO configuration for ESPEasy was changed to *require* all libraries to be locally available, to a) prevent unexpected 'surprises' when an external library is updated, and b) greatly improve build output stability and quality.
While developing a plugin or some other feature, often you use an existing library to re-use that (assumably) proven and tested functionality. To include such library, there is a prerequisite, and some generic steps to take:
@@ -516,7 +521,7 @@ Writing documentation
Updating, or adding if it does not yet exist, the documentation is a useful activity that should be part of changing or adding to the ESPEasy code. Some of the optional VSCode extensions are specifically aimed at that task.
The documentation is created in the reStructuredText format, using mostly a ``.rst`` extension, and can be built locally by installing the sphinx tool. This can be installed manually by opening a PlatformIO Terminal window in VSCode (an already open PIO Terminal can also be used, when using WSL2 a PlatformIO Terminal is *required* to execute in the correct Python Virtual Environment (venv)) and issuing these commands:
The documentation is created in the reStructuredText format, using mostly a ``.rst`` extension, and can be built locally by installing the sphinx tool. This can be installed manually by opening a PIO Terminal window in VSCode (an already open PIO Terminal can also be used, when using WSL2 a PIO Terminal is *required* to execute in the correct Python Virtual Environment (venv)) and issuing these commands:
.. code-block::
docs/source/Plugin/P000.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P000_type|
Name: |P000_name|
Status: |P000_status|
Status ESP32: |P000_status|
Status ESP8266: |P000_status_lb|
GitHub: |P000_github|_
docs/source/Plugin/P000_commands.repl
+25 -13
View File
@@ -549,37 +549,49 @@
:green:`Rules`","
Like ``PostToHTTP`` but using a TLS connection, by default on port 443
NB: No certificate validation is done!
NB: No certificate validation is done!"
"
ProvisionConfig","
Provision,Config","
:red:`Internal`","
Fetch ``config.dat`` as configured in the Provisioning configuration (see Settings Archive)
``ProvisionConfig``"
``Provision,Config``"
"
ProvisionSecurity","
Provision,Security","
:red:`Internal`","
Fetch ``security.dat`` as configured in the Provisioning configuration (see Settings Archive)
``ProvisionSecurity``"
``Provision,Security``"
"
ProvisionNotification","
Provision,DevSecurity","
:red:`Internal`","
Fetch ``devsecurity.dat`` as configured in the Provisioning configuration (see Settings Archive)
``Provision,DevSecurity``"
"
Provision,Notification","
:red:`Internal`","
Fetch ``notification.dat`` as configured in the Provisioning configuration (see Settings Archive)
``ProvisionNotification``"
``Provision,Notification``"
"
ProvisionProvision","
Provision,Provision","
:red:`Internal`","
Fetch ``provisioning.dat`` as configured in the Provisioning configuration (see Settings Archive)
``ProvisionProvision``"
``Provision,Provision``"
"
ProvisionRules","
Provision,Rules","
:red:`Internal`","
Fetch ``rulesN.txt`` as configured in the Provisioning configuration (see Settings Archive)
``ProvisionRules,1`` to fetch ``rules1.txt`` "
``Provision,Rules,1`` to fetch ``rules1.txt`` "
"
Provision,Firmware","
:red:`Internal`","
Fetch a new firmware binary, and flash it on the unit, as configured in the Provisioning configuration (see Settings Archive)
``Provision,Firmware,<url-to-firmware-file>`` to fetch and install the specified .bin file from the specified url."
"
Publish","
:green:`Rules`","
@@ -656,7 +668,7 @@
:green:`Rules`","
Like ``PutToHTTP`` but using a TLS connection, by default on port 443
NB: No certificate validation is done!
NB: No certificate validation is done!"
"
Reboot","
:red:`Internal`","
@@ -736,7 +748,7 @@
:green:`Rules`","
Like ``SendToHTTP`` but using a TLS connection, by default on port 443
NB: No certificate validation is done!
NB: No certificate validation is done!"
"
SendToUDP","
:green:`Rules`","
docs/source/Plugin/P001.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P001_type|
Name: |P001_name|
Status: |P001_status|
Status ESP32: |P001_status|
Status ESP8266: |P001_status_lb|
GitHub: |P001_github|_
docs/source/Plugin/P002.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P002_type|
Name: |P002_name|
Status: |P002_status|
Status ESP32: |P002_status|
Status ESP8266: |P002_status_lb|
GitHub: |P002_github|_
docs/source/Plugin/P003.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P003_type|
Name: |P003_name|
Status: |P003_status|
Status ESP32: |P003_status|
Status ESP8266: |P003_status_lb|
GitHub: |P003_github|_
docs/source/Plugin/P004.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P004_type|
Name: |P004_name|
Status: |P004_status|
Status ESP32: |P004_status|
Status ESP8266: |P004_status_lb|
GitHub: |P004_github|_
docs/source/Plugin/P005.rst
+4 -2
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p00x.repl
.. include:: ../Plugin/_plugin_substitutions_p00x.repl
.. _P005_page:
|P005_typename|
@@ -13,7 +13,9 @@ Type: |P005_type|
Name: |P005_name|
Status: |P005_status|
Status ESP32: |P005_status|
Status ESP8266: |P005_status_lb|
GitHub: |P005_github|_
docs/source/Plugin/P006.rst
+4 -2
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p00x.repl
.. include:: ../Plugin/_plugin_substitutions_p00x.repl
.. _P006_page:
|P006_typename|
@@ -13,7 +13,9 @@ Type: |P006_type|
Name: |P006_name|
Status: |P006_status|
Status ESP32: |P006_status|
Status ESP8266: |P006_status_lb|
GitHub: |P006_github|_
docs/source/Plugin/P007.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P007_type|
Name: |P007_name|
Status: |P007_status|
Status ESP32: |P007_status|
Status ESP8266: |P007_status_lb|
GitHub: |P007_github|_
docs/source/Plugin/P008.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P008_type|
Name: |P008_name|
Status: |P008_status|
Status ESP32: |P008_status|
Status ESP8266: |P008_status_lb|
GitHub: |P008_github|_
docs/source/Plugin/P009.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P009_type|
Name: |P009_name|
Status: |P009_status|
Status ESP32: |P009_status|
Status ESP8266: |P009_status_lb|
GitHub: |P009_github|_
docs/source/Plugin/P010.rst
+4 -2
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. _P010_page:
|P010_typename|
@@ -13,7 +13,9 @@ Type: |P010_type|
Name: |P010_name|
Status: |P010_status|
Status ESP32: |P010_status|
Status ESP8266: |P010_status_lb|
GitHub: |P010_github|_
docs/source/Plugin/P011.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P011_type|
Name: |P011_name|
Status: |P011_status|
Status ESP32: |P011_status|
Status ESP8266: |P011_status_lb|
GitHub: |P011_github|_
docs/source/Plugin/P012.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P012_type|
Name: |P012_name|
Status: |P012_status|
Status ESP32: |P012_status|
Status ESP8266: |P012_status_lb|
GitHub: |P012_github|_
docs/source/Plugin/P013.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P013_type|
Name: |P013_name|
Status: |P013_status|
Status ESP32: |P013_status|
Status ESP8266: |P013_status_lb|
GitHub: |P013_github|_
docs/source/Plugin/P014.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P014_type|
Name: |P014_name|
Status: |P014_status|
Status ESP32: |P014_status|
Status ESP8266: |P014_status_lb|
GitHub: |P014_github|_
docs/source/Plugin/P015.rst
+4 -2
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. _P015_page:
|P015_typename|
@@ -13,7 +13,9 @@ Type: |P015_type|
Name: |P015_name|
Status: |P015_status|
Status ESP32: |P015_status|
Status ESP8266: |P015_status_lb|
GitHub: |P015_github|_
docs/source/Plugin/P016.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P016_type|
Name: |P016_name|
Status: |P016_status|
Status ESP32: |P016_status|
Status ESP8266: |P016_status_lb|
GitHub: |P016_github|_
docs/source/Plugin/P017.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P017_type|
Name: |P017_name|
Status: |P017_status|
Status ESP32: |P017_status|
Status ESP8266: |P017_status_lb|
GitHub: |P017_github|_
docs/source/Plugin/P018.rst
+4 -2
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. _P018_page:
|P018_typename|
@@ -13,7 +13,9 @@ Type: |P018_type|
Name: |P018_name|
Status: |P018_status|
Status ESP32: |P018_status|
Status ESP8266: |P018_status_lb|
GitHub: |P018_github|_
docs/source/Plugin/P019.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P019_type|
Name: |P019_name|
Status: |P019_status|
Status ESP32: |P019_status|
Status ESP8266: |P019_status_lb|
GitHub: |P019_github|_
docs/source/Plugin/P020.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P020_type|
Name: |P020_name|
Status: |P020_status|
Status ESP32: |P020_status|
Status ESP8266: |P020_status_lb|
GitHub: |P020_github|_
docs/source/Plugin/P021.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P021_type|
Name: |P021_name|
Status: |P021_status|
Status ESP32: |P021_status|
Status ESP8266: |P021_status_lb|
GitHub: |P021_github|_
docs/source/Plugin/P022.rst
+3 -1
View File
@@ -13,7 +13,9 @@ Type: |P022_type|
Name: |P022_name|
Status: |P022_status|
Status ESP32: |P022_status|
Status ESP8266: |P022_status_lb|
GitHub: |P022_github|_

Some files were not shown because too many files have changed in this diff Show More