rowatt API for Inverter

this is an Node for the API on the Growatt© Shine Webserver. (Shine provided by Growatt©. I'm not affiliated.)

This implementation is based on the refectured eebinterface from Growatt&copy Shine.

Install

npm install growatt

Debug

This API supported debugging. you have to set the environment variable DEBUG

set DEBUG=growatt:*
set DEBUG=growatt:api
set DEBUG=growatt:verbose
set DEBUG=growatt:queue

Promise

This NODE-Implementation works with promise.

Understanding javascript promises

Modern Asynchronous JavaScript with Async and Await

Simple Impemation

"use strict"
const api = require('growatt')

const user="xxx"
const passwort="xx"
const options={}

async function test() {
  const growatt = new api({})
  let login = await growatt.login(user,passwort).catch(e => {console.log(e)})
  console.log('login:',login)
  let getAllPlantData = await growatt.getAllPlantData(options).catch(e => {console.log(e)})
  console.log('getAllPlatData:',JSON.stringify(getAllPlantData,null,' '));
  let logout = await growatt.logout().catch(e => {console.log(e)})
  console.log('logout:',logout)
}

test()

Constructor

Please note that you have to create an instance since version 0.2.0.

| Parameter | Type | Default | Description | | --------- | ------ | --------- | ----------------------- | | config | Object | See below | Controls the processing |

The constructor has a config object as parameter. This is optional.

Config

| config | Type | Default | Description | | ---------------- | -------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | server | String | 'https://server.growatt.com' | The Growatt server | | indexCandI | Boolean | false | Set to true if your Growatt page Plant is a C&I Plant page with indexbC or plantDo in the Path from the Growatt webinterface. | | timeout | Integer | 5000 | Session timeout in ms. | | headers | Object | {} | custom header like {'X-Custom-Header': 'foobar'}. | | lifeSignCallback | function | undefined | Called before each Axios call. |

const api = require('growatt')
const growatt = new api()

Login

There are several options for logging in:

Login with user and password

| Parameter | Type | Default | Description | | --------- | ------ | ------- | ------------ | | user | String | - | The username | | passord | String | - | The password |

  let login = await growatt.login(user,passwort).catch(e => {console.log(e)})

With resolve, the response from the website is returned. Usually the object: { result: 1, msg: 'OK' }

With reject an exception is thrown which contains the error object with result less then 1.

Login with key

| Parameter | Type | Default | Description | | --------- | ------ | ------- | ----------- | | key | String | - | The key |

You can get the key by having an email sent to you on the Grwatt website for a third party to display the data. The key is the combination of numbers and letters in the link. It has 96 characters.

  let login = await Growatt.sharePlantLogin(key).catch(e => {console.log(e)})

With resolve, the response from the website is returned. Usually the object: { result: 1, msg: 'OK' }

With reject an exception is thrown which contains the error object with result less then 1.

Login to Demo

| Parameter | Type | Default | Description | | --------- | ---- | ------- | ----------- | | | |

This plugin is intended for testing. On the Growatt page you can view the data from many systems. The problem is that the ID of the system is different here every time you login.

I needed it so that I could see how the messages to the different inverters are structured.

  let login = await Growatt.demoLogin().catch(e => {console.log(e)})

Get all plant data

| Parameter | Type | Default | Description | | --------- | ------ | --------- | ----------------------- | | option | Object | See below | Controls the processing |

This function knows the individual types of the inverter and calls up the data.

This function can be controlled via an option so that you don't always have to call up all the data that is possible:

Option

| Option | Type | Default | Description | | -------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | plantData | Boolean | true | True calls the description dataset of the plant. | | deviceData | Boolean | true | True calls the description dataset of the plantdevice. | | weather | Boolean | true | True calls the weather dataset of the plant. | | faultlog | Boolean | false | True retrieves the plant's fault logs. An array with the most recent event first is returned. | | faultlogdate | String | 'YYYY' | It is only taken into account if faultlog is true. It must be a string with the date in 'YYYY', 'YYYY-MM', 'YYYY-MM-DD'. | | faultlogdateindex | Boolean | true | It is only taken into account if faultlog is true. The array is converted into timestampsobjects. | | plantId | Integer | undefined | The ID of a plant. So that the output can be restricted. Attention, the ID is constantly changing on demologin. | | totalData | Boolean | true | Retrieves the data integrals. The sums since start time. | | statusData | Boolean | true | This is not available for all systems. Here, the current operating status, fuel injection, battery charge and generation is called up. However, the data is also contained in historyLast. | | deviceTyp | Boolean | false | Add the device type to the Output. | | historyLast | Boolean | true | The last data record from the system history table is called up here. | | historyAll | Boolean | false | All data records from the system history table is called up here. | | historyLastStartDate | new Date() | yesterday | The start time for retrieving the history. | | historyLastEndDate | new Date() | tomorrow | The end time for retrieving the history. | | historyStart | Integer | 0 | The server does not send all data for the time range. With the starting index you get the next rows. |

The call

After waiting to log in with await. Can the data be retrieved using this method. In response, an object comes out that contains the data of the length.

  options = {plantData:false,deviceData:true,deviceTyp:true,weather:false,chartLastArray:true}
  let getAllPlantData = await growatt.getAllPlantData(options).catch(e => {console.log(e)})
  console.log('getAllPlatData:',JSON.stringify(getAllPlantData,null,' '));

Logout

After retrieving the data, you should log out of the page again. It is the same call for all three login variants.

  let logout = await growatt.logout().catch(e => {console.log(e)})

isConnected

It is also possible to have the connection open and to check whether the API is still connected.

  if (growatt.isConnected()) {
  }

getDataLoggers

Returns a list of data loggers with information

  let loggers = await growatt.getDataLoggers().catch(e => {console.log(e)})

getDataLoggerRegister

| Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------- | | dataLogSn | String | - | The serial number | | addr | Integer | - | The register |

Returns the value of a datalogger register

  //api.LOGGERREGISTER.INTERVAL
  //api.LOGGERREGISTER.SERVERIP
  //api.LOGGERREGISTER.SERVERPORT
  let register = await growatt.getDataLoggerRegister(loggers[0].sn, api.LOGGERREGISTER.INTERVAL).catch(e => {console.log(e)})

The answer is an object

| Parameter | Type | Description | | --------- | ------ | ----------- | | msg | String | The value | | success | String | Ok or bad |

setDataLoggerRegister

Warning an incorrect register with the wrong value can destroy or damage the logger. Writing to the Datenlohgger is at your own risk.

| Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------- | | dataLogSn | String | - | The serial number | | addr | Integer | - | The register | | value | String | - | The value to set |

Sets the value of a datalogger register

  //api.LOGGERREGISTER.INTERVAL
  //api.LOGGERREGISTER.SERVERIP
  //api.LOGGERREGISTER.SERVERPORT
  let res = await growatt.setDataLoggerRegister(loggers[0].sn, api.LOGGERREGISTER.INTERVAL, 1).catch(e => {console.log(e)})

The answer is an object

| Parameter | Type | Description | | --------- | ------ | -------------- | | msg | String | An information | | success | String | Ok or bad |

setDataLoggerParam

Warning an incorrect register with the wrong value can destroy or damage the logger. Writing to the Datenlohgger is at your own risk.

| Parameter | Type | Default | Description | | --------- | ------- | ------- | ------------------- | | dataLogSn | String | - | The serial number | | paramType | Integer | - | The function number | | value | String | - | The value to set |

Sets the value of the datalogger

  //api.LOGGERFUNCTION.INTSERVERIP
  //api.LOGGERFUNCTION.SERVERNAME
  //api.LOGGERFUNCTION.SERVERPORT
  let res = await growatt.setDataLoggerRegister(loggers[0].sn, api.LOGGERFUNCTION.SERVERPORT, 5279).catch(e => {console.log(e)})

The answer is an object

| Parameter | Type | Description | | --------- | ------ | -------------- | | msg | String | An information | | success | String | Ok or bad |

setDataLoggerRestart

| Parameter | Type | Default | Description | | --------- | ------ | ------- | ----------------- | | dataLogSn | String | - | The serial number |

Sets the value of the datalogger

  //api.LOGGERFUNCTION.INTSERVERIP
  //api.LOGGERFUNCTION.SERVERNAME
  //api.LOGGERFUNCTION.SERVERPORT
  let res = await growatt.setDataLoggerRestart(loggers[0].sn).catch(e => {console.log(e)})

The answer is an object

| Parameter | Type | Description | | --------- | ------ | -------------- | | msg | String | An information | | success | String | Ok or bad |

checkDataLoggerFirmware

| Parameter | Type | Default | Description | | --------- | ------- | ------- | --------------------------- | | type | Integer | - | The logger type number | | version | String | - | The logger firmware version |

It is checked whether an update is available

  let res = await growatt.checkDataLoggerFirmware(loggers[0].deviceTypeIndicate,loggers[0].firmwareVersion).catch(e => {console.log(e)})

The answer is an object

| Parameter | Type | Description | | --------- | ------ | -------------- | | msg | String | An information | | success | String | Ok or bad |

getInverterCommunication

Warning: An incorrect value can lead to the destruction of the inverter. The writing to the inverter is at your own risk.

| Parameter | Type | Default | Description | | --------- | ------ | ------- | ----------------------------------- | | type | String | - | The Invertr type from the SN object |

This function does not require a connection to the server. The answer is an object

| Parameter | Type | Description | | ----------- | ----------- | ----------------- | | | Object conf | The configuration |

Object conf

| Parameter | Type | Description | | --------- | ------------ | ------------------------------------------------------------------------------------------------- | | name | String | The term for it | | param | Object param | The list of the Params | | subRead | String array | If specified, further objects must be loaded in order to receive the object completely | | isSubread | String | It is listed as subRead in another config. The param is empty, it is defined for subRead objects. |

Attention different inverters have different parameters. Therefore, the parameters cannot be crossed under the types Object param

| Parameter | Type | Optional | Description | | --------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | String | no | The term for it | | type | String | no | The valuetype | | def | any | on not read | If the parameter is not readable, it contains a value for the default value | | unit | String | if known | The unit of value | | values | Object | if needed | Contains list of translation of values ​​as Object. Key : String. The key is the value that must be passed. The string is an English description for the value. |

The Value Types from the Parameter

| valuetype | Type | Description | | ----------- | --------------- | --------------- | | INUM_0_100 | Integer | value 0 ... 100 | | INUM_0_1 | Integer | value 0 ... 1 | | BOOL | Boolean | true/false | | STIME_H_MIN | String for Time | format 'HH:MI' | | DATETIME | Integer | Date.timeOf() |

  let a = allPlantData[Object.keys(allPlantData)[0]].devices;
  let sn = Object.keys(a)[0];
  let type = a[sn].growattType;
  let com = Growatt.getInverterCommunication (type);

getInverterSetting

Warning: An incorrect value can lead to the destruction of the inverter. The writing to the inverter is at your own risk.

| Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------- | | type | Integer | - | The logger type number | | func | String | - | The to read | | serialNum | String | - | Inverters Serial number |

Returns a list of the Values as defined

The answer is an object

| Parameter | Type | Description | | --------- | ------ | ------------------- | | msg | String | An information | | success | String | Ok or bad | | param<..> | each | From the Param List |

With some inverters, it is not always possible to read the data due to the connection via RS232. If a process is in progress, the second query is rejected. Therefore, the requests are placed in a queue and processed sequentially. If the inverter does not send any data but reports success, the request is repeated.

  // Growatt must be connected

  const allPlantData = await Growatt.getAllPlantData(options).catch(e => {console.log(e);});
  console.log('Fatched all Data');
  if (allPlantData) {
    let a = allPlantData[Object.keys(allPlantData)[0]].devices;
    let sn = Object.keys(a)[0];
    let type = a[sn].growattType;
    let com = Growatt.getInverterCommunication (type);
    console.log(com);
    let run = []
    Object.keys(com).forEach(name => {
        if (com[name].subRead) {
          com[name].subRead.forEach(name => {
                                            run.push(Growatt.getInverterSetting(type, name, sn)
              .then(r => {
                console.log(name,r);
              })
              .catch(e => {
                console.log(name,e);
          }))})
        }
        if (!com[name].isSubread) {
          run.push(Growatt.getInverterSetting(type, name, sn)
          .then(r => {
            console.log(name,r);
          })
          .catch(e => {
            console.log(name,e);
          }))
        }
    })
    await Promise.all(run)
  }

setInverterSetting

Warning: An incorrect value can lead to the destruction of the inverter. The writing to the inverter is at your own risk.

| Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------- | | type | Integer | - | The logger type number | | func | String | - | The to read | | serialNum | String | - | Inverters Serial number | | val | Object | - | values to set |

The val object

| Parameter | Type | Description | | --------- | ---- | ------------------- | | param<..> | each | From the Param List |

With some inverters, it is not always possible to read the data due to the connection via RS232. If a process is in progress, the second query is rejected. Therefore, the requests are placed in a queue and processed sequentially. If the inverter does not send any data but reports success, the request is repeated.

    let a = allPlantData[Object.keys(allPlantData)[0]].devices;
    let sn = Object.keys(a)[0];
    let type = a[sn].growattType;
    let v = {param1: (new Date()).getTime()}
    await Growatt.setInverterSetting(typ, 'time', sn, v);

getNewPlantFaultLog

| Parameter | Type | Default | Description | | --------- | ------- | ------- | -------------------------------------------------------------------- | | plantId | Integer | - | The plantId | | date | String | 'YYYY' | It must be a string with the date in 'YYYY', 'YYYY-MM', 'YYYY-MM-DD' | | deviceSn | String | '' | Inverters Serial number, can be an empty string to request all | | toPageNum | Integer | 1 | Go to a specific page |

It queries the fault log and returns the posts.

The answer is an object

| Parameter | Type | Description | | --------- | ------- | --------------- | | result | Integer | 1 => Ok | | obj | Object | Response object |

Response object

| Parameter | Type | Description | | --------- | --------------- | --------------------------------- | | pages | Integer | Number of possible pesponse pages | | currPage | Integer | Number of current pesponse page | | datas | Array of object | Message objects | | count | Integer | Messages in the array |

Response datas object as array

| Parameter | Type | Description | | ------------- | ------------- | ------------------------------------------------------ | | deviceType | String | Description of which device type | | eventId | String | Code for the event | | batSn | String | Serial number of the battery if the event came from it | | solution | String | A suggestion from Growatt | | eventSolution | String | Another suggestion from Growatt | | alias | String | The device's alias | | eventName | String | The name or description of the event | | sn | String | The serial number of the equipment | | time | String (date) | When it happened YYYY-MM-DD HH:MI:SS | | deviceSn | String | The serial number of the device |

Speedup data interval new method

• Open the ShinePhone app
• Click on attachment below
• Top right +, then list data loggers
• Click on existing data logger
• Configure data logger
• Wireless hotspot mode
• Put the stick in AP mode
• Connect to Wifi hotspot, PW 123456789 ? <- check again
• Continue
• Advanced
• Time setting
• Interval to 1
• Enter password growattYYYYMMDD (e.g.growatt20220209)
• Unlock
• Click and apply changes
• Exit hotspot mode

There is no change to the charts on growatt side. There you can only see a change in the data from the datalogger.

License (MIT)

Copyright (c) 2020 Chris Traeger

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.