From 497750d0e9634f2e529d47912da2e33c70278275 Mon Sep 17 00:00:00 2001 From: MyHomeMyData Date: Fri, 1 Nov 2024 18:41:42 +0100 Subject: [PATCH 1/2] Updated package-lock --- package-lock.json | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/package-lock.json b/package-lock.json index ecaeda6..045f40b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "0.1.6", "license": "MIT", "dependencies": { - "@iobroker/adapter-core": "^3.1.6", + "@iobroker/adapter-core": "^3.2.2", "express": "^4.21.1" }, "devDependencies": { @@ -1088,15 +1088,15 @@ } }, "node_modules/@iobroker/adapter-core": { - "version": "3.1.6", - "resolved": "https://registry.npmjs.org/@iobroker/adapter-core/-/adapter-core-3.1.6.tgz", - "integrity": "sha512-cArv8IzVsP3r8HivsYwO02e5WueboIH9v66PkHSGtadeUQQKUyxV32dzirM6YArWcI6+Iw5USQgVR9E+ryP3xg==", + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/@iobroker/adapter-core/-/adapter-core-3.2.2.tgz", + "integrity": "sha512-Cuiga42WRkJ/NduyrIGgSVWpLgD6ihIflIvZiWVThwgWfDyI+Okgw3snVSlf/p4ki6BAr3MH6Dfa0qPySCGWvQ==", "license": "MIT", "engines": { - "npm": ">=7.0.0" + "node": ">=16" }, "peerDependencies": { - "@iobroker/types": "^6.0.0" + "@iobroker/types": "^6.0.11" } }, "node_modules/@iobroker/adapter-dev": { @@ -1182,9 +1182,9 @@ } }, "node_modules/@iobroker/types": { - "version": "6.0.10", - "resolved": "https://registry.npmjs.org/@iobroker/types/-/types-6.0.10.tgz", - "integrity": "sha512-3OT4a4QbLuWujobiea+zWA5JIksVdf0diZYzxcEv8W5BuvV5DUR3HlCUzXhLfF6X8Jgc+uFt3wRQ1s+m9v4/aw==", + "version": "6.0.11", + "resolved": "https://registry.npmjs.org/@iobroker/types/-/types-6.0.11.tgz", + "integrity": "sha512-RNDURjtL5Cm9wt6ocCqdRi86Qx1350zBIvvrJ9+Fjgasoi6cWCdoOghkwEeb95TH2j//q/uLqWwL8SZ0vxx6Kw==", "license": "MIT", "peer": true, "engines": { From 5583dd8a55ef84c648946920ef35c33db6db1e84 Mon Sep 17 00:00:00 2001 From: MyHomeMyData Date: Wed, 6 Nov 2024 14:48:15 +0100 Subject: [PATCH 2/2] Updated readme. Added sections Templates and Reference. --- README.md | 69 +++++++++++++++++++++++--------- templates/flexchartsTemplate1.js | 8 ++-- templates/flexchartsTemplate2.js | 4 +- 3 files changed, 57 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 1366a86..a9064e5 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ # Basic concept There are several adapters available to view charts within ioBroker. As far as I know, all of them are using a UI to configure content and options of the charts. Typically not all features of the used graphical sub system could be used in this way. E.g. it's not possible to view fully featured stacked charts with eChart-Adapter. -This adapter uses a different approach. It brings the complete feature set of [Apache ECharts](https://echarts.apache.org/en/index.html) to ioBroker. Take a look the [demo charts](https://echarts.apache.org/examples/en/index.html). +This adapter uses a different approach. It brings almost the complete feature set of [Apache ECharts](https://echarts.apache.org/en/index.html) to ioBroker. Take a look to the [demo charts](https://echarts.apache.org/examples/en/index.html). Remark: Adapter was not tested on MacOS, yet. @@ -43,6 +43,7 @@ Remark: Adapter was not tested on MacOS, yet. ``` flexchart adapter will then show this chart: + ![flexcharts_stacked1](https://github.com/user-attachments/assets/7cf6dfab-ddad-4b2f-a1e1-20fa4b876b4c) Typically you will use Blockly or javascript to create and update content of this state. @@ -50,15 +51,15 @@ Typically you will use Blockly or javascript to create and update content of thi There is another possibility to directly hand over eCharts-data via callback function within javascript. For details see below. To be clear: This approach is not intended to be used to quickly create a simple chart. -But if you have a very specific idea in mind for a more complex chart, flexcharts offers the possibility to implement it. +But if you have a specific idea in mind for a more complex chart, flexcharts offers the possibility to implement it. # Getting started ### Using the adapter -This adapter brings it's functionality as a web extension. Therefore it is mandatory to have installed and running the [web adapter](https://www.iobroker.net/#en/adapters/adapterref/iobroker.ws/README.md) (`web.0`). It's assumed you're using the standard port 8082 for web adapter. +This adapter brings it's functionality as a web extension. Therefore it is mandatory to have installed and running the [web adapter](https://www.iobroker.net/#en/adapters/adapterref/iobroker.ws/README.md) (`web.0`). In this readme it's assumed you're using the standard port 8082 for web adapter. -Wenn flexcharts adapter is active you can access it via http://localhost:8082/flexcharts/echarts.html (replace `localhost` by address of your ioBroker server). +When flexcharts adapter is active you can access it via http://localhost:8082/flexcharts/echarts.html (replace `localhost` by address of your ioBroker server). You may use this address in iFrame widgets of vis or jarvis or other visualizations. Of course you can also use it directly in a browser tab. @@ -66,13 +67,11 @@ To make it work, you have to provide additional parameters to tell the adapter a * `source=state` => You provide chart data in an ioBroker state (json) * `source=script` => You provide chart data via a script (javascript or blockly) -There is a built-in demo chart available: http://localhost:8082/flexcharts/echarts.html?source=state&id=flexcharts.0.info.chart1 - -To use dark mode of ECharts add `&darkmode`, e.g. http://localhost:8082/flexcharts/echarts.html?source=state&id=flexcharts.0.info.chart1&darkmode +There are additional options available, pls. refer to [reference section](#reference) -To enable a regulary refresh of chart use option `&refresh`, e.g. http://localhost:8082/flexcharts/echarts.html?source=state&id=flexcharts.0.info.chart1&refresh=15 to refresh chart ervery 15 seconds. Minumum value is 5 seconds. Defaults to 60 seconds. +To check for correct installation of adapter use built-in demo chart: http://localhost:8082/flexcharts/echarts.html?source=state&id=flexcharts.0.info.chart1 -### Use ioBroker state as source for an echart +### Use ioBroker state as source for an eChart Example: `http://localhost:8082/flexcharts/echarts.html?source=state&id=0_userdata.0.echarts.chart1` @@ -83,14 +82,16 @@ Example: http://localhost:8082/flexcharts/echarts.html? { - console.log(`data = ${JSON.stringify(data)}`); +onMessage('flexcharts', (httpParams, callback) => { + const myJsonParams = (httpParams.myjsonparams ? JSON.parse(httpParams.myjsonparams) : {} ); + console.log(`httpParams = ${JSON.stringify(httpParams)}`); + console.log(`myJsonParams = ${JSON.stringify(myJsonParams)}`); chart1(result => callback(result)); }); @@ -127,15 +128,46 @@ Start the script and access this in a browser: http://localhost:8082/flexcharts/ Same chart should show up as in previous example. +You should get two log entries of the example script: +``` +httpParams = {"message":"mylinechart","source":"script"} +myJsonParams = {} +``` + +Additional paramters can be forwarded to the script and will be available within the script in variable `httpParams`. Try following command: `http://localhost:8082/flexcharts/echarts.html?source=script&chart=chart1&myjsonparams={"period":"daily"}` + +Log entries now should look like this: +``` +httpParams = {"source":"script","chart":"chart1","myjsonparams":"{\"period\":\"daily\"}"}` +myJsonParams = {"period":"daily"} +``` + Pls. note, **you have to use the `onMessage()` functionality to receive the trigger from the adapter**. Default vaule for the message is `flexcharts` as shown in example above. You may use different messages by providing an additional parameter, e.g. to use message `mycharts` add `&message=mycharts` to http address: `http://localhost:8082/flexcharts/echarts.html?source=script&message=mycharts` -Additional paramters can be forwarded to the script and will be available within the script in variable `data`. Try following command: `http://localhost:8082/flexcharts/echarts.html?source=script&chart=chart1¶ms={"period":"daily"}` +## Templates +Javascript templates are available for some uses cases: +* chart using data from history adapter: [template1](templates/flexchartsTemplate1.js) +* simple chart for a heat curve: [template2](templates/flexchartsTemplate2.js) +* a very specific use case is available for Viessmann devices of E3 series, e.g. heat pump Vitocal 250. Refer to https://github.com/MyHomeMyData/ioBroker.e3oncan/discussions/35 + +## Reference + +Use **ioBroker state** as data source: `http://localhost:8082/flexcharts/echarts.html?source=state&id=my_state_id` + +Use **javascript** as data source: `http://localhost:8082/flexcharts/echarts.html?source=script` + +### Optional arguments +* `&message=my_message` - sends "my_message" to javascript. Use `onMessage('my_message', (httpParams, callback) => { callback(mychart); })` to provide chart data. Defaults to `flexcharts`. +* `&darkmode` - activates dark mode visualization of ECharts. +* `&refresh=number` - do a refresh of chart ervery "number" seconds. Defaults to 60 seconds. Minimum allowed value is 5 seconds. +* `&user_defined_arguments` - Add more parameters as per your need. All arguments are available within function `onMessage()` in object `httpParams`. See examples above and templates for more details. + +### Built-in demo chart +There is a built-in demo chart available: http://localhost:8082/flexcharts/echarts.html?source=state&id=flexcharts.0.info.chart1 -This should give a log entry in the example script: `data = {"source":"script","chart":"chart1","params":"{\"period\":\"daily\"}"}` +This should bring up a demo chart, when flexcharts- and web-adapter are running. -I'm working on more elaborated javascript templates to simplify usage of the adapter. A [first template](templates/flexchartsTemplate1.js) is available, see folder templates. -A very specific use case is available for Viessmann devices of E3 series, e.g. heat pump Vitocal 250. Refer to https://github.com/MyHomeMyData/ioBroker.e3oncan/discussions/35 -More to come. Stay tuned. +**Note:** Replace `localhost` by address of your ioBroker server. Replace `8082` by port number used by your Web-Adapter. ## Changelog ### **WORK IN PROGRESS** +* (MyHomeMyData) Updated readme. Added sections Templates and Reference. * (MyHomeMyData) Fix for issue #41 (findings of repository checker) * (MyHomeMyData) Updated ECharts to version 5.5.1, see issue #40 * (MyHomeMyData) Fix for issue #39 (html warnings) diff --git a/templates/flexchartsTemplate1.js b/templates/flexchartsTemplate1.js index a134f26..4076306 100644 --- a/templates/flexchartsTemplate1.js +++ b/templates/flexchartsTemplate1.js @@ -21,7 +21,7 @@ Implemented periods: "daily", "monthly", "yearly" */ -// 22.10.2024 MyHomeMyData +// 06.11.2024 MyHomeMyData const instanceHistory = 'history.0'; // Instance of history adapter to be used @@ -33,12 +33,12 @@ const paramKeysAllowed = ['period','start']; // List of alle allowed parameter k const DEBUG = 1; // Set to non zero value to get additional log entries. -onMessage('flexchartsdemo', (data, callback) => { +onMessage('flexchartsdemo', (httpParams, callback) => { // Waiting for messages "flexchartsdemo". Will be sent by adapter flexcharts. // Evaluate http parameters and create requested chart // In case of invalid or missing parameters create demo- or error-chart - const chart = data.chart; - const params = (data.params ? JSON.parse(data.params) : {} ); + const chart = httpParams.chart; + const params = (httpParams.params ? JSON.parse(httpParams.params) : {} ); // Check paramter keys: for (const p of Object.keys(params)) { diff --git a/templates/flexchartsTemplate2.js b/templates/flexchartsTemplate2.js index 050f789..ed27361 100644 --- a/templates/flexchartsTemplate2.js +++ b/templates/flexchartsTemplate2.js @@ -21,13 +21,13 @@ Adapt 'localhost' and '8082' according to your needs */ -// 22.10.2024 MyHomeMyData +// 06.11.2024 MyHomeMyData const instanceHistory = 'influxdb.0'; // Instance of history adapter to be used const tsScriptStart = new Date().getTime(); // Remember time stamp of start of this script -onMessage('mylinechart', (data, callback) => { +onMessage('mylinechart', (httpParams, callback) => { // Waiting for messages "mylinechart". Will be sent by adapter flexcharts. lineChart(callback); });