/compass-card

A Lovelace card that shows a directional indicator on a compass for Home Assistant

Primary LanguageTypeScriptMIT LicenseMIT

Compass card

A custom Lovelace card that displays an indicator in a circle for use with Home Assistant.

GitHub Release GitHub Release Date GitHub Releases GitHub Releases

HACS Badge HomeAssistant License

Project Maintenance GitHub Activity Open bugs Open enhancements

Community Forum Buy Me A Coffee

Installation

HACS (Home Assistant Community Store)

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

Manual

  1. Download the 'compass-card.js' from the latest release (with right click, save link as)
  2. 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)
  3. 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)
  4. Add a new resource
    1. Url = /local/compass-card.js
    2. Resource type = module
  5. Force refresh the Home Assistant page (Ctrl + F5)
  6. 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.

Default

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

Default

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

Default

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

Default

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/)

Default

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

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

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.

coffee