Initial ESPeasy tools add

This commit is contained in:
Hans-Rune Bue
2024-08-27 21:24:11 +02:00
parent 8fb409cd6f
commit f2db069e39
4 changed files with 465 additions and 0 deletions

158
tools/ESPEasy-tools.md Normal file
View File

@@ -0,0 +1,158 @@
|Latest Nightly | Build Status | Downloads | Docs | Patreon | Ko-Fi | PayPal |
|-------|-------|-------|-------|-------|-------|-------|
| [![GitHub version](https://img.shields.io/github/release/letscontrolit/ESPEasy/all.svg)](https://github.com/letscontrolit/ESPEasy/releases/latest) | ![Build status](https://github.com/letscontrolit/ESPEasy/actions/workflows/build.yml/badge.svg) | [![Downloads](https://img.shields.io/github/downloads/letscontrolit/ESPEasy/total.svg)](https://github.com/letscontrolit/ESPEasy/releases) | [![Documentation Status](https://readthedocs.org/projects/espeasy/badge/?version=latest)](https://espeasy.readthedocs.io/en/latest/?badge=latest) | [![donate](https://img.shields.io/badge/donate-Patreon-blue.svg)](https://www.patreon.com/GrovkillenTDer) | [![donate](https://img.shields.io/badge/donate-KoFi-blue.svg)](https://ko-fi.com/grovkillentder) | [![donate](https://img.shields.io/badge/donate-PayPal-blue.svg)](https://www.paypal.me/espeasy) |
For ways to *support* us, see [this announcement on the forum](https://www.letscontrolit.com/forum/viewtopic.php?f=14&t=5787), or have a look at the [Patreon](https://www.patreon.com/GrovkillenTDer), [Ko-Fi](https://ko-fi.com/grovkillentder) or [PayPal](https://www.paypal.me/espeasy) links above.
# ESPEasy (development branch)
Introduction https://espeasy.readthedocs.io/en/latest/ (and, mostly outdated, wiki: https://www.letscontrolit.com/wiki/index.php/ESPEasy#Introduction)
**MEGA**
This is the development branch of ESPEasy. All new features go into this branch, and it has become the current stable branch. If you want to do a bugfix, do it on this branch.
Check here to learn how to use this branch and help us improving ESPEasy: [Starter guide for (local) development on ESPEasy](https://espeasy.readthedocs.io/en/latest/Participate/PlatformIO.html#starter-guide-for-local-development-on-espeasy)
## Web based flasher (experimental)
To make it easier to get started, one may flash a build directly to the ESP from your browser.
Currently only Chrome and Edge are supported.
See [this flash page](https://td-er.nl/ESPEasy/) to try the new web flash feature.
The web flasher is using [ESP Web Tools](https://esphome.github.io/esp-web-tools/) made by the people behind ESPHome and Home Assistant.
## Binary releases
On demand, controlled by the repo owner, our build-bot will build a new binary release: https://github.com/letscontrolit/ESPEasy/releases
The releases are named something like 'mega-20220626' (last number is the build date)
Depending on your needs, we release different types of files:
The name is built up from a few key parts:
ESPEasy_mega\_*[releasedate]*\_*[build-type]*\_*[opt-arduino-library]*\_*[hardware-type]*\_*[flash-size][filesystem-size]*\_*[opt-build-features]*.bin
*[build-type]* can be any of:
Build type | Description | included plugins |
-------------|-------------------------------------------|----------------------------------|
climate | All plugins related to climate measurement| Stable + Climate |
custom | Custom predefined set/Defined in Custom.h | Specific |
normal | Standard plugins | Stable |
collection_A | Normal + plugin collection A | Stable + Collection base + set A |
collection_B | Normal + plugin collection B | Stable + Collection base + set B |
collection_C | Normal + plugin collection C | Stable + Collection base + set C |
collection_D | Normal + plugin collection D | Stable + Collection base + set D |
collection_E | Normal + plugin collection E | Stable + Collection base + set E |
collection_F | Normal + plugin collection F | Stable + Collection base + set F |
collection_G | Normal + plugin collection G | Stable + Collection base + set G |
max | All available plugins | All available |
energy | All plugins related to energy measurement | Stable + Energy measurement |
display | All plugins related to displays | Stable + Displays |
neopixel | All plugins related to neopixel | Stable + Neopixel |
hard | hardware specific builds | Minimal |
minimal | minimal plugins for specific use-cases | Switch and Controller |
spec_* | specialized technical builds | Not intended for regular use |
IRext | Infra-red hardware specific | Sending and receiving IR cmd |
safeboot | (Experimental) `safeboot` build to enable<br>most/all plugins on 4MB Flash boards | None |
*[opt-arduino-library]* (optional) can be any of:
Arduino library | Description |
----------------|------------------------------------|
alt_wifi | Alternative WiFi configuration |
beta | Arduino Beta release |
sdk3 | Arduino SDK v.3 |
core_274 | Arduino Core 2.7.4 release |
core_302 | Arduino Core 3.0.2 release |
core_274_sdk3 | Arduino Core 2.7.4 SDK v.3 release |
*[hardware-type]* can be any of:
Hardware type | Description |
-----------------|---------------------------------------------|
ESP8266 | Espressif ESP8266/ESP8285 generic boards |
WROOM02 | Espressif ESP8266 WRoom02 boards |
ESP32 | Espressif ESP32 generic boards |
ESP32solo1 | Espressif ESP32-Solo1 generic boards |
ESP32s2 | Espressif ESP32-S2 generic boards |
ESP32c3 | Espressif ESP32-C3 generic boards |
ESP32s3 | Espressif ESP32-S3 generic boards |
ESP32c2 | Espressif ESP32-C2 generic boards |
ESP32c6 | Espressif ESP32-C6 generic boards |
ESP32-wrover-kit | Espressif ESP32 wrover-kit boards |
SONOFF | Sonoff hardware specific |
other_POW | Switch with power measurement |
Shelly_1 | Shelly 1 switch |
Shelly_PLUG_S | Shelly plug S switch with power measurement |
Ventus | Ventus W266 weather station |
LCtech_relay | LC-tech serial switch |
N.B. Starting 2022/07/23, 1M ESP8266 builds can also be used on ESP8285 units and thus there is no longer a specific ESP8285 build anymore.
*[flash-size]* can be any of:
Flash size | Description |
-----------|-----------------------------|
1M | 1 MB with 128 kB filesystem |
2M | 2 MB with 128 kB filesystem |
2M256 | 2 MB with 256 kB filesystem |
2M320k | 2 MB with 320 kB filesystem |
4M1M | 4 MB with 1 MB filesystem |
4M2M | 4 MB with 2 MB filesystem |
16M | 16 MB with 14 MB filesystem |
4M316k | 4 MB with 316 kB filesystem |
8M1M | 8 MB with 1 MB filesystem |
16M1M | 16 MB with 1 MB filesystem |
16M8M | 16 MB with 8 MB filesystem |
N.B. Starting with release 2023/12/25, All ESP32 LittleFS builds use IDF 5.1, to support newer ESP32 chips like ESP32-C2 and ESP32-C6. Other SPIFFS based ESP32 builds will be migrated to LittleFS as SPIFFS is no longer available in IDF 5 and later. A migration plan will be made available in 2024.
*[opt-build-features]* can be any of:
Build features | Description |
----------------|-----------------------------------------------------------------------------------------------------------|
LittleFS | Use LittleFS instead of SPIFFS filesystem (SPIFFS is unstable \> 2 MB, and no longer supported in IDF \> 5) |
VCC | Analog input configured to measure VCC voltage (ESP8266 only) |
OTA | Arduino OTA (Over The Air) update feature enabled |
Domoticz | Only Domoticz controllers (HTTP) and plugins included |
Domoticz_MQTT | Only Domoticz controllers (MQTT) and plugins included |
FHEM_HA | Only FHEM/OpenHAB/Home Assistant (MQTT) controllers and plugins included |
ETH | Ethernet interface enabled (ESP32-classic only) |
OPI_PSRAM | Specific configuration to enable PSRAM detection, ESP32-S3 only |
CDC | Support USBCDC/HWCDC-serial console on ESP32-C3, ESP32-S2, ESP32-S3 and ESP32-C6 |
noOTA/NO_OTA | Does not support OTA (Over The Air-updating of the firmware) Use [the flash page](https://td-er.nl/ESPEasy/) or ESPTool via USB Serial |
Some example firmware names:
Firmware name | Hardware | Included plugins |
------------------------------------------------------------------|---------------------------------------|----------------------------------|
ESPEasy_mega-20230822_normal_ESP8266_1M.bin | ESP8266/ESP8285 with 1MB flash | Stable |
ESPEasy_mega-20230822_normal_ESP8266_4M1M.bin | ESP8266 with 4MB flash | Stable |
ESPEasy_mega-20230822_collection_A_ESP8266_4M1M.bin | ESP8266 with 4MB flash | Stable + Collection base + set A |
ESPEasy_mega-20230822_normal_ESP32_4M316k.bin | ESP32 with 4MB flash | Stable |
ESPEasy_mega-20230822_collection_A_ESP32_4M316k.bin | ESP32 with 4MB flash | Stable + Collection base + set A |
ESPEasy_mega-20230822_collection_B_ESP32_4M316k.bin | ESP32 with 4MB flash | Stable + Collection base + set B |
ESPEasy_mega-20230822_max_ESP32s3_8M1M_LittleFS_CDC.bin | ESP32-S3 with 8MB flash, CDC-serial | All available plugins |
ESPEasy_mega-20230822_max_ESP32s3_8M1M_LittleFS_OPI_PSRAM_CDC.bin | ESP32-S3 8MB flash, PSRAM, CDC-serial | All available plugins |
ESPEasy_mega-20230822_max_ESP32_16M1M.bin | ESP32 with 16MB flash | All available plugins |
ESPEasy_mega-20230822_max_ESP32_16M8M_LittleFS.bin | ESP32 with 16MB flash | All available plugins |
The binary files for the different ESP32 variants (S2, C3, S3, C2, C6, 'Classic') are available in separate archives.
To see what plugins are included in which collection set, you can find that on the [ESPEasy Plugin overview page](https://espeasy.readthedocs.io/en/latest/Plugin/_Plugin.html)
## Documentation & more info
Our new, in-depth documentation can be found at [ESPEasy.readthedocs.io](https://espeasy.readthedocs.io/en/latest/). Automatically built, so always up-to-date according to the contributed contents. The old Wiki documentation can be found at [letscontrolit.com/wiki](https://www.letscontrolit.com/wiki/index.php?title=ESPEasy).
Additional details and discussion are on the "Experimental" section of the forum: https://www.letscontrolit.com/forum/viewforum.php?f=18
[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/letscontrolit/ESPEasy)
## Icons used
Icons on courtesy of [ICONS8](https://icons8.com/).

183
tools/espeasybackup Executable file
View File

@@ -0,0 +1,183 @@
#!/bin/bash
PROG=$( basename $0 )
DATETIME=$( date "+%Y%m%d-%H%M%S-" )
PREREQS="curl jq"
MAXTIME=30
JSONTIME=6
HWPROVIDERRE="5c:cf:7f:|18:fe:34:|60:01:94:|a0:20:a6:|b4:e6:2d:|68:c6:3a:"
IPLIST=()
function dbgprint {
[[ -n "${DBGPRINT}" ]] && echo "$PROG debug: $*" >&2
}
function peerlist {
local H="$1"
local O="${DATETIME}${H}.json"
if [[ -s "${O}" ]]
then
dbgprint "PROG: Reading json file from $O ..."
else
dbgprint "PROG: Downloading json file from $H ..."
curl -s -m ${JSONTIME} "http://${H}/json" > "${O}"
fi
if [[ -s "${O}" ]]
then
jq '.nodes[]|{ IPaddr: .ip}' "${O}" | tr -d '"' | awk '{ if ( $1 == "IPaddr:" ) print $2 }'
else
rm "${O}"
echo "$PROG: Warning: Empty response from http://${H}/json" >&2
fi
}
function collectip {
local H="$1"
local IP I NIDX
for IP in $( peerlist ${H} )
do
NIDX=${#IPLIST[*]}
for ((I=0; I < ${NIDX}; I++))
do
[[ ${IPLIST[$I]} == ${IP} ]] && break
done
# if we made it to end of list without matches
if [[ ${I} == ${NIDX} ]]
then
IPLIST[$NIDX]="${IP}"
dbgprint "Found new $IP (index $NIDX ) ..."
fi
done
}
if [[ "$1" == "-h" ]] || [[ -z "$1" ]]
then
echo "Usage: $PROG [-a][-z zipfilefullpath|-Z] IPorHostname ..." >&2
exit 1
fi
#
# put CURLARGS='-u username:password' in ~/.espeasy , then chmod 600 ~/.espeasy
#
if [[ -r "${HOME}/.espeasy" ]]
then
dbgprint "PROG: sourcing ${HOME}/.espeasy"
source "${HOME}/.espeasy"
else
echo "$PROG: Cannot read ${HOME}/.espeasy" >&2
exit 1
fi
if [[ "$1" == "-a" ]]
then
shift
ARPADDR=$( /usr/sbin/arp -an | awk "/${HWPROVIDERRE}/ { print \$2 }" | tr -d '()' | tr '\n' ' ' )
dbgprint "PROG: arp address list: $ARPADDR"
fi
if [[ "$1" == "-z" ]]
then
ZIP="$2" ; shift ; shift
DATETIME=""
PREPREQS="${PREREQS} zip"
mkdir "/tmp/${PROG}-$$" && cd "/tmp/${PROG}-$$"
elif [[ "$1" == "-Z" ]]
then
shift
ZIP="/tmp/config-$(hostname -s)-$( date +%F )"
DATETIME=""
PREPREQS="${PREREQS} zip"
mkdir "/tmp/${PROG}-$$" && cd "/tmp/${PROG}-$$"
fi
[[ -n "${MAILTO}" ]] && PREPREQS="${PREREQS} mail"
for CMD in ${PREREQS}
do
type $CMD > /dev/null 2>&1 && continue
echo "$PROG: Please install all prereqs: ${PREREQS}"
exit 2
done
if [[ $# -gt 1 ]] || [[ -n "${ARPADDR}" ]]
then
echo "$PROG: Initial list $* $ARPADDR ..."
for H in $* ${ARPADDR}
do
collectip "${H}"
done
echo "$PROG: Secondary list: ${IPLIST[*]} ..."
for H in ${IPLIST}
do
collectip "${H}"
done
else
collectip "$1"
IPLIST=( $1 )
fi
echo "PROG: Backup list has ${#IPLIST[*]} nodes: ${IPLIST[*]} "
for H in ${IPLIST[*]}
do
O="${DATETIME}${H}.json"
if [[ ! -s "${O}" ]]
then
dbgprint "PROG: Downloading missing json file from $H ..."
curl -s -m ${JSONTIME} "http://${H}/json" > "${O}"
fi
NAME=$( jq '.WiFi.Hostname' "${O}" | tr -d '"')
NAME="${NAME:-$H}"
for F in config.dat security.dat notification.dat rules1.txt rules2.txt rules3.txt rules4.txt esp.css
do
O="${DATETIME}${NAME}-${F}"
echo -n "$PROG: Backup $H $F --> ${O} ..."
curl -s -m ${MAXTIME} ${CURLARGS} "http://${H}/${F}" > "${O}"
if [[ -s "${O}" ]]
then
if grep -q "URI: /${F}" "${O}"
then
echo "Header only - removed"
rm "${O}"
else
echo " OK"
fi
else
echo "empty - removed"
rm "${O}"
fi
done
#
# We're done with this IP address. Rename to hostname if relevant ...
#
[[ ${NAME} != ${H} ]] && mv "${DATETIME}${H}.json" "${DATETIME}${NAME}.json"
done
if [[ -n "${ZIP}" ]]
then
echo "$PROG: Sending ZIP file $ZIP to $MAILTO ..."
dbgprint "PROG: Creating zip-file ${ZIP}.zip from ${PWD}"
zip -rq9 "${ZIP}" .
NFILES=$( ls -1 | wc -l )
cd "${HOME}"
rm -rf "/tmp/${PROG}-$$"
if [[ -n "${MAILTO}" ]]
then
dbgprint "Email to ${MAILTO}"
SUB="$PROG backup from $( hostname -s ) on $( date +%F ) (${#IPLIST[*]} nodes, ${NFILES} files)"
#mpack -s "${SUB}" "${ZIP}.zip" ${MAILTO}
echo -e "Backup file attached from ${#IPLIST[*]} nodes, total of ${NFILES} files\n\n" | \
mail -s "${SUB}" --content-type=application/zip -A "${ZIP}.zip" ${MAILTO}
fi
fi
# :tabSize=4:indentSize=4:noTabs=true
# vim:ts=4:sw=4

71
tools/espeasyconfig Executable file
View File

@@ -0,0 +1,71 @@
#!/bin/bash
PROG=$( basename $0 .sh )
TMP="/tmp/${PROG}-$$/"
[[ "$1" == "-r" ]] && REBOOTESP="Y" && shift
H="$1"; shift
FILE="$1"
if [[ $# -lt 1 ]] || [[ ! -r "${FILE}" ]]
then
echo "Usage: $PROG [-r] NameOrIP file [ file ... ]" >&2
exit 2
fi
#
# put CURLARGS='-u username:password' in ~/.espeasy
#
if [[ -r "${HOME}/.espeasy" ]]
then
source "${HOME}/.espeasy"
else
echo "$PROG: Cannot read ${HOME}/.espeasy" >&2
exit 1
fi
mkdir "${TMP}" || exit 2
for FILE in $*
do
for NAME in notification.dat security.dat config.dat rules1.txt rules2.txt rules3.txt rules4.txt esp.css
do
if [[ ${FILE} =~ "${NAME}" ]]
then
MATCH="${NAME}"
echo -n "$PROG: File name ${NAME}: "
cp -v "${FILE}" "${TMP}/${MATCH}"
break;
fi
done
[[ -z "${MATCH}" ]] && echo "$PROG: Cannot determine name of $FILE ... Skipping"
done
cd "${TMP}" || exit 2
for FILE in *
do
echo -n "Upload $FILE: "
if curl ${CURLARGS} --progress-bar -X POST -F "name=@${FILE}" -F "type=file" "http://${H}/upload" | grep -q "Upload OK"
then
echo "$PROG: $FILE upload OK "
else
echo "$PROG: $FILE upload FAILED" >&2
fi
done
if [[ -n "${REBOOTESP}" ]]
then
echo -n "Reboot: "
if curl ${CURLARGS} --progress-bar "http://${H}/?cmd=reboot" | grep -q '>OK'
then
echo "$PROG: Reboot OK "
else
echo "$PROG: Reboot FAILED" >&2
fi
fi
cd
#echo "$PROG: Please do a manual rm -rf $TMP"
rm -rf "${TMP}"
# vim:ts=4:sw=4

53
tools/espeasyupdate Executable file
View File

@@ -0,0 +1,53 @@
#!/bin/bash
PROG=$( basename $0 .sh )
[[ "$1" == "-f" ]] && FORCEUPDATE=1 && shift
[[ "$1" == "-n" ]] && NOUPDATE=1 && shift
[[ "$1" == "-f" ]] && FORCEUPDATE=1 && shift
FILE="$1"
FILEFW=$( echo ${FILE%.bi*} | sed 's/_20[[:digit:]]*//' )
FILEFW=$( basename ${FILEFW} )
if [[ $# -lt 1 ]] || [[ ! -r "${FILE}" ]]
then
echo "Usage: $PROG [-n|-f] filename NameOrIP [ NameOrIP ... ]" >&2
exit 2
fi
shift
#
# put CURLARGS='-u username:password' in ~/.espeasy - file readable only by user
#
if [[ -r "${HOME}/.espeasy" ]]
then
source "${HOME}/.espeasy"
fi
for H in $*
do
echo "$PROG: Updating $H ..."
VER=$( curl -s "http://${H}/json"| jq -r '.System."Git Build"' )
if [[ "${VER#Custom}" != "${VER}" ]]
then
if strings "${FILE}" | grep -q "^${VER}"
then
echo "$PROG: ${H} already has '${VER}'"
[ -z "${FORCEUPDATE}" ] && continue
fi
fi
DEVFW=$( curl -s "http://${H}/json"| jq -r '.System."Binary Filename"' )
[[ -n "${DEVFW}" ]] && DEVFW=$( sed 's/_20[[:digit:]]*//' <<< ${DEVFW} )
if [[ "${DEVFW}" != "${FILEFW}" ]]
then
echo "$PROG: Firmware on file (${FILEFW}) different from device (${DEVFW}). Use -f to force update."
[ -z "${FORCEUPDATE}" ] && continue
fi
if [ -n "${NOUPDATE}" ]
then
echo "curl ${CURLARGS} -X POST -F \"name=@${FILE}\" -F \"value=Update\" \"http://${H}/update\""
continue
fi
curl ${CURLARGS} -X POST -F "name=@${FILE}" -F "value=Update" "http://${H}/update"
done
# vim:ts=4:sw=4