65 ready-to-use integrations for FHEM, written in Python. Now with Matter support.
Quick start · Matter · AI · Modules · Troubleshooting · Remote peers · Write your own module
✨ Why fhempy?
- Matter support: control Matter lights, plugs, sensors, thermostats, locks and blinds directly from FHEM, also devices behind Hue, IKEA or Aqara bridges. And the other way round: use your FHEM devices in Apple Home, Google Home and Alexa, with voice control. See Matter.
- Talk to FHEM with AI: ask Claude or a local AI model "switch off all lights when I leave the house" and it creates the DOIF for you, which you approve with one click. See AI.
- Lots of devices out of the box: Tuya, Xiaomi, Google Cast, Spotify, Zigbee2MQTT, ESPHome, solar inverters, cars, Bluetooth sensors and many more.
- No Python fiddling: fhempy sets up its own Python environment (even a newer Python if your system's is too old) and every module installs its libraries automatically the first time you use it.
- Feels like any other FHEM device:
define,set,get,attrand readings work as usual. - Extend your range: run modules on a remote Raspberry Pi, e.g. close to your Bluetooth devices.
🔗 Matter
fhempy brings Matter to FHEM. It installs and runs the same Matter server Home Assistant uses, no extra hardware or Docker needed:
define matter fhempy matter
set matter pair <code>
Use the pairing code printed on the device, or create one in Apple Home, Google Home or Alexa ("Connect to other apps"); the device keeps working there too. Every Matter device gets its own FHEM device with the matching commands (on, off, pct, ct, position, desired-temp, lock...) and readings. The Matter README explains every step, and the reading next_step always tells you what to do next.
Your FHEM devices in Apple Home, Google Home and Alexa: the Matter bridge makes FHEM devices available as Matter devices, so you can switch them in these apps and with Siri, Google Assistant/Gemini or Alexa. Everything stays local, no cloud account or gassistant-fhem/alexa-fhem setup needed:
define matterbridge fhempy matter_bridge
set matterbridge add Livingroom_Light
Then scan the QR code shown in FHEMWEB with your app. The Matter bridge README explains every step.
🤖 AI
Control FHEM in plain language with AI apps like Claude Desktop, Claude Code, LM Studio or Cursor:
define AI fhempy mcp_server
Copy the secret address shown in FHEMWEB into your AI app, then ask "Which lights are on?" or "Switch off all lights when I leave the house." Automations created by the AI wait for your approval, your passwords are never sent to the AI. The MCP server README explains every step.
🚀 Quick start
1. Install fhempy
Copy & paste this line into the FHEM command field and press enter:
{eval GetFileFromURL("https://raw.githubusercontent.com/fhempy/fhempy/master/install_fhempy.pl")}
That's it. FHEM downloads the fhempy files and creates fhempy_local, which sets up everything else on its own. No restart, no sudo and no system packages needed. A window shows the progress until fhempy is ready, the state of fhempy_local in the room fhempy shows it too:
Installing fhempy: 1/4 installing uvInstalling fhempy: 2/4 installing Python 3.13(only if your system Python is older)Installing fhempy: 3/4 installing fhempyInstalling fhempy: 4/4 starting fhempy
fhempy_local turns green with the fhempy version as soon as it's ready. If something goes wrong, the state shows the reason in red.
When fhempy is ready, the window offers Matter, Matter Bridge, Zigbee2MQTT and the AI MCP server: one click creates the device.
The line runs install_fhempy.pl: it adds the fhempy update source, downloads the fhempy FHEM modules (update all pythonbinding), loads them and defines fhempy_local. Running it again is harmless, e.g. after a failed try. If nothing happens at all, FHEM couldn't download the script from GitHub.
Optional: sudo apt install libcpanel-json-xs-perl makes FHEM decode fhempy messages much faster. Check it with {InternalVal("fhempy_local", "JSON_BACKEND", "")} in FHEM.
2. Bluetooth modules and piclock only: system packages
Most modules need nothing else. The Bluetooth modules ble_presence, bt_presence, eq3bt, miflora, mitemp and the piclock module still build some of their libraries, which needs these packages:
sudo apt install python3-dev python3-venv libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libglib2.0-dev libdbus-1-dev bluez libbluetooth-dev git
3. Define your first device
The easiest way: click + Install modules next to fhempy_local in the room fhempy. Search or browse all modules, click one and press Set up. If a module needs more information (e.g. a login or an IP address), the window asks for it and creates the device for you.
Of course you can also define devices like any other FHEM device, pick a module from the list below, for example:
define matter fhempy matter
define castdevice fhempy googlecast "Living Room"
define eq3bt fhempy eq3bt 00:11:22:33:44:66:77
define upnp fhempy discover_upnp
The module's README (linked in the list) explains its options. Its Python libraries are installed automatically on first use.
🔄 Updates
Click the update icon of fhempy_local or run set fhempy_local update. fhempy installs the new version, restarts and also updates its FHEM modules (10_BindingsIo.pm, 10_fhempy.pm, ...) and reloads them in FHEM. FHEM update and shutdown restart aren't needed for fhempy anymore. With attr fhempy_local autoUpdate 1 fhempy installs new releases automatically at night (autoUpdateTime, default 03:00).
🐳 Docker
Running FHEM in Docker? fhempy-docker provides a ready-made image per module, e.g. ghcr.io/fhem/fhempy-docker-<modulename>:latest. Start the container in the same network as FHEM and connect it with define fhempy_peer_<modulename> BindingsIo fhempy-<modulename>:15733 fhempy.
🧩 Modules
☀️ Energy & solar
| Module | Description |
|---|---|
| alphaesscloud | Alpha ESS inverter cloud integration |
| energie_gv_at | Retrieve current Austrian energy status |
| fusionsolar | Retrieve data from FusionSolar |
| goodwe | Get data from GoodWe inverters |
| huawei_modbus | Retrieve data from Huawei inverters |
| rct_power | RCT Power inverter |
| tibber | Get consumption data from tibber |
| wienernetze_smartmeter | Retrieve data from Wiener Netze smartmeter |
| zappi | Zappi charger |
🚗 Cars
| Module | Description |
|---|---|
| bmw | BMW and MINI (e.g. iX3) via official BMW CarData: battery, range, charging, doors, position, live values |
| kia_hyundai | Kia/Hyundai/Genesis car, official Pleos API (EU) or app interface |
| seatconnect | Control your Seat/Cupra car |
| skodaconnect | Control your Skoda car |
| volvo | Retrieve infos from your Volvo car (only new API) |
| volvo_software_update | Get notified about Volvo software updates |
🏠 Smart home devices
| Module | Description |
|---|---|
| erelax_vaillant | Control eRelax Vaillant |
| esphome | Installs and starts the ESPHome dashboard for easy ESPHome device management |
| gree_climate | Control Gree HVAC devices |
| homekit | Control HomeKit devices |
| matter | Control Matter devices (lights, plugs, sensors, thermostats, locks, blinds), also devices behind Hue/IKEA/Aqara bridges |
| matter_bridge | Use FHEM devices in Apple Home, Google Home, Alexa and SmartThings, including voice control |
| meross | Control Meross devices |
| miio | Control Xiaomi WiFi devices |
| mqtt_ha_discovery | Support Home Assistant MQTT discovery |
| nefit | Control Nefit devices |
| ring | Ring doorbell/chime/cam |
| pyit600 | Control Salus iT600 devices |
| tuya | Recommended: control Tuya devices locally incl. real-time updates (only WiFi devices) |
| tuya_cloud | Control Tuya devices via cloud incl. real-time updates (WiFi & ZigBee) |
| tuya_smartlife | Recommended: control Tuya devices via cloud incl. real-time updates (WiFi & ZigBee) |
| warema | Control Warema devices |
| xiaomi_gateway3 | Xiaomi Gateway V3 (only V3!) |
| xiaomi_tokens | Retrieve all Xiaomi tokens from the cloud |
| zigbee2mqtt | Install, update and run a Zigbee2MQTT server |
📶 Bluetooth
| Module | Description |
|---|---|
| ble_monitor | Supports a lot of BLE devices |
| ble_presence | Presence detection incl. RSSI for Bluetooth Low Energy |
| ble_reset | Resets all Bluetooth interfaces every X hours |
| blue_connect | Blue Connect pool sensor |
| bt_presence | Presence detection incl. RSSI for Bluetooth |
| eq3bt | Control EQ3 Bluetooth thermostats |
| gfprobt | Control GF Pro Bluetooth irrigation control |
| miflora | Xiaomi BLE plant sensor |
| miscale | Xiaomi Mi Scale V1/2 support |
| mitemp | Xiaomi BLE temperature/humidity sensor |
| nespresso_ble | Nespresso Bluetooth coffee machine |
| scooter | Xiaomi and Ninebot e-scooters (also with Scooter Hacking Utility firmware): battery, range, mileage, connects automatically when nearby |
🎵 Media
| Module | Description |
|---|---|
| dlna_dmr | Control DLNA MediaRenderer devices |
| googlecast | Control Cast devices and stream Spotify |
| spotify | Control Spotify Connect and use FHEM as Spotify Connect player |
🔍 Presence & discovery
| Module | Description |
|---|---|
| arp_presence | ARP based presence detection, works also for iOS |
| discover_ble | Discover Bluetooth LE devices |
| discover_mdns | Discover mDNS (e.g. Google Cast) devices |
| discover_upnp | Discover UPnP devices |
🧰 Information & tools
| Module | Description |
|---|---|
| aktionsfinder | Keep informed about product promotions |
| ddnssde | Dynamic DNS updater for the free ddnss.de service |
| geizhals | Retrieve prices from geizhals |
| github_backup | Backup FHEM config to GitHub |
| github_restore | Restore FHEM config from GitHub |
| ikos | Check prices for Ikos resorts |
| mcp_server | Control FHEM with AI apps (Claude, LM Studio...), the AI can also create automations for you |
| object_detection | TensorFlow Lite object detection |
| openmeteo_weather | Weather and forecast from Open-Meteo (replaces google_weather) |
| piclock | Create a LED clock with MAX7219 |
| prusalink | Prusa 3D printer |
| websitetests | Do some basic website checks |
| wienerlinien | Wiener Linien departure times |
| helloworld | Hello World example for developers to start writing their own module |
🩺 Troubleshooting
fhempy_localstays red: open the devicefhempyserver_15733in FHEM. Its readingpythonshows the Python version fhempy found, or why it can't start.- Where is the log? fhempy writes its own log file next to the FHEM log:
log/fhempy-YYYY-MM-DD.log. Setattr fhempyserver_15733 verbose 5for debug output. Installing fhempy failed: ...: the state offhempy_localnames the reason, the fhempy log has the details. If uv can't be downloaded from github.com and the system Python has no venv support, runsudo apt install python3-venvand restart fhempy withset fhempyserver_15733 restart.- A module doesn't work: check its README first. Questions are welcome in the FHEM forum, bugs in the GitHub issues.
Bluetooth auto recovery
Modules using Bluetooth LE via bleak (blue_connect, eq3bt, gfprobt, mitemp2) detect a stuck Bluetooth adapter and try to recover it automatically. After 3 failed connection attempts in a row (connect errors, or scans which don't see any device at all) the adapter gets recovered, each time escalating one stage further:
- Power cycle the adapter via BlueZ D-Bus. No extra permissions needed besides the
bluetooth.confpolicy from the module README. - Reset the adapter via bluetooth-auto-recovery (MGMT power cycle, USB reset). Requires
CAP_NET_ADMINfor the fhempy process. - Restart bluetoothd via
sudo -n systemctl restart bluetooth. Requires a sudoers entry.
If bluetoothd doesn't answer on D-Bus at all, it gets restarted right away. Stages without the required permissions are skipped. Two recoveries of the same adapter are at least 5 minutes apart (doubling up to 1 hour while the adapter doesn't recover). The reading connection_recovery shows the last recovery of a device.
Allow stage 2 by adding CAP_NET_ADMIN to the service which starts fhempy (fhem on FHEM installations, fhempy on remote peers):
sudo systemctl edit fhem
[Service]
AmbientCapabilities=CAP_NET_ADMIN
Allow stage 3 via sudo visudo (replace fhem with the user running fhempy, e.g. pi on remote peers):
fhem ALL=NOPASSWD: /usr/bin/systemctl restart bluetooth
fhempy peers (e.g. extend Bluetooth range)
fhempy can run modules on other computers (peers), e.g. a Raspberry Pi close to your Bluetooth devices or a more powerful machine for video object detection. FHEM finds peers on its own and creates a fhempy_peer_<IP> device; set a device's IODev to it to run that device there.
Install a peer from FHEM (no terminal needed)
- Prepare the Raspberry Pi with the Raspberry Pi Imager: in the settings set a host name (e.g.
fhempy-bt), user and password and enable SSH. - Start the Pi and enter in FHEM:
set fhempy_local installPeer fhempy-bt.local pi <password>
Use the host name from step 1 with .local or the IP address of the Pi, and the user and password you set. The reading peer_install of fhempy_local shows the progress (system packages, Python, fhempy, service). When it's done, fhempy_peer_<IP> is ready. The password is only used for this installation, fhempy doesn't store it.
The peer gets everything at once: the system packages for the Bluetooth modules, Bluetooth permissions for the auto recovery and a systemd service which starts fhempy on boot. Running installPeer again repairs an installation.
Install a peer from its terminal
Log in to the peer (not your FHEM machine) and run:
curl -fsSL https://raw.githubusercontent.com/fhempy/fhempy/master/install_systemd_fhempy.sh | sudo bash
fhempy runs as the user who called sudo. If autodiscovery doesn't work (it's based on zeroconf), define the peer yourself: define fhempy_peer_IP BindingsIo IP:15733 fhempy.
Log file and update
The peer's log: journalctl -u fhempy -f. Update a peer like the local fhempy with set fhempy_peer_<IP> update.
🏗️ How it works
In short:
- FHEM – you define a device as usual, e.g.
define livingroom fhempy googlecast. - BindingsIo – forwards everything for that device (define, set, attr, ...) to fhempy.
fhempy_localis created during installation and connects to the fhempy on the same computer. - fhempy – a Python process that FHEM starts automatically. It loads the matching Python module (here
googlecast), which talks to your device or cloud service. - Back to FHEM – readings and state changes travel the same way back and show up in FHEM like for any other device.
Optionally fhempy can also run on another computer (a fhempy peer), e.g. a Raspberry Pi next to a Bluetooth thermostat. FHEM finds it automatically and creates a fhempy_peer_... BindingsIo; set a device's IODev to it to run that device there.
Details for developers
| Part | What it does |
|---|---|
| 10_fhempy.pm | The FHEM module behind every define ... fhempy ... device. Hands all calls to its BindingsIo with IOWrite. |
| 10_BindingsIo.pm | DevIo device that connects to fhempy via websocket and exchanges JSON messages. |
| 10_fhempyServer.pm | Starts the local fhempy process. |
| fhempy | The Python (asyncio) server: receives the messages, runs the module function and replies. |
Example: define castdevice fhempy googlecast "Living Room"
- The fhempy device sends
IOWriteto BindingsIo. - BindingsIo sends a JSON websocket message to fhempy.
- fhempy loads the module (
googlecast), creates an instance and calls itsDefinefunction. - FHEM waits for the answer, the same way as for Perl modules, and fhempy returns the result as JSON via websocket.
At any time a module can call FHEM functions like readingsSingleUpdate(...) via the fhem.py module (fhem.readingsSingleUpdate(...)).
Write your own module
Check the helloworld example for writing an own module. Be aware that no function which is called from FHEM is allowed to run longer than 1s. In general no blocking code should be used with asyncio. If you want to call blocking code, use utils.run_blocking.
🤝 Contributing
Due to limited time I'm unable to fully support fhempy on my own and I'm looking for developers to help maintain and enhance the project. Bug fixes, new modules and documentation improvements are all welcome, just open an issue or a pull request. See DEVELOPMENT.md to get started.
Your support would mean a lot!
1 maintainer
Metadata
1 maintainer
Release files for fhempy 2.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| fhempy-2.6.1.tar.gz | 4.6 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fhempy-2.6.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 9.4 MB
Release files / fhempy-2.6.1.tar.gz
| Download URL | fhempy-2.6.1.tar.gz |
|---|---|
| Size | 4.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c699c8b2e5672a4d8bb3fa19bc4ba01e91324acb7829585c48e191ba3ad2a1f2
|
|
BLAKE2b-256 checksum How to use checksums |
4d2df55f40d0c26e055f52e10183b0dbd553d8f0f70997166cf8351b3fcde066
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logRelease files / fhempy-2.6.1-py3-none-any.whl
| Download URL | fhempy-2.6.1-py3-none-any.whl |
|---|---|
| Size | 4.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c5eaccbb8c8a059b274a90af3e32f189978ad2334fcf244b8645ba49bd2d0032
|
|
BLAKE2b-256 checksum How to use checksums |
6293da2267537e8c848117f969d7ea471ec06882a38d523f0c0bc618b60023fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logSecurity for fhempy 2.6.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for fhempy-2.6.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
