HomeMap

[Sjakie 156]

Sorry jan still getting same error doing something wrong.

Removed installation, starting fresh with .15

~/= user/user_name

~/homemapdata

~/admin.env

 

My apologies I did't know that you need to create a .environment file in the terminal window.

Hehe now I have a floor plan visible. Must first create my own.

Thanks

Edited October 30, 2025 by Sjakie
terminal

[jgab 2,647]

Update to 0.1.6

[Christb 33]

Now HomeMap is connected to my HC3 and I can see you default floor plan😀

BTW I had created some times ago a QA showing if any light is still on with 4 floor plans and a summary icon for all floors:

Please login or register to see this image.

/monthly_2025_10/image.png.0484e36607ba0961775976a20a98c9b1.png" /> 

To know where any lights is on, I have the  possibility to select floor and switch off all lights still on. Very usefull but I have no widget or notification on my smartphone...

I will use your application in parallel it seems to be easier for configuring any other devices. Thanks again for this application.

I will integrate now my own images to see how it goes.

 

 

[jgab 2,647]

Please login or register to see this link.

 - 2025-10-30

Changed

• Major Code Refactoring: Improved codebase organization and maintainability
  • Extracted 8 specialized manager modules from monolithic script.js
  • Reduced main script from 1,951 lines to 449 lines (77% reduction)
  • Clear separation of concerns with manager pattern architecture
• Module Architecture:
  • utils.js (47 lines) - Constants and utility functions
  • deviceHelpers.js (122 lines) - Multi-floor device support with auto-normalization
  • eventManager.js (187 lines) - HC3 event polling and dispatch
  • widgetManager.js (245 lines) - Widget loading and rendering
  • dialogManager.js (590 lines) - All UI dialogs (Add/Edit/Delete + widget UIs)
  • floorManager.js (269 lines) - Floor rendering, navigation, and drag-and-drop
  • contextMenuManager.js (125 lines) - Context menu handling
  • hc3ApiManager.js (213 lines) - HC3 API communication and device state management
• Device Format Normalization: Automatic conversion between single-floor and multi-floor formats
  • Devices on single floor use compact format: {id, name, type, floor_id, position}
  • Devices on multiple floors use array format: {id, name, type, floors: [{floor_id, position}]}
  • Auto-converts to simpler format when device removed from all but one floor

Fixed

• Updated example configuration (homemapdata.example) to use new widget format
• Widget version compatibility checking now properly validates minimum version (0.1.5)
• Device format consistency across add/edit/delete operations

Technical Details

• Total codebase: 2,247 lines across 9 files (vs. original 1,951 lines in single file)
• Manager pattern: Each manager receives HomeMap instance for context access
• ES6 modules with named exports/imports
• Improved code navigability and testability
• Each module has a single, well-defined responsibility

[jgab 2,647]

[0.1.7] - 2025-10-30

Added

• Color Light Widget (lightcolor.json😞
  • Multi-property state tracking (brightness + RGB color components)
  • Dynamic colored glow effect using CSS drop-shadow with actual RGB values
  • Color picker UI element with hex input and RGB display
  • setColor action to change light colors
  • Handles both colorComponents (object) and color (string) events from HC3
  • Automatic color string parsing ("R,G,B,WW,CW" format)
• Gauge Widget (gauge.json😞
  • Visual gauge with rotating needle indicator (0-100 range)
  • Inline SVG manipulation to rotate needle independently from background
  • Colored arc segments (green/yellow/red) for visual feedback
  • Expression-based rotation: ${value * 1.8 - 90}
• Color Select UI Element:
  • New colorSelect element type for widget dialogs
  • HTML5 color picker with live RGB value display
  • Hex ↔ RGB conversion utilities
  • Styled with custom CSS for consistent appearance
• Expression Evaluation in Templates:
  • Support for mathematical expressions: ${value * 1.8}, ${value / 10 + 5}
  • Support for conditional expressions: ${value > 50 ? 100 : 0}
  • Property references automatically replaced with state values
  • Works in style templates, text templates, and action parameters

Changed

• Enhanced Event System:
  • OR conditions in conditional updates: (prop1 == event.property || prop2 == event.property) ? event.newValue
  • Smarter event filtering checks both state properties and update expressions
  • Automatic color string parsing when updating colorComponents
• Widget Manager Improvements:
  • Nested property interpolation: ${colorComponents.red}
  • Dynamic style rendering on icon elements
  • Inline SVG loading and manipulation for advanced styling
  • SVG-specific style application to internal elements via selector
• Dialog Manager:
  • Added rgbToHex() and hexToRgb() helper methods
  • Color picker event handlers with automatic RGB extraction
• HC3 API Manager:
  • Object-based action parameters (e.g., {red: 255, green: 0, blue: 0})
  • Template variable replacement for object properties
  • Color string parsing for colorComponents properties

Technical Details

• New Rust command: read_file_as_text for SVG source loading
• SVG manipulation using DOMParser and XMLSerializer
• Expression evaluation with property substitution in interpolateTemplate
• Enhanced widget render system with svg section for internal element styling
• Color component normalization (string → object conversion)

1 hour ago, Christb said:

Now HomeMap is connected to my HC3 and I can see you default floor plan😀

BTW I had created some times ago a QA showing if any light is still on with 4 floor plans and a summary icon for all floors:

Please login or register to see this link.

 

To know where any lights is on, I have the  possibility to select floor and switch off all lights still on. Very usefull but I have no widget or notification on my smartphone...

I will use your application in parallel it seems to be easier for configuring any other devices. Thanks again for this application.

I will integrate now my own images to see how it goes.

Yes, this will probably not run on a phone... but I'm looking into having a tablet version eventually.
Now it only works from within your homes firewall so no remote control from the Internet.

[Christb 33]

Just a quick one: when I was trying to launch HomeMap whith logging issue, I got a lot of security (around 3 timex 20) alerts by email and my remote access has been finaly locked for some times... In your next release, could you add a function to stop access trial after 4 or 5 connection failed?  

[jgab 2,647]

Yes, good point.

[jgab 2,647]

[0.1.8] - 2025-10-30

Added

• Authentication Protection System:
  • Tracks failed authentication attempts (401/403 responses)
  • Automatically locks API calls after 2 consecutive failures
  • Prevents HC3 account lockout (HC3 locks after 4 attempts)
  • Shows clear error dialog when auth fails
  • Stops event polling immediately on auth lock
  • Status indicator shows "Authentication Failed - Check Credentials"
  • Auto-reset when credentials are updated in Settings
• Widget Package System Documentation:
  • CREATE_WIDGET_PACKAGE.md - Comprehensive guide for creating .hwp packages
  • Step-by-step manual creation instructions for non-technical users
  • Package structure specification
  • Manifest format reference with complete field documentation
  • Testing and distribution guidelines
  • Troubleshooting section with common issues
• Package Export Script (scripts/create-package.sh😞
  • Export installed packages as .hwp files
  • Lists available packages in homemapdata
  • Extracts package metadata from manifest
  • Creates properly named archives: package-id-version.hwp
  • Includes widgets, icons, README, and screenshots
  • Shows package contents summary after creation
• Device Dialog Enhancements:
  • Shows all installed package widgets in add/edit device dialogs
  • "Available from Packages" section lists unloaded package widgets
  • Consistent display format showing package IDs
  • Saves package reference with device configuration

Changed

• Package Manager Integration:
  • Widget selection now includes all installed packages, not just loaded ones
  • Package widgets display with format: "widget-id (package-id)"
  • Device widget field stores package reference: "package-id/widget-id"

Fixed

• Authentication Failure Handling:
  • testConnection() checks auth lock before attempting connection
  • executeAction() checks auth lock and handles 401/403 responses
  • updateDeviceIcon() silently skips updates when auth locked
  • Event polling checks auth lock at start of each cycle
  • All HC3 API calls detect and handle authentication failures
• Package Installation:
  • Switched to non-blocking Tauri dialogs for reinstall confirmation
  • Proper widget reload after package operations

Security

• Auth failure counter prevents repeated failed login attempts
• Protects users from accidentally triggering HC3 account lockouts
• Safe margin of 2 attempts below HC3's 4-attempt limit

Documentation

• docs/AUTH_PROTECTION.md - Complete authentication protection documentation
• docs/CREATE_WIDGET_PACKAGE.md - Widget package creation guide

[Sjakie 156]

Jan can you add this to ERUpdater?

 

[jgab 2,647]

4 minutes ago, Sjakie said:

Jan can you add this to ERUpdater?

 

It's not a QA. It has it's own updater in the menu.

[Sjakie 156]

What is handy? 

One floor plan for 1st floor or divided in several rooms?

[jgab 2,647]

21 hours ago, Brors94 said:

and maybe a Dual temperature sensor? 
As you see I got 2 Temperatures on the room (floor and Rom temp) 
Just to give you an Idea  

 

Can you elaborate on this - what would you like to do with the 2 temp sensors?

[Christb 33]

Just a suggestion, if not yet done (not have emought time yet to explore all capabilities of HomeMap):

Is it possible fo the selected floor, to launch eather a crate with coordinates or a scale left and bottom side with the mouse pointer cross dote line halping to get coordinates oof lcation where you want to place a device?

I have such optional  crate in my QA.

[jgab 2,647]

But if you check edit mode you can just drag around the widgets? no need to calculate.
Right click in edit mode on the floor allow you to add a device.
Right click in edit mode on widget allow you to edit it...

[jgab 2,647]

[0.1.9] - 2025-10-30

Added

• View Zoom Controls:
  • Zoom slider (50% - 200% range)
  • Quick zoom buttons: +/- for increment/decrement
  • "Fit to Window" button for auto-scaling to available space
  • "Reset" button to return to 100%
  • Per-floor zoom memory - each floor remembers its zoom level
  • Zoom settings persist across sessions via localStorage
  • Transform-based scaling for smooth performance

Changed

• Zoom Controls UI:
  • Zoom controls only visible in Edit Mode
  • Integrated into header bar to save screen space
  • Compact design with smaller buttons and slider
  • No dedicated row taking up vertical space
  • Contextual appearance - hidden during normal use

Improved

• User Experience:
  • Users can scale entire floor view to fill window
  • Smaller floor plan images can be zoomed up for larger relative widget sizes
  • Better utilization of available screen space
  • Zoom level restores automatically when switching between floors

[jgab 2,647]

HomeMap Tutorial

Welcome to HomeMap! This tutorial will help you get started with visualizing your HC3 home automation on interactive floor plans.

Table of Contents

1. Please login or register to see this link.

2. Please login or register to see this link.

3. Please login or register to see this link.

4. Please login or register to see this link.

5. Please login or register to see this link.

6. Please login or register to see this link.

7. Please login or register to see this link.

---

1. Introduction

What is HomeMap?

HomeMap is a visual interface for your Fibaro HC3 home automation system. Instead of lists and menus, you see your devices on actual floor plans of your home.

What You'll Learn

• Connect HomeMap to your HC3
• Add floor plan images
• Place devices on your floor plans
• Control devices by clicking them
• Move devices around and edit them

What You'll Need

• A Fibaro HC3 system
• Your HC3 IP address and login credentials
• Floor plan images (PNG, JPG, or SVG files)
• 10 minutes to get started

---

2. Initial Setup

2.1 First Launch

When you first open HomeMap:

• The app automatically creates a configuration folder
• Built-in widgets and icons are installed automatically
• You'll see a welcome dialog guiding you to set up your HC3 connection

2.2 Opening Settings

Click the ⚙️ Settings button in the top-right corner.

2.3 Configure HC3 Connection

In the Settings dialog, go to the HC3 tab and fill in:

Field	Description	Example
HC3 Host	Your HC3's IP address or hostname	192.168.1.57
HC3 Username	Your HC3 username	admin
HC3 Password	Your HC3 password	Your password
Protocol	HTTP or HTTPS	http (most common)

2.4 Optional: Configure House Settings

In the General tab, you can set:

• House Name: Display name for your home (shows in window title)
• House Icon: An emoji icon for branding (max 2 characters)

These are optional but make HomeMap feel more personalized!

2.5 Save and Test Connection

1. Click Save
2. The app automatically tests your connection
3. You should see "Connected to HC3" (green indicator) at the top right

Tip: If you see "Authentication Failed", double-check your username and password!

Where are files stored? HomeMap automatically creates its configuration folder at:

• macOS: ~/Library/Application Support/HomeMap/homemapdata
• Windows: %APPDATA%\HomeMap\homemapdata

You don't need to worry about this unless you want to create custom widgets or icons!

---

3. Adding Floor Plans

3.1 Prepare Your Floor Plan Images

What works best:

• PNG, JPG, or SVG format
• Size: 1000-2000 pixels wide recommended
• Clear, simple floor plans work better than complex ones
• Name them something simple: floor1.png, floor2.png, etc.

Where to put them: Place your floor plan images in your data folder:

3. Adding Floor Plans

3.1 Prepare Your Floor Plan Image

1. Create or obtain a floor plan image (PNG, JPG, or GIF)
2. Name it something descriptive like ground-floor.png or first-floor.jpg
3. Recommended size: 1500-3000 pixels wide for best quality

3.2 Add Floor via Settings

1. Open Settings (⚙️)
2. Go to the Floors tab
3. Click Add Floor
4. Fill in the floor information:

Field	Description	Example
Floor ID	Unique identifier (simple name)	floor1
Floor Name	Display name	Ground Floor
Floor Image	Click Browse... to select your image	ground-floor.png

5. Click Save
6. The floor appears in your floor tabs

The floor image is automatically copied to your data folder, so you don't need to worry about file paths!

3.3 Verify the Floor

You should now see your new floor as a tab at the top of the window.

Click on the tab to view the floor plan!

3.4 Add More Floors

Repeat the process for additional floors:

• Ground Floor (id: floor1)
• First Floor (id: floor2)
• Basement (id: basement)

Tip: Start with one floor to get familiar with HomeMap, then add more floors later!

---

4. Adding Devices

There are two ways to add devices to your floor plans:

4.1 Using Device Management Panel (Recommended)

This is the easiest and most visual way to add devices.

Step 1: Enter Edit Mode

1. Click the Edit button (✏️) at the top right
2. The floor plan enters edit mode (you'll see editing controls)

Step 2: Open Device Management

1. Click the hamburger menu (☰) at the top left
2. Select Device Management

Step 3: Install a Device

1. The panel shows all your HC3 devices organized by room
2. Find the device you want to add
3. Click Install next to the device
4. The device appears on your floor plan!

Step 4: Position the Device

1. Drag the device to the correct location on your floor
2. Devices snap to a grid for easier alignment
3. The device automatically uses the appropriate widget based on its type
4. Click Exit Edit Mode when done

Tip: The Device Management panel groups devices by room, making it easy to find what you need!

4.2 Common Widget Types

HomeMap automatically selects the right widget based on your HC3 device type:

Device Type	Widget Type	Controls
Dimmable Light	lightdim	On/Off + Brightness slider
On/Off Light	binaryswitch	On/Off button
Door/Window Sensor	binarysensor	Open/Closed status
Motion Sensor	motion	Motion detected indicator
Temperature Sensor	temperature	Current temperature
Multi-level Sensor	multilevel	Sensor value display
Colored Light	lightcolor	On/Off + Color picker

Where to find Device ID: In the HC3 web interface, go to Devices, and look at the device details. The ID is shown in the URL or device info.

4.3 Advanced: Manual Configuration (config.json)

For developers or advanced users who want direct file control:

Open your configuration file at:

• macOS: ~/Library/Application Support/HomeMap/homemapdata/config.json
• Windows: %APPDATA%\HomeMap\homemapdata\config.json

Add devices manually:

Please login or register to see this code.

Finding coordinates:

• Enable Edit Mode
• Add a device visually to see where it lands
• Check config.json to see the coordinates
• Use those coordinates for other devices

Note: Using the Device Management panel is much easier and less error-prone!

---

5. Editing Devices

5.1 Moving Devices

Step 1: Enable Edit Mode

Check the Edit Mode checkbox at the top right.

Step 2: Drag to Move

Click and drag any device to move it to a new position. The position saves automatically!

5.2 Editing Device Properties

Step 1: Enable Edit Mode

Make sure Edit Mode is enabled.

Step 2: Right-Click Device

Right-click on any device and select Edit.

Step 3: Change Settings

You can modify:

• Device name
• Widget type
• Which floors the device appears on

Step 4: Save Changes

Click Save to apply your changes.

5.3 Moving Devices Between Floors

A device can appear on multiple floors!

To add a device to another floor:

1. Right-click the device → Edit
2. Check additional floors in the "Floors" section
3. Click Save
4. Switch to the other floor tab
5. The device appears there (you can drag it to the right position)

To remove from a floor:

1. Right-click the device → Edit
2. Uncheck the floor you want to remove it from
3. Click Save

5.4 Deleting Devices

Step 1: Enable Edit Mode

Step 2: Right-Click Device

Right-click on the device you want to remove.

Step 3: Choose "Delete"

Select Delete from the menu.

Step 4: Confirm

Click Delete in the confirmation dialog.

The device will be removed from all floors.

---

6. Zooming Floor Plans

Sometimes your floor plan is too small or too large. Use zoom to adjust!

6.1 Enable Zoom Controls

Zoom controls only appear in Edit Mode.

1. Check the Edit Mode checkbox
2. Zoom controls appear in the top bar (between Settings and Edit Mode)

6.2 Zoom Options

Control	What It Does
− button	Zoom out by 10%
+ button	Zoom in by 10%
Slider	Drag to set exact zoom (50% - 200%)
Fit button	Auto-scale to fill the window
Reset button	Return to 100% zoom

6.3 Using Zoom

To make everything bigger:

• Click the + button a few times, or
• Drag the slider to the right, or
• Try Fit to automatically fill your window

To make everything smaller:

• Click the − button, or
• Drag the slider to the left, or
• Click Reset to go back to 100%

6.4 Per-Floor Zoom

Each floor remembers its own zoom level!

• Set zoom to 150% on Floor 1
• Switch to Floor 2, set zoom to 100%
• Switch back to Floor 1 → still at 150%

Zoom settings are saved even when you close HomeMap.

6.5 Why Use Zoom?

Use Cases:

• Small floor plans: Zoom in to make devices appear larger
• Large displays: Zoom out to see everything at once
• Presentations: Use "Fit" to fill the screen
• Different floor sizes: Each floor can have its own zoom level

---

7. Tips & Tricks

Getting Device IDs Quickly

Method 1: HC3 Web Interface

1. Open your HC3 web interface
2. Go to Devices
3. Click on a device
4. Look at the URL: http://192.168.1.57/devices/385 → ID is 385

Method 2: HC3 Mobile App

1. Long-press a device
2. Select "Advanced"
3. Device ID is shown at the top

Organizing Your Floor Plans

Best practices:

• Start with one floor until you're comfortable
• Use consistent naming: "floor1", "floor2", etc.
• Keep floor plan images simple and clear
• Optimize image size (1000-2000px wide is plenty)
• Use PNG or JPG format

Dealing with Many Devices

Strategies:

• Don't add every device - focus on the ones you use most
• Group similar devices (e.g., all lights on one floor)
• Use descriptive names: "Kitchen Light" not just "Light 1"
• Color-code using different widget types if needed

Controlling Devices

To control a device:

1. Make sure Edit Mode is OFF
2. Click on any device icon
3. A control dialog appears
4. Use sliders, buttons, or toggles to control the device

Quick actions:

• Lights: Click to see dimmer slider
• Switches: Click to toggle on/off
• Sensors: Click to see current value

Keyboard Shortcuts

• Edit Mode Toggle: Just click the Edit Mode checkbox (no keyboard shortcut yet)
• Settings: Click the ⚙️ button

Backup Your Configuration

Your configuration is automatically stored in:

• macOS: ~/Library/Application Support/HomeMap/homemapdata/
• Windows: %APPDATA%\HomeMap\homemapdata\

To backup:

1. Copy the entire homemapdata folder to a safe location
2. This includes config.json and all your floor plan images
3. Keep backups before making major changes

To restore:

1. Copy the backup homemapdata folder back to the app support location
2. Restart HomeMap

When Things Go Wrong

HomeMap won't start:

• Check the console/terminal for error messages
• Try resetting to defaults by temporarily moving the homemapdata folder
• Reinstall if needed (your data folder is preserved)

Can't connect to HC3:

• Verify IP address in Settings → HC3 tab
• Check username and password
• Make sure HC3 is powered on and accessible
• Try accessing HC3 web interface in a browser

Devices not appearing:

• Check device ID is correct in HC3
• Make sure device is enabled in HC3
• Try uninstalling and reinstalling the device via Device Management panel
• Check that the device is visible on the current floor

Floor plans not loading:

• Make sure you selected a valid image file (PNG, JPG, or GIF)
• Try re-adding the floor via Settings → Floors tab
• Check that the image file isn't corrupted
• Try a different image format if needed

Getting Help

Resources:

• Check the 

  Please login or register to see this link.

   for feature overview
• See the 

  Please login or register to see this link.

   for community discussion
• Review 

  Please login or register to see this link.

   for advanced options (developers)
• See 

  Please login or register to see this link.

   for custom widget development

Common Questions:

• Q: Can I use HomeMap on multiple computers?

  • A: Yes! The configuration folder can be synced via cloud storage, or you can export/import by copying the homemapdata folder

• Q: How do I add custom widgets?

  • A: See the Widget Format documentation - place custom widgets in homemapdata/widgets/packages/

• Q: Can I export my configuration?

  • A: Yes! Copy your entire homemapdata folder (found in Application Support) to backup or share

• Q: Do I need to manually edit config files?

  • A: No! HomeMap is designed to be fully configurable through the UI. Direct file editing is only for advanced customization.

---

Quick Start Checklist

Ready to get started? Follow this checklist:

•  Launch HomeMap (configuration folder created automatically)
•  Open Settings (⚙️) and go to HC3 tab
•  Enter your HC3 credentials (IP, username, password)
•  Save settings and verify "Connected to HC3" appears (green dot)
•  Go to Settings → Floors tab
•  Click "Add Floor" and select your floor plan image
•  Fill in floor name and ID, click Save
•  Close Settings and verify you see your floor tab
•  Click Edit Mode (✏️)
•  Open hamburger menu (☰) → Device Management
•  Find a device and click "Install"
•  Drag the device to position it on your floor plan
•  Exit Edit Mode
•  Try clicking the device to control it
•  Use zoom controls (in Edit Mode) to adjust the view
•  Add more devices and floors as needed!

---

 

Edited October 31, 2025 by jgab

[Brors94 115]

1 hour ago, jgab said:

 

Can you elaborate on this - what would you like to do with the 2 temp sensors?

What I mean is to make a widget for temperature to show 2 measurements, So I can add 1 temp widget for a room and display floor and room temperature without having 2 icons  




But ill gues we also could look into a widget for Thermostats later?  

Thermostat Widget (what I think it needs)

• setpoint 5-40(imported what the termostat actually supports)
• Mode (imported if the thermostat support modes)
• Display 1-3 Temperatures 

[Christb 33]

With the latest version, when I try to create a new device I do not have anymore the choices of widget  *

Please login or register to see this image.

/monthly_2025_10/image.png.ccf6e1e0df2d01e535504ea9bc433dec.png" />

I have already added device 195 with previous version and the only widget selectable was "light" but it was  not visible on the floor map**

Questions:

1) when you click on Add Device button, is a succes message displayed: I did not had any with  previous version but If I was willing to add it again, I got a message stating that this id was already existing...

2) in which file the added devices data are stored? I assume 'config.json' in  "devices" array: mine is still empty

3) is the following format for devices array correct?

devices": [

{

 "id": 195,
            "name": "Escalier Cave",
            "type": "light",
            "floor_id": "Cellar0",
            "position": {
                                 "x": 400,
                                 "y": 690

}

}

]

When I am adding the above in my config.json, I have a HC3 connection error message 1 seconds after launch  (HTTP 401) but HomeMap starts connected

 

* When HomeMap is not connected to HC3, then I can again select 

**it may be because I already had the http API error  

[Christb 33]

With the last vesion, 2 json files have been added in homemapdata: 'installed-packages.json' and 'widget-mappings.json' but all their elements are empty: {}, normal? 

[jgab 2,647]

I'm building v0.1.10, should be available in 10min. Fixes the missing widget bug, hopefully.
Yes, it's for supporting installing custom widgets. The idea is that we can package the widget.json + icons and distribute it as a custom widget file people can easily install.
(Coming in  a near future)