Skip to content

Latest commit

 

History

History
176 lines (128 loc) · 13.8 KB

README.md

File metadata and controls

176 lines (128 loc) · 13.8 KB
Raw

Home Assistant Map Card

Take a look at the blog post introducing the custom:map-card for Home Assistant.

An example of the custom:map-card

Installation

Manual

  1. Copy map-card.js to your /var/lib/hass/www folder.
  2. Click on Edit Dashboard, Manage resources add /local/map-card.js as JavaScript Module.

HACS

TIP

The PR to add this to the default HACS repo is still open: hacs/default#2377

Follow the instructions to add a HACS Custom Repository.

Usage

TIP

Home Assistant contains a native map feature, if you don't need advanced features like WMS layers it might be a better choice.

Minimal

type: custom:map-card
x: 51.23
y: 3.652

More advanced

TIP

Take a look at: https://nathan.gs/2024/01/06/ha-map-card-a-new-and-alternative-leaflet-based-map/#a-more-advanced-example-measuring-pm25-air-quality-for-my-home

Options

name Default note
x Longitude
y Latitude
history_start Date: 2022-03-01T12:00:00Z
Time code: 5 hours ago
Entity: input_number.example_number
See History options for full details.
history_end now Date: 2022-03-01T12:00:00Z
Time code: 5 hours ago
Entity: input_number.example_number
See History options for full details.
focus_entity Entity to focus on. Map will default to show all markers if this and X/Y are not set.
title If empty, don't show a title
zoom 12 The zoom level. Ignored unless focus_entity or X & Y coords are set.
card_size 5 The Home Assistant card size
entities [] Array of entities, will be listed as markers
wms [] WMS Layers, an array of WMS see below
tile_layers [] Tile Layers, an array of Tile Layers see below
tile_layer_url https://tile.openstreetmap.org/{z}/{x}/{y}.png Override the default map source
tile_layer_attribution &copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> Set the correct map attribution
tile_layer_options {} The options for the default TileLayer
history_date_selection false Will link with a energy-date-selection on the page to provide an interactive date range picker.
theme_mode auto auto, light ordark
debug false Enable debug messages in console.

If x & y or focus_entity is not set it will take the lat/long from the first entity.

Entity options

Either the name of the entity or:

name Default note
entity The entity id
display marker icon, state or marker. marker will display the picture if available
picture Set a custom picture to use on the marker.
size 48 Size of the icon
color Random Color Can defined as red, rgb(255,0,0), rgba(255,0,0,0.1), #ff0000, var(--red-color)
css text-align: center; font-size: 60%; CSS for the marker (only for state and marker)
history_start Will inherit from map config if not set.
Date: 2022-03-01T12:00:00Z
Time code: 5 hours ago
Entity: input_number.example_number
See History options for full details.
history_end now Will inherit from map config if not set.
Date: 2022-03-01T12:00:00Z
Time code: 5 hours ago
Entity: input_number.example_number
See History options for full details.
history_line_color Random Color Can defined as red, rgb(255,0,0), rgba(255,0,0,0.1), #ff0000, var(--red-color)
history_show_lines true Show the path
history_show_dots true Show little dots on the path
fixed_x Display a fixed marker, this will ignore the latitude/longitude attributes
fixed_y Display a fixed marker, this will ignore the latitude/longitude attributes
fallback_x If the latitude/longitude is missing, use these fixed attributes
fallback_y If the latitude/longitude is missing, use these fixed attributes
tap_action {"action": "more-info"} Allow custom action to be triggered when this entity is clicked. Actions include more-info, call-service, navigate, url, assist, none. Some actions require additional paramaters. navigate requires a navigation_path. url requires a url_path. call-service requires service and an optional data
gradual_opacity The total amount of opacity will be gradually distributed across the paths. gradual_opacity is divided by the number of paths to calculate the opacity step for each path. The base opacity is generated by (1 - gradual_opacity), and as each path progresses, its opacity gradually darkens by the step amount.
focus_on_fit true If this variable is set to false, This entity will be excluded when the map fits the included entities on the screen.
z_index_offset 1 z-index value that determines what is displayed on top when markers overlap. (Setting a gap of at least 20 between the values assigned to each entity is recommended.)

History options.

If history_date_selection:true, any entities that do not define their own history_start and history_end configuration will be automatically linked to this. Please ensure a card of type: energy-date-selection exists on the page before enabling this.

This can be added via the "Add Card" dialog by selecting Manual and entering the text type: energy-date-selection.

Alternatively history_start and history_end can be set to

  • A specific date such as 2022-03-01T12:00:00Z
  • A time code such as 10 days ago 4 hours ago 1 week ago etc.
  • An entity that will provide either a date or number (which will be used as the amount of hours ago to show). e.g. input_number.example_number_value

If you want to specify your own unit, configure the history_start/history_end as the below.

history_start:
  entity: input_number.example_number_value
  suffix: days ago

Each entity can individually override the base config by setting its own history_start/history_end, using any of the options above. Any entity without its own settings will inherit the map level config.

WMS and tile_layers options

name note
url The url of the layer
options The leaflet layer WMS options or Tile Layer options
history The name of the layer option which controls the dat, if it supports a date or time option. Set history to the name of this property. The history_start value, state or date range picker will then set this property on the layer and update it as necessary.
Zooming & tile_layer_options.maxZoom

By default the map-card will not zoom beyond default property of the maxZoom of the tilelayer, the default is 18, but it can be overriden as follows:

type: custom:map-card
tile_layer_options:
  maxZoom: 20

Keep in mind that the tile layer source also has a maximum zoom level, which is 20 for most OSM maps.

Advanced WMS/Tile layer options.

More complex use of the WMS/Tile history property can be configured within the history property of the layer.

  • property is the option this should control (often named time or date)
  • source defaults to auto (which means it will inherit from the main map settings). Set this to a date or number entity if this is different.
  • suffix days ago/weeks ago as with other history entities
  • force_midnight some WMS/Tile layers only work if the date is set as midnight.
  history:
    property: time
    source: input_number.test_number_value
    suffix: months ago
    force_midnight: true

Extra Tile Layers

The leaflet-extras has a nice list of available tile layer providers.

Development

git clone [email protected]:nathan-gs/ha-map-card.git

This project uses devenv.sh.

  1. Install devenv
  2. devenv shell and then watch or devenv shell watch to immediatly drop into a watched shell.

NPM alternatives

  • npm install
  • npm run build (npm run watch to update on change)

Mentions & Discussions