OpenDTU-OnBattery

https://opendtu-onbattery.net/
Admin
OpenDTU-OnBattery is an open-source firmware for ESP32 microcontrollers that communicates with...
Tokens:48,788
Snippets:474
Trust Score:5.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Development Server

Source: https://opendtu-onbattery.net/firmware/compile_webapp

Execute this command to start the local development server.

```bash
yarn dev
```

--------------------------------

### Example Device Profile JSON Configurations

Source: https://opendtu-onbattery.net/firmware/device_profiles

A collection of example JSON profiles for various hardware setups, including NodeMCU, Olimex ESP32-POE, and OpenDTU FUSION v2 configurations.

```json
[
    {
        "name": "Generic NodeMCU 38 pin with SSD1306 display",
        "nrf24": {
            "miso": 19,
            "mosi": 23,
            "clk": 18,
            "irq": 16,
            "en": 4,
            "cs": 5
        },
        "victron": {
            "rx": 22,
            "tx": -1
        },
        "battery": {
            "rx": 27,
            "tx": 14
        },
        "huawei": {
            "miso": 12,
            "mosi": 13,
            "clk": 26,
            "irq": 25,
            "power": 33,
            "cs": 15
        },
        "display": {
            "type": 2,
            "data": 21,
            "clk": 22
        },
        "eth": {
            "enabled": false
        }
    },
    {
        "name": "Generic NodeMCU 38 pin with SSD1306",
        "nrf24": {
            "miso": 19,
            "mosi": 23,
            "clk": 18,
            "irq": 16,
            "en": 4,
            "cs": 5
        },
        "eth": {
            "enabled": false
        },
        "display": {
            "type": 2,
            "data": 21,
            "clk": 22
        },
        "powermeter": {
            "rx": 25,
            "tx": 26,
            "dere": 27
        }
    },
    {
        "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
        }
    },
    {
        "name": "OpenDTU FUSION v2 + JK BMS on RS485 Transceiver",
        "battery": {
            "rx": 16,
            "rxen": 15,
            "tx": 45,
            "txen": 46
        }
    },
    {
        "name": "OpenDTU FUSION v2 + 2xVictron MPPT + Victron SmartShunt",
        "nrf24": {
            "miso": 48,
            "mosi": 35,
            "clk": 36,
            "irq": 47,
            "en": 38,
            "cs": 37
        },
        "cmt": {
            "clk": 6,
            "cs": 4,
            "fcs": 21,
            "sdio": 5,
            "gpio2": 3,
            "gpio3": 8
        },
        "led": {
            "led0": 17,
            "led1": 18
        },
        "battery": {
            "rx": 16,
            "tx": -1
        },
        "victron": {
            "rx": 22,
            "tx": -1,
            "rx2": 23,
            "tx2": -1
        }
    },
    {
        "name": "OpenDTU Fusion v2 with NRF24, MPPT, SDM72",
        "nrf24": {
            "miso": 48,
            "mosi": 35,
            "clk": 36,
            "irq": 47,
            "en": 38,
            "cs": 37
        },
        "victron": {
            "rx": 22,
            "tx": -1
        },
        "powermeter": {
            "rx": 16,
            "tx": 45,
            "rxen": 15,
            "txen": 46
        }
    }
]
```

--------------------------------

### Install esptool via pip

Source: https://opendtu-onbattery.net/firmware/flash_esp

Commands to set up a virtual environment and install the esptool utility for flashing.

```bash
python3 -m venv /path/to/your/venv
source /path/to/your/venv/bin/activate # on Linux
/path/to/your/venv/bin/Activate.ps1 # on Windows
pip install esptool
esptool version # should show esptool version
```

--------------------------------

### Build the WebApp

Source: https://opendtu-onbattery.net/firmware/compile_webapp

Commands to install dependencies and build the WebApp, placing the output in the webapp_dist directory.

```bash
cd webapp
yarn install
yarn build
```

--------------------------------

### Language pack JSON example

Source: https://opendtu-onbattery.net/firmware/language_pack

Example structure of a language pack JSON file with meta, display, and webapp sections. The meta section requires name and code, display includes date_format and translation keys with format specifiers, and webapp contains web interface translations.

```json
{
    "meta": {
        "name": "Italiano",
        "code": "it"
    },
    "display": {
        "date_format": "%d/%m/%Y %H:%M",
        ...
    },
    "webapp": {
        "menu": {
            ...
        },
        ...
    }
}
```

--------------------------------

### Get authenticated configuration data

Source: https://opendtu-onbattery.net/firmware/web_api

Access protected configuration endpoints by providing the default admin credentials.

```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"}
```

--------------------------------

### Interactive program startup notice

Source: https://opendtu-onbattery.net/license

Output this short notice when an interactive program starts. The hypothetical commands `show w' and `show c' should display the appropriate parts of the General Public License; they may be replaced with other commands or UI elements.

```text
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

```

--------------------------------

### GPL notice for source files

Source: https://opendtu-onbattery.net/license

Attach this notice to the start of each source file to convey the exclusion of warranty and provide a pointer to the full license. Replace the placeholders for program name, year, and author name.

```text
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

```

--------------------------------

### Get inverter eventlog

Source: https://opendtu-onbattery.net/firmware/web_api

Fetch the event log for a specific inverter serial number, piped through jq for formatting.

```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
      }
    ]
  }
}
```

--------------------------------

### MQTT Topic: [serial]/cmd/restart

Source: https://opendtu-onbattery.net/firmware/mqtt_topics

Write-only topic to restart the inverters, which also resets YieldDay.

```APIDOC
## MQTT Topic: [serial]/cmd/restart

### Description
Write-only topic to restart the inverters, which also resets YieldDay.

### Topic
[serial]/cmd/restart

### Access
Write (W)

### Value / Unit
1

### Request Example
{
  "value": 1
}
```

--------------------------------

### Get inverter detail livedata

Source: https://opendtu-onbattery.net/firmware/web_api

Retrieve the current status and data for a specific inverter using its serial number.

```bash
$ curl http://192.168.10.10/api/livedata/status?inv=1161716xxxxx
{"inverters":[{"serial":"1161716xxxxx","name":"Meine Solaranlage","order":0,"data_age":30824,"poll_enabled":true,"reachable":false,"producing":false,"limit_relative":100,"limit_absolute":1500,"AC":{"0":{"Power":{"v":0,"u":"W","d":1},"Voltage":{"v":0,"u":"V","d":1},"Current":{"v":0,"u":"A","d":2},"Frequency":{"v":0,"u":"Hz","d":2},"PowerFactor":{"v":0,"u":"","d":3},"ReactivePower":{"v":0,"u":"var","d":1}}},"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":834.2609863,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3,"max":385}},"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":832.7069702,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3,"max":385}},"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":843.7299805,"u":"kWh","d":3},"Irradiation":{"v":0,"u":"%","d":3,"max":385}},"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":4.907999992,"u":"kWh","d":3}}},"INV":{"0":{"Power DC":{"v":0,"u":"W","d":1},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":2515.605957,"u":"kWh","d":3},"Temperature":{"v":0,"u":"°C","d":1},"Efficiency":{"v":0,"u":"%","d":3}}},"events":2}],"total":{"Power":{"v":0,"u":"W","d":1},"YieldDay":{"v":0,"u":"Wh","d":0},"YieldTotal":{"v":2515.605957,"u":"kWh","d":3}},"hints":{"time_sync":false,"radio_problem":false,"default_password":false}}
```

--------------------------------

### GET /api/ntp/config

Source: https://opendtu-onbattery.net/firmware/web_api

Retrieves the NTP configuration. This endpoint requires authentication with username `admin` and the configured password (default `openDTU42`).

```APIDOC
## GET /api/ntp/config

### Description
Retrieves the NTP configuration. This endpoint requires authentication with username `admin` and the configured password (default `openDTU42`).

### Method
GET

### Endpoint
/api/ntp/config

### Authentication
Basic authentication required. Username: `admin`, password: default `openDTU42`.

### Request Example
```
curl --u admin:openDTU42 http://192.168.10.10/api/ntp/config
```

### Response
#### Success Response (200)
- **ntp_server** (string) - NTP server address.
- **ntp_timezone** (string) - Timezone string.
- **ntp_timezone_descr** (string) - Human-readable timezone description.

#### Response Example
```
{"ntp_server":"pool.ntp.org","ntp_timezone":"CET-1CEST,M3.5.0,M10.5.0/3","ntp_timezone_descr":"Europe/Berlin"}
```
```

--------------------------------

### Configure NTP settings via Web API

Source: https://opendtu-onbattery.net/firmware/web_api

Fetch current NTP configuration and then update it by sending a POST request with the modified JSON data.

```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"}
```

```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!"}
```

--------------------------------

### GET /api/ntp/config

Source: https://opendtu-onbattery.net/firmware/web_api

Fetches the current NTP configuration from the OpenDTU-OnBattery device. This endpoint returns the NTP server, timezone, and timezone description.

```APIDOC
## [GET] /api/ntp/config

### Description
Fetches the current NTP configuration including the NTP server, timezone, and timezone description.

### Method
GET

### Endpoint
/api/ntp/config

### Parameters
#### Authentication
- Basic authentication required (username and password).

### Response
#### Success Response (200)
- **ntp_server** (string) - The NTP server address.
- **ntp_timezone** (string) - The timezone string.
- **ntp_timezone_descr** (string) - The timezone description.

#### Response Example
{
  "ntp_server": "pool.ntp.org",
  "ntp_timezone": "CET-1CEST,M3.5.0,M10.5.0/3",
  "ntp_timezone_descr": "Europe/Berlin"
}
```
Tokens:
Raw