{"id":15692623,"url":"https://github.com/jedie/pysmartmeter","last_synced_at":"2025-07-31T05:08:06.425Z","repository":{"id":63432821,"uuid":"564415568","full_name":"jedie/pysmartmeter","owner":"jedie","description":"Collect data from Hitchi Smartmeter and expose it via MQTT","archived":false,"fork":false,"pushed_at":"2025-05-06T20:13:22.000Z","size":383,"stargazers_count":8,"open_issues_count":9,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-09T06:42:48.749Z","etag":null,"topics":["energy-consumption","energy-monitor","homeassistant","mqtt","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jedie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-10T17:07:22.000Z","updated_at":"2025-06-22T08:43:46.000Z","dependencies_parsed_at":"2024-01-01T18:27:36.956Z","dependency_job_id":"e32f1df0-cb27-466a-b6f4-a4d913f6619f","html_url":"https://github.com/jedie/pysmartmeter","commit_stats":{"total_commits":82,"total_committers":3,"mean_commits":"27.333333333333332","dds":"0.024390243902439046","last_synced_commit":"ce1f35c5d2b7a2a1385cef1118ab3e72aa6d49c9"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/jedie/pysmartmeter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fpysmartmeter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fpysmartmeter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fpysmartmeter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fpysmartmeter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jedie","download_url":"https://codeload.github.com/jedie/pysmartmeter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fpysmartmeter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267988948,"owners_count":24177018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["energy-consumption","energy-monitor","homeassistant","mqtt","python"],"created_at":"2024-10-03T18:36:40.571Z","updated_at":"2025-07-31T05:08:06.393Z","avatar_url":"https://github.com/jedie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pysmartmeter\n\n[![tests](https://github.com/jedie/pysmartmeter/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/jedie/pysmartmeter/actions/workflows/tests.yml)\n[![codecov](https://codecov.io/github/jedie/pysmartmeter/branch/main/graph/badge.svg)](https://app.codecov.io/github/jedie/pysmartmeter)\n[![pysmartmeter @ PyPi](https://img.shields.io/pypi/v/pysmartmeter?label=pysmartmeter%20%40%20PyPi)](https://pypi.org/project/pysmartmeter/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/pysmartmeter)](https://github.com/jedie/pysmartmeter/blob/main/pyproject.toml)\n[![License GPL-3.0-or-later](https://img.shields.io/pypi/l/pysmartmeter)](https://github.com/jedie/pysmartmeter/blob/main/LICENSE)\n\n\nCollect data from Hichi Smartmeter aka `volkszaehler.org` (USB Version) and expose it via MQTT.\n\nDiscussion: https://www.photovoltaikforum.com/thread/188160-pysmartmeter (de)\n\nIn the end it can looks like the following [Home Assistant](https://www.home-assistant.io/) dashboard screenshot, using [MQTT integration](https://www.home-assistant.io/integrations/mqtt):\n\n![2023-02-26_17-39.png](https://raw.githubusercontent.com/jedie/jedie.github.io/master/screenshots/pysmartmeter/2023-02-26_17-39.png \"2023-02-26_17-39.png\")\n\nWith my \"eBZ DD3\" energy meter by eBZ GmbH the values update live every second ;)\n\n\nCurrently only energy meters that send [OBIS text protocol](https://wiki.volkszaehler.org/software/obis) are supported! (Test this with `./cli.py dump`)\n\nTODO: [#37 - Add support for SML (Smart Message Language) binary protocol](https://github.com/jedie/pysmartmeter/issues/37)\n\n\n## quickstart\n\n### prepare\n\nInstall minimum requirements, e.g.:\n```bash\n~$ sudo apt install python3-venv\n```\n\nNote: If you using a Raspberry Pi: Check that https://www.piwheels.org/ are in use.\nFor this, just look into `etc/pip.conf` it should be looked like this:\n```bash\n~/pysmartmeter$ cat /etc/pip.conf\n[global]\nextra-index-url=https://www.piwheels.org/simple\n```\n\n\n### clone and start\n\nClone sources and install project:\n```bash\n~$ git clone https://github.com/jedie/pysmartmeter.git\n~$ cd pysmartmeter\n~/pysmartmeter$ ./cli.py --help\n```\n\nThe output of `./cli.py --help` looks like:\n\n[comment]: \u003c\u003e (✂✂✂ auto generated main help start ✂✂✂)\n```\nusage: ./cli.py [-h]\n                {debug-settings,edit-settings,publish-loop,systemd-debug,systemd-remove,systemd-setup,systemd-status,s\nystemd-stop,version}\n\n\n\n╭─ options ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ -h, --help        show this help message and exit                                                                  │\n╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n╭─ subcommands ──────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ {debug-settings,edit-settings,publish-loop,systemd-debug,systemd-remove,systemd-setup,systemd-status,systemd-stop, │\n│ version}                                                                                                           │\n│     debug-settings                                                                                                 │\n│                   Display (anonymized) MQTT server username and password                                           │\n│     edit-settings                                                                                                  │\n│                   Edit the settings file. On first call: Create the default one.                                   │\n│     publish-loop  Publish all values via MQTT to Home Assistant in a endless loop.                                 │\n│     systemd-debug                                                                                                  │\n│                   Print Systemd service template + context + rendered file content.                                │\n│     systemd-remove                                                                                                 │\n│                   Stops the systemd service and removed the service file. (May need sudo)                          │\n│     systemd-setup                                                                                                  │\n│                   Write Systemd service file, enable it and (re-)start the service. (May need sudo)                │\n│     systemd-status                                                                                                 │\n│                   Display status of systemd service. (May need sudo)                                               │\n│     systemd-stop  Stops the systemd service. (May need sudo)                                                       │\n│     version       Print version and exit                                                                           │\n╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n[comment]: \u003c\u003e (✂✂✂ auto generated main help end ✂✂✂)\n\nTest if you Hichi Smartmeter with CP2102 USB to UART Bridge Controller will be found, e.g.:\n```bash\n~/pysmartmeter$ ./cli.py detect-serial\n```\n\nNote: It's a good idea to use the `/dev/serial/by-id/{your-device-id}` path as serial port, instead of `/dev/ttyUSB1`\nCall `udevadm info -n /dev/ttyUSB*` to get information about all USB serial devices and `ls -l /dev/serial/by-id/` to see the existing links.\n\nMaybe you didn't have permissions to access the port, e.g.:\n```bash\n~/pysmartmeter$ ./cli.py dump\n...\ntry: /dev/ttyUSB0 CP2102 USB to UART Bridge Controller - CP2102 USB to UART Bridge Controller USB VID:PID=10C4:EA60\n/dev/ttyUSB0 file mode: 0o20660\n/dev/ttyUSB0 user ID: 0\n/dev/ttyUSB0 user group ID: 20\n/dev/ttyUSB0 user group: 'dialout'\nERROR: [Errno 13] could not open port /dev/ttyUSB0: [Errno 13] Permission denied: '/dev/ttyUSB0'\n...\n```\n\nFix fiy by add the user to the group, e.g.:\n```bash\nsudo usermod -a -G dialout $USER\n```\n\n## publish smartmeter data via MQTT\n\nYou have to store your MQTT settings (host, port, username, password) one time, e.g.:\n```bash\n~/pysmartmeter$ ./cli.py store-settings\n```\nThis will create a JSON file here: `~/.pysmartmeter`\n\nYou can test reading this settings file with:\n```bash\n~/pysmartmeter$ ./cli.py debug-settings\n```\n\nTest your MQTT settings with:\n```bash\n~/pysmartmeter$ ./cli.py test-mqtt-connection\n```\n\nSetup systemd service:\n```bash\n~/pysmartmeter$ sudo ./cli.py setup-systemd-service\n```\nThis will create a systemd service that automaticly starts on every boot.\n\nNote: Before you start the systemd service, check if everything works correctly with `./cli.py dump` and `./cli.py publish-loop`\nOtherwise you may start a services that will just deal wie gabage (e.g.: your energy meters speaks no OBIS text protocol) and restarts on and on again ;)\n\n\nCheck if service is running:\n```bash\n~/pysmartmeter$ sudo ./cli.py systemd-status\n```\n\nIf everything is fine: Go to your [Home Assistant and check the MQTT integration](https://www.home-assistant.io/integrations/mqtt/)\nThe device discovery will be made automaticly.\n\n\n# Troubleshooting\n\nIf you have any trouble, try to recreate the Python Virtual Environment first.\nFor this, just delete it and start the CLI to recreate it, e.g.:\n```bash\n~/pysmartmeter$ rm -Rf .venv-app/\n~/pysmartmeter$ ./cli.py\n```\n\n\n# Start hacking\n\n```bash\n~$ git clone https://github.com/jedie/pysmartmeter.git\n~$ cd pysmartmeter\n~/pysmartmeter$ ./dev-cli.py --help\n```\n\n\n[comment]: \u003c\u003e (✂✂✂ auto generated dev help start ✂✂✂)\n```\nusage: ./dev-cli.py [-h]\n                    {check-code-style,coverage,fix-code-style,install,mypy,nox,pip-audit,publish,test,update,update-re\nadme-history,update-test-snapshot-files,version}\n\n\n\n╭─ options ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ -h, --help        show this help message and exit                                                                  │\n╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n╭─ subcommands ──────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ {check-code-style,coverage,fix-code-style,install,mypy,nox,pip-audit,publish,test,update,update-readme-history,upd │\n│ ate-test-snapshot-files,version}                                                                                   │\n│     check-code-style                                                                                               │\n│                   Check code style by calling darker + flake8                                                      │\n│     coverage      Run tests and show coverage report.                                                              │\n│     fix-code-style                                                                                                 │\n│                   Fix code style of all pysmartmeter source code files via darker                                  │\n│     install       Install requirements and 'pysmartmeter' via pip as editable.                                     │\n│     mypy          Run Mypy (configured in pyproject.toml)                                                          │\n│     nox           Run nox                                                                                          │\n│     pip-audit     Run pip-audit check against current requirements files                                           │\n│     publish       Build and upload this project to PyPi                                                            │\n│     test          Run unittests                                                                                    │\n│     update        Update \"requirements*.txt\" dependencies files                                                    │\n│     update-readme-history                                                                                          │\n│                   Update project history base on git commits/tags in README.md Will be exited with 1 if the        │\n│                   README.md was updated otherwise with 0.                                                          │\n│                                                                                                                    │\n│                   Also, callable via e.g.:                                                                         │\n│                       python -m cli_base update-readme-history -v                                                  │\n│     update-test-snapshot-files                                                                                     │\n│                   Update all test snapshot files (by remove and recreate all snapshot files)                       │\n│     version       Print version and exit                                                                           │\n╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n[comment]: \u003c\u003e (✂✂✂ auto generated dev help end ✂✂✂)\n\n\n# various links\n\n* Discussion: https://www.photovoltaikforum.com/thread/188160-pysmartmeter (de)\n* https://github.com/pyserial/pyserial\n* https://github.com/eclipse/paho.mqtt.python\n* https://github.com/eclipse/mosquitto\n* https://dewiki.de/Lexikon/OBIS-Kennzahlen (de) | https://www.promotic.eu/en/pmdoc/Subsystems/Comm/PmDrivers/IEC62056_OBIS.htm (en)\n* https://www.photovoltaikforum.com/thread/145886-habe-lesk%C3%B6pfe-mit-usb-%C3%BCber/ (de)\n* https://www.heise.de/tests/Ausprobiert-Guenstiger-IR-Lesekopf-fuer-Smart-Meter-mit-Tastmota-Firmware-7065559.html (de)\n* https://www.home-assistant.io\n\n\n# Backwards-incompatible changes\n\n## v0.4.x -\u003e v0.5.x\n\nWe split the CLI files into:\n\n* `./cli.py` - Commands for end users\n* `./dev-cli.py` - Commands for developers\n\n## v0.2.x -\u003e v0.3.x\n\nPackages changes:\n\n* We switched from `poetry` to `pip-tools`\n* `Makefile` was removed\n* \"Renamed\" `cli.sh` to `cli.py`\n\nThe `Makefile` is no longer needed, because \"Bootstrapping\" will be made, just by call `cli.py`\n\nTo migrate, just remove the existing `.venv` and create a fresh one, e.g.:\n```bash\n~$ cd pysmartmeter\n~/pysmartmeter$ git pull origin main\n~/pysmartmeter$ rm -Rf .venv\n~/pysmartmeter$ ./cli.py --help\n```\n\n\n# History\n\n[comment]: \u003c\u003e (✂✂✂ auto generated history start ✂✂✂)\n\n* [v0.6.0](https://github.com/jedie/pysmartmeter/compare/v0.5.0...v0.6.0)\n  * 2025-04-25 - Modernize Project\n  * 2024-01-17 - +typeguard\n  * 2024-01-17 - +\"flake8-bugbear\"\n  * 2024-01-01 - Update README.md\n  * 2023-12-29 - +# Troubleshooting\n  * 2023-12-29 - Add a note about https://www.piwheels.org/\n* [v0.5.0](https://github.com/jedie/pysmartmeter/compare/v0.4.1...v0.5.0)\n  * 2023-12-29 - cleanup pyproject.toml and cli scripts\n  * 2023-12-29 - Move BaseTestCase\n  * 2023-12-29 - Apply manageprojects updates\n  * 2023-06-05 - Update README.md\n  * 2023-05-27 - Split CLI into: cli.py and dev-cli.py\n* [v0.4.1](https://github.com/jedie/pysmartmeter/compare/v0.4.0...v0.4.1)\n  * 2023-03-09 - Ignore empty input lines and add expand OBIS map\n* [v0.4.0](https://github.com/jedie/pysmartmeter/compare/v0.3.4...v0.4.0)\n  * 2023-03-08 - mock version\n  * 2023-03-08 - update requirements\n  * 2023-03-08 - Bump version to 0.4.0\n  * 2023-03-07 - Fix#32 add \"test-mqtt-connection\" CLI command\n\n\u003cdetails\u003e\u003csummary\u003eExpand older history entries ...\u003c/summary\u003e\n\n* [v0.3.4](https://github.com/jedie/pysmartmeter/compare/v0.3.3...v0.3.4)\n  * 2023-02-26 - Update README.md\n  * 2023-02-26 - Set HA device class \"voltage\" for voltage entries\n  * 2023-02-26 - Add test with HomeAssistantMqtt + ObisParser\n  * 2023-02-26 - Add a test snapshot with the full RAW_TEST_DATA_BIG\n* [v0.3.3](https://github.com/jedie/pysmartmeter/compare/v0.3.2...v0.3.3)\n  * 2023-02-26 - Enhance \"detect-serial\"\n  * 2023-02-26 - Update README.md\n* [v0.3.2](https://github.com/jedie/pysmartmeter/compare/v0.3.1...v0.3.2)\n  * 2023-02-26 - Bugfix \"publish-loop\" CLI command and add tests for it\n  * 2023-02-26 - Display systemd config file, after create / before status\n* [v0.3.1](https://github.com/jedie/pysmartmeter/compare/v0.3.0...v0.3.1)\n  * 2023-02-26 - Use publish_package() from manageprojects\n* [v0.3.0](https://github.com/jedie/pysmartmeter/compare/v0.2.0...v0.3.0)\n  * 2023-02-26 - README: How to migrate from v0.2 to v0.3\n  * 2023-02-26 - Display systemd status after commands\n  * 2023-02-26 - unify systemd command error handling\n  * 2023-02-26 - Update README\n  * 2023-02-26 - Add \"systemd-restart\" to CLI\n  * 2023-02-26 - sudo info for systemd command\n  * 2023-02-24 - migrate form poetry to piptools via manageprojects\n  * 2023-02-26 - update tests\n  * 2023-02-25 - Update obis_map.py\n  * 2023-02-24 - Update README.md\n  * 2023-02-24 - +manageprojects\n  * 2023-02-24 - manageprojects updates\n  * 2023-02-24 - fix CI\n  * 2023-02-24 - Update requirements\n  * 2023-02-24 - Test credentials utilities\n  * 2023-02-24 - Bugfix Error store-settings #17\n* [v0.2.0](https://github.com/jedie/pysmartmeter/compare/v0.1.0...v0.2.0)\n  * 2022-12-18 - Fix #13: \"last_reset\" is missing (for Home Assistant)\n  * 2022-12-20 - Snapshot a complete configs/data MQTT payload for Home Assistant\n* [v0.1.0](https://github.com/jedie/pysmartmeter/compare/7d8631b...v0.1.0)\n  * 2022-12-10 - Update README.md\n  * 2022-11-24 - Fix #11 by disable logging in systemd daemon mode\n  * 2022-11-23 - fix typo: '1-0:76.7.0*255' is 'Momentane Leistung L3' ;)\n  * 2022-11-21 - Update README\n  * 2022-11-21 - Fix typo \"Hitchi\" -\u003e \"Hichi\"\n  * 2022-11-18 - Hit about permission errors\n  * 2022-11-18 - fix publish to PyPi\n  * 2022-11-18 - CLI: Build and upload this project to PyPi\n  * 2022-11-18 - fix tests\n  * 2022-11-18 - Implement MQTT publishing via systemd service\n  * 2022-11-14 - test code style + mypy\n  * 2022-11-14 - fix code style\n  * 2022-11-14 - setup CI\n  * 2022-11-14 - Bugfix 'identifier'\n  * 2022-11-14 - Don't use poetry in cli.sh\n  * 2022-11-14 - Add a way to setup the project without poetry\n  * 2022-11-13 - Add cli.sh\n  * 2022-11-13 - switch to poetry\n  * 2022-11-13 - cleanup\n  * 2022-11-13 - Add OBIS Parser\n  * 2022-11-10 - make serial-dump\n  * 2022-11-10 - switch to https://github.com/jedie/cookiecutter_templates/tree/main/pipenv-python\n  * 2022-11-10 - Add a simple dump serial output script\n  * 2022-11-10 - update project\n  * 2022-11-10 - init project\n  * 2022-11-10 - Initial commit\n\n\u003c/details\u003e\n\n\n[comment]: \u003c\u003e (✂✂✂ auto generated history end ✂✂✂)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedie%2Fpysmartmeter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjedie%2Fpysmartmeter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedie%2Fpysmartmeter/lists"}