search

dermotduffy / frigate-hass-card

A Lovelace card for Frigate in Home Assistant
MIT License
477 stars 53 forks source link

Provide a full expanded config reference #486

Closed pejotigrek closed 2 years ago

pejotigrek commented 2 years ago

while I didn't checked the documentation for a long time, I've glanced into it after the v3 update and have an impression that the count of available options skyrocketed, which is good! on the other way, the method of explaination for each of the options is not always giving me clear infos, as there's an element of confusion like "where this or that should go", and examples given at the end sometimes confuse more.

Describe the solution you'd like I'd love to see a full config scheme, the "yaml-tree" which can be used as a template for tinkering.

Additional context I'm not saying that the "template" should have all the explainations inside [even if that would help more] but I guess that just all the "naked" options would be sufficent.

something like the Frigate full configuration reference seen here

blakeblackshear commented 2 years ago

What do you think is missing from the existing full configuration reference?

pejotigrek commented 2 years ago

What do you think is missing from the existing full configuration reference?

I don't think that something is missing in the terms of explaining every option - but thought it would be great if the frigate-hass-card had an additional example with full option-set just like Frigate has [under the link I gave above]. when I was tinkering my Frigate config, I just pasted the full reference from the Frigate's docs into my yml file and went line by line to set/delete stuff I wanted/needed/was obsolete etc. planned to do the same with the card but without the full source it's not that easy and quick :)

EDIT: I meant the form of the reference - kinda copy-n-paste yaml code, maybe that was unclear in my original post

blakeblackshear commented 2 years ago

Thanks. I got mixed up on which repository this was and thought it was in the main frigate repo. Oops.

pejotigrek commented 2 years ago

no problem, glad it cleared out :)

dermotduffy commented 2 years ago

Hi @pejotigrek , just want to make sure I understand. I think this is less about the options and explanations themselves (which should be fairly well described today), but more about being clear where the configuration goes?

In each option section I try to include All configuration is under: to make this clear, but I'll admit I'm not that happy with the clarity this offers.

Two caveats:

So I think your proposal of the "naked" options in an example would work.

Let me know if you disagree with any of the above / or have better ideas?

pejotigrek commented 2 years ago

Hi @pejotigrek , just want to make sure I understand. I think this is less about the options and explanations themselves (which should be fairly well described today), but more about being clear where the configuration goes?

h! yes, basically that's it. explanations are ok, just the where part is confusing here and there :)

In each option section I try to include All configuration is under: to make this clear, but I'll admit I'm not that happy with the clarity this offers.

I think that the overall number of options made the structure harder to understand. especially that there is a multi-level structure, something is under something, next thing is under that under-thing etc. ;) also: I am aware that it can be just my problem, but I thought I'll just ask if you can polish it a bit :)

  • I would like to avoid re-explanation of all the options as that's more places to update.

sure, that's why I thought that the "naked" template would be ok. explanations are already there :)

  • I'd like to discourage the "copy and paste a giant YAML block with the defaults" behavior. It's just more places for users to update when the configuration changes -- and at this stage in card maturity, they are changing a lot. There's also a visual editor that is intended to ensure 90%+ of users don't need YAML at all.

yeah, the visual editor - that's why I know it is probably just my problem ;) and maybe a few others. just because I do all my config "oldschool-way". in the yaml [tried the visual, but with my level of dashboards, it's almost impossible to build views with WYSIWYG editor ;)

So I think your proposal of the "naked" options in an example would work.

the "naked" template could be an index with hyperlinks pointing to each section in the docs. two birds with one stone: a quick index, and convenient child/parent options visualisation :)

Let me know if you disagree with any of the above / or have better ideas?

no problem - I'm just thinking out loud. of course there's no obligation for you to implement any of my words, so don't feel bad if you want to tell me "no" at any point ;)

dermotduffy commented 2 years ago

the "naked" template could be an index with hyperlinks pointing to each section in the docs. two birds with one stone: a quick index, and convenient child/parent options visualisation :)

Probably run into formatting/markdown issues there, don't think you can put hyperlinks into code markdowns -- but I can experiment.

no problem - I'm just thinking out loud. of course there's no obligation for you to implement any of my words, so don't feel bad if you want to tell me "no" at any point ;)

If you have this problem / concern, so will the next person. I'm never going to say no to a good idea :-)

r3wt commented 2 years ago

@dermotduffy as a person who is brand new to home assistant, custom cards, basically all of this crap other than the coding aspect, i can't figure out based on your documentation how to get started with this. the documentation seems to assume some prior knowledge of lovelace/ha. I can't figure out how to find the card in the UI, though i did install the files in the server. would have been great if the "manual installation" instructions were more explicit, eg that the frigate-hass-card.js needs to be placed in <config dir>/www/frigate-hass-card.js, then imported with yaml configuration or from the add resource dialog. it took me a while fumbling around and restarting the server to figure it out. once i have figured out where to place the file, and how to edit the configuration.yaml, after i restared the server now i can see the card in the card list

dermotduffy commented 2 years ago

Thanks for the feedback @r3wt !

May I ask why you were doing a manual install in the first place, vs a HACS install? It removes the need for much of what you describe. The instructions in the README are:

Home Assistant > HACS > Frontend > "Explore & Add Integrations" > Frigate Card
lovelace:
  resources:
    - url: /hacsfiles/frigate-hass-card/frigate-hass-card.js
      type: module

Maybe the piece missing is to make it explicit on what HACS is, and that (for brand new people) installing HACS is the first step? And that you really (really) should install using it rather than trying to do it manually?

r3wt commented 2 years ago

I'm running HA Supervised so i don't have access to HACS @dermotduffy. anything i want i have to install manually.

dermotduffy commented 2 years ago

I'm running HA Supervised so i don't have access to HACS @dermotduffy. anything i want i have to install manually.

I do not believe that is accurate -- HACS should work fine for HA supervised. See download instructions: https://hacs.xyz/docs/setup/download (Note 'OS/Supervised' tab).

r3wt commented 2 years ago

@dermotduffy if i do that, then i can't have "Add ons" anymore? I don't think i want that at all

pejotigrek commented 2 years ago

@dermotduffy if i do that, then i can't have "Add ons" anymore? I don't think i want that at all

I am almost sure you're messing up some naming and/or installation types and that's confusing not only for us to understand what's up with your install, but also for you to know what to do ;)

I've got a supervised install [on ubuntu server], I installed HACS almost at the beginning of it's existence and have no problems at all.

addons won't interfere with HACS, HACS won't interfere with addons. it all still works like it should.

r3wt commented 2 years ago

@pejotigrek No, i am definitely running HA Supervised, on linux mint 20.3 - When i proceed through the hacs installation, it gives a popup with checkboxes, one of which says "I understand that there are no Add-ons in hacs". So are you saying this is simply not true, but a scare tactic? I do not want to lose my already installed addons, just to add this "hacs"

pejotigrek commented 2 years ago

@pejotigrek No, i am definitely running HA Supervised, on linux mint 20.3 - When i proceed through the hacs installation, it gives a popup with checkboxes, one of which says "I understand that there are no Add-ons in hacs". So are you saying this is simply not true, but a scare tactic? I do not want to lose my already installed addons, just to add this "hacs"

it's just an information, that you can't find any addons in the HACS ;) addons are still in the "addon store" where they should be :) HACS is for custom integrations, custom cards etc. :)

EDIT: consider HACS as an additional integration/cards-store :) not an alternative to addons-store.

dermotduffy commented 2 years ago

Yes, the naming is certainly confusing if you're new to the Home Assistant world. Briefly:

HACS provides a store for the latter two. The addon-store provides the store for the former. Most users (of Supervised / HAOS) will have both, they are perfectly compatible and complimentary.

dermotduffy commented 2 years ago

Full expanded examples added in the documentation for v4.0.0: https://github.com/dermotduffy/frigate-hass-card/tree/release-4.0.0#illustrative-expanded-configuration-reference