mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-18 23:06:58 +00:00
Doorbird refactor documentation update (#9483)
* Doorbird refactor documentation update * Update token description * Whitespace changes * Update config key
This commit is contained in:
Matt Snyder
Martin Hjelmare
parent
103b0f7015
commit
439ed20950
@ -37,18 +37,15 @@ To connect your device, add the following to your `configuration.yaml` file:
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
doorbird:
|
||||
token: YOUR_DOORBIRD_TOKEN
|
||||
devices:
|
||||
- host: DOORBIRD_IP_OR_HOSTNAME
|
||||
username: YOUR_USERNAME
|
||||
password: YOUR_PASSWORD
|
||||
token: YOUR_DOORBIRD_TOKEN
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
token:
|
||||
description: Token to be used to authenticate Doorbird calls to Home Assistant. This can be obtained from your "Digital Passport" document provided with your Doorbird.
|
||||
required: true
|
||||
type: string
|
||||
|
||||
devices:
|
||||
description: List of Doorbird devices.
|
||||
required: true
|
||||
@ -66,6 +63,10 @@ devices:
|
||||
description: The password for the user specified.
|
||||
required: true
|
||||
type: string
|
||||
token:
|
||||
description: Token to be used to authenticate Doorbird calls to Home Assistant. This is a user defined value and should be unique across all Doorbird devices.
|
||||
required: true
|
||||
type: string
|
||||
name:
|
||||
description: Custom name for this device.
|
||||
required: false
|
||||
@ -74,56 +75,62 @@ devices:
|
||||
description: If your DoorBird cannot connect to the machine running Home Assistant because you are using dynamic DNS or some other HTTP configuration (such as HTTPS), specify the LAN IP of the machine here to force a LAN connection.
|
||||
required: false
|
||||
type: string
|
||||
monitored_conditions:
|
||||
description: Monitor motion and/or doorbell events for this device.
|
||||
events:
|
||||
description: Custom event names to be registered on the device. User defined values. Special characters should be avoided.
|
||||
required: false
|
||||
type: string
|
||||
keys:
|
||||
doorbell:
|
||||
description: Monitor doorbell events.
|
||||
motion:
|
||||
description: Monitor motion events (Motion monitoring must be enabled on the doorstation via DoorBird app).
|
||||
relay:
|
||||
description: Monitor relay events. This event is fired even if a relay is not physically connected to the door station. Can be used to lock/unlock any smart lock present in Home Assistant via the Doorbird app.
|
||||
|
||||
type: list
|
||||
|
||||
{% endconfiguration %}
|
||||
|
||||
## {% linkable_title Full example %}
|
||||
|
||||
```yaml
|
||||
doorbird:
|
||||
token: YOUR_DOORBIRD_TOKEN
|
||||
devices:
|
||||
- host: DOORBIRD_IP_OR_HOSTNAME
|
||||
username: YOUR_USERNAME
|
||||
password: YOUR_PASSWORD
|
||||
token: CUSTOM_TOKEN_1
|
||||
hass_url_override: HASS_URL
|
||||
name: Front Door
|
||||
- host: DOORBIRD_IP_OR_HOSTNAME
|
||||
username: YOUR_USERNAME
|
||||
password: YOUR_PASSWORD
|
||||
token: CUSTOM_TOKEN_2
|
||||
name: Driveway Gate
|
||||
monitored_conditions:
|
||||
- doorbell
|
||||
- motion
|
||||
- relay
|
||||
events:
|
||||
- doorbell_1
|
||||
- somebody_pressed_the_button
|
||||
- relay_unlocked
|
||||
- unit_2_bell
|
||||
- rfid_card_scanned
|
||||
```
|
||||
|
||||
## {% linkable_title Events %}
|
||||
|
||||
Home Assistant will fire an event any time a `monitored_condition` happens on a doorstation. Event names are created using the format `doorbird_{station}_{event}` (Examples: `doorbird_side_entry_button`, `doorbird_side_entry_motion`). You can verify the assigned event names in the Available Events list on the Events developer view.
|
||||
Events can be defined for each configured DoorBird device independently. These events will be registered on the device and can be attached to a schedule via the DoorBird app.
|
||||
|
||||
See [Schedules](#schedules) section below for details on how to configure schedules.
|
||||
|
||||
Event names will be prefixed by `doorbird_`. For example, the example event `somebody_pressed_the_button` will be seen in Home Assistant as `doorbird_somebody_pressed_the_button`. This is to prevent conflicts with other events.
|
||||
|
||||
See [Automation Example](#automation_example) section below for details on how to use the event names in an automation.
|
||||
|
||||
<p class="note info">
|
||||
Home Assistant will register the monitored conditions with the device as schedule entries that correspond to favorites on startup. If you remove monitored conditions from your configuration, Home Assistant will attempt to remove these items from the device. However, in some cases, such as if the IP address of the machine running Home Assistant changes or if the device is renamed in your configuration, this will not work correctly and some data will be left in device storage.
|
||||
<br><br>
|
||||
This should not cause any problems, but if you would like to remove it, open a new browser window and navigate to `{Home Assistant URL}/api/doorbird/clear/{DoorBird name}`. Replace `{Home Assistant URL}` with the full path to your running instance, such as `http://localhost:8123`. Replace `{DoorBird name}` with the name specified in your configuration for the device you would like to clear, or how it appears in the Home Assistant UI if you have not specified one, such as `DoorBird 1`. Then use the mobile app to reschedule push notifications.
|
||||
<br><br>
|
||||
Please note that clearing device registrations will prevent the device from sending pushes to Home Assistant until you restart your instance with the component enabled. It could also affect other third-party applications you may use with your DoorBird device. It will not break the official mobile app in any way, so mobile push notifications will still work.
|
||||
Events will not be received in Home Assistant until a schedule is defined via the DoorBird app.
|
||||
</p>
|
||||
|
||||
#### {% linkable_title Clearing Registered Events %}
|
||||
Events can be cleared from DoorBird devices by visiting a special URL.
|
||||
|
||||
Simply open a new browser window and navigate to `{Home Assistant URL}/api/doorbird/clear?token={DEVICE_TOKEN}`. Replace `{Home Assistant URL}` with the full path to your running instance, such as `http://localhost:8123`. Replace `{DEVICE_TOKEN}` with the token specified in your configuration for the device you would like to clear.
|
||||
<br><br>
|
||||
Please note that clearing device events will require configuration steps above to be taken again. It could also affect other third-party applications you may use with your DoorBird device. It will not break the official mobile app in any way, so mobile push notifications will still work.
|
||||
|
||||
|
||||
#### {% linkable_title Event Data %}
|
||||
|
||||
Each event includes live image and video URLs for the Doorbird device that triggered the event. These URLs can be found on the event data and can be useful in automation actions. For example, you could use `html5_viewer_url` on a notification to be linked directly to the live view of the device that triggered the automation.
|
||||
Each event will include live image and video URLs for the Doorbird device that triggered the event. These URLs can be found on the event data and can be useful in automation actions. For example, you could use `html5_viewer_url` on a notification to be linked directly to the live view of the device that triggered the automation.
|
||||
|
||||
The following keys are available on `event_data`:
|
||||
|
||||
@ -134,16 +141,33 @@ The following keys are available on `event_data`:
|
||||
- `html5_viewer_url`
|
||||
|
||||
<p class="note">
|
||||
The URLs on the event will be based on the configuration used to connect to your Doorbird device. Ability to connect from outside your network will depend on your configuration.
|
||||
The URLs on the event will be based on the configuration used to connect to your Doorbird device. Ability to connect from outside your network will depend on your configuration.
|
||||
</p>
|
||||
|
||||
#### {% linkable_title Schedules %}
|
||||
|
||||
Once events have been registered on the DoorBird device, they must be attached to a schedule using the official DoorBird app on Android or iOS. Currently there are schedules available for doorbell, motion, relay, and RFID events (on supported devices).
|
||||
|
||||
For iOS, the schedules can be found by navigating to the following areas of the app:
|
||||
|
||||
- Doorbell | Settings > Administration > Specific Device > Schedule for Doorbell
|
||||
- Motion | Settings > Administration > Specific Device > 3D Motion Sensor (Settings) > Schedule for Actions
|
||||
- Relay | Settings > Administration > Specific Device > Relays > Schedule
|
||||
- RFID | Settings > Administration > Specific Device > RFID Transponder > Settings > Select Transponder > Schedule
|
||||
|
||||
Once you are on the desired schedule, click the dropdown button in the upper left to switch to the HTTP Calls view. Now if you click on the heading just above the schedule, you can select the event you would like to be called for the particular schedule that is being viewed.
|
||||
|
||||
On the desired event, you should be able to specify blocks of time for when you would like the event to be sent to Home Assistant. If you want the event to always send, the square in the upper right can be used to populate the entire schedule. Events will be fired to Home Assistant for blocks of time that are blue.
|
||||
|
||||
Remember to complete the schedule assignment steps above for each event type that you registered.
|
||||
|
||||
### {% linkable_title Automation Example %}
|
||||
|
||||
```yaml
|
||||
- alias: Doorbird Ring
|
||||
trigger:
|
||||
platform: event
|
||||
event_type: doorbird_side_entry_button
|
||||
event_type: doorbird_somebody_pressed_the_button
|
||||
action:
|
||||
service: light.turn_on
|
||||
entity_id: light.side_entry_porch
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user