Find the camera on the network instead of asking for its address

The add-camera form asked for an IP address, and a shop owner does not
know their camera's IP address - it is on a sticker under the camera or
in a menu that differs by make. That field is where onboarding stopped
for anyone who was not an installer.

behavision/discover.py: one ONVIF WS-Discovery multicast (names the
camera and often its make) merged with a TCP sweep of port 554 across
the local /24 (misses nothing that streams). Stdlib only, ~4 s on the
office network, both cameras found. The add-camera sheet leads with
'Find cameras on this network'; picking a row fills the address and,
when the make is recognisable, the stream path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KGcjxF1cNLcuwc3DAPcnfj

behavision/api.py

@@ -332,6 +332,17 @@ def create_app(engine: Engine) -> FastAPI:
             worker.commission.cancel()
         return {"cancelled": camera_id}
 
+    @app.get("/api/cameras/discover")
+    def discover_cameras() -> dict:
+        """Cameras on this PC's network, for the add-camera form to pick from.
+
+        A sync def so FastAPI runs it in the threadpool: it holds a socket
+        open for a couple of seconds and sweeps a /24, and the event loop
+        must keep serving the live picture meanwhile.
+        """
+        from .discover import discover
+        return discover()
+
     @app.post("/api/cameras/test")
     def test_camera(payload: CameraPayload) -> dict:
         """Try a camera WITHOUT saving it - the UI's Test button.

behavision/discover.py

@@ -0,0 +1,206 @@
+"""Find the cameras on the shop's network, so nobody has to type an address.
+
+The add-camera form asked for an IP address, and a shop owner does not know
+their camera's IP address. It is on a sticker under the camera, if at all, or
+inside the camera's own app under a menu called something different for every
+make. That one field is where onboarding stopped for anyone who was not an
+installer.
+
+Two probes, merged:
+
+- **WS-Discovery** (ONVIF's discovery protocol): one multicast to
+  239.255.255.250:3702 and every ONVIF camera on the LAN answers with its
+  address and, usually, its make and model. Cheap, fast, and names the device
+  - but only cameras that speak ONVIF answer, and some cheap ones do not.
+- **A TCP sweep of port 554** across the local /24: anything listening on the
+  RTSP port is very probably a camera or a recorder. Names nothing, misses
+  nothing that streams.
+
+A host found by either is a candidate; one found by both is a camera with a
+name. The result is a list to pick from, not a decision: the person still
+supplies the password, and Test still proves the stream opens.
+
+Stdlib only. This runs inside the engine, which ships as a small wheel, and a
+network-scanning dependency would be a large thing to add for two sockets.
+"""
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field, asdict
+from typing import Iterable
+
+# ONVIF WS-Discovery probe. The MessageID must be unique per probe; devices
+# ignore a repeat.
+_PROBE = (
+    '<?xml version="1.0" encoding="UTF-8"?>'
+    '<e:Envelope xmlns:e="http://www.w3.org/2003/05/soap-envelope" '
+    'xmlns:w="http://schemas.xmlsoap.org/ws/2004/08/addressing" '
+    'xmlns:d="http://schemas.xmlsoap.org/ws/2005/04/discovery" '
+    'xmlns:dn="http://www.onvif.org/ver10/network/wsdl">'
+    '<e:Header><w:MessageID>uuid:{mid}</w:MessageID>'
+    '<w:To e:mustUnderstand="true">urn:schemas-xmlsoap-org:ws:2005:04:discovery</w:To>'
+    '<w:Action e:mustUnderstand="true">http://schemas.xmlsoap.org/ws/2005/04/discovery/Probe</w:Action>'
+    '</e:Header><e:Body><d:Probe><d:Types>dn:NetworkVideoTransmitter</d:Types></d:Probe></e:Body>'
+    '</e:Envelope>'
+)
+_MCAST = ("239.255.255.250", 3702)
+
+# Makes we can name from an ONVIF scope or hostname, mapped to the ids the
+# camera-make picker uses so the form can preselect the stream path.
+_MAKES = (
+    ("hikvision", "hikvision"), ("hik", "hikvision"), ("dahua", "dahua"),
+    ("cp plus", "cpplus"), ("cpplus", "cpplus"), ("cp-plus", "cpplus"),
+    ("uniview", "uniview"), ("unv", "uniview"), ("tapo", "tplink"),
+    ("tp-link", "tplink"), ("reolink", "reolink"), ("amcrest", "amcrest"),
+    ("axis", "axis"),
+)
+
+
+@dataclass
+class Found:
+    host: str
+    rtsp: bool = False            # port 554 answered
+    onvif: bool = False           # answered WS-Discovery
+    name: str = ""                # from ONVIF scopes, e.g. "Hikvision DS-2CD2043"
+    make: str = ""                # picker id, when it can be guessed
+    onvif_url: str = ""
+    sources: list[str] = field(default_factory=list)
+
+
+def local_networks() -> list[ipaddress.IPv4Network]:
+    """The /24s this machine sits on, best effort and without dependencies.
+
+    Interface masks are not portable in the stdlib, so this assumes /24 - the
+    shape of nearly every shop's router - for each local IPv4 address it can
+    find. A bigger network would need a scan anyway that this should not run
+    unasked.
+    """
+    addrs: set[str] = set()
+    try:
+        # The address the OS would use to reach the internet: the LAN we care about.
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.settimeout(0.5)
+        s.connect(("8.8.8.8", 80))
+        addrs.add(s.getsockname()[0])
+        s.close()
+    except OSError:
+        pass
+    try:
+        for a in socket.gethostbyname_ex(socket.gethostname())[2]:
+            addrs.add(a)
+    except OSError:
+        pass
+    nets = []
+    for a in addrs:
+        try:
+            ip = ipaddress.IPv4Address(a)
+        except ValueError:
+            continue
+        if ip.is_loopback or ip.is_link_local:
+            continue
+        nets.append(ipaddress.IPv4Network(f"{a}/24", strict=False))
+    return sorted(set(nets), key=str)
+
+
+def ws_discover(timeout: float = 2.5) -> list[Found]:
+    """One ONVIF probe, every answer within `timeout` seconds."""
+    out: dict[str, Found] = {}
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, 2)
+        sock.settimeout(timeout)
+        sock.sendto(_PROBE.format(mid=uuid.uuid4()).encode(), _MCAST)
+    except OSError:
+        return []
+    import time
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            data, (host, _) = sock.recvfrom(65535)
+        except socket.timeout:
+            break
+        except OSError:
+            break
+        f = parse_probe_match(data.decode("utf-8", "replace"), host)
+        if f:
+            out[f.host] = f
+    sock.close()
+    return list(out.values())
+
+
+_XADDR = re.compile(r"<[^>]*XAddrs[^>]*>([^<]+)<")
+_SCOPES = re.compile(r"<[^>]*Scopes[^>]*>([^<]+)<")
+
+
+def parse_probe_match(xml: str, host: str) -> Found | None:
+    """Pull the address and the human-readable scopes out of a ProbeMatch.
+
+    A regex rather than an XML parser on purpose: cameras emit every namespace
+    prefix imaginable and some emit XML that is not quite well-formed, and the
+    two fields wanted are flat text.
+    """
+    xaddrs = _XADDR.search(xml)
+    scopes = _SCOPES.search(xml)
+    if not xaddrs and not scopes:
+        return None
+    url = xaddrs.group(1).split()[0] if xaddrs else ""
+    # Prefer the host from the XAddrs URL: a device with several interfaces
+    # answers from the one it heard us on, which is the one we can reach.
+    m = re.match(r"https?://([^/:]+)", url)
+    ip = m.group(1) if m else host
+    f = Found(host=ip, onvif=True, onvif_url=url, sources=["onvif"])
+    if scopes:
+        words = []
+        for s in scopes.group(1).split():
+            if "/name/" in s or "/hardware/" in s:
+                from urllib.parse import unquote
+                words.append(unquote(s.rsplit("/", 1)[-1]))
+        f.name = " ".join(dict.fromkeys(words))  # dedupe, keep order
+    f.make = guess_make(f.name)
+    return f
+
+
+def guess_make(text: str) -> str:
+    low = text.lower()
+    for needle, make in _MAKES:
+        if needle in low:
+            return make
+    return ""
+
+
+def rtsp_sweep(nets: Iterable[ipaddress.IPv4Network], timeout: float = 0.5,
+               workers: int = 128) -> list[str]:
+    """Every host in `nets` with port 554 open. ~254 hosts in about a second."""
+    def probe(ip: str) -> str | None:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(timeout)
+        try:
+            return ip if s.connect_ex((ip, 554)) == 0 else None
+        except OSError:
+            return None
+        finally:
+            s.close()
+    hosts = [str(h) for n in nets for h in n.hosts()]
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        return [ip for ip in ex.map(probe, hosts) if ip]
+
+
+def discover(timeout: float = 2.5) -> dict:
+    """Both probes, merged, as the API returns it."""
+    nets = local_networks()
+    found: dict[str, Found] = {f.host: f for f in ws_discover(timeout)}
+    for ip in rtsp_sweep(nets):
+        f = found.setdefault(ip, Found(host=ip))
+        f.rtsp = True
+        f.sources.append("rtsp")
+    cams = sorted(found.values(), key=lambda f: (not (f.rtsp and f.onvif), not f.rtsp,
+                                                 ipaddress.IPv4Address(f.host)))
+    return {
+        "networks": [str(n) for n in nets],
+        "cameras": [asdict(c) for c in cams],
+    }

desktop/app.go

@@ -609,6 +609,14 @@ func (a *App) Cameras() ([]map[string]any, error) {
 	return a.local.Cameras(ctx)
 }
 
+// DiscoverCameras lists the cameras on this PC's network, so the add-camera
+// form is a pick-list and not a request for an IP address nobody knows.
+func (a *App) DiscoverCameras() (map[string]any, error) {
+	ctx, cancel := context.WithTimeout(a.ctx, 30*time.Second)
+	defer cancel()
+	return a.local.DiscoverCameras(ctx)
+}
+
 func (a *App) TestCamera(cam map[string]any) (map[string]any, error) {
 	ctx, cancel := context.WithTimeout(a.ctx, 60*time.Second)
 	defer cancel()

desktop/frontend/dist/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Behavision</title>
-    <script type="module" crossorigin src="./assets/index-C-oYbwC6.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-Z_jL3Bie.css">
+    <script type="module" crossorigin src="./assets/index-uOKaPIDr.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-CGAmTH1J.css">
   </head>
   <body>
     <div id="root"></div>

desktop/frontend/src/bridge.js

@@ -32,6 +32,7 @@ export const api = {
 
   cameras:            () => call('Cameras'),
   testCamera:         (cam) => call('TestCamera', cam),
+  discoverCameras:    () => call('DiscoverCameras'),
   saveCamera:         (id, cam) => call('SaveCamera', id, cam),
   deleteCamera:       (id) => call('DeleteCamera', id),
   startPlacement:     (id, seconds) => call('StartPlacementCheck', id, seconds),

desktop/frontend/src/mock.js

@@ -47,6 +47,11 @@ if (scenario) {
     StartEngine: () => delay({state: 'running', reachable: true}),
     StopEngine: () => delay({state: 'stopped', reachable: false}),
     Cameras: () => delay(st.cameras.map(c => ({...c, connected: true, frames: 1200, faces: 9}))),
+    DiscoverCameras: () => delay({networks: ['192.168.1.0/24'], cameras: [
+      {host: '192.168.1.122', rtsp: true, onvif: true, name: 'HIKVISION DS-2CD2043G2', make: 'hikvision'},
+      {host: '192.168.1.121', rtsp: true, onvif: true, name: 'IPC-model IPC', make: ''},
+      {host: '192.168.1.40', rtsp: true, onvif: false, name: '', make: ''},
+    ]}, 2500),
     TestCamera: (cam) => delay({ok: Boolean(cam.host), width: 800, height: 448, codec: 'hevc', error: cam.host ? '' : 'no host'}, 1500),
     SaveCamera: (id, cam) => { const c = {id: id || cam.id || 'cam' + (st.cameras.length + 1), ...cam, has_password: Boolean(cam.password)}; delete c.password; st.cameras = [...st.cameras.filter(x => x.id !== c.id), c]; return delay(c) },
     DeleteCamera: (id) => { st.cameras = st.cameras.filter(c => c.id !== id); return delay(null) },

desktop/frontend/src/styles.css

@@ -598,3 +598,15 @@ tr.click { cursor: pointer; } tr.click:hover td { background: var(--s2); }
   box-shadow: var(--shadow-lg); cursor: pointer; font-size: 13px; font-weight: 600; }
 .loya-fab img { width: 20px; height: 20px; object-fit: contain; }
 .loya-fab:hover { background: var(--accent-3); border-color: var(--accent); }
+
+/* Camera finder: the pick-list that replaces "type an IP address". */
+.finder { display: flex; flex-direction: column; gap: var(--sp-3); align-items: flex-start; padding: var(--sp-3) var(--sp-4); border: 1px dashed var(--line); border-radius: var(--r); background: var(--s2); }
+.finder p { font-size: 13px; color: var(--ink-2); line-height: 1.5; margin: 0; }
+.finder.busy { flex-direction: row; align-items: center; color: var(--ink-2); font-size: 13px; border-style: solid; }
+.foundlist { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; }
+.foundlist li button { width: 100%; display: flex; align-items: center; gap: var(--sp-3); padding: 10px 12px; border-radius: var(--r); border: 1px solid var(--line); background: var(--s2); color: var(--ink); cursor: pointer; text-align: left; font-size: 13px; }
+.foundlist li button:hover { border-color: var(--accent); }
+.foundlist li.picked button { border-color: var(--accent); background: var(--accent-3); }
+.foundlist .mono { font-family: var(--font-mono); font-size: 12.5px; min-width: 120px; }
+.foundlist .what { flex: 1; color: var(--ink-2); }
+.foundlist li.rescan button { width: auto; border: 0; background: none; padding: 4px 0; color: var(--ink-3); }

desktop/frontend/src/views/Cameras.jsx

@@ -165,6 +165,24 @@ function CameraSheet({ cam, onClose, onSaved }) {
 
   const chosen = makeById(make)
 
+  // The camera is picked from a scan of the shop's network rather than typed.
+  // Nobody knows their camera's address; the sticker is under the camera and
+  // the menu is different in every make's app. The scan names ONVIF cameras
+  // and lists anything with the RTSP port open; picking one fills the
+  // address and, when the make is recognisable, the stream path too.
+  const [scan, setScan] = useState(null)      // null | 'busy' | {cameras, networks} | {error}
+  async function findCameras() {
+    setScan('busy')
+    try { setScan(await api.discoverCameras()) } catch (e) { setScan({ error: message(e) }) }
+  }
+  function pick(c) {
+    const m = c.make ? makeById(c.make) : null
+    setF(prev => ({ ...prev, host: c.host, path: m?.path || prev.path,
+                    id: prev.id || (m ? '' : ''), }))
+    if (m) setMake(m.id)
+    setTest(null)
+  }
+
   return (
     <div className="drawer" onMouseDown={e => e.target === e.currentTarget && onClose()}>
       <div className="sheet">
@@ -176,6 +194,40 @@ function CameraSheet({ cam, onClose, onSaved }) {
           <p className="lead">Three things from the camera: its address, its make, and its password. Test before you save — a wrong address is the most common mistake.</p>
           {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
 
+          {isNew && (
+            <section className="formsection">
+              <h4>Find it</h4>
+              {scan === null && (
+                <div className="finder">
+                  <p>Behavision can look for cameras on this shop’s network.</p>
+                  <button type="button" className="btn primary" onClick={findCameras}><Icon.Search size={14} />Find cameras on this network</button>
+                </div>
+              )}
+              {scan === 'busy' && <div className="finder busy"><span className="spinner" />Looking on the network… a few seconds.</div>}
+              {scan?.error && <div className="err"><Icon.Warning size={15} />{scan.error}</div>}
+              {scan?.cameras && (
+                scan.cameras.length === 0
+                  ? <div className="finder">
+                      <p>Nothing answered on {scan.networks?.join(', ') || 'this network'}. The camera may be on a different network, switched off, or not yet connected — check its cable and power, then try again. You can still type its address below.</p>
+                      <button type="button" className="btn" onClick={findCameras}>Try again</button>
+                    </div>
+                  : <ul className="foundlist">
+                      {scan.cameras.map(c => (
+                        <li key={c.host} className={f.host === c.host ? 'picked' : ''}>
+                          <button type="button" onClick={() => pick(c)}>
+                            <span className="mono">{c.host}</span>
+                            <span className="what">{c.name || (c.rtsp ? 'Streams video (RTSP)' : 'Answers ONVIF')}</span>
+                            {c.make && <span className="tag seen">{makeById(c.make).label}</span>}
+                            {f.host === c.host && <Icon.Check size={16} />}
+                          </button>
+                        </li>
+                      ))}
+                      <li className="rescan"><button type="button" className="btn sm" onClick={findCameras}>Scan again</button></li>
+                    </ul>
+              )}
+            </section>
+          )}
+
           <section className="formsection">
             <h4>The camera</h4>
             {isNew && (

desktop/internal/local/client.go

@@ -105,6 +105,12 @@ func (c *Client) DeleteCamera(ctx context.Context, id string) error {
 	return c.do(ctx, http.MethodDelete, "/api/cameras/"+id, nil, nil)
 }
 
+// DiscoverCameras asks the engine to scan the shop's network. A few seconds.
+func (c *Client) DiscoverCameras(ctx context.Context) (map[string]any, error) {
+	var out map[string]any
+	return out, c.do(ctx, http.MethodGet, "/api/cameras/discover", nil, &out)
+}
+
 func (c *Client) TestCamera(ctx context.Context, cam map[string]any) (map[string]any, error) {
 	var out map[string]any
 	return out, c.do(ctx, http.MethodPost, "/api/cameras/test", cam, &out)

tests/test_discover.py

@@ -0,0 +1,44 @@
+"""Discovery parsing, with no network: the two shapes cameras actually send."""
+from behavision.discover import parse_probe_match, guess_make, local_networks
+
+HIK = ('<?xml version="1.0"?><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">'
+       '<env:Body><d:ProbeMatches xmlns:d="http://schemas.xmlsoap.org/ws/2005/04/discovery"><d:ProbeMatch>'
+       '<d:Scopes>onvif://www.onvif.org/type/video_encoder onvif://www.onvif.org/name/HIKVISION%20DS-2CD2043G2 '
+       'onvif://www.onvif.org/hardware/DS-2CD2043G2-I onvif://www.onvif.org/location/city/hangzhou</d:Scopes>'
+       '<d:XAddrs>http://192.168.1.122/onvif/device_service</d:XAddrs>'
+       '</d:ProbeMatch></d:ProbeMatches></env:Body></env:Envelope>')
+
+BARE = ('<SOAP-ENV:Envelope><SOAP-ENV:Body><wsdd:ProbeMatches><wsdd:ProbeMatch>'
+        '<wsdd:XAddrs>http://10.0.0.9:8080/onvif/device_service http://[fe80::1]/onvif</wsdd:XAddrs>'
+        '</wsdd:ProbeMatch></wsdd:ProbeMatches></SOAP-ENV:Body></SOAP-ENV:Envelope>')
+
+
+def test_hikvision_probe_match_is_named_and_recognised():
+    f = parse_probe_match(HIK, "192.168.1.122")
+    assert f.host == "192.168.1.122"
+    assert f.onvif and not f.rtsp
+    assert "HIKVISION DS-2CD2043G2" in f.name and "DS-2CD2043G2-I" in f.name
+    assert f.make == "hikvision"
+
+
+def test_a_nameless_match_still_yields_its_address():
+    f = parse_probe_match(BARE, "10.0.0.9")
+    assert f.host == "10.0.0.9" and f.name == "" and f.make == ""
+    assert f.onvif_url.startswith("http://10.0.0.9:8080")
+
+
+def test_garbage_is_not_a_camera():
+    assert parse_probe_match("<html>not soap</html>", "1.2.3.4") is None
+
+
+def test_make_guesses_the_common_indian_retail_brands():
+    assert guess_make("CP PLUS CP-UNC-TA21L3") == "cpplus"
+    assert guess_make("Dahua IPC-HDW1230") == "dahua"
+    assert guess_make("TP-LINK Tapo C200") == "tplink"
+    assert guess_make("Something Else") == ""
+
+
+def test_local_networks_are_slash_24_and_never_loopback():
+    for n in local_networks():
+        assert n.prefixlen == 24
+        assert not n.network_address.is_loopback