Skip to content

bvis/fermax-blue-hass

BranchesTags

Repository files navigation

Fermax Blue for Home Assistant

hacs_badge

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: 
    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:

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.<name>_visitor Camera Live MJPEG stream when active; last frame as preview when idle
event.<name>_doorbell Event Fires when someone rings the doorbell
event.<name>_door_opened Event Fires when a door is successfully opened
event.<name>_camera_on Event Fires when camera preview / live stream starts
binary_sensor.<name>_connection Binary Sensor Device connectivity (entities go unavailable when disconnected)
lock.<name>_<door>_lock Lock Lock/unlock (open) the door
button.<name>_<door>_open Button One-press door opening
button.<name>_camera_preview Button Start camera preview / live stream
button.<name>_f1 Button F1 auxiliary function
button.<name>_call_guard Button Call the building's guard/janitor
sensor.<name>_wifi_signal Sensor WiFi signal strength (0-4 bars)
sensor.<name>_status Sensor Device activation status
sensor.<name>_last_opening Sensor Last door opening timestamp (with user, door, guest attributes)
sensor.<name>_last_call Sensor Last call/doorbell ring timestamp (with call_id, answered, recent_calls count)
switch.<name>_notifications Switch Enable/disable push notifications
switch.<name>_dnd Switch Do Not Disturb mode
switch.<name>_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. 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 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.

# 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.

Cast doorbell to Google Nest

Show doorbell video on a Nest Hub and announce on speakers: 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

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

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:

# 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 for full guidelines.

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.

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 for guidelines.

Acknowledgments

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

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 file.

About

Home Assistant HACS integration for Fermax Blue

Topics

doorbell intercom home-assistant hacs fermax

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

4 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 31

v0.16.3 - FCM listener watchdog Latest
May 4, 2026
+ 30 releases

Packages

 
 
 

Contributors

Languages