Installation instructions aren't straightforward enough.

RickSanchezC136 commented 1 year ago

Bug description

Installation instructions were not specific enough to allow me to install the card. There was mention in the instructions to reach out if so...

To Reproduce

Steps to reproduce the behavior:

Goto HACS frontend, and download Swiss Army Knife card.
?

Expected behavior

It says something about resource.yaml, but I didn't see what code to add.

Desktop browser (please complete the following information):

OS: Windows
Browser Edge
Version ?

Additional context Just wanted to help provide assistance to make the install documentation easier to follow.

github-actions[bot] commented 1 year ago

Thank you for creating your first issue for the Swiss Army Knife custom card!

albarlow commented 1 year ago

Agreed, I went to the website and step 2a talks about putting files into a lovelace folder. I don't have one. I couldn't create one because all my dashboard data is stored in a file called 'lovelace' (no extension) so not possible to create a lovelace folder. I then went back and started working from the top and step 1c talks about a lovelace entry in configuration.yaml. I don't have an entry and it points to this non-existent lovelace folder again. I've been using HACS custom cards for years and this has never been an issue.

I think the request has got to be to streamline the install if at all possible - I realise not everything can be point and click but, in my opinion, I think that if you're putting it in HACS, it should create the structure and you just need to drop e.g. the template files in.

It looks really good from the website and I was eager to try it out back before you released it earlier this year so I'm keen to get it working.

drmandel01 commented 1 year ago

This is designed to be a basic, follow-the-directions-exactly, installation of the Swiss Army Knife card, using the Hybrid Installation. This is for those who have only built HA Dashboards through the GUI and may have become a bit lost in the complete, but detailed (for some overally-detailed) installation procedures at https://swiss-army-knife-card-manual.amoebelabs.com/start/installation/.

Please let me know if this works for you and if there are any issues or errors. Thanks.

Step-by-Step Hybrid Install of the complete system, including example and tutorial dashboards

NOTE: These instructions will allow you to keep your GUI-created dashboards while adding YAML-based ones like Swiss Army Knife Card (just remember not to call your YAML file ui-lovelace.yaml).

Install the following cards using HACS

a. Decluttering card b. Button-card c. Swiss Army Knife Card

Install the necessary files into Home Assistant folders

Download the zip file from https://github.com/AmoebeLabs/swiss-army-knife-card (find it under the green Code button) and unzip in a location where you can easily copy directories and files to the Home Assistant "root" folder.

What I mean by the "root" folder. This is the folder that contains the configuration.yaml file. It is actually under config/ if you use Samba (highly recommended - see Home Assistant' Samba Share Add-on). By using Samba I can unzip the files on my local hard drive and copy-and-paste them to the Home Assistant server.

If you are copy-and-pasting entire folders, then you will not need to create the folders on the Home Assistant server. If you are copying individual files, then first create the folders (if they do not already exist):

In the root folder: -- themes -- lovelace

In www folder -- images

Now start copying

a. From unzipped folder, copy sak-examples-dashboard.yaml to root level

b. From the unzipped ha-config/lovelace folder copy all files into their respective folders: -- Ha-config/lovelace/decluttering_templates -> lovelace/decluttering_templates -- Ha-config/lovelace/resources -> lovelace/resources -- Ha-config/lovelace/sak_templates -> lovelace/sak_templates -- Ha-config/lovelace/views -> lovelace/views

c. For the unzipped ha-config/themes folder you only want to copy one of the m3- themes (I chose magenta) and the following files: -- Ha-config/themes/m3-c12-magenta.yaml -> themes/m3-c12-magenta.yaml -- Ha-config/themes/nm-01-gonsboro.yaml -> themes/nm-01-gonsboro.yaml -- Ha-config/themes/nm-03-dark-steelblue.yaml -> themes/nm-03-dark-steelblue.yaml

d. For the unzipped images, you want to copy all the files in ha-config/images into a www/images folder -- Ha-config/www/images -> www/images

e. You need two dashboards for the full install. Copy these files to the root folder:

-- Ha-config/sak-examples-dashboard.yaml -> sak-examples-dashboard.yaml -- Ha-config/sak-tutorials-dashboard.yaml -> sak-tutorials-dashboard.yaml

Add the following to configuration.yaml

-- Place the following near the top (I have it after my various !includes, but just after "default_config:" should work)

frontend:
  themes: !include_dir_merge_named themes/

-- Place the following in the body of the file. I have it as the last block.

lovelace:
  mode: storage
  # Add yaml dashboards
  dashboards:
    sak-tutorials:
      mode: yaml
      filename: sak-tutorials-dashboard.yaml
      title: Swiss Army Knife Tutorial
      icon: mdi:hospital-box
      show_in_sidebar: true
    sak-examples:
      mode: yaml
      filename: sak-examples-dashboard.yaml
      title: Swiss Army Knife Examples
      icon: mdi:hospital-box
      show_in_sidebar: true

Restart Home Assistant

a. Developer tools b. Check Configuration (fix any errors) c. Restart

After restarting you should see two new dashboards on the left sidebar. Not all tabs will show images as some are tied to entities you may not have installed (like weather). Check on the other tabs and you should see wonderful buttons and controls.

FINAL NOTE: When you want to build your own SAK dashboard, I would recommend you DO NOT name it ui-lovelace.yaml. Doing so and placing this as the dashboard filename in the lovelace block in configuration.yaml will replace your current default dashboard with this and hide your previous default file. Call it something else. If you do accidentally use ui-lovelace.yaml, you can undo by temporarily removing the lovelace: block in configuration.yaml, rename the file and the reference to it, and put it back in the configuration.

AmoebeLabs commented 1 year ago

Thanks for the additions. It was hard to write something down initially.

I will review your comments!

BarBaar44 commented 11 months ago

Thanks! This is much more straightforward for me!

I do believe steps 2A and 2E have an overlap. sak-examples-dashboard.yaml is being copied twice.

Some small remarks that got me confused during my initial try to follow https://github.com/AmoebeLabs/swiss-army-knife-card

The resources are now manageable via Lovalace (three dots in the upper right corner when in edit mode). However, HACS should already have set this.
You need to download some files from Github, even when installing using HACS. This got me very confused as I kept trying to find them locally after my HACS install
/hacsfiles is the same as /www/community (by default?)
Last one: maybe emphasize that you need to change all references to the weather sensors (basically find and replace) in the examples to get them to fully work.

Hope this helps!

papperone commented 8 months ago

I am sure I miss something but no matter what I do, following these instructions multiple time I cannot use this card at all! All the ones from demo dashboard shows the error "i.setConfig is not a function" and if I try to add a new card from scratch in my existing dashboard same error :( I feel really stupid as I've been using/testing dozens of cards and component and only this one there's no way I can add it to my HA... before I give up and remove it completely can someone help somehow?

AmoebeLabs / swiss-army-knife-card