{"id":13340,"library":"iobroker.echarts","title":"ioBroker ECharts Adapter","description":"ioBroker.echarts is an ioBroker adapter designed for building and displaying useful charts within the ioBroker smart home ecosystem. It leverages the powerful Apache ECharts library to render various chart types like line, bar, and radar charts. Currently at version 3.1.0, the adapter receives updates with moderate frequency, often including bug fixes, dependency updates, and minor feature enhancements. Key differentiators include its tight integration with ioBroker states, allowing data from various devices and services to be easily visualized. It supports data input from custom JSON states and offers server-side rendering capabilities to generate static chart images (SVG, PNG, JPG, PDF) for use in other applications or storage. The adapter also provides dedicated widgets for ioBroker Vis for easy chart embedding.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/ioBroker/ioBroker.echarts","tags":["javascript","charts","diagram","ioBroker"],"install":[{"cmd":"npm install iobroker.echarts","lang":"bash","label":"npm"},{"cmd":"yarn add iobroker.echarts","lang":"bash","label":"yarn"},{"cmd":"pnpm add iobroker.echarts","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ioBroker.echarts is an adapter. Programmatic interaction happens via the global `sendTo` function provided by the ioBroker host, not via direct JS module imports. The 'echarts.0' is the instance ID.","wrong":"import { generateChart } from 'iobroker.echarts'; // Incorrect: This package is an adapter, not a traditional JS library with direct exports.\nconst echartsAdapter = require('iobroker.echarts'); // Incorrect: Not a CommonJS module for direct programmatic use.","symbol":"sendTo","correct":"sendTo('echarts.0', { preset: 'echarts.0.myPreset', renderer: 'png', width: 800, height: 400 }, result => {\n  if (result.error) {\n    console.error(result.error);\n  } else {\n    console.log('Chart generated:', result.data);\n  }\n});"}],"quickstart":{"code":"/* Example of server-side chart rendering using sendTo */\n\n// Assuming 'echarts.0.myPreset' is a pre-configured chart preset in the ioBroker.echarts adapter.\n// You can create presets via the ioBroker admin interface for the echarts adapter.\n\nsendTo(\n    'echarts.0',\n    {\n        preset: 'echarts.0.myPreset', // The ID of your pre-defined chart preset\n        renderer: 'png',             // Output format: 'svg', 'png', 'jpg', 'pdf'\n        width: 1024,                 // Width of the generated image\n        height: 768,                 // Height of the generated image\n        background: '#FFFFFF',       // Background color (e.g., for PNG/JPG)\n        theme: 'light',              // Chart theme: 'light' or 'dark'\n        quality: 0.9,                // Quality for JPG renderer (0.0 - 1.0)\n        fileName: 'my_chart.png',    // Name to save the file in ioBroker DB (e.g., echarts.0/my_chart.png)\n        cache: 300                   // Cache time for this preset in seconds\n    },\n    result => {\n        if (result.error) {\n            console.error('Failed to render chart:', result.error);\n        } else {\n            console.log('Chart rendering successful. Data or file path:', result.data);\n            // result.data could be a base64 URL if fileName is not specified,\n            // or a confirmation if fileName is used to save to ioBroker DB.\n        }\n    }\n);\n\n// Example of updating a chart with data from a JSON state\n// This assumes you have a state '0_userdata.0.myCustomChartData' of type 'json'\n// and your chart preset is configured to use this state as a data source.\nconst customJsonStateId = '0_userdata.0.myCustomChartData';\nconst chartData = [\n    { \"ts\": Date.now() - 3600000, \"val\": 25 },\n    { \"ts\": Date.now() - 1800000, \"val\": 30 },\n    { \"ts\": Date.now(), \"val\": 28 }\n];\n\n// To update the chart, simply update the JSON state. The adapter will react to changes.\nsetState(customJsonStateId, JSON.stringify(chartData), true);\nconsole.log(`Updated state '${customJsonStateId}' with new chart data.`);\n","lang":"javascript","description":"Demonstrates how to programmatically request server-side chart rendering and how to update a chart by writing to an ioBroker JSON state."},"warnings":[{"fix":"Ensure your ioBroker host system is running Node.js version 20 or newer. Update Node.js if necessary using recommended ioBroker upgrade procedures.","message":"Starting with versions 3.0.0 and 3.0.1, ioBroker.echarts removed support for Node.js 18. The adapter now explicitly requires Node.js version 20 or higher.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Refer to the Sentry-Plugin Documentation (linked in the adapter's README) for instructions on how to disable this error reporting feature if desired.","message":"The adapter utilizes Sentry libraries for automatic error reporting. This sends exceptions and code errors to the developers. Users concerned about data privacy should be aware of this.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pre-process your data to include desired aggregations or specific time ranges before formatting it as JSON and writing it to the ioBroker state. Ensure 'ts', 'time', 't', or 'date' are used for timestamps and 'val', 'value', 'v', 'data', or 'y' for values in the JSON objects.","message":"When using JSON data sources for charts, the adapter automatically calculates start and end times from the provided data. Aggregation of values is not performed by the adapter; all data manipulation must be done before writing the JSON to the ioBroker state.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For touch devices, consider disabling zoom if legend interaction is critical, or provide alternative controls for data visibility outside the chart legend.","message":"Due to rendering limitations, it is not possible to enable or disable individual lines in the chart legend on touch devices when chart zoom functionality is enabled.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your ioBroker `js-controller` is updated to at least version 6.0.11 and the Admin adapter to at least 7.6.20. Update your `io-package.json` and `package.json` dependencies if you are developing or contributing to the adapter itself.","message":"Older versions of js-controller and admin adapter might cause compatibility issues. Recent checks indicate that js-controller 6.0.11 and admin 7.6.20 are required minimums for full compatibility, while `io-package.json` might list older dependencies.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Check your Node.js version (`node -v`) and ensure it's `>=20`. Run `iobroker fix` to correct permissions. Verify network connectivity to npm registries. Try `npm cache clean --force` and then retry installation.","cause":"Often due to an incompatible Node.js version, insufficient permissions, or network issues preventing package download.","error":"Cannot install iobroker.echarts@<version>... host.<hostname> Cannot install iobroker..."},{"fix":"Review your chart preset configuration in the ioBroker admin interface. Validate your JSON data structure, ensuring it contains valid `ts`/`time`/`t`/`date` for timestamps and `val`/`value`/`v`/`data`/`y` for values. Use a JSON validator to check syntax.","cause":"The ECharts preset might be misconfigured, or the JSON data provided to a state-based chart is malformed or uses incorrect key names.","error":"Error: No config provided. | Charts dont show the correct JSON value, when they showing them."},{"fix":"This often points to missing system-level dependencies for `node-canvas` or `jsdom`. Install required build tools and libraries for your OS (e.g., `sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev` on Debian/Ubuntu). Then, try reinstalling the adapter or running `npm rebuild` within the adapter's directory.","cause":"This error can occur during server-side rendering if underlying graphics libraries (like 'canvas' or 'jsdom') are missing or cannot be built on the host system.","error":"Cannot find required modules: looks like it is not possible to generate charts on your Hardware/OS"},{"fix":"Verify that the `echarts.0` adapter instance is running in the ioBroker admin interface. Double-check the `preset` ID in your `sendTo` call against your configured presets. Review the ioBroker logs for the `echarts.0` instance for more specific error messages related to the rendering request. Ensure all parameters in the `sendTo` payload are correct and valid.","cause":"The ioBroker.echarts adapter instance might not be running, the specified preset ID is incorrect, or there's an issue with the rendering parameters. The `sendTo` call itself might not fail, but the callback indicates an internal adapter error.","error":"sendTo('echarts.0', ...): Callback result.error is true or no data is received."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}