Compass card

A custom Home Assistant dashboard card that displays an indicator in a circle.

Installation

HACS (Home Assistant Community Store)

Go to HACS page on your Home Assistant instance
Select Frontend
Press add icon and search for compass
Select Compass Card repo and install
Force refresh the Home Assistant page (Ctrl + F5)
Add compass-card to your page

Manual

Download the 'compass-card.js' from the latest release (with right click, save link as)
Place the downloaded file on your Home Assistant machine in the config/www folder (when there is no www folder in the folder where your configuration.yaml file is, create it and place the file there)
In Home Assistant go to Configuration->Lovelace Dashboards->Resources (When there is no resources tag on the Lovelace Dashboard page, enable advanced mode in your account settings, and retry this step)
Add a new resource
1. Url = /local/compass-card.js
2. Resource type = module
Force refresh the Home Assistant page (Ctrl + F5)
Add compass-card to your page

Using the card

Add the card with the visual editor
Or add the card manually with the following (minimal) configuration:

type: custom:compass-card
indicator_sensors:
  - sensor: sensor.wind_dir

Lovelace Examples

Default

type: custom:compass-card
header:
  title:
    value: Friend's location
indicator_sensors:
  - sensor: sensor.friends_direction
value_sensors:
  - sensor: sensor.friends_distance

Issue #41 shows an example how to calculate the distance/direction of your friend.

Compass indicator `arrow_inward`

type: custom:compass-card
header:
  title:
    value: Wind
indicator_sensors:
  - sensor: sensor.wind_dir
    indicator:
      type: arrow_inward
value_sensors:
  - sensor: sensor.wind_speed

Compass indicator `circle`

type: custom:compass-card
header:
  title:
    value: Sun
indicator_sensors:
  - sensor: sun.sun
    attribute: azimuth
    indicator:
      type: circle
value_sensors:
  - sensor: sun.sun
    attribute: elevation

Compass `north indicator` and `direction offset`

Left image yaml:

type: custom:compass-card
header:
  title:
    value: Sun
indicator_sensors:
  - sensor: sun.sun
    attribute: azimuth
    indicator:
      type: circle
value_sensors:
  - sensor: sun.sun
    attribute: elevation
compass:
  north:
    show: true

Right image yaml:

type: custom:compass-card
header:
  title:
    value: Sun
indicator_sensors:
  - sensor: sun.sun
    attribute: azimuth
    indicator:
      type: circle
value_sensors:
  - sensor: sun.sun
    attribute: elevation
compass:
  north:
    show: true
    offset: 15

Compass `cardinal indicators` and `background`

type: custom:compass-card
header:
  title:
    value: Sun
indicator_sensors:
  - sensor: sun.sun
    attribute: azimuth
    indicator:
      type: circle
value_sensors:
  - sensor: sun.sun
    attribute: elevation
compass:
  circle:
    background_image: /local/compass-card/home.png
    background_opacity: 0.5
  north:
    show: true
    offset: 30
  east:
    show: true
  west:
    show: true
  south:
    show: true

Store the background image in your config/www/ folder (this maps to /local/)

Options

Name	Type	Requirement	Supported	Config	Description
type	string	Required	v0.0.1	N.a.
header	header object	Optional	v1.0.0	See header object	Card header settings
compass	compass object	Optional	v1.0.0	See compass object	Compass settings
indicator_sensors	Array of indicator sensors object	Required	v1.0.0	See indicator sensors object	Entities to use as indicator on compass
value_sensors	Array of value sensors object	Optional	v1.0.0	See value sensors object	Entities to show under the direction in compass
language	language	Optional	v1.0.0	Visual/YAML	Show the abbreviation in the language configured in Home Assistant (default/empty), or configured language
tap_action	action config object	Optional	v1.0.0	See action config object	Tap action settings (what happens when you click/touch the card)
debug	boolean	Optional	v1.0.0	YAML	Show inflated configration & incorrect configured entities and attributes in browsers developers console

Header object

Name	Type	Requirement	Supported	Config	Description
title	title object	Optional	v1.0.0	See title object	Settings for the title in the header
icon	icon object	Optional	v1.0.0	See icon object	Settings for the icon in the header

Title object

Name	Type	Requirement	Supported	Config	Description
value	string	Optional	v1.0.0	YAML	Title to show in the card header
color	string	Optional	v1.0.0	YAML	Color of object
show	boolean	Optional	v1.0.0	YAML	Show object
dynamic_style	dynamic style object	Optional	v1.0.0 (WIP)	YAML	Change style on entity values

Icon object

Name	Type	Requirement	Supported	Config	Description
value	string	Optional	v1.0.0	YAML	Icon show in the card header
color	string	Optional	v1.0.0	YAML	Color of object
show	boolean	Optional	v1.0.0	YAML	Show object
dynamic_style	dynamic style object	Optional	v1.0.0 (WIP)	YAML	Change style on entity values

Compass object

Name	Type	Requirement	Supported	Config	Description
north	north object	Optional	v1.0.0	See north object	Settings for the north indicator (default hidden)
east	properties object	Optional	v1.2.0	YAML	Settings for the east indicator (default hidden)
south	properties object	Optional	v1.2.0	YAML	Settings for the south indicator (default hidden)
west	properties object	Optional	v1.2.0	YAML	Settings for the west indicator (default hidden)
circle	circle object	Optional	v1.0.0	See circle object	Settings for the compass circle

North object

Name	Type	Requirement	Supported	Config	Description
offset	string	Optional	v1.0.0	YAML	Value to offset the indicator display with. (E.g. to create a relative north)
color	string	Optional	v1.0.0	YAML	Color of object
show	boolean	Optional	v1.0.0	YAML	Show object
dynamic_style	dynamic style object	Optional	v1.0.0 (WIP)	YAML	Change style on entity values

Circle object

Name	Type	Requirement	Supported	Config	Description
background_image	string	Optional	v1.2.0	YAML	URL of image to show in the background of the circle (use square image of preferably 126px by 126px). See Home Assistant documentation for info about hosting files.
background_opacity	number	Optional	v1.2.0	YAML	Opacity of the background image 1 = 100% visible, 0.5 = 50% half visible, 0 = fully hidden, anything between 0 and 1 will do.
offset_background	boolean	Optional	v1.2.0	YAML	If `true` then image rotates with north offset (default), if `false` then image does not rotate with north offset
color	string	Optional	v1.0.0	YAML	Color of object
show	boolean	Optional	v1.0.0	YAML	Show object
dynamic_style	Array of dynamic style objects	Optional	v1.0.0	YAML	Change style on entity values

Indicator Sensors object

Name	Type	Requirement	Supported	Config	Description
sensor	string	Required	v1.0.0	First visual, others YAML	Entity to read state from
attribute	string	Optional	v1.0.0	YAML	Attribute of sensor to read value from instead of entity state
units	string	Optional	v1.0.0	YAML	Units of measurement to display, default for entity, units of measurement of entity, default for attribute ''
decimals	number	Optional	v1.0.0	YAML	Decimals to show the value in, default 0
indicator	indicator object	Optional	v1.0.0	See indicator object	Settings for displaying the state as indicator
state_abbreviation	properties object	Optional	v1.0.0	YAML	Settings for displaying the state abbreviation
state_value	properties object	Optional	v1.0.0	YAML	Settings for displaying the state value
state_units	properties object	Optional	v1.0.0	YAML	Settings for displaying the state units

Value Sensors object

Name	Type	Requirement	Supported	Config	Description
sensor	string	Required	v1.0.0	First visual, others YAML	Entity to read state from
attribute	string	Optional	v1.0.0	YAML	Attribute of sensor to read value from instead of entity state
units	string	Optional	v1.0.0	YAML	Units of measurement to display, default for entity, units of measurement of entity, default for attribute ''
decimals	number	Optional	v1.0.0	YAML	Decimals to show the value in, default 0
state_value	properties object	Optional	v1.0.0	YAML	Settings for displaying the state value
state_units	properties object	Optional	v1.0.0	YAML	Settings for displaying the state units

Indicator object

Name	Type	Requirement	Supported	Config	Description
type	string	Optional	v1.0.0	First visual, others YAML	One of `arrow_outward` (default), `arrow_inward`, `circle`, the shape of the indicator

Properties object

Name	Type	Requirement	Supported	Config	Description
color	string	Optional	v1.0.0	YAML	Color of object
show	boolean	Optional	v1.0.0	YAML	Show object
dynamic_style	Array of dynamic style objects	Optional	v1.0.0	YAML	Change style on entity values

Dynamic Style object

Name	Type	Requirement	Supported	Config	Description
sensor	string	Optional	v1.0.0	YAML	Entity to listen to read value from style
attribute	string	Optional	v1.0.0	YAML	Attribute of sensor to read value from to change style
bands	Array of style band objects	Required	v1.0.0	YAML	Styles to use from a certain value (values below the lowest configured value will display as the parent properties object settings)

Style band object

Name	Type	Requirement	Supported	Config	Description
from_value	string	Required	v1.0.0	YAML	Value from which upward this bands settings are used to display the parent object with
color	string	Optional	v1.0.0	YAML	Color of object
show	boolean	Optional	v1.0.0	YAML	Show object

Dynamic Style & Style band example

For a card that

Displays indicator for the suns azimuth
Changes color of the icon, compass and north indicator depending on the current UV Index
Hide sun indicator when elevation is below horizon

Use the following configuration

type: 'custom:compass-card'
header:
  title:
    value: Sun
  icon:
    color: green # default color (for state is less than the lowest dynamic_style.bands.from_value)
    dynamic_style:
      sensor: sensor.uvi
      bands:
        - from_value: 3
          color: yellow
        - from_value: 6
          color: orange
        - from_value: 8
          color: red
        - from_value: 11
          color: purple
indicator_sensors:
  - sensor: sun.sun
    attribute: azimuth
    indicator:
      type: circle
      color: orange
      show: false # default visibility (for state is less than the lowest dynamic_style.bands.from_value)
      dynamic_style:
        sensor: sun.sun
        attribute: elevation
        bands:
          - from_value: 0
            show: true
value_sensors:
  - sensor: sun.sun
    attribute: elevation
    decimals: 1
compass:
  north:
    show: true
    color: green # default color (for state is less than the lowest dynamic_style.bands.from_value)
    dynamic_style:
      sensor: sensor.uvi
      bands:
        - from_value: 3
          color: yellow
        - from_value: 6
          color: orange
        - from_value: 8
          color: red
        - from_value: 11
          color: purple
  circle:
    color: green # default color (for state is less than the lowest dynamic_style.bands.from_value)
    dynamic_style:
      sensor: sensor.uvi
      bands:
        - from_value: 3
          color: yellow
        - from_value: 6
          color: orange
        - from_value: 8
          color: red
        - from_value: 11
          color: purple

Action Config object

Name	Type	Requirement	Default	Supported	Config	Description
action	list item	Optional	`more-info`	v0.4.0	YAML only	Type of action to launch when clicking/touching the card: `more-info` `navigate` `url` `call-service`
entity	string	Optional for action `more-info`	`entity` used for compass direction	v0.4.0	YAML only	Entity to show the `more-info` of. When empty the compass direction `more-info` is shown
navigation_path	string	Required for action `navigate`		v0.4.0	YAML only	Path to navigate to, has to be on the same host as the card is. E.g. `/logbook`, `/config/dashboard` or `lovelace/default_view`
url	string	Required for action `url`		v0.4.0	YAML only	Url to navigate to, can be any valid webpage
new_tab	boolean	Optional for action `url` and `navigate`	`true`	v0.4.1	YAML only	Open url or navigate in new tab/window
service	string	Required for action `call-service`		v0.4.0	YAML only	Home Assistant service to call, see `Developer Tools -> Services` what services are available, e.g. `light.turn_on`
service_data	string, json format	Optional for action `call-service`		v0.4.0	YAML only	Service data to send, see `Developer Tools -> Services` what data specific services need. Needs to be a string in json format e.g. `{"entity_id": "light.kitchen", "rgb_color": [255,100,100]}`

Action config examples

More Info

Open the more info of a person entity when clicking/touching the card

type: custom:compass-card
indicator_sensors:
  - sensor: sensor.friends_direction
value_sensors:
  - sensor: sensor.friends_distance
tap_action:
  entity: person.friend

Navigate

Open the Home Assistant map page when clicking/touching the card

type: custom:compass-card
indicator_sensors:
  - sensor: sensor.friends_direction
value_sensors:
  - sensor: sensor.friends_distance
tap_action:
  action: navigate
  navigation_path: /map

Url

Open Google Maps when clicking/touching the card

type: custom:compass-card
indicator_sensors:
  - sensor: sensor.friends_direction
value_sensors:
  - sensor: sensor.friends_distance
tap_action:
  action: url
  url: https://www.google.nl/maps

Call Service

Send notification when clicking/touching the card

type: custom:compass-card
indicator_sensors:
  - sensor: sensor.friends_direction
value_sensors:
  - sensor: sensor.friends_distance
tap_action:
  action: call-service
  service: notify.notify
  service_data: '{"message": "Hey Im watching you.", "title": "Message from your best friend"}'

Language

The following languages are supported:

Language	Yaml value	Supported	Translated by
Bulgarian	`bg`	v1.4.0	@Saentist
Catalan	`ca`	v1.6.0	@joan-mb
Czech	`cz`	v0.4.0	@woodcat64
Danish	`da`	v1.3.0	@DurgNomis-drol
Dutch	`nl`	v0.3.0	@tomvanswam
English	`en`	v0.3.0	@tomvanswam
French	`fr`	v0.3.1	@andilge
German	`de`	v0.3.0	@rainer-geiger
Hungarian	`hu`	v1.0.0	@bboti86
Icelandic	`is`	v1.5.0	@halliiav
Italian	`it`	v0.3.0	@matteofranceschini
Norwegian	`no`	v0.3.1	@hwikene
Portugese	`pt`	v0.3.1	@andilge
Polish	`pl`	v0.3.2	@porebas
Slovenian	`sl`	v1.2.0	@thehijacker
Russian	`ru`	v0.4.0	@artemyevav
Spanish	`es`	v0.3.1	@andilge
~~Swedish~~	~~`se`~~	~~v1.5.0~~	~~@Boris65 and @nickrout~~
Swedish	`sv`	v2.0.0	@Boris65 and @nickrout

Pick the language in the visual editor, or add it to yaml config.

Example for Portugese abbreviations (regardless of Home Assistant language setting):

type: custom:compass-card
indicator_sensors:
  - sensor: sensor.friends_direction
value_sensors:
  - sensor: sensor.friends_distance
compass:
  language: pt

More YAML examples

See the issues with the config how-to label for more configuration examples.

Upgrade from version v0.x.x to v1.0.0 +

v1.0.0 has breaking changes, meaning the card wil not work as expected after updating.

Semi-automatic update procedure

To upgrade your v0.x.x card, just open the card in the editor, and save it. No changes needed to the card. The configuration will update to the correct version, and your card is v1.0.0 ready.

If the compass-card is inside another card (horizontal/vertical-stack), use the visual editor menu to navigate to the compass-card. It will update to the new config.

Manual update procedure

See following YAML examples of a full v0.x.x config and its v1.0.0 equivalent Note: the tap_action object does not change and you can keep the v0.x.x version.

v0.x.x

type: custom:compass-card
name: title
entity: sensor.friends_direction
secondary_entity: sensor.friends_distance
direction_offset: 15
compass:
  language: pt
  indicator: arrow_outward
  show_north: true

v1.0.0 +

type: custom:compass-card
header:
  title:
    value: title
indicator_sensors:
  - sensor: sensor.friends_direction
    indicator:
      type: arrow_outward
value_sensors:
  - sensor: sensor.friends_distance
compass:
  north:
    show: true
    offset: 15
language: pt

Wish/Todo list

Background image (#12)
Resizing compass on smaller cards (#44)

Contact

You can find me on the Home Assistant Community Site
And occasionally on the HACS and Home Assistant Discord

Thanks to

@rsnodgrass for the idea to make this
@iantrich for the boiler-plate card, which got me started
All the translators

Support

Help me out for a couple of 🍻, a ☕ or legos!
Or clone, and create and a PR to help make the card even better.

Name		Name	Last commit message	Last commit date
Latest commit History 438 Commits
.devcontainer		.devcontainer
.github		.github
docs/images		docs/images
elements		elements
ha		ha
rollup-plugins		rollup-plugins
src		src
.env.example		.env.example
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.prettierrc.js		.prettierrc.js
LICENSE		LICENSE
README.md		README.md
docker-compose.yaml		docker-compose.yaml
hacs.json		hacs.json
package.json		package.json
rollup.config.dev.js		rollup.config.dev.js
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

License

tomvanswam/compass-card

Folders and files

Latest commit

History

Repository files navigation