Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bvis/fermax-blue-hass

Home Assistant HACS integration for Fermax Blue
https://github.com/bvis/fermax-blue-hass

doorbell fermax hacs home-assistant intercom

Last synced: about 1 month ago
JSON representation

Home Assistant HACS integration for Fermax Blue

Awesome Lists containing this project

README 

          
# Fermax Blue for Home Assistant



[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)



Home Assistant custom integration for **Fermax Blue** video door entry systems (DUOX PLUS / blueStream).



This integration simulates a Fermax Blue mobile app client, connecting to the Fermax cloud API and receiving real-time push notifications via Firebase Cloud Messaging when someone rings your doorbell.



## Features



- **Live video streaming** — Real-time MJPEG video from the intercom camera (~720x480, ~24fps). The card auto-switches between static preview and live stream

- **Camera preview** — Last captured frame persists across HA restarts, always visible in the camera card

- **Doorbell detection** — Real-time push notification when someone rings (via Firebase Cloud Messaging)

- **Door opening** — Open your building's door remotely (lock entity + button)

- **On-demand camera** — Triggers the intercom camera without a doorbell ring via auto-on

- **F1 auxiliary button** — Trigger the intercom's F1 function

- **Call guard** — Call the building's guard/janitor

- **Do Not Disturb** — Toggle DND mode per device (useful for night automations)

- **Photo caller control** — Enable/disable automatic visitor photo capture

- **Opening history** — Track who opened the door and when

- **Connection status** — Monitor if your intercom is online (entities go unavailable when offline)

- **WiFi signal** — Track the intercom's wireless signal strength

- **Notification control** — Enable/disable doorbell notifications

- **Media browser** — Browse doorbell photos and call recordings from the HA media browser

- **Diagnostics** — Built-in troubleshooting data (with redacted credentials)

- **Configurable polling** — Adjust the status polling interval (1-30 minutes)



## Supported Devices



Tested with:

- Fermax VEO-XL WiFi DUOX PLUS

- Fermax VEO-XS WiFi DUOX PLUS (REF: 9449)



Should work with any Fermax Blue-compatible intercom (devices that work with the Fermax Blue / DuoxMe mobile app).



## Installation



### HACS (Recommended)



1. Open HACS in Home Assistant

2. Go to **Integrations** > **Custom repositories**

3. Add this repository URL with category **Integration**

4. Search for "Fermax Blue" and install

5. Restart Home Assistant

6. Go to **Settings** > **Devices & Services** > **Add Integration** > **Fermax Blue**



### Manual Installation



1. Download the latest release from GitHub

2. Copy the `custom_components/fermax_blue` folder to your Home Assistant `config/custom_components/` directory

3. Restart Home Assistant

4. Go to **Settings** > **Devices & Services** > **Add Integration** > **Fermax Blue**



## Configuration



The integration is configured through the Home Assistant UI:



1. Go to **Settings** > **Devices & Services**

2. Click **Add Integration**

3. Search for **Fermax Blue**

4. Enter your Fermax Blue app credentials (see below)



The integration will automatically discover all paired devices on your account.



### Options



After setup, you can configure the integration options:



1. Go to **Settings** > **Devices & Services**

2. Click **Configure** on your Fermax Blue integration

3. Available options:

   - **Polling interval** (1-30 minutes, default: 5)

   - **Recording retention** (1-90 days, default: 10) — auto-deletes older call recordings

   - **Auto-respond to doorbell** — when enabled, answers the call automatically: starts video stream, sends audio file through the intercom speaker, records the call to MP4. When disabled, only triggers notifications without interacting with the intercom

   - **Audio file path** — WAV/MP3 file for auto-response (e.g., `/config/media/mi_mensaje.wav`)



### API Credentials



During setup, after entering your Fermax Blue username and password, you will be asked for the **API and Firebase credentials**. These values are needed to communicate with Fermax's servers and receive push notifications.



The integration requires:

- **Fermax API**: Auth URL, Base URL, Auth Basic header (OAuth client credentials)

- **Firebase**: API Key, Sender ID, App ID, Project ID, Package Name



A `credentials.example.json` file is included as a template. Copy it to `credentials.json` and fill in your values.



#### How to Obtain Credentials



##### Firebase credentials (from the APK)



The Firebase credentials can be extracted automatically from the official Fermax Blue Android APK:



1. **Download the Fermax Blue APK** from your device or a trusted source (e.g., Softonic)

2. **Run the extraction script:**

   ```bash

   make extract-credentials APK=/path/to/fermax-blue.apk

   ```

   Or directly: `python scripts/extract_credentials.py /path/to/fermax-blue.apk`

3. The script extracts Firebase credentials from `resources.arsc` and API URLs from the binary. It also attempts to decrypt AES-encrypted OAuth credentials from the decompiled source if a JADX output directory is found alongside the APK.



The script reliably finds: `firebase_api_key`, `firebase_sender_id`, `firebase_app_id`, `firebase_project_id`, `firebase_package_name`, `fermax_auth_url`, and `fermax_base_url`.



##### OAuth client credentials (fermax_auth_basic)



The OAuth `client_id` and `client_secret` (encoded as a `Basic` auth header) are available thanks to the work of the open-source Fermax community. They can be found in these projects:



- [fermax-blue-intercom](https://github.com/marcosav/fermax-blue-intercom) by @marcosav

- [hass-bluecon](https://github.com/AfonsoFGarcia/hass-bluecon) by @AfonsoFGarcia and the [fork](https://github.com/patrikulus/hass-bluecon) by @patrikulus

- [HASS-BlueCon](https://github.com/cvc90/HASS-BlueCon) by @cvc90

- [Fermax-Blue-Intercom](https://github.com/cvc90/Fermax-Blue-Intercom) by @cvc90



This integration exists thanks to the reverse-engineering work of these developers. If you find this project useful, please consider starring their repositories.



##### Manual extraction (fallback)



If the script doesn't find all values, decompile the APK with JADX and search manually:



1. **API URLs**: search for `oauth/token` and `fermax.io` in `Urls.java`

2. **Firebase**: found in `google-services.json` inside the APK:

   - `firebase_api_key` → `client[0].api_key[0].current_key`

   - `firebase_sender_id` → `project_info.project_number`

   - `firebase_app_id` → `client[0].client_info.mobilesdk_app_id`

   - `firebase_project_id` → `project_info.project_id`

   - `firebase_package_name` → `client[0].client_info.android_client_info.package_name`



> **Legal note:** These credentials are part of a publicly distributed application. Extracting configuration from software you own as a paying customer for personal interoperability use is a legitimate exercise of your consumer rights.



### Dedicated User for Doorbell Notifications (Recommended)



Fermax Blue only allows **one active push notification token per user**. If you use your main account for the integration, your mobile app will stop receiving doorbell notifications (or vice versa).



To solve this, **create a dedicated user** for the integration:



1. Open the **Fermax Blue app** on your phone

2. Go to **Settings** > **Users** > **Invite user**

3. Enter a new email address (e.g., `yourname+ha@gmail.com` — Gmail `+` aliases work)

4. The invited user will receive an email with a registration link

5. Open the link, **download the Fermax Blue app** on any phone, and complete the registration with a password

6. Once registered, you can uninstall the app — the account is now active

7. Use this new account's credentials when configuring the integration in Home Assistant



This way, your main account keeps receiving notifications on your phone, and the integration receives them independently via its own account.



> **Note:** If you skip this step and use your main account, the integration will still work for door opening, device status, and camera — but real-time doorbell notifications may conflict with your mobile app.



## Entities



For each paired intercom device, the integration creates:



| Entity | Type | Description |

|--------|------|-------------|

| `camera._visitor` | Camera | Live MJPEG stream when active; last frame as preview when idle |

| `event._doorbell` | Event | Fires when someone rings the doorbell |

| `event._door_opened` | Event | Fires when a door is successfully opened |

| `event._camera_on` | Event | Fires when camera preview / live stream starts |

| `binary_sensor._connection` | Binary Sensor | Device connectivity (entities go unavailable when disconnected) |

| `lock.__lock` | Lock | Lock/unlock (open) the door |

| `button.__open` | Button | One-press door opening |

| `button._camera_preview` | Button | Start camera preview / live stream |

| `button._f1` | Button | F1 auxiliary function |

| `button._call_guard` | Button | Call the building's guard/janitor |

| `sensor._wifi_signal` | Sensor | WiFi signal strength (0-4 bars) |

| `sensor._status` | Sensor | Device activation status |

| `sensor._last_opening` | Sensor | Last door opening timestamp (with user, door, guest attributes) |

| `sensor._last_call` | Sensor | Last call/doorbell ring timestamp (with call_id, answered, recent_calls count) |

| `switch._notifications` | Switch | Enable/disable push notifications |

| `switch._dnd` | Switch | Do Not Disturb mode |

| `switch._photo_caller` | Switch | Enable/disable automatic visitor photos |



## Dashboard Card



A ready-to-use dashboard card template is included in [`blueprints/fermax_dashboard_card.yaml`](blueprints/fermax_dashboard_card.yaml). It provides a complete intercom control panel with:



- Live camera / preview image

- Door open + camera preview buttons

- F1 + call guard buttons

- Doorbell event, connection status, door lock

- DND, photo caller, notification switches

- WiFi signal + last opening info



**To use it:**



1. Install [mushroom-cards](https://github.com/piitaya/lovelace-mushroom) via HACS (for status indicators)

2. Copy the content of `blueprints/fermax_dashboard_card.yaml`

3. Edit your dashboard > Add card > Manual YAML

4. Paste and replace `DEVICE_NAME` and `DOOR` with your entity names



> **Tip:** To find your entity IDs, go to **Settings** > **Devices & Services** > **Fermax Blue** > click your device.



## Call Recordings



Every video stream session is automatically recorded to MP4 (video + intercom audio) in `/config/media/fermax_recordings/`. Doorbell visitor photos are saved as JPG in the same directory. Files are named with timestamps (e.g., `2026-04-06_13-00-00.mp4`, `2026-04-06_13-00-00_photo.jpg`).



Recordings and photos are automatically deleted after the retention period (default: 10 days, configurable in options).



### Media browser



All recordings and photos are browsable directly from the HA media browser via **Media** > **Fermax Blue**. Files are listed newest-first with thumbnails for photos and playback for videos.



You can also access them from the dashboard via the **Grabaciones** button, or browse **Media** > **Local media** > **fermax_recordings**.



## Services



### `fermax_blue.send_audio`



Send audio to the intercom speaker during an active video stream.



```yaml

# Send a pre-recorded audio file

service: fermax_blue.send_audio

data:

  audio_file: /config/media/mi_mensaje.wav



# Or send a TTS message

service: fermax_blue.send_audio

data:

  message: "Hola, ahora bajo"

  language: es

```



## Automation Blueprints



### Doorbell notification



A doorbell notification blueprint is available at [`blueprints/fermax_doorbell_notification.yaml`](blueprints/fermax_doorbell_notification.yaml).



### Cast doorbell to Google Nest



Show doorbell video on a Nest Hub and announce on speakers: [`blueprints/fermax_cast_doorbell.yaml`](blueprints/fermax_cast_doorbell.yaml). Supports optional auto-response to the intercom via TTS.



**To install:**



1. Copy `blueprints/fermax_doorbell_notification.yaml` to your HA `config/blueprints/automation/fermax_blue/` folder

2. Go to **Settings** > **Automations** > **Create Automation** > **Use Blueprint**

3. Select "Fermax: Doorbell notification"

4. Configure your doorbell event entity, camera, and notification service



The blueprint supports:

- Mobile push notification on doorbell ring

- Optional camera snapshot attachment

- Customizable title and message



## Automation Examples



### Flash lights when doorbell rings



```yaml

automation:

  - alias: "Flash lights on doorbell"

    trigger:

      - platform: state

        entity_id: event.fermax_your_home_doorbell

        attribute: event_type

    action:

      - service: light.turn_on

        target:

          entity_id: light.hallway

        data:

          flash: long

```



### Enable Do Not Disturb at night



```yaml

automation:

  - alias: "DND at night"

    trigger:

      - platform: time

        at: "23:00:00"

    action:

      - service: switch.turn_on

        target:

          entity_id: switch.fermax_your_home_dnd



  - alias: "Disable DND in the morning"

    trigger:

      - platform: time

        at: "07:00:00"

    action:

      - service: switch.turn_off

        target:

          entity_id: switch.fermax_your_home_dnd

```



## How It Works



1. **Authentication**: The integration authenticates with the Fermax Blue cloud API (`pro-duoxme.fermax.io`) using your account credentials

2. **Device Discovery**: It fetches all paired intercom devices and their accessible doors

3. **Firebase Registration**: It registers a Firebase Cloud Messaging client (simulating the mobile app) to receive real-time doorbell push notifications

4. **Camera Preview**: The auto-on feature triggers the intercom camera. A push notification arrives with the media room ID and signaling server URL

5. **Video Streaming**: The integration connects to the Fermax mediasoup SFU via Socket.IO, negotiates WebRTC transport, and receives live video frames (~720x480) that are served as MJPEG to the HA frontend

6. **Push Notifications**: When someone rings your doorbell, Fermax sends a push notification via Firebase, which the integration receives instantly and acknowledges

7. **Frame Persistence**: The last video frame is saved to disk so the camera card always shows a preview, even after HA restarts

8. **Polling**: Device status (connection, signal, opening history) is polled at a configurable interval (default: 5 minutes)

9. **Retry Logic**: API calls are automatically retried with exponential backoff on transient errors (5xx, connection failures)



## Troubleshooting



### "Invalid credentials" error

Make sure you're using the same email and password you use in the Fermax Blue mobile app. The password is case-sensitive.



### Doorbell notifications not working

The integration needs to register with Firebase Cloud Messaging. This happens automatically but can take a few minutes on first setup. Check the Home Assistant logs for `fermax_blue` entries.



### Camera shows no image

Press the "Camera preview" button to trigger the first stream. After that, the last frame will be saved and shown as preview even after restarts.



### Diagnostics

For troubleshooting, you can download diagnostics from **Settings** > **Devices & Services** > **Fermax Blue** > **3 dots menu** > **Download diagnostics**. Credentials are automatically redacted.



## Local Testing (CLI)



You can test every API feature locally without Home Assistant using the interactive CLI tool:



```bash

# Interactive mode (will prompt for credentials)

make cli



# Or pass credentials via environment variables

FERMAX_USER=your@email.com FERMAX_PASS=yourpassword make cli

```



This launches a Docker container with a menu-driven interface to test door opening, F1, call guard, DND, photo caller, opening history, camera preview, call log, and raw API calls.



No local Python installation needed — everything runs in Docker.



## Development



All development tools run via Docker — no local Python dependencies needed. Only Docker is required.



See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.



```bash

make check         # Run all checks (lint + format + type-check + dead-code + tests)

make lint           # Ruff linting (E, F, W, I, N, UP, B, A, SIM, TCH)

make format         # Auto-format code

make format-check   # Verify formatting (CI mode)

make typecheck      # Mypy type checking

make deadcode       # Vulture dead code analysis

make test           # Pytest with coverage (min 40%)

make cli            # Interactive API tester

make pre-push       # Full CI replica (same as GitHub Actions)

```



This project uses [Conventional Commits](https://www.conventionalcommits.org/).



## Roadmap



Features available in the Fermax Blue mobile app that are not yet implemented:



| Feature | Complexity | Description |

|---------|-----------|-------------|

| ~~**Two-way audio**~~ | ~~High~~ | ✅ Implemented — Send audio via `fermax_blue.send_audio` service (file or TTS), auto-response on doorbell configurable in options |

| **Switch camera during call** | Low | Switch between cameras on multi-camera intercoms (`/device/incall/changevideosource`) |

| **F1 during active call** | Low | Trigger the F1 auxiliary function while a stream is active (`/device/incall/f1`) |

| **Guest management** | Medium | Add, remove, and authorize guest users for the intercom via the API |

| **Delete call history** | Low | Clear call log entries (`DELETE /callmanager/api/v1/callregistry/participants`) |

| **Delete opening history** | Low | Clear door opening records (`DELETE /rexistro/api/v1/opendoorregistry`) |

| **Rename house/doors** | Low | Change the display name of the house or doors (`PATCH /pairing/api/v3/pairings/{id}/tag/`) |



Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.



## Acknowledgments



This integration would not be possible without the reverse-engineering work of the Fermax open-source community:



- **[@marcosav](https://github.com/marcosav)** — [fermax-blue-intercom](https://github.com/marcosav/fermax-blue-intercom): original script for Fermax Blue API interaction and OAuth credential discovery

- **[@AfonsoFGarcia](https://github.com/AfonsoFGarcia)** — [hass-bluecon](https://github.com/AfonsoFGarcia/hass-bluecon): first Home Assistant integration for Fermax Blue, BlueCon library

- **[@patrikulus](https://github.com/patrikulus)** — [hass-bluecon fork](https://github.com/patrikulus/hass-bluecon): working fork with improved authentication

- **[@cvc90](https://github.com/cvc90)** — [HASS-BlueCon](https://github.com/cvc90/HASS-BlueCon) and [Fermax-Blue-Intercom](https://github.com/cvc90/Fermax-Blue-Intercom): community maintenance and documentation

- **[firebase-messaging](https://github.com/sdb9696/firebase-messaging)** by @sdb9696: FCM push notification library that enables real-time doorbell detection



Thanks to the collaborative work of this community, the OAuth credentials needed for third-party integrations are publicly available. Without their effort, projects like this one would not be possible.



## Disclaimer



This integration is not affiliated with or endorsed by Fermax. It uses unofficial APIs that may change at any time. Use at your own risk.



## License



MIT License - see [LICENSE](LICENSE) file.