Feelloo Home Assistant Integration

Custom integration for Feelloo cat trackers in Home Assistant.

Features

• Real-time GPS tracking — live location on the Home Assistant map
• Activity monitoring — rest, calm, and action percentages with hourly history
• Territory sessions — track outings with start/end timestamps and session count
• Battery & charging status — never miss a low battery
• Presence detection — home / away / in-range status
• Ring button — locate your cat by triggering the tag ringtone
• Extended search mode — monitor search activation and expiration
• Dynamic fast polling — when Petite Souris mode is enabled, polling increases to 1 minute for real-time GPS and signal strength updates

Installation

HACS (recommended)

1. Open HACS in Home Assistant
2. Go to Integrations
3. Click the menu (⋮) and select Custom repositories
4. Add https://github.com/ccxdomo/ha-feelloo with category Integration
5. Click Download
6. Restart Home Assistant

Manual

1. Copy the custom_components/feelloo folder to your Home Assistant config/custom_components directory
2. Restart Home Assistant

Configuration

1. Go to Settings → Devices & Services → Add Integration
2. Search for Feelloo
3. Enter your Feelloo account email and password

Your cats and their data will be automatically discovered.

Architecture

The integration uses three separate DataUpdateCoordinators for optimal polling:

Coordinator	Endpoint	Interval
Main	/users/cats + /users/cats/{cat_id}	5 minutes (1 min with Petite Souris)
Activity	/users/cats/{cat_id}/activity?period_type=day	15 minutes
Territory	/users/cats/{cat_id}/territory/paths	15 minutes

All coordinators share a single Firebase auth manager with automatic token refresh every 50 minutes.

Dynamic Fast Polling

When the Petite Souris switch is turned ON for a cat:

• A dedicated timer triggers the Main coordinator refresh every 1 minute
• This affects GPS location, signal strength, battery, and all main coordinator entities
• When the switch is turned OFF, the timer stops and normal 5-minute polling resumes
• Multiple cats can have independent fast polling timers

Entities

For each detected cat, the following entities are created:

Binary Sensors

• Home — whether the cat is at home
• In Range — whether the tag is in LoRa range
• Gateway Online — whether the gateway is connected
• Charging — whether the tag is charging
• Is Ringing — whether the tag is currently ringing
• Battery Low — low battery warning
• Extended Search — whether extended search mode is enabled

Sensors

• Signal Strength — LoRa signal strength (%) from tag to gateway
  • Attribute: rssi_dbm — raw RSSI value
• Battery — battery level (%)
• Latitude / Longitude — last known GPS coordinates
• GPS Precision — accuracy in meters
• Last Seen — timestamp of last location update
• Presence Time — timestamp of last presence detection
• Activity — current dominant activity (sleep / calm / active)
  • Attribute: history — full 24-hour hourly breakdown
• Activity Rest — rest percentage (%)
• Activity Calm — calm percentage (%)
• Activity Action — action percentage (%)
  • Attribute: history — full 24-hour hourly breakdown
• Extended Search Expiration — when extended search expires
• Last Outing Start — timestamp of last territory session start
• Last Outing End — timestamp of last territory session end
• Outing Count — total number of territory sessions

Device Tracker

• Tracker — GPS location on the Home Assistant map
  • source_type: GPS
  • latitude / longitude: last known coordinates
  • location_accuracy: precision radius in meters (circle on the map)
  • State: home if presence.status.in_range is true, otherwise not_home
  • Attributes:
    • last_seen: ISO timestamp of last location update
    • precision_meter: GPS accuracy in meters
  • Icon: mdi:cat
  • Custom picture: see Custom Cat Images below

Custom Cat Images

You can display a custom photo for each cat on the map and in the device tracker card.

How it works:

• At startup, the integration checks if an image file exists for each cat
• If found, it automatically sets entity_picture on the device tracker
• No API call or cloud storage needed — purely local files

Where to place the image:

Create the folder and copy your cat's photo:

mkdir -p /config/www/feelloo
cp /path/to/your/photo.jpg /config/www/feelloo/{cat_name}.jpg

Replace {cat_name} with your cat's name slug (lowercase, spaces as underscores).

File naming:

• The filename must match the cat name slug (lowercase, spaces replaced by underscores)
• Example: cat named Moustache → file must be named moustache.jpg or moustache.png
• Example: cat named Moustache Le Chat → file must be named moustache_le_chat.jpg

Supported formats: .jpg and .png

Recommended resolution: 400×400 pixels (1:1 ratio) for optimal display on the map and entity cards

Dynamic detection: the integration checks for the image file at every coordinator refresh (every 5 minutes, or every 1 minute when Petite Souris is ON). No restart required — just add the image and wait for the next refresh.

Result: the device tracker will show your cat's photo instead of the default mdi:cat icon on the map and in entity cards.

Switches

• Petite Souris — enables/disables extended search mode with fast polling
  • When ON: polling interval drops to 1 minute for real-time GPS and signal strength
  • When OFF: returns to normal 5 minute polling
  • Each cat has its own independent timer

Button

• Ring — trigger the tag ringtone (only if can_ring is true)

Device Registry

Each cat is registered as a device with:

• Name: the cat's profile name
• Manufacturer: Feelloo
• Model: Cat Tracker

Requirements

• Home Assistant 2024.1.0 or newer

Support

For issues and feature requests, please use the GitHub issue tracker.