diff --git a/README.md b/README.md index c3d48776b..eb5a941f9 100644 --- a/README.md +++ b/README.md @@ -15,17 +15,24 @@ It was the goal to replace the original Hoymiles DTU (Telemetry Gateway) with th ## Documentation -Currently the documentation is separated into different locations (this README.md, the `doc` folder and the [Wiki](https://github.com/tbnobody/OpenDTU/wiki)). -This is not very nice and it's planned to move everything into the [Wiki](https://github.com/tbnobody/OpenDTU/wiki). +The documentation can be found [here](https://tbnobody.github.io/OpenDTU-docs/). +Please feel free to support and create a PR in [this](https://github.com/tbnobody/OpenDTU-docs) repository to make the documentation even better. -## Screenshots - -Several screenshots of the frontend can be found here: [Screenshots](docs/screenshots/README.md) +## Breaking changes -## Builds +Generated using: `git log --date=short --pretty=format:"* %h%x09%ad%x09%s" | grep BREAKING` -Different builds from existing installations can be found here [Builds](docs/builds/README.md) -Like to show your own build? Just send me a Pull Request. +```code +* 71d1b3b 2023-11-07 BREAKING CHANGE: Home Assistant Auto Discovery to new naming scheme +* 04f62e0 2023-04-20 BREAKING CHANGE: Web API Endpoint /api/eventlog/status no nested serial object +* 59f43a8 2023-04-17 BREAKING CHANGE: Web API Endpoint /api/devinfo/status requires GET parameter inv= +* 318136d 2023-03-15 BREAKING CHANGE: Updated partition table: Make sure you have a configuration backup and completly reflash the device! +* 3b7aef6 2023-02-13 BREAKING CHANGE: Web API! +* d4c838a 2023-02-06 BREAKING CHANGE: Prometheus API! +* daf847e 2022-11-14 BREAKING CHANGE: Removed deprecated config parsing method +* 69b675b 2022-11-01 BREAKING CHANGE: Structure WebAPI /api/livedata/status changed +* 27ed4e3 2022-10-31 BREAKING: Change power factor from percent value to value between 0 and 1 +``` ## Currently supported Inverters @@ -65,60 +72,7 @@ Like to show your own build? Just send me a Pull Request. | TSUN TSOL-M800 | NRF24L01+ | 2 | 2 | 1 | | TSUN TSOL-M1600 | NRF24L01+ | 4 | 2 | 1 | -**TSUN compatibility remark:** -Compatibility with OpenDTU is most likly related to the serial number of the inverter. Current findings indicate that TSUN inverters with a serial number starting with "11" are supported, whereby inverters with a serial number starting with "10" are not. - -**Hoymiles HMS-xxxx-xT-NA compatibility remark:** -Currently it seems not to be possible to change the communication frequency of the "-NA" inverters. Please set the communication freuqency to 915MHz to get these inverters working. - -## Features for end users - -* Read live data from inverter -* Show inverters internal event log -* Show inverter information like firmware version, firmware build date, hardware revision and hardware version -* Show and set the current inverter limit -* Function to turn the inverter off and on -* Uses ESP32 microcontroller and NRF24L01+ -* Multi-Inverter support -* MQTT support (with TLS) -* Home Assistant MQTT Auto Discovery support -* Nice and fancy WebApp with visualization of current data -* Firmware upgrade using the web UI -* Default source supports up to 10 inverters -* Time zone support -* Ethernet support -* Prometheus API endpoint (/api/prometheus/metrics) -* English, german and french web interface -* Displays (SSD1306, SH1106, PCD8544) -* Status LEDs -* Configuration management (export / import configurations) -* Dark Theme - -## Features for developers - -* The microcontroller part - * Build with Arduino PlatformIO Framework for the ESP32 - * Uses a fork of [ESPAsyncWebserver](https://github.com/yubox-node-org/ESPAsyncWebServer) and [espMqttClient](https://github.com/bertmelis/espMqttClient) -* The WebApp part - * Build with [Vue.js](https://vuejs.org) - * Source is written in TypeScript - -## Breaking changes - -Generated using: `git log --date=short --pretty=format:"* %h%x09%ad%x09%s" | grep BREAKING` - -```code -* 71d1b3b 2023-11-07 BREAKING CHANGE: Home Assistant Auto Discovery to new naming scheme -* 04f62e0 2023-04-20 BREAKING CHANGE: Web API Endpoint /api/eventlog/status no nested serial object -* 59f43a8 2023-04-17 BREAKING CHANGE: Web API Endpoint /api/devinfo/status requires GET parameter inv= -* 318136d 2023-03-15 BREAKING CHANGE: Updated partition table: Make sure you have a configuration backup and completly reflash the device! -* 3b7aef6 2023-02-13 BREAKING CHANGE: Web API! -* d4c838a 2023-02-06 BREAKING CHANGE: Prometheus API! -* daf847e 2022-11-14 BREAKING CHANGE: Removed deprecated config parsing method -* 69b675b 2022-11-01 BREAKING CHANGE: Structure WebAPI /api/livedata/status changed -* 27ed4e3 2022-10-31 BREAKING: Change power factor from percent value to value between 0 and 1 -``` ## Hardware you need @@ -132,47 +86,6 @@ Sample Picture: Also supported: Board with Ethernet-Connector and Power-over-Ethernet [Olimex ESP32-POE](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE/open-source-hardware) -### NRF24L01+ radio board (See inverter table above for supported inverters) - -The PLUS sign is IMPORTANT! There are different variants available, with antenna on the printed circuit board or external antenna. - -Sample picture: - -![nrf24l01plus](docs/nrf24l01plus.png) - -Buy your hardware from a trusted source, at best from a dealer/online shop in your country where you have support and the right to return non-functional hardware. -When you want to buy from Amazon, AliExpress, eBay etc., take note that there is a lot of low-quality or fake hardware offered. Read customer comments and ratings carefully! - -A heavily incomplete list of trusted hardware shops in germany is: - -* [AZ-Delivery](https://www.az-delivery.de/) -* [Makershop](https://www.makershop.de/) -* [Berrybase](https://www.berrybase.de/) - -This list is for your convenience only, the project is not related to any of these shops. - -### CMT2300A radio board (See inverter table above for supported inverters) - -It is important to get a module which supports SPI communicatiton. The following modules are currently supported: - -* EBYTE E49-900M20S - -The CMT2300A uses 3-Wire half duplex SPI communication. Due to this fact it currently requires a separate SPI bus. If you want to run the CMT2300A module on the same ESP32 as a NRF24L01+ module or a PCD8544 display make sure you get a ESP which supports 2 SPI busses. Currently the SPI bus host is hardcoded to number 2. This may change in future. - -### Power supply - -Use a power suppy with 5 V and 1 A. The USB cable connected to your PC/Notebook may be powerful enough or may be not. - -## Wiring up the NRF24L01+ module - -### Schematic - -![Schematic](docs/Wiring_ESP32_Schematic.png) - -### Symbolic view - -![Symbolic](docs/Wiring_ESP32_Symbol.png) - ### Change pin assignment Its possible to change all the pins of the NRF24L01+ module, the Display, the LED etc. @@ -189,160 +102,3 @@ It is also possible to create a custom environment and compile the source yourse ``` It is recommended to make all changes only in the 'platformio_override.ini', this is your personal copy. - -## Flashing and starting up - -### with Visual Studio Code - -* Install [Visual Studio Code](https://code.visualstudio.com/download) (from now named "vscode") -* In Visual Studio Code, install the [PlatformIO Extension](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide) -* Install git and enable git in vscode - [git download](https://git-scm.com/downloads/) - [Instructions](https://www.jcchouinard.com/install-git-in-vscode/) -* Clone this repository (you really have to clone it, don't just download the ZIP file. During the build process the git hash gets embedded into the firmware. If you download the ZIP file a build error will occur): Inside vscode open the command palette by pressing `CTRL` + `SHIFT` + `P`. Enter `git clone`, add the repository-URL `https://github.com/tbnobody/OpenDTU`. Next you have to choose (or create) a target directory. -* In vscode, choose File --> Open Folder and select the previously downloaded source code. (You have to select the folder which contains the "platformio.ini" and "platformio_override.ini" file) -* Adjust the COM port in the file "platformio_override.ini" for your USB-to-serial-converter. It occurs twice: - * upload_port - * monitor_port -* Select the arrow button in the blue bottom status bar (PlatformIO: Upload) to compile and upload the firmware. During the compilation, all required libraries are downloaded automatically. -* Under Linux, if the upload fails with error messages "Could not open /dev/ttyUSB0, the port doesn't exist", you can check via ```ls -la /dev/tty*``` to which group your port belongs to, and then add your user this group via ```sudo adduser dialout``` (if you are using ```arch-linux``` use: ```sudo gpasswd -a uucp```, this method requires a logout/login of the affected user). -* There are two videos showing these steps: - * [Git Clone and compilation](https://youtu.be/9cA_esv3zeA) - * [Full installation and compilation](https://youtu.be/xs6TqHn7QWM) - -### on the commandline with PlatformIO Core - -* Install [PlatformIO Core](https://platformio.org/install/cli) -* Clone this repository (you really have to clone it, don't just download the ZIP file. During the build process the git hash gets embedded into the firmware. If you download the ZIP file a build error will occur) -* Adjust the COM port in the file "platformio_override.ini". It occurs twice: - * upload_port - * monitor_port -* build: `platformio run -e generic` -* upload to esp module: `platformio run -e generic -t upload` -* other options: - * clean the sources: `platformio run -e generic -t clean` - * erase flash: `platformio run -e generic -t erase` - -### using the pre-compiled .bin files - -The pre-compiled binary files can be found here on the [github page behind "Releases"](https://github.com/tbnobody/OpenDTU/releases) (look at the right column). For a first installation on an ESP32, download `opendtu-generic.factory.bin` and use a ESP32 flash tool of your choice to flash the `.bin` file to the address `0x0`. (The previous method with different .bin files is no more necessary.) - -For further updates download `opendtu-generic.bin` and use the over-the-air firmware update in OpenDTU's web interface. - -#### Flash with esptool.py (Linux) - -```bash -esptool.py --port /dev/ttyUSB0 --chip esp32 --before default_reset --after hard_reset \ - write_flash --flash_mode dout --flash_freq 40m --flash_size detect \ - 0x0 opendtu-generic.factory.bin -``` - -#### Flash with Espressif Flash Download Tool (Windows) - -[Download link](https://www.espressif.com/en/support/download/other-tools) - -* On startup, select Chip Type -> "ESP32" / WorkMode -> "Develop" -* Prepare all settings (see picture). Make sure to uncheck the `DoNotChgBin` option. Otherwise you may get errors like "invalid header". -* ![flash tool image](docs/esp32_flash_download_tool.png) -* Press "Erase" button on screen. Look into the terminal window, you should see dots appear. Then press the "Boot" button on the ESP32 board. Wait for "FINISH" to see if flashing/erasing is done. -* To program, press "Start" on screen, then the "Boot" button. -* When flashing is complete (FINISH appears) then press the Reset button on the ESP32 board (or powercycle ) to start the OpenDTU application. - -#### Flash with ESP_Flasher (Windows) - -Users report that [ESP_Flasher](https://github.com/Jason2866/ESP_Flasher/releases/) is suitable for flashing OpenDTU on Windows. - -#### Flash with [ESP_Flasher](https://espressif.github.io/esptool-js/) - web version - -It is also possible to flash it via the web tools which might be more convenient and is platform independent. - -## First configuration - -* After the initial flashing of the microcontroller, an Access Point called "OpenDTU-*" is opened. The default password is "openDTU42". -* Use a web browser to open the address [http://192.168.4.1](http://192.168.4.1) -* Navigate to Settings --> Network Settings and enter your WiFi credentials. The username to access the config menu is "admin" and the password the same as for accessing the Access Point (default: "openDTU42"). -* OpenDTU then simultaneously connects to your WiFi AP with these credentials. Navigate to Info --> Network and look into section "Network Interface (Station)" for the IP address received via DHCP. -* If your WiFi AP uses an allow-list for MAC-addresses, please be aware that the ESP32 has two different MAC addresses for its AP and client modes, they are also listed at Info --> Network. -* When OpenDTU is connected to a configured WiFI AP, the "OpenDTU-*" Access Point is closed after 3 minutes. -* OpenDTU needs access to a working NTP server to get the current date & time. Both are sent to the inverter with each request. Default NTP server is pool.ntp.org. If your network has different requirements please change accordingly (Settings --> NTP Settings). -* Add your inverter in the inverter settings (Settings --> Inverter Settings) - -## Flashing an Update using "Over The Air" OTA Update - -Once you have your OpenDTU running and connected to WLAN, you can do further updates through the web interface. -Navigate to Settings --> Firmware upgrade and press the browse button. Select the firmware file from your local computer. - -You'll find the firmware file (after a successful build process) under `.pio/build/generic/firmware.bin`. - -If you downloaded a precompiled zip archive, unpack it and choose `opendtu-generic.bin`. - -After the successful upload, the OpenDTU immediately restarts into the new firmware. - -## MQTT Topic Documentation - -A documentation of all available MQTT Topics can be found here: [MQTT Documentation](docs/MQTT_Topics.md) - -## Web API Documentation - -A documentation of the Web API can be found here: [Web-API Documentation](docs/Web-API.md) - -## OpenDTU Breakoutboard - -We sat down together and designed a PCB. This is 100% compatible with openDTU and has space for all extensions such as display and LEDs. You can find the PCB design here: - -A ready to solder kit can be found here: - -OpenDTU Breakout Board with CaseOpenDTU Breakout Board with Case - -## Available cases - -* -* -* -* -* -* -* - -## Available layouts for printed circuit boards - -* [BreakoutBoard - sample printed circuit board for OpenDTU and Ahoy](https://github.com/dokuhn/openDTU-BreakoutBoard) -* [Board for OpenDTU with Display](https://github.com/SteffMUC/openDTU_wDisplay2) -* [OpenDTU PCB mit Display](https://github.com/turrican944/OpenDTU-PCB) -* [PCB for OpenDTU in Cable Branchbox](https://github.com/plewka/ESP-Solar_OpenDTU) - -## Building - -* Building the WebApp - * The WebApp can be build using yarn - - ```bash - cd webapp - yarn install - yarn build - ``` - - * The updated output is placed in the 'webapp_dist' directory - * It is only necessary to build the webapp when you made changes to it -* Building the microcontroller firmware - * Visual Studio Code with the PlatformIO Extension is required for building - -## Troubleshooting - -* First: When there is no light on the solar panels, the inverter completely turns off and does not answer to OpenDTU! So if you assembled your OpenDTU in the evening, wait until tomorrow. -* When there is no data received from the inverter(s) - try to reduce the distance between the openDTU and the inverter (e.g. move it to the window towards the roof) -* Under Settings -> DTU Settings you can increase the transmit power "PA level". Default is "minimum". -* The NRF24L01+ needs relatively much current. With bad power supply (and especially bad cables!) a 10 µF capacitor soldered directly to the NRF24L01+ board connector brings more stability (pin 1+2 are the power supply). Note the polarity of the capacitor… -* You can try to use an USB power supply with 1 A or more instead of connecting the ESP32 to the computer. -* Try a different USB cable. Once again, a stable power source is important. Some USB cables are made of much plastic and very little copper inside. -* Double check that you have a radio module NRF24L01+ with a plus sign at the end. NRF24L01 module without the plus are not compatible with this project. -* There is no possibility of auto-discovering the inverters. Double check you have entered the serial numbers of the inverters correctly. -* OpenDTU needs access to a working NTP server to get the current date & time. -* If your problem persists, check the [Issues on Github](https://github.com/tbnobody/OpenDTU/issues). Please inspect not only the open issues, also the closed issues contain useful information. -* Another source of information are the [Discussions](https://github.com/tbnobody/OpenDTU/discussions/) -* When flashing with VSCode Plattform.IO fails and also with ESPRESSIF tool a demo bin file cannot be flashed to the ESP32 with error message "A fatal error occurred: MD5 of file does not match data in flash!" than un-wire/unconnect ESP32 from the NRF24L01+ board. Try to flash again and rewire afterwards. -* Make sure to connect one inverter only to one DTU (Original, Ahoy, OpenDTU doesn't make a difference). If you query a inverter by multiple DTUs you will get strange peaks in your values. - -## Related Projects - -* [Ahoy](https://github.com/grindylow/ahoy) -* [DTU Simulator](https://github.com/Ziyatoe/DTUsimMI1x00-Hoymiles) -* [OpenDTU extended to talk to Victrons MPPT battery chargers (Ve.Direct)](https://github.com/helgeerbe/OpenDTU_VeDirect) diff --git a/docs/DeviceProfiles.md b/docs/DeviceProfiles.md index 5e4a708a0..fd19199e1 100644 --- a/docs/DeviceProfiles.md +++ b/docs/DeviceProfiles.md @@ -1,113 +1,3 @@ # Device Profiles -It is possible to change hardware settings like pin assignments or ethernet support using a json file. The json file can be uploaded using the configuration management in the web interface. Just select "Pin Mapping (pin_mapping.json)" in the recovery section. - -When the file is uploaded the ESP performs a reboot. This is required as the pin settings could have changed within the file. By default all the pin assignments are used as compiled into the firmware. - -To change the device profile, navigate to the "Device Manager" and selected the appropriate profile. You can see the current (Active) and the new (Selected) in assignment in the table below the combobox. - -## Structure of the json file - -```json -[ - { - "name": "Generic NodeMCU 38 pin", - "nrf24": { - "miso": 19, - "mosi": 23, - "clk": 18, - "irq": 16, - "en": 4, - "cs": 5 - }, - "eth": { - "enabled": false, - "phy_addr": -1, - "power": -1, - "mdc": -1, - "mdio": -1, - "type": -1, - "clk_mode": -1 - } - }, - { - "name": "Generic NodeMCU 38 pin with SSD1306", - "nrf24": { - "miso": 19, - "mosi": 23, - "clk": 18, - "irq": 16, - "en": 4, - "cs": 5 - }, - "eth": { - "enabled": false, - "phy_addr": -1, - "power": -1, - "mdc": -1, - "mdio": -1, - "type": -1, - "clk_mode": -1 - }, - "display": { - "type": 2, - "data": 21, - "clk": 22 - } - }, - { - "name": "Olimex ESP32-POE", - "nrf24": { - "miso": 15, - "mosi": 2, - "clk": 14, - "irq": 13, - "en": 16, - "cs": 5 - }, - "eth": { - "enabled": true, - "phy_addr": 0, - "power": 12, - "mdc": 23, - "mdio": 18, - "type": 0, - "clk_mode": 3 - } - } -] -``` - -The json file can contain multiple profiles. Each profile requires a name and different parameters. If one parameter is not set, the default value, as compiled into the firmware is used. The example above shows all the currently supported values. Others may follow. Sample files for some boards can be found [here](DeviceProfiles/). This means you can just flash the generic bin file and upload the json file. Then you select your board and everything works hopyfully as expected. - -## Implemented configuration values - -| Parameter | Data Type | Description | -| ------------- | --------- | ----------- | -| name | string | Unique name of the profile (max 63 characters) | -| nrf24.miso | number | MISO Pin | -| nrf24.mosi | number | MOSI Pin | -| nrf24.clk | number | Clock Pin | -| nrf24.irq | number | Interrupt Pin | -| nrf24.en | number | Enable Pin | -| nrf24.cs | number | Chip Select Pin | -| cmt.sdio | number | SDIO Pin | -| cmt.clk | number | CLK Pin | -| cmt.cs | number | CS Pin | -| cmt.fcs | number | FCS Pin | -| cmt.gpio2 | number | GPIO2 Pin (optional) | -| cmt.gpio3 | number | GPIO3 Pin (optional) | -| eth.enabled | boolean | Enable/Disable the ethernet stack | -| eth.phy_addr | number | Unique PHY addr | -| eth.power | number | Power Pin (if available). Use -1 for not assigned pins. | -| eth.mdc | number | Serial Management Interface MDC Pin. Use -1 for not assigned pins. | -| eth.mdio | number | Serial Management Interface MDIO Pin. Use -1 for not assigned pins. | -| eth.type | number | Possible values:
* 0 = ETH_PHY_LAN8720
* 1 = ETH_PHY_TLK110
* 2 = ETH_PHY_RTL8201
* 3 = ETH_PHY_DP83848
* 4 = ETH_PHY_DM9051
* 5 = ETH_PHY_KSZ8041
* 6 = ETH_PHY_KSZ8081 | -| eth.clk_mode | number | Possible values:
* 0 = ETH_CLOCK_GPIO0_IN
* 1 = ETH_CLOCK_GPIO0_OUT
* 2 = ETH_CLOCK_GPIO16_OUT
* 3 = ETH_CLOCK_GPIO17_OUT | -| display.type | number | Specify type of display. Possible values:
* 0 = None (default)
* 1 = PCD8544
* 2 = SSD1306
* 3 = SH1106 | -| display.data | number | Data Pin (e.g. SDA for i2c displays) required for all displays. Use 255 for not assigned pins. | -| display.clk | number | Clock Pin (e.g. SCL for i2c displays) required for SSD1306 and SH1106. Use 255 for not assigned pins. | -| display.cs | number | Chip Select Pin required for PCD8544. Use 255 for not assigned pins. | -| display.reset | number | Reset Pin required for PCD8544, optional for all other displays. Use 255 for not assigned pins. | -| led.led0 | number | LED pin for network indication. Blinking = WLAN connected but NTP & MQTT (if enabled) disconnected. On = WLAN, NTP, MQTT connected. Off = Network not connected | -| led.led1 | number | LED pin for inverter indication. On = All inverters reachable & producing. Blinking = All inverters reachable but not producing. Off = At least one inverter is not reachable. Only inverters with polling enabled are considered. | +This documentation will has been moved and can be found here: diff --git a/docs/MQTT_Topics.md b/docs/MQTT_Topics.md index 204916f7d..e9925f874 100644 --- a/docs/MQTT_Topics.md +++ b/docs/MQTT_Topics.md @@ -1,88 +1,3 @@ # MQTT Topics -The base topic, as configured in the web GUI is prepended to all follwing topics. - -## General topics - -| Topic | R / W | Description | Value / Unit | -| --------------------------------------- | ----- | ---------------------------------------------------- | -------------------------- | -| dtu/ip | R | IP address of OpenDTU | IP address | -| dtu/hostname | R | Current hostname of the dtu (as set in web GUI) | | -| dtu/rssi | R | WiFi network quality | db value | -| dtu/status | R | Indicates whether OpenDTU network is reachable | online / offline | -| dtu/uptime | R | Time in seconds since startup | seconds | - -## Inverter total topics - -Enabled inverter means, that only inverters with "Poll inverter data" enabled are considered. - -| Topic | R / W | Description | Value / Unit | -| --------------------------------------- | ----- | ---------------------------------------------------- | -------------------------- | -| ac/power | R | Sum of AC active power of all enabled inverters | W | -| ac/yieldtotal | R | Sum of energy converted to AC since reset watt hours of all enabled inverters | Kilo watt hours (kWh) | -| ac/yieldday | R | Sum of energy converted to AC per day in watt hours of all enabled inverters | Watt hours (Wh) -| ac/is_valid | R | Indicator whether all enabled inverters where reachable | 0 or 1 | -| dc/power | R | Sum of DC power of all enabled inverters | Watt (W) | -| dc/irradiation | R | Produced power of all enabled inverter stripes with defined irradiation settings divided by sum of all enabled inverters irradiation | % | -| dc/is_valid | R | Indicator whether all enabled inverters where reachable | 0 or 1 | - -## Inverter specific topics - -serial will be replaced with the serial number of the inverter. - -| Topic | R / W | Description | Value / Unit | -| --------------------------------------- | ----- | ---------------------------------------------------- | -------------------------- | -| [serial]/name | R | Name of the inverter as configured in web GUI | | -| [serial]/device/bootloaderversion | R | Bootloader version of the inverter | | -| [serial]/device/fwbuildversion | R | Firmware version of the inverter | | -| [serial]/device/fwbuilddatetime | R | Build date / time of inverter firmware | | -| [serial]/device/hwpartnumber | R | Hardware part number of the inverter | | -| [serial]/device/hwversion | R | Hardware version of the inverter | | -| [serial]/status/reachable | R | Indicates whether the inverter is reachable | 0 or 1 | -| [serial]/status/producing | R | Indicates whether the inverter is producing AC power | 0 or 1 | -| [serial]/status/last_update | R | Unix timestamp of last inverter statistics udpate | seconds since JAN 01 1970 (UTC) | - -### AC channel / global specific topics - -| Topic | R / W | Description | Value / Unit | -| --------------------------------------- | ----- | ---------------------------------------------------- | -------------------------- | -| [serial]/0/current | R | AC current in ampere | Ampere (A) | -| [serial]/0/efficiency | R | Ratio AC Power over DC Power in percent | % | -| [serial]/0/frequency | R | AC frequency in hertz | Hertz (Hz) | -| [serial]/0/power | R | AC active power in watts | Watt (W) | -| [serial]/0/powerdc | R | DC power in watts | Watt (W) | -| [serial]/0/powerfactor | R | Power factor in percent | % | -| [serial]/0/reactivepower | R | AC reactive power in VAr | VAr | -| [serial]/0/temperature | R | Temperature of inverter in degree celsius | Degree Celsius (°C) | -| [serial]/0/voltage | R | AC voltage in volt | Volt (V) | -| [serial]/0/yieldday | R | Energy converted to AC per day in watt hours | Watt hours (Wh) | -| [serial]/0/yieldtotal | R | Energy converted to AC since reset watt hours | Kilo watt hours (kWh) | - -### DC input channel topics - -[1-4] represents the different inputs. The amount depends on the inverter model. - -| Topic | R / W | Description | Value / Unit | -| --------------------------------------- | ----- | ---------------------------------------------------- | -------------------------- | -| [serial]/[1-4]/current | R | DC current of specific input in ampere | Ampere (A) | -| [serial]/[1-4]/name | R | Name of the DC input channel as configured in web GUI| | -| [serial]/[1-4]/irradiation | R | Ratio DC Power over set maximum power (in web GUI) | % | -| [serial]/[1-4]/power | R | DC power of specific input in watt | Watt (W) | -| [serial]/[1-4]/voltage | R | DC voltage of specific input in volt | Volt (V) | -| [serial]/[1-4]/yieldday | R | Energy converted to AC per day on specific input | Watt hours (Wh) | -| [serial]/[1-4]/yieldtotal | R | Energy converted to AC since reset on specific input | Kilo watt hours (kWh) | - -### Inverter limit specific topics - -cmd topics are used to set values. Status topics are updated from values set in the inverter. - -| Topic | R / W | Description | Value / Unit | -| ----------------------------------------- | ----- | ---------------------------------------------------- | -------------------------- | -| [serial]/status/limit_relative | R | Current applied production limit of the inverter | % of total possible output | -| [serial]/status/limit_absolute | R | Current applied production limit of the inverter | Watt (W) | -| [serial]/cmd/limit_persistent_relative | W | Set the inverter limit as a percentage of total production capability. The value will survive the night without power. The updated value will show up in the web GUI and limit_relative topic immediatly. | % | -| [serial]/cmd/limit_persistent_absolute | W | Set the inverter limit as a absolute value. The value will survive the night without power. The updated value will set immediatly within the inverter but show up in the web GUI and limit_relative topic after around 4 minutes. If you are using a already known inverter (known Hardware ID), the updated value will show up within a few seconds. | Watt (W) | -| [serial]/cmd/limit_nonpersistent_relative | W | Set the inverter limit as a percentage of total production capability. The value will reset to the last persistent value at night without power. The updated value will show up in the web GUI and limit_relative topic immediatly. The value must be published non-retained, otherwise it will be ignored! | % | -| [serial]/cmd/limit_nonpersistent_absolute | W | Set the inverter limit as a absolute value. The value will reset to the last persistent value at night without power. The updated value will set immediatly within the inverter but show up in the web GUI and limit_relative topic after around 4 minutes. If you are using a already known inverter (known Hardware ID), the updated value will show up within a few seconds. The value must be published non-retained, otherwise it will be ignored! | Watt (W) | -| [serial]/cmd/power | W | Turn the inverter on (1) or off (0) | 0 or 1 | -| [serial]/cmd/restart | W | Restarts the inverters (also resets YieldDay) | 1 | +This documentation will has been moved and can be found here: diff --git a/docs/Web-API.md b/docs/Web-API.md index 3e3eeb939..baa648974 100644 --- a/docs/Web-API.md +++ b/docs/Web-API.md @@ -1,564 +1,3 @@ # Web API -Information in JSON format can be obtained through the web API - -## List of URLs - -may be incomplete - -| GET/POST | Auth required | URL | -| -------- | --- | -- | -| Get | yes | /api/config/get | -| Post | yes | /api/config/delete | -| Get | yes | /api/config/list | -| Post | yes | /api/config/upload | -| Get+Post | yes | /api/device/config | -| Get | no | /api/devinfo/status | -| Get+Post | yes | /api/dtu/config | -| Get | no | /api/eventlog/status?inv=inverter-serialnumber | -| Post | yes | /api/firmware/update | -| Get | yes | /api/inverter/list | -| Post | yes | /api/inverter/add | -| Post | yes | /api/inverter/del | -| Post | yes | /api/inverter/edit | -| Post | yes | /api/limit/config | -| Get | no | /api/limit/status | -| Get | no | /api/livedata/status | -| Post | yes | /api/maintenance/reboot | -| Get+Post | yes | /api/mqtt/config | -| Get | no | /api/mqtt/status | -| Get+Post | yes | /api/network/config | -| Get | no | /api/network/status | -| Get+Post | yes | /api/ntp/config | -| Get | no | /api/ntp/status | -| Get+Post | yes | /api/ntp/time | -| Get | no | /api/power/status | -| Post | yes | /api/power/config | -| Get | no | /api/prometheus/metrics | -| Get+Post | yes | /api/security/config | -| Get | yes | /api/security/authenticate | -| Get | no | /api/system/status | - -## Examples of Use - -### Important notes - -- IP addresses and serial numbers in this examples are anonymized. Adjust to your own needs. -- The output from curl is without a linefeed at the end, so please be careful when copying the output - do not accidentally add the shell prompt directly after it. -- When POSTing config data to OpenDTU, always send all settings back, even if only one setting was changed. Sending single settings is not supported and you will receive a response `{"type":"warning","message":"Values are missing!"}` -- When POSTing, always put single quotes around the data part. Do not confuse the single quote `'` with the backtick `` ` ``. You have been warned. -- Some API calls have a single URL for GET and POST - e.g. `/api/ntp/config` -- Other API calls use e.g. `/api/limit/status` to GET data and a different URL `/api/limit/config` to POST data. -- If you want to investigate the web api communication, a good tool is [Postman](https://www.postman.com/) -- Settings API require username and password provided with Basic Authentication credentials -- If you disable the readonly access to the web API, every endpoint requires authentication - -### Get information - -You can "talk" to the OpenDTU with a command line tool like `curl`. The output is in plain JSON, without carriage return/linefeed and is therefore not very human readable. - -#### Get current livedata - -```bash -$ curl http://192.168.10.10/api/livedata/status -{"inverters":[{"serial":"11617160xxxx","name":"Meine Solaranlage","data_age":6983,"reachable":false,"producing":false,"limit_relative":0,"limit_absolute":-1,"AC":{"0":{"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"Power DC":{"v":0,"u":"W","d":1},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3},"Frequency":{"v":0,"u":"Hz","d":2},"PowerFactor":{"v":0,"u":"","d":3},"ReactivePower":{"v":0,"u":"var","d":1},"Efficiency":{"v":0,"u":"%","d":3}}},"DC":{"0":{"name":{"u":""},"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3}},"1":{"name":{"u":""},"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3}},"2":{"name":{"u":""},"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3}},"3":{"name":{"u":""},"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3}}},"INV":{"0":{"Temperature":{"v":0,"u":"°C","d":1}}},"events":0},{"serial":"11417160xxxx","name":"test","data_age":6983,"reachable":false,"producing":false,"limit_relative":0,"limit_absolute":-1,"AC":{"0":{"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"Power DC":{"v":0,"u":"W","d":1},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3},"Frequency":{"v":0,"u":"Hz","d":2},"PowerFactor":{"v":0,"u":"","d":3},"ReactivePower":{"v":0,"u":"var","d":1},"Efficiency":{"v":0,"u":"%","d":3}}},"DC":{"0":{"name":{"u":"test 1"},"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3}},"1":{"name":{"u":"test 2"},"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3}}},"INV":{"0":{"Temperature":{"v":0,"u":"°C","d":1}}},"events":0}],"total":{"Power":{"v":0,"u":"W","d":1},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":0,"u":"kWh","d":2}},"hints":{"time_sync":false,"radio_problem":false,"default_password":false}} -``` - -To enhance readability (and filter information) use the JSON command line processor `jq`. - -```bash -$ curl --no-progress-meter http://192.168.10.10/api/livedata/status | jq -{ - "inverters": [ - { - "serial": "116171603546", - "name": "Meine Solaranlage", - "data_age": 7038, - "reachable": false, - "producing": false, - "limit_relative": 0, - "limit_absolute": -1, - "AC": { - "0": { - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "Power DC": { - "v": 0, - "u": "W", - "d": 1 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - }, - "Frequency": { - "v": 0, - "u": "Hz", - "d": 2 - }, - "PowerFactor": { - "v": 0, - "u": "", - "d": 3 - }, - "ReactivePower": { - "v": 0, - "u": "var", - "d": 1 - }, - "Efficiency": { - "v": 0, - "u": "%", - "d": 3 - } - } - }, - "DC": { - "0": { - "name": { - "u": "" - }, - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - }, - "Irradiation": { - "v": 0, - "u": "%", - "d": 3 - } - }, - "1": { - "name": { - "u": "" - }, - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - }, - "Irradiation": { - "v": 0, - "u": "%", - "d": 3 - } - }, - "2": { - "name": { - "u": "" - }, - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - }, - "Irradiation": { - "v": 0, - "u": "%", - "d": 3 - } - }, - "3": { - "name": { - "u": "" - }, - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - } - } - }, - "INV": { - "0": { - "Temperature": { - "v": 0, - "u": "°C", - "d": 1 - } - } - }, - "events": 0 - }, - { - "serial": "114171603548", - "name": "test", - "data_age": 7038, - "reachable": false, - "producing": false, - "limit_relative": 0, - "limit_absolute": -1, - "AC": { - "0": { - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "Power DC": { - "v": 0, - "u": "W", - "d": 1 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - }, - "Frequency": { - "v": 0, - "u": "Hz", - "d": 2 - }, - "PowerFactor": { - "v": 0, - "u": "", - "d": 3 - }, - "ReactivePower": { - "v": 0, - "u": "var", - "d": 1 - }, - "Efficiency": { - "v": 0, - "u": "%", - "d": 3 - } - } - }, - "DC": { - "0": { - "name": { - "u": "test 1" - }, - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - }, - "Irradiation": { - "v": 0, - "u": "%", - "d": 3 - } - }, - "1": { - "name": { - "u": "test 2" - }, - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "Voltage": { - "v": 0, - "u": "V", - "d": 1 - }, - "Current": { - "v": 0, - "u": "A", - "d": 2 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 3 - }, - "Irradiation": { - "v": 0, - "u": "%", - "d": 3 - } - } - }, - "INV": { - "0": { - "Temperature": { - "v": 0, - "u": "°C", - "d": 1 - } - } - }, - "events": 0 - } - ], - "total": { - "Power": { - "v": 0, - "u": "W", - "d": 1 - }, - "YieldDay": { - "v": 0, - "u": "Wh", - "d": 0 - }, - "YieldTotal": { - "v": 0, - "u": "kWh", - "d": 2 - } - }, - "hints": { - "time_sync": false, - "radio_problem": false, - "default_password": false - } -} -``` - -The eventlog can be fetched with the inverter serial number as parameter: - -```bash -$ curl --no-progress-meter http://192.168.10.10/api/eventlog/status?inv=11418186xxxx | jq -{ - "11418186xxxx": { - "count": 4, - "events": [ - { - "message_id": 1, - "message": "Inverter start", - "start_time": 28028, - "end_time": 28028 - }, - { - "message_id": 209, - "message": "PV-1: No input", - "start_time": 28036, - "end_time": 0 - }, - { - "message_id": 2, - "message": "DTU command failed", - "start_time": 28092, - "end_time": 28092 - }, - { - "message_id": 207, - "message": "MPPT-A: Input undervoltage", - "start_time": 28336, - "end_time": 0 - } - ] - } -} -``` - -#### combine curl and jq - -`jq` can filter specific fields from json output. - -For example, filter out the current total power: - -```bash -$ curl --no-progress-meter http://192.168.10.10/api/livedata/status | jq '.total | .Power.v' -140.7999878 -``` - -#### Get information where login is required - -When config data is requested, username and password have to be provided to `curl` -Username is always `admin`, the default password is `openDTU42`. The password is used for both the admin login and the Admin-mode Access Point. - -```bash -$ curl --u admin:openDTU42 http://192.168.10.10/api/ntp/config -{"ntp_server":"pool.ntp.org","ntp_timezone":"CET-1CEST,M3.5.0,M10.5.0/3","ntp_timezone_descr":"Europe/Berlin"} -``` - -### Post information - -With HTTP POST commands information can be written to the OpenDTU. - -The Web API is designed to allow the web frontend in the web browser to communicate with the OpenDTU software running on the ESP32. It is not designed to be intuitive or user-friendly, so please follow the instructions here. - -#### Example 1: change ntp settings - -If you want to configure the ntp server setting, first fetch the information from the web API: - -```bash -$ curl -u "admin:password" http://192.168.10.10/api/ntp/config -{"ntp_server":"pool.ntp.org","ntp_timezone":"CET-1CEST,M3.5.0,M10.5.0/3","ntp_timezone_descr":"Europe/Berlin"} -``` - -Then, second step, send your new settings. Use the text output from curl in the first step, add `data=` and enclose the whole data with single quotes. - -```bash -$ curl -u "admin:password" http://192.168.10.10/api/ntp/config -d 'data={"ntp_server":"my.own.ntp.server.home","ntp_timezone":"CET-1CEST,M3.5.0,M10.5.0/3","ntp_timezone_descr":"Europe/Berlin"}' -{"type":"success","message":"Settings saved!"} -``` - -You will receive a json formatted response. - -#### Example 2: change power limit - -In the second example, I want to change the non persistent power limit of an inverter. Again, first fetch current data: - -```bash -$ curl http://192.168.10.10/api/limit/status -{"11418186xxxx":{"limit_relative":100,"max_power":600,"limit_set_status":"Ok"},"11418180xxxx":{"limit_relative":100,"max_power":800,"limit_set_status":"Ok"}} -``` - -I see data from two configured inverters. - -Now I set the relative power limit of inverter with serialnumber `11418180xxxx` to 50%. - -```bash -$ curl -u "admin:password" http://192.168.10.10/api/limit/config -d 'data={"serial":"11418180xxxx", "limit_type":1, "limit_value":50}' -{"type":"success","message":"Settings saved!"} -``` - -Then I read again the limit status. In the first answer the status is `pending`, some seconds later it changed to `OK`. - -```bash -$ curl http://192.168.10.10/api/limit/status -{"11418186xxxx":{"limit_relative":100,"max_power":600,"limit_set_status":"Ok"},"11418180xxxx":{"limit_relative":100,"max_power":800,"limit_set_status":"Pending"}} - -... - -$ curl http://192.168.10.10/api/limit/status -{"11418186xxxx":{"limit_relative":100,"max_power":600,"limit_set_status":"Ok"},"11418180xxxx":{"limit_relative":50,"max_power":800,"limit_set_status":"Ok"}} -``` +This documentation will has been moved and can be found here: