myenergi-api 0.9.2 → 1.0.2

package/README.md

@@ -1,2 +1,147 @@
 # myenergi-api
+
+[![DeepScan grade](https://deepscan.io/api/teams/16513/projects/19831/branches/520479/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=16513&pid=19831&bid=520479)
+![GitHub last commit](https://img.shields.io/github/last-commit/bisand/myenergi-api)
+[![Node.js CI](https://github.com/bisand/myenergi-api/actions/workflows/node.js.yml/badge.svg?branch=master)](https://github.com/bisand/myenergi-api/actions/workflows/node.js.yml)
+[![Node.js Package](https://github.com/bisand/myenergi-api/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/bisand/myenergi-api/actions/workflows/npm-publish.yml)
+![npm](https://img.shields.io/npm/v/myenergi-api)
+![npm](https://img.shields.io/npm/dw/myenergi-api)
+![NPM](https://img.shields.io/npm/l/myenergi-api)
+
 NodeJS implementation of MyEnergi API for controlling Zappi, Eddi and other MyEnergi products
+
+## General
+
+This node.js module is used for communicating with [myenergi](https://myenergi.com/) API. It enables you to communicate, retrieve data and control some of the myeneri products like [Zappi](https://myenergi.com/product/zappi/) and [Eddi](https://myenergi.com/product/eddi/).
+
+[Zappi](https://myenergi.com/product/zappi/) is a smart EV charger that is able to charge your EV using solar enegy or other renewable energy sources which saves energy and money. [Eddi](https://myenergi.com/product/eddi/) is a power diverter that controls up to two heating sources. It works in the same way as Zappi by diverting generated renewable enegy directly to the heating source and potentially draw the rest of the energy from the grid.
+
+## Prerequisites
+
+In order to use this module you have to own a myenergi [hub](https://myenergi.com/product/hub/). This will have to be registered to the [myenergi My Account](https://myaccount.myenergi.com/).
+The hubs serial is used for the username and the password is the password you created when registering the product on [myenergi My Account](https://myaccount.myenergi.com/location#devices).
+
+## Installation
+
+> npm package [https://www.npmjs.com/package/myenergi-api](https://www.npmjs.com/package/myenergi-api)
+
+```
+npm install myenergi-api
+```
+
+## Usage
+
+### Create an instance of MyEnergi class.
+Here you find all methods needed to communicate with your myenergi hub. You will have to create one instance per hub if you have more than one.
+```typescript
+const myenergi = new MyEnergi("1234567", "!3uper3ecretPassw0rd");
+```
+
+### Get status of all myenergi devices
+Return status of all myenergi devices connected to the hub. Zappi, Eddi and Harvi
+```typescript
+const statusAll = await myenergi.getStatusAll();
+console.log(statusAll);
+```
+
+### Get status of all Zappi devices.
+Return status of all Zappi devices connected to the hub.
+```typescript
+const zappiAll: Zappi[] = await myenergi.getStatusZappiAll();
+console.log(zappiAll);
+```
+
+### Get status of one Zappi device.
+Return status of a Zappi device with the provided serial number.
+```typescript
+const sno = '1234567';
+const statusZappi: Zappi = await myenergi.getStatusZappi(sno);
+console.log(statusZappi);
+
+```
+
+### Set Zappi charge mode.
+Set the current charge mode for the specified Zappi device. You can also use this function to stop charging. See [Charge Mode](#charge_mode) in the documentation below for more details.
+```typescript
+const sno = '1234567';
+const chargeMode = ZappiChargeMode.EcoPlus;
+const result = await myenergi.setZappiChargeMode(sno, chargeMode);
+console.log(result);
+
+```
+
+### Set Zappi minimum green level (MGL)
+Set minimum green level to decide how much grid power zappi uses to keep the 1.4kW minimum charge rate going. See [MGL](#mgl) in the documentation below for more details.
+```typescript
+const result = await myenergi.setZappiGreenLevel(sno, 75);
+console.log(result);
+```
+
+### Set Zappi boost mode
+In ECO and ECO+ you can use the boosts to top up your battery quickly.  There are three different boosts available. See [Boost Mode](#boost_mode) in the documentation below for more details.
+```typescript
+const result = await myenergi.setZappiBoostMode(sno, ZappiBoostMode.Smart, 22, '0615');
+console.log(result);
+```
+
+### Get status for all Harvi devices
+Return status of all Harvi devices connected to the hub.
+```typescript
+const result = await myenergi.getStatusHarviAll();
+console.log(result);
+```
+### Get status of a specific Harvi device
+Return status of a Harvi device with the provided serial number.
+```typescript
+const sno = '1234567';
+const result = await myenergi.getStatusHarvi(sno);
+console.log(result);
+```
+### Get status for all Eddi devices
+Return status of all Eddi devices connected to the hub.
+```typescript
+const result = await myenergi.getStatusEddiAll();
+console.log(result);
+```
+### Get status of a specific Eddi device
+Return status of a Eddi device with the provided serial number.
+```typescript
+const sno = '1234567';
+const result = await myenergi.getStatusEddi(sno);
+console.log(result);
+```
+
+
+## From myenergi documentation
+<a name="myenergi_documentation"></a>
+<a name="charge_mode"></a>
+### Zappi charge modes.
+zappi has four charge modes to help you charge your EV
+
+| Mode | Description |
+|------|-------------|
+| FAST | Charge your EV as fast as possible – this is just like a dumb charger.  As soon as your EV is plugged it it will start charging and draw as much power as it can |
+| ECO  | In this mode, zappi will try to control the power going to your EV to match any surplus generation. However, as the EV charging standard says that the minimum charge rate is 1.4kW. If your surplus generation goes below this then the car will continue charging, taking extra power from the grid as needed to get to the 1.4kW minimum charge rateIf you want to charge your car quickly (for instance to top up the battery with cheap overnight electricity) then use one of the boosts to charge it at full power |
+| ECO+ 	| Like ECO, zappi will control the power going to your EV to match the surplus generation. However, if the surplus power goes below 1.4kW then zappi will pause the charge so you are not taking power from the grid. (*** See MGL below ***) If you want to charge your car quickly (for instance to top up the battery with cheap overnight electricity) then use one of the boosts to charge it at full power |
+| STOP  | In STOP mode zappi will not charge your car Boosts are also blocked. |
+
+<a name="boost_mode"></a>
+### Zappi boost modes.
+In ECO and ECO+ you can use the boosts to top up your battery quickly.  There are three different boosts available
+| Mode | Description |
+|------|-------------|
+| Manual | Charge your EV straight away with a set amount of energy (kWh) Use the slider in the app or touch on the boost power number to set an exact charge energy |
+| Smart | With Smart Boost you tell zappi how much energy you want to add to your battery and the target time. Zappi will start a quick charge at full power to test the charge speed but then goes back to the normal operation for ECO and ECO+, matching the charge rate to your spare generation. A boost at full power will then take place to top up your battery to the target value by the time set. With Smart Boost your charge will be as green as possible whilst making sure your battery has the desired energy added to it |
+| Scheduled | With Scheduled Boost you can set up to four time periods when the zappi will charge your EV at full power. This is useful for charging your car when electricity is cheap, but we would recommend you use the “My Flexible Tariff” settings in the myenergi online account (myaccount.myenergi.com) so these are set for you automatically. |
+
+<a name="mgl"></a>
+### Minimum Green Level (MGL)
+Minimum Green Level allows you to decide how much grid power zappi uses to keep the 1.4kW minimum charge rate going.
+The feature only works in ECO+ and was introduced for those people who want to squeeze as much of their surplus generation into the EV battery.
+
+With MGL set to 100% all the power going to your EV will come from the local generation.
+If you have less than 1.4kW of local surplus generation available then zappi will pause the charge.  Of course this means that you could be exporting some surplus generation to the grid…
+
+With MGL set to 50% then zappi will take up to 700W from the grid to keep the charge going
+
+If you want to make sure that all your surplus generation is used to charge your EV, then try setting MGL to 1%

package/dist/AuthDigest.js

@@ -27,7 +27,7 @@ class AuthDigest {
         this._password = password;
         this._nc = 0;
         this._initialized = false;
-        this._algorithm = 'MD5';
+        this._algorithm = "MD5";
         if (errorHandler)
             this._onError = errorHandler;
     }
@@ -58,7 +58,7 @@ class AuthDigest {
     get nc() {
         var _a;
         this._nc++;
-        var myHex = ('0000000' + ((_a = this._nc) === null || _a === void 0 ? void 0 : _a.toString(16))).substr(-8);
+        var myHex = ("0000000" + ((_a = this._nc) === null || _a === void 0 ? void 0 : _a.toString(16))).substr(-8);
         return myHex;
     }
     get cnonce() {
@@ -66,38 +66,38 @@ class AuthDigest {
         return this._cnonce;
     }
     md5(data) {
-        let md5 = crypto.createHash('md5');
-        let result = md5.update(data).digest('hex');
+        let md5 = crypto.createHash("md5");
+        let result = md5.update(data).digest("hex");
         return result;
     }
     init(wwwAuthHeader) {
-        let authSplit = wwwAuthHeader.split(',');
+        let authSplit = wwwAuthHeader.split(",");
         for (let item of authSplit) {
-            if (item.indexOf('realm=') >= 0) {
+            if (item.indexOf("realm=") >= 0) {
                 let realmSplit = item.split('="');
                 this._realm = realmSplit[realmSplit.length - 1];
                 this._realm = this._realm.substring(0, this._realm.length - 1);
             }
-            if (item.indexOf('nonce=') >= 0) {
+            if (item.indexOf("nonce=") >= 0) {
                 let nonceSplit = item.split('="');
                 this._nonce = nonceSplit[nonceSplit.length - 1];
                 this._nonce = this._nonce.substring(0, this._nonce.length - 1);
             }
-            if (item.indexOf('qop=') >= 0) {
+            if (item.indexOf("qop=") >= 0) {
                 let qopSplit = item.split('="');
                 this._qop = qopSplit[qopSplit.length - 1];
                 this._qop = this._qop.substring(0, this._qop.length - 1);
             }
-            if (item.indexOf('opaque=') >= 0) {
+            if (item.indexOf("opaque=") >= 0) {
                 let opaqueSplit = item.split('="');
                 this._opaque = opaqueSplit[opaqueSplit.length - 1];
                 this._opaque = this._opaque.substring(0, this._opaque.length - 1);
             }
-            if (item.indexOf('algorithm=') >= 0) {
-                let algorithmSplit = item.split('=');
+            if (item.indexOf("algorithm=") >= 0) {
+                let algorithmSplit = item.split("=");
                 this._algorithm = algorithmSplit[algorithmSplit.length - 1];
                 this._algorithm = this._algorithm.substring(0, this._algorithm.length);
-                if (this._onError && this.algorithm !== 'MD5') {
+                if (this._onError && this.algorithm !== "MD5") {
                     this._onError(`Algorithm ${this.algorithm} is ont supported. Only MD5 is supportet`);
                 }
             }
@@ -106,12 +106,12 @@ class AuthDigest {
     }
     getAuthorization(httpMethod, path) {
         if (!this._initialized)
-            return '';
+            return "";
         const nc = this.nc;
         const cnonce = this.cnonce;
-        let HA1 = this.md5(this.username + ':' + this.realm + ':' + this._password);
-        let HA2 = this.md5(httpMethod + ':' + path);
-        let response = this.md5(HA1 + ':' + this.nonce + ':' + nc + ':' + cnonce + ':' + this.qop + ':' + HA2);
+        let HA1 = this.md5(this.username + ":" + this.realm + ":" + this._password);
+        let HA2 = this.md5(httpMethod + ":" + path);
+        let response = this.md5(HA1 + ":" + this.nonce + ":" + nc + ":" + cnonce + ":" + this.qop + ":" + HA2);
         let res = `Digest username="${this.username}",`;
         res += `realm="${this.realm}",`;
         res += `nonce="${this.nonce}",`;

package/dist/Digest.js

@@ -33,7 +33,7 @@ class Digest {
     request(options, data, retryCount = 0, redirectCount = 0) {
         return new Promise((resolve, reject) => {
             var _a;
-            let resData = '';
+            let resData = "";
             if (!options.headers)
                 options.headers = {};
             options.headers.Authorization = (_a = this._authDigest) === null || _a === void 0 ? void 0 : _a.getAuthorization(options.method, options.path);
@@ -41,13 +41,13 @@ class Digest {
                 var _a, _b;
                 if (res.statusCode == 401) {
                     if (retryCount > 1) {
-                        reject('Authentication failed');
+                        reject("Authentication failed");
                         return;
                     }
                     retryCount++;
-                    const wwwAuth = res.headers['www-authenticate'];
-                    if (!wwwAuth.startsWith('Digest')) {
-                        reject('Unsupported authentication method. Supported authentication schemes: Digest');
+                    const wwwAuth = res.headers["www-authenticate"];
+                    if (!wwwAuth.startsWith("Digest")) {
+                        reject("Unsupported authentication method. Supported authentication schemes: Digest");
                         return;
                     }
                     (_a = this._authDigest) === null || _a === void 0 ? void 0 : _a.init(wwwAuth);
@@ -63,9 +63,8 @@ class Digest {
                     });
                 }
                 else if (res.statusCode >= 200 && res.statusCode < 300) {
-                    // myenergi asn redirect handler.
-                    const myenergiAsn = res.headers['x_myenergi-asn'];
-                    if (myenergiAsn && myenergiAsn !== 'undefined' && myenergiAsn !== this._baseUrl.host) {
+                    const myenergiAsn = res.headers["x_myenergi-asn"];
+                    if (myenergiAsn && myenergiAsn !== "undefined" && myenergiAsn !== this._baseUrl.host) {
                         if (redirectCount > 2) {
                             reject(`Too many redirects: ${myenergiAsn}`);
                             return;
@@ -83,21 +82,20 @@ class Digest {
                             reject(resaon);
                         });
                     }
-                    // Plain 200 handling
-                    res.setEncoding('utf8');
-                    res.on('data', (chunk) => {
+                    res.setEncoding("utf8");
+                    res.on("data", (chunk) => {
                         resData += chunk;
                     });
-                    res.on('end', () => {
+                    res.on("end", () => {
                         resolve(resData);
                     });
                 }
                 else if (res.statusCode >= 300 && res.statusCode < 400) {
                     if (redirectCount > 2) {
-                        reject(`Too many redirects: ${res.headers['location']}`);
+                        reject(`Too many redirects: ${res.headers["location"]}`);
                         return;
                     }
-                    const location = res.headers['location'];
+                    const location = res.headers["location"];
                     const uri = url.parse(location, true);
                     if (uri.host !== this._baseUrl.host) {
                         this._baseUrl.host = uri.host;
@@ -112,12 +110,12 @@ class Digest {
                     });
                 }
                 else {
-                    console.error('status code failed!!');
-                    reject('status code failed!!');
+                    console.error("status code failed!!");
+                    reject("status code failed!!");
                     return;
                 }
             });
-            req.on('error', (e) => {
+            req.on("error", (e) => {
                 console.error(`problem with request: ${e.message}`);
                 reject(e);
             });
@@ -134,11 +132,11 @@ class Digest {
             host: this._baseUrl.host,
             port: this._baseUrl.port,
             path: uri.path,
-            method: 'GET',
+            method: "GET",
             headers: {
-                Connection: 'Keep-Alive',
-                'Content-Type': 'application/json',
-                Accept: 'application/json',
+                Connection: "Keep-Alive",
+                "Content-Type": "application/json",
+                Accept: "application/json",
                 Host: uri.hostname,
             },
         };

package/dist/MyEnergi.d.ts

@@ -1,7 +1,7 @@
-import { Eddi } from './models/Eddi';
-import { Harvi } from './models/Harvi';
-import { EddiBoost, EddiMode, ZappiBoostMode, ZappiChargeMode } from './models/Types';
-import { Zappi } from './models/Zappi';
+import { Eddi } from "./models/Eddi";
+import { Harvi } from "./models/Harvi";
+import { EddiBoost, EddiMode, ZappiBoostMode, ZappiChargeMode } from "./models/Types";
+import { Zappi } from "./models/Zappi";
 export declare class MyEnergi {
     private _config;
     private _digest;

package/dist/MyEnergi.js

@@ -15,19 +15,18 @@ const Types_1 = require("./models/Types");
 class MyEnergi {
     constructor(username, password) {
         this._config = {
-            username: '',
-            password: '',
-            base_url: 'https://s18.myenergi.net',
-            eddi_url: '/cgi-jstatus-E',
-            zappi_url: '/cgi-jstatus-Z',
-            harvi_url: '/cgi-jstatus-H',
-            status_url: '/cgi-jstatus-*',
-            dayhour_url: '/cgi-jdayhour-',
-            zappi_mode_url: '/cgi-zappi-mode-Z',
-            zappi_min_green_url: '/cgi-set-min-green-Z',
-            eddi_mode_url: '/cgi-eddi-mode-E',
-            eddi_boost_url: '/cgi-eddi-boost-E'
-            //https://s18.myenergi.net/cgi-jdayhour-Znnnnnnnn-YYYY-MM-DD
+            username: "",
+            password: "",
+            base_url: "https://s18.myenergi.net",
+            eddi_url: "/cgi-jstatus-E",
+            zappi_url: "/cgi-jstatus-Z",
+            harvi_url: "/cgi-jstatus-H",
+            status_url: "/cgi-jstatus-*",
+            dayhour_url: "/cgi-jdayhour-",
+            zappi_mode_url: "/cgi-zappi-mode-Z",
+            zappi_min_green_url: "/cgi-set-min-green-Z",
+            eddi_mode_url: "/cgi-eddi-mode-E",
+            eddi_boost_url: "/cgi-eddi-boost-E",
         };
         this._config.username = username;
         this._config.password = password;
@@ -75,11 +74,11 @@ class MyEnergi {
             return jsonData;
         });
     }
-    setZappiBoostMode(serialNo, boostMode, kwh = 0, completeTime = '0000') {
+    setZappiBoostMode(serialNo, boostMode, kwh = 0, completeTime = "0000") {
         return __awaiter(this, void 0, void 0, function* () {
             if (boostMode === Types_1.ZappiBoostMode.Stop) {
                 kwh = 0;
-                completeTime = '0000';
+                completeTime = "0000";
             }
             const url = `${this._config.zappi_mode_url}${serialNo}-0-${boostMode}-${kwh}-${completeTime}`;
             const data = yield this._digest.get(url);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { Eddi } from './models/Eddi';
-import { Harvi } from './models/Harvi';
-import { EddiBoost, EddiHeaterStatus, EddiMode, ZappiBoostMode, ZappiChargeMode } from './models/Types';
-import { Zappi } from './models/Zappi';
-import { MyEnergi } from './MyEnergi';
-export { MyEnergi, Eddi, Zappi, Harvi, EddiBoost, EddiMode, EddiHeaterStatus, ZappiBoostMode, ZappiChargeMode };
+import { Eddi } from "./models/Eddi";
+import { Harvi } from "./models/Harvi";
+import { EddiBoost, EddiHeaterStatus, EddiMode, ZappiBoostMode, ZappiChargeMode, ZappiStatus } from "./models/Types";
+import { Zappi } from "./models/Zappi";
+import { MyEnergi } from "./MyEnergi";
+export { MyEnergi, Eddi, Zappi, Harvi, EddiBoost, EddiMode, EddiHeaterStatus, ZappiBoostMode, ZappiChargeMode, ZappiStatus };

package/dist/index.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZappiChargeMode = exports.ZappiBoostMode = exports.EddiHeaterStatus = exports.EddiMode = exports.EddiBoost = exports.MyEnergi = void 0;
+exports.ZappiStatus = exports.ZappiChargeMode = exports.ZappiBoostMode = exports.EddiHeaterStatus = exports.EddiMode = exports.EddiBoost = exports.MyEnergi = void 0;
 const Types_1 = require("./models/Types");
 Object.defineProperty(exports, "EddiBoost", { enumerable: true, get: function () { return Types_1.EddiBoost; } });
 Object.defineProperty(exports, "EddiHeaterStatus", { enumerable: true, get: function () { return Types_1.EddiHeaterStatus; } });
 Object.defineProperty(exports, "EddiMode", { enumerable: true, get: function () { return Types_1.EddiMode; } });
 Object.defineProperty(exports, "ZappiBoostMode", { enumerable: true, get: function () { return Types_1.ZappiBoostMode; } });
 Object.defineProperty(exports, "ZappiChargeMode", { enumerable: true, get: function () { return Types_1.ZappiChargeMode; } });
+Object.defineProperty(exports, "ZappiStatus", { enumerable: true, get: function () { return Types_1.ZappiStatus; } });
 const MyEnergi_1 = require("./MyEnergi");
 Object.defineProperty(exports, "MyEnergi", { enumerable: true, get: function () { return MyEnergi_1.MyEnergi; } });

package/dist/models/Types.d.ts

@@ -30,3 +30,11 @@ export declare enum ZappiChargeMode {
     Eco = 2,
     EcoPlus = 3
 }
+export declare enum ZappiStatus {
+    EvDisconnected = "A",
+    EvConnected = "B1",
+    WaitingForEv = "B2",
+    EvReadyToCharge = "C1",
+    Charging = "C2",
+    Fault = "F"
+}

package/dist/models/Types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZappiChargeMode = exports.ZappiBoostMode = exports.EddiMode = exports.EddiHeaterStatus = exports.EddiBoost = void 0;
+exports.ZappiStatus = exports.ZappiChargeMode = exports.ZappiBoostMode = exports.EddiMode = exports.EddiHeaterStatus = exports.EddiBoost = void 0;
 var EddiBoost;
 (function (EddiBoost) {
     EddiBoost["CancelHeater1"] = "1-1";
@@ -38,3 +38,12 @@ var ZappiChargeMode;
     ZappiChargeMode[ZappiChargeMode["Eco"] = 2] = "Eco";
     ZappiChargeMode[ZappiChargeMode["EcoPlus"] = 3] = "EcoPlus";
 })(ZappiChargeMode = exports.ZappiChargeMode || (exports.ZappiChargeMode = {}));
+var ZappiStatus;
+(function (ZappiStatus) {
+    ZappiStatus["EvDisconnected"] = "A";
+    ZappiStatus["EvConnected"] = "B1";
+    ZappiStatus["WaitingForEv"] = "B2";
+    ZappiStatus["EvReadyToCharge"] = "C1";
+    ZappiStatus["Charging"] = "C2";
+    ZappiStatus["Fault"] = "F";
+})(ZappiStatus = exports.ZappiStatus || (exports.ZappiStatus = {}));

package/dist/models/Zappi.d.ts

@@ -40,9 +40,9 @@ export interface Zappi {
     tbk: number;
     tbm: number;
     zmo: number;
-    zs: number;
     rdc: number;
     rac: number;
     rrac: number;
+    zs: number;
     zsl: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "myenergi-api",
-    "version": "0.9.2",
+    "version": "1.0.2",
     "description": "NodeJS implementation of MyEnergi API for controlling Zappi, Eddi and other MyEnergi products",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
     "scripts": {
         "build": "tsc",
         "test": "env TS_NODE_PROJECT='tsconfig.testing.json' mocha -r ts-node/register tests/**/*-spec.ts",
-        "format": "prettier --write \"src/**/*.ts\" \"src/**/*.js\"",
+        "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
         "lint": "tslint -p tsconfig.json",
         "prepare": "tsc",
         "preversion": "npm test",