Project: ONVIF IP cameras in openHAB with the IP Camera binding (discovery, motion alarms, streams)

[ZerOne]

The IP Camera binding covers most IP cameras, with extra features for brands with an open API. This walkthrough is built from the binding's documentation (openHAB 5.2.x docs, October 2026). I have flagged where I'm extrapolating from the docs rather than quoting them - please correct me if your experience differs.

Before you start

• Create a dedicated user on the camera for openHAB (don't reuse the admin account).
• Enable ONVIF on the camera if it has a switch for it. Some cameras need ONVIF users configured separately from web users.
• Install FFmpeg on the openHAB host. The binding needs it for snapshots from RTSP, MJPEG/HLS streams and FFmpeg-based motion/audio alarms. On Debian/Ubuntu/openHABian:

Code: Select all

sudo apt update && sudo apt install ffmpeg

• Keep the camera on a fixed IP (DHCP reservation).
• Time sync: ONVIF event subscriptions can behave oddly if the camera clock is badly wrong (general ONVIF experience, not from the openHAB docs) - set NTP on the camera.

Step 1 - Discovery

The docs recommend using discovery for ONVIF cameras because it finds the IP, ports and URLs for you. In the UI: Settings > Things > + (or the Inbox) > IpCamera. The binding sends discovery using UDP port 3702 on openHAB's primary network address, so that port must not be blocked by a firewall. If the camera is not found after a few searches, it may not be ONVIF, or discovery traffic isn't reaching it (VLANs, Docker bridge networking). In that case add the camera manually. (My assumption: with Docker you may need host networking for discovery - I haven't tested this.)

Step 2 - Choose the right Thing type

• onvif - ONVIF cameras without a brand API.
• generic - non-ONVIF cameras with working RTSP or HTTP URLs (you supply the URLs).
• hikvision, dahua (also for Amcrest), foscam, instar, doorbird, amcrest (older polling method; the docs say to try dahua first) - use these when your camera supports the brand API as well as ONVIF, since many features then use far less CPU.
• group - show several cameras as one (advanced).

Step 3 - Credentials and key parameters

After adding the Thing, enter the username and password before it will come online. Parameters you will meet (all in the docs):

• ipAddress, port (HTTP, used for snapshots and API calls), onvifPort (needed for PTZ, events and auto-discovery of RTSP/snapshot URLs; 0 stops the binding trying ONVIF)
• username, password
• onvifMediaProfile - 0 is the main stream; higher numbers are substreams
• snapshotUrl - if your camera has one, test it in a browser first and provide it; otherwise FFmpeg generates snapshots from RTSP, which costs CPU
• ffmpegLocation and ffmpegOutput (a unique folder per camera, ending with a slash)
• ipWhitelist - see the security note below

The docs say to leave user:pass@ out of any URLs; the binding inserts the credentials itself, which keeps them in one place and out of logs.

Step 4 - Channels for automations

Channels differ per brand, but these are the common ones (all documented):

• motionAlarm - video motion events from ONVIF and API cameras. cellMotionAlarm is the ONVIF-only cell-motion event; the two can give different results, so try both.
• audioAlarm - ON when noise exceeds a threshold (FFmpeg-based).
• pollImage / createSnapshots - turn FFmpeg snapshot creation on and off to save CPU.
• pan, tilt, zoom, gotoPreset - PTZ.
• hlsUrl, mjpegUrl and others for stream URLs.

A text-file sketch for Items (adjust the Thing UID to whatever your camera shows in the UI - the channel UID format is ipcamera:<thingtype>:<id>:<channel>):

Code: Select all

Switch FrontDoorMotion "Front door motion" { channel="ipcamera:onvif:FrontDoor:motionAlarm" }
Switch FrontDoorAudio  "Front door audio"  { channel="ipcamera:onvif:FrontDoor:audioAlarm" }

Step 5 - Streams

Once the camera is online, streams are served by the binding at:

Code: Select all

http://<openhab-host>:8080/ipcamera/<cameraUID>/ipcamera.mjpeg
http://<openhab-host>:8080/ipcamera/<cameraUID>/ipcamera.m3u8

• MJPEG is the most compatible and typically lags 1 second or less; HLS (m3u8) uses H.264 and can be cast, but lags behind real time because of how HLS works.
• If the camera creates keyframes only every 2+ seconds, FFmpeg-based snapshots will only update that often. Check whether the camera lets you set a shorter keyframe interval.
• The docs suggest setting the camera substream to something like 4 FPS and 640x360 to lower CPU load when using the MJPEG stream.

Security note

The binding's built-in file server serves snapshots and streams without a username or password, but only to IPs in ipWhitelist. Requests from other IPs fail. Setting it to DISABLE lets any internal IP in, so use your firewall if you do that. Never expose this port to the internet. Also remember cameras themselves are a favourite target - keep them on a restricted VLAN with no internet route if you can.

Troubleshooting (from the docs)

• If the Thing is offline, the reason is shown on the Thing - read it first.
• Enable TRACE logging for the binding. FFmpeg and camera errors often don't reach INFO logs.
• Search the openHAB community forum for your log message before opening a new topic.

Question for the group: which camera brands are you using with openHAB (Hikvision, Dahua, Reolink, Uniview...), and did ONVIF discovery work first time? Share any quirks with motion events or streams so we can build a brand-by-brand list here.