From 99d9fa3b66d8f277278262c4437a00bd8b6036a6 Mon Sep 17 00:00:00 2001 From: proddy Date: Wed, 16 Sep 2020 10:08:56 +0200 Subject: [PATCH] updated README, removed docs --- README.md | 109 +++++++------------------------------------------ doc/MQTT.md | 55 ------------------------- doc/coding.md | 80 ------------------------------------ doc/console.md | 72 -------------------------------- 4 files changed, 14 insertions(+), 302 deletions(-) delete mode 100644 doc/MQTT.md delete mode 100644 doc/coding.md delete mode 100644 doc/console.md diff --git a/README.md b/README.md index 2299119c6..7654ade2c 100644 --- a/README.md +++ b/README.md @@ -19,22 +19,21 @@ If you like **EMS-ESP**, please give it a star, or fork it and contribute! [![GitHub forks](https://img.shields.io/github/forks/proddy/EMS-ESP.svg?style=social&label=Fork)](https://github.com/proddy/EMS-ESP/network) [![donate](https://img.shields.io/badge/donate-PayPal-blue.svg)](https://www.paypal.com/paypalme/prderbyshire/2) -Note, EMS-ESP requires a small hardware circuit that can convert the EMS bus data to be read by the microcontroller. These can be purchased at https://bbqkees-electronics.nl/. +Note, EMS-ESP requires a small hardware circuit that can convert the EMS bus data to be read by the microcontroller. These can be ordered at https://bbqkees-electronics.nl. --- -## **New Features in version 2** +## **Features** - Support for both ESP8266 and ESP32 modules -- A new multi-user Web interface (based on React/TypeScript) -- A new Console, accessible via Serial and Telnet -- Tighter security in both Web and Console. Admin privileges required to access core settings and commands. -- Support for Home Assistant MQTT Discovery (https://www.home-assistant.io/docs/mqtt/discovery/) +- A multi-user secure Web interface (based on React/TypeScript and Material-UI) +- A Console, accessible via Serial and Telnet +- Native support for Home Assistant [MQTT Discovery](https://www.home-assistant.io/docs/mqtt/discovery/) (in development) - Can be run standalone as an independent Access Point or join an existing WiFi network -- Easier first-time configuration via a web Captive Portal -- Supporting over 70 EMS devices (boilers, thermostats, solar modules, mixing modules, heat pumps, gateways) +- Easy first-time configuration via a web Captive Portal +- Supporting over [70 EMS](https://emsesp.github.io/docs/#/Supported-EMS-Devices) devices (boilers, thermostats, solar modules, mixing modules, heat pumps, gateways) ## **Screenshots** @@ -44,101 +43,21 @@ Note, EMS-ESP requires a small hardware circuit that can convert the EMS bus dat | | | -## **Migrating from versions 1.9** +## **Installing** -EMS-ESP will attempt to automatically migrate the 1.9 settings. +Refer to the [Wiki](https://emsesp.github.io/docs) articles to install the firmware. -Note there are some noticeable differences to be aware of in version 2: -### MQTT: - - MQTT base has been removed. All MQTT topics are prefixed with only the hostname, for example `ems-esp/status` as opposed to `home/ems-esp/status`. - - `heatPmp` renamed to `heatPump` - - `ServiceCodeNumber` renamed to `serviceCodeNumber` - - Firmware version has been moved to the `start` topic - - `desinfection` renamed to `disinfection` - -### General: - - There is no "serial mode" anymore like with version 1.9. When the Wifi cannot connect to the SSID it will automatically enter a "safe" mode where the Serial console is activated (note Serial is always available on the ESP32 because it has multiple UARTs). The EMS-ESP's LED will blink fast when in Serial mode. When this happens connect via a USB using baud 115200. - -If you run into issues try first erasing the ESP8266 with `esptool.py erase_flash` and uploading the new firmware manually. BBQKees has a good write-up at https://bbqkees-electronics.nl/wiki/gateway/firmware-update-to-v2.html. - -## **Building the firmware using PlatformIO** - -1. Install [PlatformIO](https://platformio.org/install) and [NodeJS](https://nodejs.org/en/). -2. Decide how you want to upload the firmware, via USB or OTA (Over The Air). OTA requires that a version of EMS-ESP is already running. -3. Create a new file called `pio_local.ini` and add these two lines for USB: -```yaml -upload_protocol = esptool -upload_port = -``` -or these 2 for OTA: -```yaml -upload_protocol = espota -upload_flags = - --port=8266 - --auth=ems-esp-neo -upload_port = ems-esp.local -``` -3. type `pio run -t upload` to build and upload the firmware - -## **Uploading the firmware** - -Here we'll use the command-line. You'll need [Python]( https://www.python.org/downloads/) (version 3) installed and these 2 scripts: - -- `esptool.py`. Install using `pip install esptool`. -- `espota.py` downloaded from https://github.com/esp8266/Arduino/blob/master/tools/espota.py - -Both these tools are also in the repo in the `scripts` directory. - -Next step is to fetch the latest firmware binary from https://github.com/proddy/EMS-ESP/releases, and if you're using USB with an ESP8266: - - `esptool.py -p -b 921600 write_flash 0x00000 ` - -and for OTA: - - `espota.py --debug --progress --port 8266 --auth ems-esp-neo -i -f ` - -## **Configuring EMS-ESP for the first time** - - - After powering up the ESP, watch the onboard blue LED. A solid light means good connection and EMS data is coming in. A slow pulse means either the WiFi or the EMS bus is not connected yet. A very fast pulse is when the system is booting up and configuring itself which typically takes 5 seconds. - - - Connect to the Access Point called `ems-esp` using the WPA password `ems-esp-neo`. When you see the captive portal sign-in with username `admin` and password `admin`. Set the WiFi credentials and go back to http://ems-esp. Remember to change the passwords! - - - First thing to check is if Tx is working and that you have a connection to the EMS bus. If Tx fails are shown in the Web interface try changing the Tx Mode from the settings page. There is no need to re-start the EMS-ESP. - - - If Rx incomplete telegrams are reported in the Web interface, don't panic. Some telegrams can be missed and this is usually caused by noise interference on the line. - -## **Using the Console** - -Connecting to the console will give you more insight into the EMS bus traffic, MQTT queues and the full device information. - -The console is reachable via Telnet (port 22) or via the Serial port if using an USB (on baud 115200). To change any settings in the console you must be admin (use `su` with the default password `ems-esp-neo`). - -Some of the most common commands are: - * `help` lists the commands and keywords. This works in each context. - * `exit` will exit the console or exit the current context. `CTRL-D` does the same. - * `CTRL-U` for Undo - * `` for auto-complete - * Some specific commands are behind contexts. Think of this as a sub-menu. e.g. `system`, `thermostat`. The path will always show you which context you are in. `$` is the root. - * `su` will switch to the Admin super-user. The default password is `ems-esp-neo` and can be changed with `passwd` from the system menu or via the Web interface (called secret password). When in Admin mode the command prompt switches from `$` to `#`. - * Some settings can be changed in the console. The `set` command will list them. - * `show` shows the data specific to the which context you're in. From the root it will show you all the EMS device information and any external temperature sensors. - * `log` sets the logging level. `log off` disables logging. Use `log debug` for debugging commands and actions. This will be reset next time the console is opened. - * `watch` will output the incoming Rx telegrams directly to the console. You can also put on a watch on a specific EMS device ID or telegram ID. Also choose to output as verbose text as raw data bytes. - -The `call` command is to execute a command. The command names (`[cmd]`) are the same as the MQTT commands used in MQTT. - -For further details please refer to the [Wiki](https://emsesp.github.io/docs) and [BBQKees's gateway Wiki](https://bbqkees-electronics.nl/wiki/). +* [Uploading a pre-built binary](https://emsesp.github.io/docs/#/Uploading-firmware) +* [Building the firmware and flashing manually](https://emsesp.github.io/docs/#/Building-firmware) ## **Support Information** -For a list of the EMS devices currently supported see BBQKees's [EMS device compatibility list](https://bbqkees-electronics.nl/ems-device-compatibility/). - If you're looking for support on **EMS-ESP** there are some options available: ### Documentation * [Documentation Site](https://emsesp.github.io/docs): For information on how to build and upload the firmware -* [FAQ and Troubleshooting](https://bbqkees-electronics.nl/wiki/gateway/troubleshooting.html): For information on common problems and solutions +* [FAQ and Troubleshooting](https://emsesp.github.io/docs/#/Troubleshooting): For information on common problems and solutions. See also [BBQKees's site](https://bbqkees-electronics.nl/wiki/gateway/troubleshooting.html) ### Support's Community @@ -151,7 +70,7 @@ If you're looking for support on **EMS-ESP** there are some options available: * [Feature Request](https://github.com/proddy/EMS-ESP/issues/new?template=feature_request.md): For requesting features/functions * [Troubleshooting](https://github.com/proddy/EMS-ESP/issues/new?template=questions---troubleshooting.md): As a last resort, you can open new *Troubleshooting & Question* issue on GitHub if the solution could not be found using the other channels. Just remember: the more info you provide the more chances you'll have to get an accurate answer -## **Contribute** +## **Contributing** You can contribute to EMS-ESP by - providing Pull Requests (Features, Fixes, suggestions) @@ -162,7 +81,7 @@ You can contribute to EMS-ESP by A shout out to the people helping EMS-ESP get to where it is today - @MichaelDvP for all his amazing contributions and patience. The core UART code is his. -- @BBQkees for his endless testing and building the awesome circuits +- @BBQKees for his endless testing and building the awesome circuits - @susisstrolch for writing a first working version of the EMS bridge circuit which I used to design EMS-ESP version 0.1 - Plus many more providing suggestions, PRs and Donations. Thanks! diff --git a/doc/MQTT.md b/doc/MQTT.md deleted file mode 100644 index df9fc432c..000000000 --- a/doc/MQTT.md +++ /dev/null @@ -1,55 +0,0 @@ -# **MQTT commands** - -All commands must be written as `{"cmd": ,"data":, "id":}`. - -The `id` can be replaced with `hc` for some devices that use heating circuits, and represented either as a string or a number. `cmd` is a string, `data` can be a string or number. - -topic = *boiler_cmd* -``` - comfort - flowtemp - wwtemp - boilhyston (negative value) - boilhystoff (positive value) - burnperiod - burnminpower <%> - burnmaxpower <%> - pumpdelay -``` - -topic = *thermostat_cmd* -``` ---- without hc --- - wwmode - calinttemp - minexttemp - building - language (0=de, 1=nl, 2=fr, 3=it) only RC30 - display (0=int temp, 1= int set, 2=ext. temp, 3=burner, 4=ww, 5=mode, 6=time, 7=date, 8=smoke) only RC30 - clockoffset (only RC30) - ---- with hc --- - mode - temp - nighttemp - daytemp - nofrosttemp - ecotemp - heattemp - summertemp - designtemp - offsettemp - holidaytemp - remotetemp - control <0 | 1 | 2> - pause - party - holiday - date -``` - -topic = *system_cmd* -``` - send <"0B XX XX .."> - pin -``` \ No newline at end of file diff --git a/doc/coding.md b/doc/coding.md deleted file mode 100644 index b0a4c13ae..000000000 --- a/doc/coding.md +++ /dev/null @@ -1,80 +0,0 @@ -# Notes on customizing the code - -## **Basic Design Principles** - -- The core services like telnet, logging and shell are based off the libraries from @nomis. I also adopted his general design pattens such as making everything as asynchronous as possible so that no one operation should starve another operation of it's time to execute (https://isocpp.org/wiki/faq/ctors#static-init-order). -- All EMS devices (e.g. boiler, thermostat, solar modules, mixing units etc) are derived from a factory base class and each class handles its own registering of telegram and mqtt handlers. This makes the EMS device code easier to manage and we can extend with new telegrams types and features. -- For debugging there is an offline mode where the code can be compiled and executed standalone without uploading to an ESP controller. Use `make` (based off GNUMakefile). - -## **Customizing the Web UI** - -The Web is based off Rick's awesome [esp8266-react](https://github.com/rjwats/esp8266-react/) framework. These are the files that are modified: - -**`interface:`** - * `.env` project name and project path to ems-esp - * `.env.development` CORS URL - -**`interface/public:`** - * `app/manifest.json` ems-esp name - * `index.html` ems-esp name - * `app/icon.png` 256x256 PNG - * `favicon.ico` replaced - -**`interface/src:`** - * `CustomMuiTheme.tsx` colors for dark mode - * `interface/src/wifi/WifiSettingsController.tsx` rename esp8266-react - -**`interface/src/project:`** - * `ProjectRouting.tsx` removed demo, added paths to ems-esp/status, ems-esp/settings and * - * `DemoProject.tsx` remove /demo/ and changed title, renamed to EMSESP.tsx - * `ProjectMenu.tsx` title change, added /ems-esp/settings - * `DemoInformation.tsx` removed file - * `types.ts` add variables - * added all custom files starting with EMSESP* - -**`interface/src/mqtt:`** - * `types.ts` added mqtt_fails - * `MqttStatusForm.tsx` added MQTT Publish Errors - * `MqttStatus.ts` added function mqttPublishHighlight - * `MqttSettingsForm.tsx` added publish time, qos, format - -**`interface/src/authentication:`** - * `AuthenticationWrapper.tsx` commented out features.security because we added version - * `AuthenticationContext.tsx` added version - * `MqttSettingsForm.tsx` added publish time, qos, format - -**`interface/src/components:`** - * `MenuAppBar.tsx` added version to toolbar - -**`interface/src/system:`** - * `types.ts` added uptime and free_mem - * `SystemStatusForm.tsx` added system uptime, % free mem - -**`lib/framework`:** - * `SystemStatus.h` added #include , #include , #include "../../src/system.h" - * `SystemStatus.cpp` added LittleFS.info(fs_info); root["uptime"], root["free_mem"] - * Commented out all `Serial.print`'s in all files - * `MqttStatus.h` added #include "../../src/mqtt.h" - * `MqttStatus.cpp` added root["mqtt_fails"] - * `SecuritySettingsService.cpp` added version to the JWT payload - * `SecuritySettingsService.h` #include "../../src/version.h" - * `WiFiSettingsService.cpp` added WiFi.setOutputPower(20.0f), moved setHostname - * `OTASettingsService.h` added #include "../../src/system.h" - * `OTASettingsService.cpp` added call to emsesp::System::upload_status(true) - * `features.ini`: -D FT_NTP=0 - * `platformio.ini` using our own version - * `factory_settings.ini` modified with `ems-esp-neo` as password and `ems-esp` everywhere else - - -## To develop and test the Web UI -- uncomment the `-D ENABLE_CORS` in `platformio.ini` -```sh -cd interface -npm start -``` - -## To test the core, standalone with an ESP - -```sh -make run -``` diff --git a/doc/console.md b/doc/console.md deleted file mode 100644 index d4105c3d1..000000000 --- a/doc/console.md +++ /dev/null @@ -1,72 +0,0 @@ -# **Console commands** - - -Connecting to the console will give you more insight into the EMS bus traffic, MQTT queues and the full device information. - -The console is reachable via Telnet (port 22) or via the Serial port if using an USB (on baud 115200). To change any settings in the console you must be admin (use `su` with the default password `ems-esp-neo`). - -Some of the most common commands are: - * `help` lists the commands and keywords. This works in each context. - * `exit` will exit the console or exit the current context. `CTRL-D` does the same. - * `CTRL-U` for Undo - * `` for auto-complete - * Some specific commands are behind contexts. Think of this as a sub-menu. e.g. `system`, `thermostat`. The path will always show you which context you are in. `$` is the root. - * `su` will switch to the Admin super-user. The default password is `ems-esp-neo` and can be changed with `passwd` from the system menu or via the Web interface (called secret password). When in Admin mode the command prompt switches from `$` to `#`. - * Some settings can be changed in the console. The `set` command will list them. - * `show` shows the data specific to the which context you're in. From the root it will show you all the EMS device information and any external temperature sensors. - * `log` sets the logging level. `log off` disables logging. Use `log debug` for debugging commands and actions. This will be reset next time the console is opened. - * `watch` will output the incoming Rx telegrams directly to the console. You can also put on a watch on a specific EMS device ID or telegram ID. Also choose to output as verbose text as raw data bytes. - -The `call` command is to execute a command. The command names (`[cmd]`) are the same as the MQTT commands used in MQTT. - -``` -(* = available in su/Admin mode) - -common commands available in all contexts: - exit - help - log [level] - watch [ID] - su - -(from the root) - system (enters a context) - boiler (enters a context) - thermostat (enters a context) - set - fetch - scan devices [deep] * - send telegram <"XX XX ..."> * - set bus_id * - set tx_mode * - show - show devices - show ems - show values - show mqtt - read * - -system - set - show - format * - show users * - passwd * - restart * - set wifi hostname * - set wifi password * - set wifi ssid * - wifi reconnect * - pin [data] * - -boiler - read * - call [cmd] [data] * - -thermostat - set - set master [device ID] * - read * - call [cmd] [data] [heating circuit] * - -``` \ No newline at end of file