Documentation would benefit from example configurations

[JelkeH]

Hi,

I found the discussion in the HA community. Although it is a great resource it is also more of a log of things people tried instead a clear how-to.

Things that could for example be added:

• how to setup a card with the latest picture. Download/ or camera definition (not clear to me)
• What is the effect of the collect postcard service? Won't I see and have to check it in my BB app. And what is the effect if I do not collect the sighting in HA.

Maybe even:

• Downloading all images
• a card with rotation of the downloaded images

Furthermore, I think there are some entities missing from the documentation.

I'm currently struggling to get it working in my HA. If I have a working configuration I'm happy to help with a PR.

[jhansche]

Lots of questions here, I'll try to address them all.

how to setup a card with the latest picture. Download/ or camera definition (not clear to me)

That's a good idea to document it, perhaps as a cookbook recipe or something. Likewise for using Downloader to save or archive the most recent media (or all media if you have a need for that).

I had started to toy around with the idea of adding our own camera entity that just shows the last seen photo, or even last N photos as a slideshow, or the videoMedia from the most recent visit. But it feels like anything more than just the last photo is a lot of complexity for something that is really a matter of preference and choice, which causes complexity to increase dramatically. That leaves us with a few options for the implementation:

1. Single photo: very simple (works just like the Generic Camera), and allows us to work around the expiring AWS link.
2. Multiple photos: more complex because now we have to manually maintain the list of media and rotate between them.
   • We have to decide or expose configurations for how many images to cycle, and whether the images should be from only the most recent postcard visit, or maintain the most recent N photos across multiple visits, or a single photo from each of the last N visits, etc. Those choices could be represented with just 2 options: number of visits/postcards to rotate, and number of images per visit; such that recent_visits: 1 and images_per_visit: 1 effectively emulates the (1) single photo option.
   • Since all of these are a matter of preference, I decided that it's probably better suited to using another integration that is designed for your specific requirements, coupled with manually downloading the exact images you want in your slideshow. This is what many users in the HA forum decided to do, because there's really no one-size-fits-all solution. Rather than forcing my interpretation of one or more of these options, I leave it as an exercise for the user to decide what your requirements are, and then utilize existing integrations to satisfy those requirements.
3. Video: this is a whole other beast, because Generic Camera does not support streaming a single mp4 video file, only an HTTP image URL, or an RTSP camera feed.
   • FFMPEG does have this capability (looping input from an mp4 video file), and in theory you could probably get the FFMPEG Camera to do this for you. I don't know what would happen in this case, if the input video file gets replaced -- does ffmpeg pick up the new file and switch it in its loop, or will it see that as a broken file and stop working? There's also an issue that I recall reading a while back, about how the FFMPEG integration will not allow looping the video file, because the Stream integration still sees the "end of stream" marker, and effectively closes the stream when that is encountered. I'm not sure if that is still an issue, and/or if the FFMPEG -stream_loop option works around that issue.
   • Additionally, Frigate has support for this in much the same way, where Frigate can expose a looping mp4 video file as if it is a camera. This is usually used for testing so that you can have a single clip taken from a camera, and test different motion and object detection settings until you get the exact behavior you want for a given clip. Same question applies here: what happens when the underlying video file gets overwritten? I don't know, and if it doesn't already handle that, I doubt that the maintainers would entertain the ability to pick up file changes in a reliable way, given this capability is advertised only for development and testing purposes.

Due to all of these possibilities, and the fact that there are multiple ways it could be implemented depending on the user's preference, I've been hesitant to actually add official support for any of it, or as you're suggesting, even to add documentation advocating for one option over another. Even the (2) scenario doesn't really make sense for us to recreate the "slideshow" capability here, when there are already multiple implementations of this available in the community. Recreating it would just create Yet Another implementation that won't have all the support necessary to please everyone. The one scenario that could be most universally useful would be the (1) scenario of a single image file, because that's simple to implement and doesn't raise all the other questions and options; plus the "Recent Visitor" entity already gets us just about the whole way there.

Which brings me to: we do already have the "Recent Visitor" entity, which adds the most recent media as its entity_picture attribute, and the bird species name as the state value. That allows the entity itself to display the image as its "picture" (usually a small circle to the left of the name, like what you would see when viewing a Person entity), and this works automatically. To convert that into a larger image that can be used with the Picture Entity card, you can set up a Generic Camera using this template as the "Still Image URL":

# Replace "my_bird_buddy" with the actual name of your own feeder for this entity
{{ state_attr('sensor.my_bird_buddy_recent_visitor', 'entity_picture') }}

and enable the "Limit refetch to URL change" setting. Then you can get a large version of the image appearing using the picture-entity card, for example:

type: picture-entity
show_state: true
show_name: false
camera_view: auto
# The "Generic Camera" entity
camera_image: camera.bird_buddy_recent_visitor
# Your "Recent Visitor" Bird Buddy entity.
# This is used to show the bird species name at the bottom of the card.
entity: sensor.my_bird_buddy_recent_visitor
aspect_ratio: 5x6

The "Recent Visitor" entity has its own challenges, because the URL we get from the Bird Buddy API is an AWS link which has an expiring access token. Once the image is downloaded for that URL, the expiration doesn't affect it anymore because the image bytes will remain in memory in most cases - but there are scenarios where the URL expires and we don't have the image bytes in memory anymore, and in that case the image will fail to load.

What is the effect of the collect postcard service?

The collect postcard service effectively removes (or replaces) the need to manually open the BB app and save the media for a new postcard. It is not very useful by itself, because you can't really call it with manual inputs, unless you rebuild the majority of the JSON payload that it needs in order to emulate the BB app in this process. It is really only usable in conjunction with the "new_postcard" event or device trigger. To remove that confusion, I recently added a Blueprint that combines that trigger with the service call, using the UI to configure the Blueprint. If all you want to do is automate the opening/saving of new postcards, this is probably the best way to do that, because it removes the need to manually configure the automation yaml, because you can use the Blueprint UI to configure it.

Won't I see and have to check it in my BB app.

When you use this blueprint or combine the new_postcard trigger with the collect_postcard service, then you do not have to use or open the BB app at all. Based on how you configured the Blueprint or service inputs, it will behave as documented for the service, which means it will either accept the BB identification for the species if the BB AI is confident in its selection, accept the highest-confidence best guess identification for it, or fall back to mystery visitor. Be aware that if you select recognized and BB is not confident in the identification, that sighting will be discarded (no way to get it back - the same as if you remove a sighting or media from the BB app when opening a postcard), and the same is true if you use best_guess and none of the suggested species meets the configured best_guess_confidence.

And what is the effect if I do not collect the sighting in HA.

If you do not configure an automation that combines the trigger and service call, or the Blueprint, then the effect is simply that the integration will not attempt to automatically process a new postcard. The postcard remains unopened in the BB app, and will not appear in the Media Browser in HA -- unless/until you manually open the postcard from the BB app.

Furthermore, I think there are some entities missing from the documentation.

You're right. There are 10 entities (per feeder) exposed by the integration. We document 6 of them. Of the remaining 4, 3 of them are disabled or hidden by default, because they are effectively "incubating", meaning either their function is unknown, or they do not function properly because Bird Buddy has not enabled those features yet. Those 3 disabled entities are Food Level (not functional on BB API yet), Temperature (not functional on BB API yet), and Frequency (functional as far as the API is concerned, but actual effect is dubious, or has no known effect).

That leaves the "Recent VIsitor" entity that has not been documented. Thanks for pointing that out.

I'm currently struggling to get it working in my HA.

Sorry but I haven't actually seen a question in your description that points to something that is not working? As far as I can tell, your confusion is about documentation, or possibly not knowing what to expect from the integration?

If you're actually having trouble getting the integration to work, then please reframe that specific question.

It sounds like maybe you have it working, but don't know what to do with it next? And that's not really something I can answer for you - it has to be the other way around: determine what you want from the integration, and reframe your question to ask if that is possible or how to achieve it.

If I have a working configuration I'm happy to help with a PR.

Again, getting mixed signals here. This implies that you do not have a working integration? If that's the case, I need more information.

[JelkeH]

I'm sorry for the confusion.
The integration is (and was) working. I could not get the results shown on my dashboard.
I just got it (mostly a card) working as I wanted.

The biggest thing I was missing here was the camera. When adding the integration in the UI I was not allowed to put the template in and in de configuration I made some small (but alas important) mistakes in the beginning.

When I got the camera working I could easily create a card. I did not have any visits yet since but I hope the downloading will also work and I'll be able to try using https://github.com/jodur/imagesdirectory-camera#camera-entity

What I was actually missing was an example of the camera config (and I find a lot of places where such example would have helped me)

Something like:

camera:
  - platform: generic
    name: birdbuddy
    limit_refetch_to_url_change: true
    still_image_url: "{{ state_attr('sensor.<<YOUR__BIRD_BUDDY_ENTITY>>_recent_visitor', 'entity_picture') }}"

Another thing I noticed is that the charging entity is not named similar to the rest and does not contain the name of the birdbuddy.

[jhansche]

I made some small (but alas important) mistakes in the beginning.

Do you mind sharing what those small/important mistakes were? Maybe I can make changes to prevent those kinds of mistakes in the future.

What I was actually missing was an example of the camera config
Something like:

Unfortunately HA is moving away from requiring (or even allowing) manual configuration.yaml entries for many integrations like this. Your example generic camera configuration might work for now, but it will likely generate a warning in HA logs, as things like that should be converted to being configured from the UI rather than from YAML.

Your code block does make a good, easy to understand way of just copy/pasting a config; but I would rather not propose a configuration that is ultimately deprecated and may be removed in the future. The Generic Camera documentation (linked above) does not even list manual YAML configuration as an option.

I agree that documenting the "Generic Camera + Recent Visitor + Picture Entity card" recipe would be useful. You should not have to sift through the entire HA community thread to find several examples of things that didn't work, and ultimately one hard-to-find example of something that did work.

I updated the README to add some points of clarification, and to add the missing documentation for things like Recent Visitor. And I will work on surfacing those other common example ideas as cookbook recipe ideas - perhaps linking to the Github wiki. There were several examples in that thread of things that other community users accomplished, that could be useful to surface here.

Another thing I noticed is that the charging entity is not named similar to the rest and does not contain the name of the birdbuddy.

I'm seeing this named correctly in my integration: my Feeder is named "Elm Bird Buddy", and my entities are named:

• Elm Bird Buddy Battery (sensor.elm_bird_buddy_battery)
• Elm Bird Buddy Charging (binary_sensor.elm_bird_buddy_charging)
• and so on...

When viewing the Device Info page, it automatically drops the redundant device name from the entity name (so it appears there as "Battery", "Charging", etc).

Depending on when you first installed the integration, you may very well have had an early version where that naming was not done following current best practices, so it might have been named differently at that time. That naming convention was updated to match best practices in v0.0.6 on Jan 1, 2023.

And another possibility is you may have manually updated the name of the entity. If you open the entity, and then click the ⚙️ cog, do you see a value in the "Name" field? If so, that will override the name provided by the integration. Just remove the name override and it will go back to default HA behavior described above.

[JelkeH]

I installed the integration last Saturday. And I did not change any of the names. At least not knowingly, and there is now override on the name.
All the devices names are sensor.XXX_feeder_state etc, except the charging which is binary_sensor.bird_buddy_charging
Not sure what is the reason.

Regarding the camera. I could not add {{ state_attr('sensor.<<YOUR__BIRD_BUDDY_ENTITY>>_recent_visitor', 'entity_picture') }} in the first field of the camera UI. So I had to do it in the configuration. I'm not sure what I tried that failed before it worked. But I had some tries before the platform was correct and the the correct field still_image_url with the correct value was there :)

When I had that setting up a card was some work to get it as I wanted, but it was kinda straightforward from there.

The only thing I can't seem to find is how to get the translated values of the state. They are visible in the details and the history. But I can't seem to get them on a card :)

[jhansche]

That's exactly how I added it, and it works:

However, the 2nd screen of the initial Generic Camera config flow probably requires showing and confirming the image works as you expect. So if your Recent Visitor entity doesn't currently have an entity_picture attribute, or that attribute's URL has expired, it's possible that configuring the Generic Camera might not work correctly if it cannot download the URL to show in the 2nd screen preview.

If your Recent Visitor entity has a bird species name identified, then it should have what's needed. It should look like this:

But if the picture beside the entity is blank, then the URL might have expired, or it might not have had a value yet. This is not uncommon for very new feeders (i.e., if you have not received any visitors yet). But if you have at least one postcard in your feed for that feeder, it should populate the name and image URL when the integration starts up - which you can do by going to Settings > Integrations > clicking the 3-dots overflow menu for Bird Buddy integration, and then select "Reload". It will try to re-initialize the Recent Visitor attributes from the current Bird Buddy feed.

The only thing I can't seem to find is how to get the translated values of the state. They are visible in the details and the history. But I can't seem to get them on a card

If you see the correct translations in the entity dialog, but not in a lovelace card, then it might be an incorrect lovelace card implementation. What card are you trying to use? Also which entity is not being translated? is it the "Feeder State" entity?

The entity name itself ("Feeder State") does not appear to be using translations currently, but not because it can't -- it just wasn't set up (and therefore we don't have translations contributed currently). But the actual value options (i.e., "Sleeping", "Ready", etc) should have translations for de, nl, and sv. If it shows values like "DEEP_SLEEP" or "READY_TO_STREAM" (or lowercase versions of those), then it means it isn't using the translated state value, but instead using the symbolic enumerated states:

class FeederState(Enum):
    """Feeder states"""

    DEEP_SLEEP = "DEEP_SLEEP"
    FACTORY_RESET = "FACTORY_RESET"
    FIRMWARE_UPDATE = "FIRMWARE_UPDATE"
    OFFLINE = "OFFLINE"
    OFF_GRID = "OFF_GRID"
    ONLINE = "ONLINE"
    OUT_OF_FEEDER = "OUT_OF_FEEDER"
    PENDING_FACTORY_RESET = "PENDING_FACTORY_RESET"
    PENDING_REMOVAL = "PENDING_REMOVAL"
    READY_TO_STREAM = "READY_TO_STREAM"
    STREAMING = "STREAMING"
    TAKING_POSTCARDS = "TAKING_POSTCARDS"

    UNKNOWN = "UNKNOWN"

those then get mapped to these strings (or translations):

    "sensor": {
      "feeder_state": {
        "state": {
          "deep_sleep": "Sleeping",
          "firmware_update": "Updating firmware",
          "factory_reset": "Reset to Factory",
          "offline": "Offline",
          "off_grid": "Off-grid",
          "online": "Online",
          "out_of_feeder": "Out of feeder",
          "pending_factory_reset": "Factory reset pending",
          "pending_removal": "Pending removal",
          "ready_to_stream": "Ready",
          "streaming": "Streaming",
          "taking_postcards": "Taking postcards",
          "unknown": "Unknown"
        }

[jhansche]

All the devices names are sensor.XXX_feeder_state etc, except the charging which is binary_sensor.bird_buddy_charging
Not sure what is the reason.

Also not sure why this would happen. Mine is named binary_sensor.elm_bird_buddy_charging. The only thing I can think is that when the sensor was added, the integration didn't have the Feeder name yet, but that doesn't make sense why it would be the only entity that didn't.

When creating the entity, we set has_entity_name = True and set the name with name = "Charging". It then uses the device.name and appends the entity.name, so because my Feeder.name is "Elm Bird Buddy", the entity gets created and shows the name "Elm Bird Buddy Charging", which gets converted to entity id "elm_bird_buddy_charging". In device.name, it uses the feeder.name attribute from the BB API response, but if that attribute was missing, it falls back to a default of "Bird Buddy". So if the initial integration was added before it was able to get the name of your feeder, then it might get initialized as "Bird Buddy Charging", which would get converted to binary_sensor.bird_buddy_charging.

• Did you add the integration before you paired your Bird Buddy to your account?
• Are you logging in as the Bird Buddy feeder owner account, or as a member account? In other words, did you have to use an invitation code in order to grant permission to the email+password account that you created for the integration -- usually because you initially created your Bird Buddy account using SSO like Google/Apple/Facebook, which we are not able to use for this integration?
• If you had to use an invitation code, did you confirm the claimed invitation from the owner account before or after configuring the integration in HA?

I ask because if you used an invitation code, there is a possible half-state where Bird Buddy tells us that we have access to a Feeder, but it is in a "pending approval" state, and we can't really access any of the data until the owner confirms the invitation. We should still have access to "FeederForMemberPending.name" though, even in this case, so it still should have created the entity with the correct name.

[JelkeH]

That's exactly how I added it, and it works: However, the 2nd screen of the initial Generic Camera config flow probably requires showing and confirming the image works as you expect. So if your Recent Visitor entity doesn't currently have an entity_picture attribute, or that attribute's URL has expired, it's possible that configuring the Generic Camera might not work correctly if it cannot download the URL to show in the 2nd screen preview.

If your Recent Visitor entity has a bird species name identified, then it should have what's needed. It should look like this:

The recent visit was showing. And adding again seems to work. Don't know why. I would swear I now try the same string. I do not have the two checkboxes in the bottom of the screen by the way.

Regarding the translations. I guess it is the card. I think I used a mushroom card. The entity card seems to work now.

regarding the charging entity. I'm using my own owner account and the bird buddy was already paired. But looking at your comments, it looks like some kind of race-condition

[jhansche]

I do not have the two checkboxes in the bottom of the screen by the way.

I don't know why, but the Generic Camera config flow is specifically written this way. The "Limit refetch" checkbox is present only when you reconfigure after adding, but not present when adding it initially.

But looking at your comments, it looks like some kind of race-condition

Yeah, that's what it sounds like, but I don't see how - since it's all written using coroutines, there really isn't a way for it to hit a race condition. The entities cannot be added until the authentication flow completes the initial refresh request, which will then include all the feeders on your account. Then the entities are added, all the same way, using the same list of feeders. I don't see any path where one entity would get no name but the rest do.

Did you ever delete the integration and re-add it for any reason?

Regarding the translations. I guess it is the card. I think I used a mushroom card. The entity card seems to work now.

I haven't tried any custom cards for this, so it's possible that some cards might try to display the state values instead of the translated states. But I'm not sure how the frontend handles that. I would be surprised if the built-in lovelace cards can do it but something as popular as mushroom cards can't - that doesn't seem to make any sense.

But if you're seeing that the built-in cards work correctly, but mushroom cards don't, then that sounds like there's a bug in mushroom.

[JelkeH]

I did not change or delete the integration. 🤔

[Matz88]

Do you have also issues with entity_picture ? The methods with sympke camera was working upmto recently but now not anymore and of a check the recent visitor entity there is no more the attribute entity_picture within

[Matz88]

False alarm ...was something transitiory, pictures are now back