diff --git a/tools/ESPEasy-tools.md b/tools/ESPEasy-tools.md new file mode 100644 index 000000000..54602e24c --- /dev/null +++ b/tools/ESPEasy-tools.md @@ -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
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/). diff --git a/tools/espeasybackup b/tools/espeasybackup new file mode 100755 index 000000000..d781935f0 --- /dev/null +++ b/tools/espeasybackup @@ -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 diff --git a/tools/espeasyconfig b/tools/espeasyconfig new file mode 100755 index 000000000..d58f4b8e4 --- /dev/null +++ b/tools/espeasyconfig @@ -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 + diff --git a/tools/espeasyupdate b/tools/espeasyupdate new file mode 100755 index 000000000..55824a5d0 --- /dev/null +++ b/tools/espeasyupdate @@ -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