DOCS.md

Home Assistant Add-on: Hikvision Doorbell

Configuration

Note: Remember to restart the add-on when the configuration is changed.

Note: When the add-on connects to a doorbell for the first time, it might happen that your door station gets stuck, because it is downloading the complete backlog of events. You will also see a lot of false events just give it a while, it can sometimes takes a few hours... A reboot might be required.

The following configuration options are available to be setup using the Configuration tab of this add-on in the Home Assistant interface:

Doorbells

Configure the connection to the doorbells. If a value is not defined, the default setting is used.

For each of your doorbells, repeat the following configuration:

Option	Default	Description
name		Custom name for this doorbell (visibile in the HA UI and the sensors names)
ip		IP address of the doorbell
port	8000	(Optional) Port of the doorbell
username	admin	Username to access the doorbell
password		Password to access the doorbell
output_relays	2	(optional) Set this option if you don't see the correct number of door switches or if you have attached an secure door control module on your indoor
scenes	false	(optional) Extra Scene buttons for indoor panels

Example config

The following configuration setups two doorbells, named Front door and Rear door and an Indoor panel

- name: "Front door"
  ip: 192.168.0.1
  username: admin
  password: password  

- name: "Rear door"
  ip: 192.168.0.2
  username: admin
  password: password

- name: "Indoor"
  ip: 192.168.0.3
  username: admin
  password: password

- name: "Indoor Extension"
  ip: 192.168.0.4
  username: admin
  password: password

System

The following system settings are available:

Name	Default	Description
log_level	WARNING	The verbosity of the add-on logs. Available options: ERROR WARNING INFO DEBUG
sdk_log_level	NONE	The verbosity of the Hikvision SDK logs. Available options: NONE ERROR INFO DEBUG

Example config

log_level: WARNING
sdk_log_level: NONE

Setup

Requirements

A running MQTT broker.

You can use the officially supported Mosquitto broker, available in the official add-ons section of your Home Assistant instance. You can quickly set it up by clicking the following button: , or by manually finding it inside your Add-on store.

After you have started the Mosquitto broker add-on, you should be able to automatically connect Home Assistant to the broker by going to Settings -> Devices & Services -> MQTT, and clicking Configure.

(Optional) If you have an external MQTT broker, you can define it the add-on config too:

Example config

host: 192.168.0.17
port: 1883
ssl: false
username: user
password: pass

Getting started

After you have setup an MQTT broker, you can start Hikvision Doorbell. Each of you defined doorbell should be visible as a device under Settings -> Devices & Services -> Devices.

Sensors, switches and buttons

For each of your doorbells, the following entities are available:

• Sensors

  • Call state (idle, ringing, dismissed)

• Switches

  • Door relays (one for each available relay, open the door connected to the output relay of the device)

• Buttons

  • Answer call (The device needs to be connected to Hikconnect in to make "answer" work, if its not possible, you can use "reject" instead)
  • Hangup call (The device needs to be connected to Hikconnect in to make "hangup" work, if its not possible, you can use "reject" instead)
  • Reject call
  • Reboot
  • ...

• Device triggers (depending on device model)

  • Motion detected
  • Tamper alarm
  • Door not closed
  • ...

  The device triggers are used to signal alarms and events generated by the doorbells (the type of events generated depends on the specific model). These are special entities that do not have a state associated to them (therefore are not visible in the list of HA entities, but under each Device info page).

  NOTE: The device triggers are discovered once the associated event is triggered on the device at least once.

  You can use a device trigger in an automation by using a trigger of type Device. Check out the Automating Home Assistant guide on automations or the Automation documentation for full details.

  

Sending commands to the doorbells

There are two ways in which you can interact with your doorbells:

• via the automatically created MQTT entities (switches, buttons)
• manually invoking the add-on stdin service

MQTT entities

This add-on automatically creates switches and buttons you can toggle and react to from the Home Assistant UI or from your own automations.

STDIN service (advanced)

There is an advanced method to interact with the devices by sending a text message to the add-on on its standard input (STDIN). You can use the built-in hassio.addon_stdin service provided by Home Assistant.

The input string must be in the format

<command> <doorbell_name> <optional_parameter>

• <command> is one of:

  Command	Description
  unlock	Unlock the specified door (<optional_parameter> must be 1 or 2) connected to the doorbell station output relay
  reboot	Reboot the specified door station
  reject	Reject the incoming call and stop the indoor stations from ringing
  request	Unknown
  cancel	Unknown
  answer	Answers the call, usefull in combination with "hangUp" afterwards, so the intercom stops ringing (idle) and you can start two way audio with Frigate for example
  reject	Unknown
  bellTimeout	Unknown
  hangUp	Hangs up the call, usefull in combination with "answer" before, so the intercom stops ringing (idle) and you can start two way audio with Frigate for example
  deviceOnCall	Unknown
  atHome	Sending scene "At home" for indoor panels
  goOut	Sending scene "Go out" for indoor panels
  goToBed	Sending scene "Go to bed" for indoor panels
  custom	Sending scene "custom" for indoor panels
  setupAlarm	Turn on the alarm on the indoor panel
  closeAlarm	Turn off the alarm on the indoor panel
  muteAudioOutput	Mutes the audio output of the doorbell / indoor station
  unmuteAudioOutput	Unmutes the audio output of the doorbell / indoor station

• <doorbell_name> is the custom name given to the doorbell in the configuration options, all lowercase and with whitespace substituted by underscores _.

  E.G.: If the doorbell is named Front door, the input string must reference it as front_door.

• <optional_parameter> can be an additional string, used for instance to specify additional options for a command

Example

For more details see the official documentation about the hassio.addon_stdin service.

Unlock a door

This service unlocks the door connected to the 1st output relay of the door station named Front door:

service: hassio.addon_stdin
data:
  addon: aff2db71_hikvision_doorbell
  input: unlock front_door 1

Reboot the device

To reboot the doorbell named Rear door:

service: hassio.addon_stdin
data:
  addon: aff2db71_hikvision_doorbell
  input: reboot rear_door

Reject a call

It might come in handy in tandem with a sensor monitoring the status of the front door. When someone presses the ring button on the doorbell, if the door is opened by hand without picking up the call, the below service rejects the call. All indoor stations including the Hik-Connect devices stop ringing.

This example has been tested on a DS-KD8003 outdoor unit with indoor stations named Indoor unit. This type of command must be sent to an indoor station only.

service: hassio.addon_stdin
data:
  addon: aff2db71_hikvision_doorbell
  input: reject indoor_unit

Support

If you find a bug or need support open an issue here on GitHub. If possible, please provide a copy of your logs in the issue form to help us better diagnose the problem!

Troubleshooting

Have a look at the Log tab of the add-on in the Home Assistant UI.

You can increase the verbosity by changing the system.log_level configuration option. For instance:

system:
  log_level: DEBUG
  sdk_log_level: DEBUG

N.B.: When the add-on connects to a doorbell for the first time, it might happen that your door station gets stuck, because it is downloading the complete backlog of events. A reboot might be required.