suprema-biostar-mcp 1.0.1__py3-none-any.whl

biostar_x_mcp_server/handlers/device_handler.py

@@ -0,0 +1,4344 @@
+import logging
+from typing import Sequence, Dict, Any, List, Optional, Tuple
+from mcp.types import TextContent
+import httpx
+from .base_handler import BaseHandler
+import re
+import asyncio
+import json
+from collections.abc import Iterable
+
+logger = logging.getLogger(__name__)
+
+TZ_MAP: Dict[str, int] = {
+    "(UTC-12:00)": -43200, "Eniwetok": -43200, "Kwajalein": -43200,
+    "(UTC-11:00)": -39600, "Midway": -39600, "Samoa": -39600,
+    "(UTC-10:00)": -36000, "Hawaii": -36000, "HST": -36000,
+    "(UTC-9:30)": -34200, "Marquesas": -34200, "French Polynesia": -34200,
+    "(UTC-9:00)": -32400, "Alaska": -32400, "AKST": -32400,
+    "(UTC-8:00)": -28800, "Pacific Standard Time": -28800, "PST": -28800,
+    "(UTC-7:00)": -25200, "Mountain Standard Time": -25200, "MST": -25200,
+    "(UTC-6:00)": -21600, "Central Standard Time": -21600, "CST": -21600, "Mexico City": -21600,
+    "(UTC-5:00)": -18000, "Eastern Standard Time": -18000, "EST": -18000, "Bogota": -18000, "Lima": -18000,
+    "(UTC-4:30)": -16200, "Venezuela": -16200,
+    "(UTC-4:00)": -14400, "Atlantic Standard Time": -14400, "AST": -14400, "Caracas": -14400, "La Paz": -14400,
+    "(UTC-3:30)": -12600, "Newfoundland": -12600,
+    "(UTC-3:00)": -10800, "Brazil": -10800, "Buenos Aires": -10800, "Georgetown": -10800,
+    "(UTC-2:00)": -7200, "Mid-Atlantic": -7200,
+    "(UTC-1:00)": -3600, "Azores": -3600, "Cape Verde": -3600,
+    "(UTC±0:00)": 0, "UTC": 0, "GMT": 0,
+
+    # East (positive)
+    "(UTC+1:00)": 3600, "Western Europe Time": 3600, "WET": 3600, "Lisbon": 3600, "Casablanca": 3600,
+    "(UTC+2:00)": 7200, "Kaliningrad": 7200, "South Africa": 7200, "SAST": 7200, "EET": 7200,
+    "(UTC+3:00)": 10800, "Baghdad": 10800, "Riyadh": 10800, "Moscow": 10800,
+    "(UTC+3:30)": 12600, "Tehran": 12600, "IRST": 12600,
+    "(UTC+4:00)": 14400, "Abu Dhabi": 14400, "Muscat": 14400, "Baku": 14400, "Tbilisi": 14400,
+    "(UTC+4:30)": 16200, "Kabul": 16200,
+    "(UTC+5:00)": 18000, "Yekaterinburg": 18000, "Islamabad": 18000, "Karachi": 18000, "Tashkent": 18000,
+    "(UTC+5:30)": 19800, "India": 19800, "New Delhi": 19800, "Colombo": 19800, "IST": 19800,
+    "(UTC+5:45)": 20700, "Kathmandu": 20700,
+    "(UTC+6:00)": 21600, "Almaty": 21600, "Dhaka": 21600,
+    "(UTC+6:30)": 23400, "Myanmar": 23400, "Cocos": 23400,
+    "(UTC+7:00)": 25200, "Bangkok": 25200, "Hanoi": 25200, "Jakarta": 25200,
+    "(UTC+8:00)": 28800, "Beijing": 28800, "Perth": 28800, "Singapore": 28800, "Hong Kong": 28800,
+    "China Standard Time": 28800,
+    "(UTC+8:30)": 30600, "Pyongyang": 30600,
+    "(UTC+8:45)": 31500, "Eucla": 31500,
+    "(UTC+9:00)": 32400, "Seoul": 32400, "Tokyo": 32400, "KST": 32400, "JST": 32400,
+    "(UTC+9:30)": 34200, "Adelaide": 34200, "Darwin": 34200,
+    "(UTC+10:00)": 36000, "Eastern Australia": 36000, "Guam": 36000, "Vladivostok": 36000,
+    "(UTC+10:30)": 37800, "Lord Howe": 37800,
+    "(UTC+11:00)": 39600, "Magadan": 39600, "Solomon": 39600, "New Caledonia": 39600,
+    "(UTC+12:00)": 43200, "Auckland": 43200, "Wellington": 43200, "Fiji": 43200, "Kamchatka": 43200,
+    "(UTC+12:45)": 45900, "Chatham": 45900,
+    "(UTC+13:00)": 46800, "Samoa (West)": 46800, "Tonga": 46800,
+    "(UTC+14:00)": 50400, "Kiritimati": 50400,
+}
+
+ALIASES: Dict[str, int] = {
+    # Common English aliases / cities
+    "tehran": 12600, "hawaii": -36000, "vancouver": -28800, "los angeles": -28800, "seoul": 32400,
+    "tokyo": 32400, "singapore": 28800, "hong kong": 28800, "bangkok": 25200, "guam": 36000,
+    "alaska": -32400, "american samoa": -39600, "midway": -39600, "kiritimati": 50400,
+}
+
+UTC_OFFSET_RE = re.compile(r"^(?P<sign>[+-])(?P<h>\d{1,2})(?::(?P<m>\d{2}))?$")
+
+
+def _normalize_label(s: str) -> str:
+    """Normalize label for matching irrespective of spaces, parens, commas, hyphens, case."""
+    return (
+        s.strip().lower()
+        .replace("(", "").replace(")", "")
+        .replace(" ", "").replace(",", "").replace("-", "")
+    )
+
+
+def _parse_utc_offset_str(s: str) -> Optional[int]:
+    """Parse '+09:00', '-08', '+3:30' to seconds."""
+    m = UTC_OFFSET_RE.match(s.strip())
+    if not m:
+        return None
+    h = int(m.group("h"))
+    mnt = int(m.group("m") or 0)
+    seconds = h * 3600 + mnt * 60
+    return -seconds if m.group("sign") == "-" else seconds
+
+
+def _lookup_tz_offset(args: Dict[str, Any]) -> Tuple[Optional[int], str]:
+    """
+    Resolve offset in seconds from one of: offset_seconds, utc_offset, tz_label.
+    tz_label can be any English label like '(UTC+9:00) Seoul, Tokyo' or 'Pacific Standard Time', or a city/abbr.
+    """
+    if "offset_seconds" in args and isinstance(args["offset_seconds"], int):
+        return args["offset_seconds"], "resolved by offset_seconds"
+
+    if "utc_offset" in args and isinstance(args["utc_offset"], str):
+        sec = _parse_utc_offset_str(args["utc_offset"])
+        if sec is not None:
+            return sec, f"parsed from utc_offset='{args['utc_offset']}'"
+
+    if "tz_label" in args and isinstance(args["tz_label"], str):
+        raw = args["tz_label"].strip()
+
+        # 1) Exact key
+        if raw in TZ_MAP:
+            return TZ_MAP[raw], f"matched tz_label exact='{raw}'"
+
+        # 2) If label starts with '(UTC±hh[:mm])', parse the offset directly → language-agnostic
+        if raw.startswith("(") and "UTC" in raw:
+            inside = raw[1: raw.find(")")]  # e.g. 'UTC+9:00'
+            off = inside.replace("UTC", "")
+            sec = _parse_utc_offset_str(off)
+            if sec is not None:
+                return sec, f"parsed from label parentheses='{inside}'"
+
+        # 3) Normalized lookup against our English keys
+        key = _normalize_label(raw)
+        for k, v in TZ_MAP.items():
+            if _normalize_label(k) == key:
+                return v, f"matched tz_label normalized='{raw}'"
+
+        # 4) English aliases (cities/abbrs)
+        al = raw.lower()
+        if al in ALIASES:
+            return ALIASES[al], f"matched alias='{raw}'"
+
+    return None, "unable to resolve timezone (provide offset_seconds, or utc_offset like '+09:00', or an English tz_label)"
+
+
+class DeviceHandler(BaseHandler):
+    """Handle device-related operations."""
+
+    async def list_devices(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get list of devices."""
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json()
+            devices = data.get("DeviceCollection", {}).get("rows", [])
+
+            # Filter by group if specified
+            if args.get("group_id"):
+                devices = [d for d in devices if args["group_id"] in d.get("device_group_id", {}).get("id_list", [])]
+
+            # Filter by device type if specified
+            if args.get("device_type"):
+                devices = [d for d in devices if d.get("device_type", {}).get("name") == args["device_type"]]
+
+            return self.success_response({
+                "message": f"Found {len(devices)} devices",
+                "total": len(devices),
+                "devices": [self.format_device_info(device) for device in devices]
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def _fetch_all_doors(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """GET /api/doors and return rows (best-effort on error)."""
+        async with httpx.AsyncClient(verify=False) as client:
+            resp = await client.get(f"{self.session.config.biostar_url}/api/doors", headers=headers)
+        if resp.status_code != 200:
+            return []
+        return (resp.json() or {}).get("DoorCollection", {}).get("rows", []) or []
+
+    # ---------- [MODIFY] get_device to use the resolver ----------
+    async def get_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get specific device details.
+        Now supports resolving by device_name/device_search_text/door_name/q (+ edge/prefer_entry).
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # Use resolver (device_id straight-through; else name → door fallback)
+            resolved_id, early = await self._resolve_device_id_from_args(args, headers)
+            if resolved_id is None:
+                return early  # Either needs_selection or error already formatted
+
+            device_id = resolved_id
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json()
+            device = data.get("Device", {})
+
+            return self.success_response({
+                "device": self.format_device_info(device)
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def add_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Add a new device to the system."""
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # Convert IP address to array format
+            ip_parts = args["ip_address"].split(".")
+            ip_array = [int(part) for part in ip_parts]
+
+            # Format IP for sorting (pad each octet to 3 digits with leading zeros)
+            ip_for_sorting = "".join([f"{int(part):05d}" for part in ip_parts])
+
+            device_data = {
+                "Device": {
+                    "id": args["device_id"],
+                    "name": args["name"],
+                    "device_group_id": {
+                        "id": args["device_group_id"],
+                        "name": "All Devices"
+                    },
+                    "lan": {
+                        "enable_dhcp": "false",
+                        "ip": args["ip_address"],
+                        "device_port": str(args.get("port", 51211))
+                    },
+                    "rs485": {
+                        "mode": "1",
+                        "channels": [{"index": "0", "mode": "1"}]
+                    },
+                    "support_ssl": str(args.get("use_ssl", True)).lower(),
+                    "is_exist_root_cert": "false",
+                    "system": {
+                        "use_alphanumeric": "false"
+                    },
+                    "capacity": {
+                        "support_alphanumeric": "true",
+                        "support_ssl": str(args.get("use_ssl", True)).lower(),
+                        "is_exist_root_cert": "false",
+                        "fw_upgrade_required": "false"
+                    },
+                    "server_connected": {
+                        "status": "disconnected"
+                    },
+                    "isDisabled": False,
+                    "ip": ip_array,
+                    "ipForSorting": ip_for_sorting,
+                    "secureModeStatus": "Connectable.",
+                    "status": "OK"
+                }
+            }
+
+            # Add device_type_id if provided
+            if "device_type_id" in args:
+                device_data["Device"]["device_type_id"] = {
+                    "id": str(args["device_type_id"]),
+                    "name": args.get("device_type_name", "")
+                }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices",
+                    headers=headers,
+                    json=device_data
+                )
+
+            if response.status_code not in [200, 201]:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            logger.info(
+                f"##################### ADD DEVICE RESPONSE: {response} #########################################################")
+
+            return self.success_response({
+                "message": f"Device '{args['name']}' added successfully",
+                "device_id": args["device_id"]
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def bulk_add_devices(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Bulk add devices by sequentially calling the existing add_device() for each item.
+
+        Input:
+        - devices: [ { device_id, name, ip_address, device_group_id, (device_type_id), (device_type_name), (port), (use_ssl) }, ... ]
+        - continue_on_error: bool (default True)
+
+        Behavior:
+        - For each element, call self.add_device(item) to reuse the exact same logic.
+        - Aggregate per-item results (success/error) and return a summary.
+        """
+        try:
+            self.check_auth()
+            rows = args.get("devices")
+            if not isinstance(rows, (list, tuple)) or not rows:
+                return self.error_response(
+                    "Provide 'devices' as a non-empty array of objects (same schema as 'add-device').")
+
+            continue_on_error = bool(args.get("continue_on_error", True))
+
+            import ast
+            results: List[Dict[str, Any]] = []
+            success_cnt = 0
+
+            for idx, item in enumerate(rows):
+                if not isinstance(item, dict):
+                    results.append({
+                        "index": idx,
+                        "status": "error",
+                        "error": "Item must be an object"
+                    })
+                    if not continue_on_error:
+                        break
+                    continue
+
+                try:
+                    # ⬇ '완전히 동일한 로직' 보장을 위해 기존 단일 메서드를 그대로 호출
+                    single_seq = await self.add_device(item)
+
+                    # add_device()는 success_response/error_response 형태의 TextContent를 1개 반환함
+                    parsed = None
+                    if isinstance(single_seq, (list, tuple)) and single_seq:
+                        t = getattr(single_seq[0], "text", None)
+                        if isinstance(t, str) and t.strip():
+                            try:
+                                parsed = ast.literal_eval(t)  # dict로 파싱 시도
+                            except Exception:
+                                parsed = {"raw": t}
+                    else:
+                        parsed = {"raw": single_seq}
+
+                    ok = isinstance(parsed, dict) and str(parsed.get("status")) == "success"
+                    if ok:
+                        success_cnt += 1
+                        results.append({
+                            "index": idx,
+                            "status": "success",
+                            "device_id": parsed.get("device_id"),
+                            "message": parsed.get("message")
+                        })
+                    else:
+                        results.append({
+                            "index": idx,
+                            "status": "error",
+                            "response": parsed
+                        })
+                        if not continue_on_error:
+                            break
+
+                except Exception as e:
+                    results.append({
+                        "index": idx,
+                        "status": "error",
+                        "error": f"{type(e).__name__}: {e}"
+                    })
+                    if not continue_on_error:
+                        break
+
+            return self.success_response({
+                "message": f"Bulk add attempted for {len(results)} item(s).",
+                "success": success_cnt,
+                "failed": len(results) - success_cnt,
+                "results": results
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Update device configuration."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # First get existing device data
+            async with httpx.AsyncClient(verify=False) as client:
+                get_response = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                    headers=headers
+                )
+
+                if get_response.status_code != 200:
+                    return self.error_response(f"Failed to get device: {get_response.status_code}")
+
+                device_data = get_response.json()
+
+                # Update only provided fields
+                if "name" in args:
+                    device_data["Device"]["name"] = args["name"]
+                if "description" in args:
+                    device_data["Device"]["description"] = args["description"]
+                if "time_zone" in args:
+                    device_data["Device"]["time_zone"] = args["time_zone"]
+                if "volume" in args:
+                    device_data["Device"]["volume"] = args["volume"]
+
+                # Update the device
+                update_response = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                    headers=headers,
+                    json=device_data
+                )
+
+            if update_response.status_code != 200:
+                return self.error_response(f"API call failed: {update_response.status_code} - {update_response.text}")
+
+            return self.success_response({
+                "message": f"Device {device_id} updated successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def reboot_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Restart device(s) via POST /api/devices/reset.
+
+        STRICT SELECTION RULES:
+        - device_names: exact (case-sensitive) match ONLY. No autocorrect, no fuzzy matching.
+        * 0 match  -> NO ACTION. Return full list and needs_selection=true.
+        * >1 match -> NO ACTION. Return candidates and needs_selection=true.
+        * 1 match  -> use that id.
+        - device_ids: validate existence. If any unknown id is included -> NO ACTION (return available devices).
+        - device_search_text: optional substring browse. If provided without an exact selection,
+        return candidates ONLY (no action).
+        - If both device_ids and device_names are provided, the resolved id sets must be IDENTICAL.
+        - If multiple devices will be restarted, confirm_multi=true is REQUIRED.
+
+        SUCCESS CRITERIA (double-check):
+        - HTTP 200
+        - AND (Response.code == "0" if present)
+        - AND every DeviceResponse.rows[*].code == "0"
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ---- Parse inputs ----
+            raw_ids = args.get("device_ids")
+            legacy_id = args.get("device_id")
+            raw_names = args.get("device_names")
+            search_text = (args.get("device_search_text") or "").strip()
+            confirm_multi = bool(args.get("confirm_multi", False))
+
+            # Normalize ids (support scalar)
+            ids_from_args = []
+            if raw_ids is not None and not isinstance(raw_ids, (list, tuple, set)):
+                raw_ids = [raw_ids]
+            if isinstance(raw_ids, (list, tuple, set)):
+                for x in raw_ids:
+                    try:
+                        v = int(str(x).strip())
+                        if v not in ids_from_args:
+                            ids_from_args.append(v)
+                    except Exception:
+                        continue
+            if legacy_id is not None:
+                try:
+                    v = int(str(legacy_id).strip())
+                    if v not in ids_from_args:
+                        ids_from_args.append(v)
+                except Exception:
+                    pass
+
+            # Normalize names (support scalar)
+            names_from_args = []
+            if raw_names is not None and not isinstance(raw_names, (list, tuple, set)):
+                raw_names = [raw_names]
+            if isinstance(raw_names, (list, tuple, set)):
+                names_from_args = [str(n) for n in raw_names]
+
+            # Browse-only path: no exact selection, but search text provided
+            if not ids_from_args and not names_from_args and search_text:
+                all_rows = await self._fetch_all_devices(headers)
+                q = search_text.lower()
+                candidates = [
+                    self.format_device_info(d) for d in all_rows
+                    if q in str(d.get("name") or "").lower()
+                ]
+                return self.success_response({
+                    "message": f"No exact selection given. Found {len(candidates)} candidates for '{search_text}'. Please choose exact device_names or device_ids.",
+                    "status": "needs_selection",
+                    "needs_selection": True,
+                    "candidates": candidates
+                })
+
+            # No targets at all
+            if not ids_from_args and not names_from_args:
+                return self.error_response(
+                    "No targets provided. Use 'device_names' (exact) or 'device_ids', or use 'device_search_text' to browse candidates."
+                )
+
+            # Load all devices once for validation
+            all_rows = await self._fetch_all_devices(headers)
+
+            # Build indexes
+            known_id_set = set()
+            by_exact_name = {}
+            for d in all_rows:
+                did = d.get("id")
+                try:
+                    known_id_set.add(int(did))
+                except Exception:
+                    pass
+                nm = str(d.get("name") or "")
+                by_exact_name.setdefault(nm, []).append(d)
+
+            # Resolve names strictly (case-sensitive equals)
+            resolved_from_names = []
+            not_found_names = []
+            ambiguous_names = []
+            for nm in names_from_args:
+                exact = by_exact_name.get(nm, [])
+                if len(exact) == 0:
+                    not_found_names.append(nm)
+                elif len(exact) > 1:
+                    ambiguous_names.append({
+                        "name": nm,
+                        "candidates": [self.format_device_info(r) for r in exact]
+                    })
+                else:
+                    try:
+                        resolved_from_names.append(int(exact[0].get("id")))
+                    except Exception:
+                        not_found_names.append(nm)
+
+            # Hard-stop if names are unresolved or ambiguous
+            if not_found_names or ambiguous_names:
+                return self.error_response(
+                    "Strict device name match failed; explicit selection required.",
+                    {
+                        "status": "needs_selection",
+                        "unresolved_names": not_found_names,
+                        "ambiguous": ambiguous_names,
+                        "available_devices": [self.format_device_info(r) for r in all_rows]
+                    }
+                )
+
+            # Validate ids existence
+            unknown_ids = [i for i in ids_from_args if i not in known_id_set]
+            if unknown_ids:
+                return self.error_response(
+                    "Unknown device id(s). No action performed.",
+                    {
+                        "status": "unknown_ids",
+                        "unknown_ids": unknown_ids,
+                        "available_devices": [self.format_device_info(r) for r in all_rows]
+                    }
+                )
+
+            # If both ids and names provided, sets must match exactly
+            if ids_from_args and resolved_from_names:
+                if set(ids_from_args) != set(resolved_from_names):
+                    return self.error_response(
+                        "device_ids and device_names do not resolve to the same set. No action performed.",
+                        {
+                            "status": "mismatched_selection",
+                            "ids_from_device_ids": sorted(set(ids_from_args)),
+                            "ids_from_device_names": sorted(set(resolved_from_names))
+                        }
+                    )
+
+            # Final target list
+            final_ids = sorted(list(set(ids_from_args or resolved_from_names)))
+
+            # Multi-target safety
+            if len(final_ids) > 1 and not confirm_multi:
+                return self.error_response(
+                    "Multiple devices requested but confirm_multi=false.",
+                    {"requested_device_ids": final_ids}
+                )
+
+            # Build payload and call API
+            payload = {
+                "DeviceCollection": {
+                    "rows": [{"id": did} for did in final_ids],
+                    "total": len(final_ids)
+                }
+            }
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/reset",
+                    headers=headers,
+                    json=payload
+                )
+
+            if resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {resp.status_code} - {resp.text}",
+                    {"request_body": payload}
+                )
+
+            # Parse and evaluate success
+            try:
+                body = resp.json() or {}
+            except Exception:
+                body = {}
+
+            device_resp = body.get("DeviceResponse") or {}
+            rows = device_resp.get("rows") or []
+            response_block = body.get("Response") or {}
+            overall_code = str(response_block.get("code")) if response_block.get("code") is not None else None
+
+            success_ids = []
+            failures = []
+            for r in rows:
+                rid = r.get("id")
+                code = r.get("code")
+                try:
+                    rid_int = int(str(rid))
+                except Exception:
+                    rid_int = None
+                if str(code) == "0" and rid_int is not None:
+                    success_ids.append(rid_int)
+                else:
+                    failures.append({"id": rid, "code": code})
+
+            overall_ok = (overall_code in (None, "0")) and (len(failures) == 0)
+
+            summary = {
+                "requested": final_ids,
+                "success_ids": sorted(success_ids),
+                "failed": failures,
+                "device_response": device_resp,
+                "response_block": response_block,
+                "request_body": payload
+            }
+
+            if overall_ok:
+                return self.success_response({"message": f"Restart executed: {len(success_ids)} success", **summary})
+            else:
+                if response_block.get("message"):
+                    summary["response_message"] = response_block.get("message")
+                return self.error_response("Restart completed with errors.", summary)
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_device_status(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Get device status and health."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}/status",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json()
+            status = data.get("DeviceStatus", {})
+
+            return self.success_response({
+                "device_id": device_id,
+                "status": {
+                    "is_online": status.get("is_online", False),
+                    "is_locked": status.get("is_locked", False),
+                    "last_seen": status.get("last_seen"),
+                    "cpu_usage": status.get("cpu_usage"),
+                    "memory_usage": status.get("memory_usage"),
+                    "storage_usage": status.get("storage_usage"),
+                    "temperature": status.get("temperature")
+                }
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def scan_devices(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Scan network for devices."""
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            scan_data = {
+                "network_range": args.get("network_range", ""),
+                "port": args.get("port", 51211)
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/scan",
+                    headers=headers,
+                    json=scan_data
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json()
+            discovered_devices = data.get("discovered_devices", [])
+
+            return self.success_response({
+                "message": f"Found {len(discovered_devices)} devices on network",
+                "devices": discovered_devices
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def sync_device_time(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Sync device time with server."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}/sync_time",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device {device_id} time synchronized successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def clear_device_log(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Clear device logs."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+            log_type = args.get("log_type", "all")
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            clear_data = {
+                "log_type": log_type
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}/clear_log",
+                    headers=headers,
+                    json=clear_data
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device {device_id} logs cleared successfully (type: {log_type})"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def lock_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Lock a device."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}/lock",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device {device_id} locked successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def unlock_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Unlock a device."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}/unlock",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device {device_id} unlocked successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def disconnect_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Disconnect a device from the BioStar 2 server."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+
+            headers = {
+                "bs-session-id": self.session.session_id,
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}/disconnect",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device {device_id} disconnected successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def remove_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Remove a device from the BioStar 2 system."""
+        try:
+            self.check_auth()
+
+            device_id = args["device_id"]
+
+            headers = {
+                "bs-session-id": self.session.session_id,
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.delete(
+                    f"{self.session.config.biostar_url}/api/devices?id={device_id}",
+                    headers=headers
+                )
+
+            if response.status_code not in [200, 204]:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device {device_id} removed successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def udp_search(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Search for devices using UDP broadcast."""
+        try:
+            self.check_auth()
+
+            timeout = args.get("timeout", 5)
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            search_data = {
+                "timeout": timeout,
+                "with_rs485": True
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/udp_search",
+                    headers=headers,
+                    json=search_data,
+                    timeout=timeout + 5  # Give extra time for the API call
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            data = response.json()
+            discovered_devices = data.get("DeviceCollection", {}).get("rows", [])
+
+            # 연결되지 않은 장치만 필터링 (server_connected.status가 "disconnected"인 장치)
+            disconnected_devices = [
+                device for device in discovered_devices
+                if device.get("server_connected", {}).get("status") == "disconnected"
+            ]
+
+            logger.info(
+                f"UDP search found {len(discovered_devices)} total devices, {len(disconnected_devices)} disconnected devices")
+
+            return self.success_response({
+                "message": f"UDP search found {len(disconnected_devices)} disconnected devices (out of {len(discovered_devices)} total)",
+                "total_discovered": len(discovered_devices),
+                "total_disconnected": len(disconnected_devices),
+                "devices": [
+                    {
+                        "device_id": d.get("id"),
+                        "device_type": d.get("device_type_id", {}).get("name", "Unknown"),
+                        "device_type_id": d.get("device_type_id", {}).get("id"),
+                        "ip_address": d.get("lan", {}).get("ip"),
+                        "port": d.get("lan", {}).get("device_port"),
+                        "dhcp_enabled": d.get("lan", {}).get("enable_dhcp") == "true",
+                        "support_ssl": d.get("support_ssl") == "true",
+                        "server_connected": d.get("server_connected", {}).get("status"),
+                        "server_ip": d.get("server_connected", {}).get("ip_addr"),
+                        "rs485_mode": d.get("rs485", {}).get("mode"),
+                        "use_alphanumeric": d.get("system", {}).get("use_alphanumeric") == "true"
+                    }
+                    for d in disconnected_devices
+                ]
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def tcp_search(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Search for a specific device using TCP connection.
+        This is the preferred method when you know the device IP address.
+        Use TCP search BEFORE UDP search for more reliable connection.
+        """
+        try:
+            self.check_auth()
+
+            ip_address = args["ip_address"]
+            port = args.get("port", 51211)
+            timeout = args.get("timeout", 10)
+            retry_count = args.get("retry_count", 2)
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # TCP Search payload format as specified by user
+            search_data = {
+                "Device": {
+                    "lan": {
+                        "ip": ip_address,
+                        "device_port": str(port)
+                    }
+                },
+                "FollowerServer": {
+                    "id": "1"
+                }
+            }
+
+            last_error = None
+            for attempt in range(retry_count + 1):
+                try:
+                    logger.info(f"TCP Search attempt {attempt + 1}/{retry_count + 1} for {ip_address}:{port}")
+                    
+                    async with httpx.AsyncClient(verify=False) as client:
+                        response = await client.post(
+                            f"{self.session.config.biostar_url}/api/devices/tcp_search",
+                            headers=headers,
+                            json=search_data,
+                            timeout=timeout
+                        )
+
+                    if response.status_code in [200, 201]:
+                        logger.info(f" TCP Search successful for {ip_address}:{port}")
+                        
+                        # Parse response to get device info
+                        data = response.json()
+                        logger.info(f" TCP Search Response: {json.dumps(data, indent=2)}")
+                        
+                        # Extract device from DeviceCollection.rows[0]
+                        device_collection = data.get("DeviceCollection", {})
+                        rows = device_collection.get("rows", [])
+                        if not rows:
+                            return self.error_response({
+                                "message": f"No device found at {ip_address}:{port}",
+                                "method": "TCP Search"
+                            })
+                        
+                        device_info = rows[0]
+                        device_id = device_info.get("id")
+                        device_type_id = device_info.get("device_type_id", {}).get("id")
+                        
+                        # Device name from TCP search (use as-is, don't modify!)
+                        device_name = device_info.get("name")
+                        if not device_name:
+                            # If no name in response, use device ID
+                            device_name = f"Device {device_id}"
+                        
+                        return self.success_response({
+                            "message": f"Successfully connected to device at {ip_address}:{port}",
+                            "method": "TCP Search",
+                            "device": {
+                                "device_id": device_id,
+                                "name": device_name,
+                                "device_type_id": device_type_id,
+                                "ip_address": ip_address,
+                                "port": port,
+                                "full_info": device_info
+                            }
+                        })
+                    
+                    last_error = f"HTTP {response.status_code}: {response.text}"
+                    
+                except Exception as e:
+                    last_error = str(e)
+                    logger.warning(f" TCP Search attempt {attempt + 1} failed: {e}")
+                
+                # Wait before retry (except on last attempt)
+                if attempt < retry_count:
+                    await asyncio.sleep(2)
+
+            # All attempts failed
+            logger.error(f" TCP Search failed after {retry_count + 1} attempts for {ip_address}:{port}")
+            return self.error_response({
+                "message": f"Failed to connect to device at {ip_address}:{port} after {retry_count + 1} attempts",
+                "method": "TCP Search",
+                "last_error": last_error,
+                "suggestion": "Try using udp-search instead, or verify the IP address and port are correct"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # Device Group methods
+    async def get_device_groups(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        List device groups via POST /api/v2/device_groups/search.
+        - Input:
+        • group_search_text (optional): case-insensitive substring filter on name
+        - Output per group:
+        • id, name, depth, parent_id, is_root, is_top_level
+        - Notes:
+        • This endpoint does NOT return device counts. Do not infer counts here.
+        • Root group: id==1 or depth==0
+        • Top-level group: parent_id==1
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            payload = {"order_by": "depth:false"}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/v2/device_groups/search",
+                    headers=headers,
+                    json=payload
+                )
+
+            if resp.status_code != 200:
+                return self.error_response(f"API call failed: {resp.status_code} - {resp.text}")
+
+            body = resp.json() or {}
+            rows = (body.get("DeviceGroupCollection") or {}).get("rows", []) or []
+
+            group_search_text = (args.get("group_search_text") or "").strip().lower()
+
+            out = []
+            for g in rows:
+                gid = self._to_int_safe(g.get("id"))
+                depth = self._to_int_safe(g.get("depth"))
+                pid = self._to_int_safe((g.get("parent_id") or {}).get("id"))
+
+                item = {
+                    "id": gid,
+                    "name": g.get("name"),
+                    "depth": depth,
+                    "parent_id": pid,
+                    "is_root": (gid == 1 or depth == 0),
+                    "is_top_level": (pid == 1)
+                }
+                out.append(item)
+
+            if group_search_text:
+                out = [r for r in out if group_search_text in str(r.get("name") or "").lower()]
+
+            return self.success_response({
+                "message": f"Found {len(out)} device groups (v2 search)",
+                "total": len(out),
+                "groups": out
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def get_device_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Fetch a device group by STRICT selection:
+        - Accept one of:
+        • group_id (preferred)
+        • group_name (EXACT, case-sensitive; no fuzzy)
+        • group_search_text (substring browse; returns candidates ONLY)
+        - Branch:
+        • 0 match  -> NO ACTION. Return all available groups (compact) and needs_selection=true.
+        • 1 match  -> GET /api/device_groups/{id} and return detailed shape (devices + children + is_top_level).
+        • >1 match -> NO ACTION. Return candidates (id/name/depth/parent) and needs_selection=true.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            group_id = args.get("group_id")
+            group_name = args.get("group_name")
+            group_search_text = (args.get("group_search_text") or "").strip()
+
+            # --- Case 1: direct by id ---
+            if group_id is not None:
+                gid = int(group_id)
+                detail = await self._fetch_group_detail(gid, headers)
+                if detail is None:
+                    return self.error_response(f"Device group id {gid} not found.")
+                return self.success_response(self._format_group_detail(detail))
+
+            # Load all groups (for name/substring resolution)
+            all_groups = await self._fetch_all_device_groups(headers)
+
+            # --- Case 2: browse by substring only (no exact selection) ---
+            if not group_name and group_search_text:
+                q = group_search_text.lower()
+                candidates = [
+                    self._compact_group_row(g) for g in all_groups
+                    if q in str(g.get("name") or "").lower()
+                ]
+                return self.success_response({
+                    "message": f"Found {len(candidates)} candidate group(s) for '{group_search_text}'. Please choose one.",
+                    "status": "needs_selection",
+                    "needs_selection": True,
+                    "candidates": candidates
+                })
+
+            # --- Case 3: strict exact name (case-sensitive) ---
+            if group_name:
+                exact = [g for g in all_groups if str(g.get("name", "")) == group_name]
+
+                if len(exact) == 0:
+                    return self.error_response(
+                        "No device group matched exactly. Please choose one from the list.",
+                        {
+                            "status": "group_not_found",
+                            "needs_selection": True,
+                            "available_groups": [self._compact_group_row(g) for g in all_groups]
+                        }
+                    )
+
+                if len(exact) > 1:
+                    return self.error_response(
+                        "Multiple device groups share the same exact name. Please choose one by id.",
+                        {
+                            "status": "ambiguous_group",
+                            "needs_selection": True,
+                            "candidates": [self._compact_group_row(g) for g in exact]
+                        }
+                    )
+
+                gid = int(exact[0].get("id"))
+                detail = await self._fetch_group_detail(gid, headers)
+                if detail is None:
+                    return self.error_response(f"Device group id {gid} not found (detail).")
+                return self.success_response(self._format_group_detail(detail))
+
+            # --- No selection input at all ---
+            return self.error_response(
+                "Provide one of: group_id, group_name (exact), or group_search_text (browse)."
+            )
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ------------------------ helpers for device group detail ------------------------
+
+    async def _fetch_all_device_groups(self, headers: Dict[str, str]) -> List[Dict[str, Any]]:
+        """GET /api/device_groups → return rows."""
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                r = await client.get(f"{self.session.config.biostar_url}/api/device_groups", headers=headers)
+            if r.status_code != 200:
+                return []
+            data = r.json() or {}
+            return (data.get("DeviceGroupCollection") or {}).get("rows", []) or []
+        except Exception:
+            return []
+
+    async def _fetch_group_detail(self, gid: int, headers: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """GET /api/device_groups/{id} → return DeviceGroup dict or None."""
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                r = await client.get(f"{self.session.config.biostar_url}/api/device_groups/{gid}", headers=headers)
+            if r.status_code != 200:
+                return None
+            body = r.json() or {}
+            return body.get("DeviceGroup") or None
+        except Exception:
+            return None
+
+    def _compact_group_row(self, g: Dict[str, Any]) -> Dict[str, Any]:
+        """Compact shape for selection lists."""
+        pid = (g.get("parent_id") or {}).get("id")
+        return {
+            "id": self._to_int_safe(g.get("id")),
+            "name": g.get("name"),
+            "depth": self._to_int_safe(g.get("depth")),
+            "parent_id": self._to_int_safe(pid),
+        }
+
+    def _format_group_detail(self, dg: Dict[str, Any]) -> Dict[str, Any]:
+        """Normalize DeviceGroup detail into a friendly, explicit structure."""
+        gid = self._to_int_safe(dg.get("id"))
+        name = dg.get("name")
+        desc = dg.get("description")
+        depth = self._to_int_safe(dg.get("depth"))
+        parent = dg.get("parent_id") or {}
+        parent_id = self._to_int_safe(parent.get("id"))
+        parent_name = parent.get("name")
+        is_top_level = (parent_id == 1)
+
+        # children groups
+        children = []
+        for cg in (dg.get("device_groups") or []):
+            children.append({
+                "id": self._to_int_safe(cg.get("id")),
+                "name": cg.get("name"),
+                "description": cg.get("description"),
+                "depth": self._to_int_safe(cg.get("depth"))
+            })
+
+        # devices in group (flatten common fields)
+        devs = []
+        for d in (dg.get("devices") or []):
+            devs.append({
+                "id": self._to_int_safe(d.get("id")),
+                "name": d.get("name"),
+                "model_id": self._to_int_safe((d.get("device_type_id") or {}).get("id")),
+                "model_name": (d.get("device_type_id") or {}).get("name"),
+                "status": d.get("status"),
+                "firmware": (d.get("version") or {}).get("firmware"),
+                "product_name": (d.get("version") or {}).get("product_name"),
+                "ip": (d.get("lan") or {}).get("ip"),
+                "connection_mode": (d.get("lan") or {}).get("connection_mode"),
+                "rs485_mode": (d.get("rs485") or {}).get("mode"),
+            })
+
+        return {
+            "message": f"Device group '{name}' (id={gid}) detail",
+            "group": {
+                "id": gid,
+                "name": name,
+                "description": desc,
+                "depth": depth,
+                "parent": {"id": parent_id, "name": parent_name},
+                "is_top_level": is_top_level,
+                "counts": {"devices": len(devs), "children": len(children)},
+                "devices": devs,
+                "children": children,
+            }
+        }
+
+    def _to_int_safe(self, v: Any) -> Optional[int]:
+        """Best-effort int coercion; None on failure."""
+        try:
+            return int(str(v))
+        except Exception:
+            return None
+
+    async def create_device_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Create a new device group."""
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            group_data = {
+                "DeviceGroup": {
+                    "name": args["name"],
+                    "description": args.get("description", ""),
+                    "parent_id": {
+                        "id": args.get("parent_id", 1)
+                    }
+                }
+            }
+
+            # Only add device_id_list if devices are provided
+            if args.get("device_ids"):
+                group_data["DeviceGroup"]["device_id_list"] = args["device_ids"]
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/device_groups",
+                    headers=headers,
+                    json=group_data
+                )
+
+            if response.status_code not in [200, 201]:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device group '{args['name']}' created successfully",
+                "group_id": response.json().get("id")
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_device_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Update an existing device group."""
+        try:
+            self.check_auth()
+
+            group_id = args["group_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # First get existing group data
+            async with httpx.AsyncClient(verify=False) as client:
+                get_response = await client.get(
+                    f"{self.session.config.biostar_url}/api/device_groups/{group_id}",
+                    headers=headers
+                )
+
+                if get_response.status_code != 200:
+                    return self.error_response(f"Failed to get device group: {get_response.status_code}")
+
+                group_data = get_response.json()
+
+                # Update only provided fields
+                if "name" in args:
+                    group_data["DeviceGroup"]["name"] = args["name"]
+                if "description" in args:
+                    group_data["DeviceGroup"]["description"] = args["description"]
+                if "device_ids" in args:
+                    group_data["DeviceGroup"]["device_id_list"] = args["device_ids"]
+
+                # Update the group
+                update_response = await client.put(
+                    f"{self.session.config.biostar_url}/api/device_groups/{group_id}",
+                    headers=headers,
+                    json=group_data
+                )
+
+            if update_response.status_code != 200:
+                return self.error_response(f"API call failed: {update_response.status_code} - {update_response.text}")
+
+            return self.success_response({
+                "message": f"Device group {group_id} updated successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def delete_device_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """Delete a device group."""
+        try:
+            self.check_auth()
+
+            group_id = args["group_id"]
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.delete(
+                    f"{self.session.config.biostar_url}/api/device_groups/{group_id}",
+                    headers=headers
+                )
+
+            if response.status_code not in [200, 204]:
+                return self.error_response(f"API call failed: {response.status_code} - {response.text}")
+
+            return self.success_response({
+                "message": f"Device group {group_id} deleted successfully"
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    def format_device_info(self, device: Dict[str, Any]) -> Dict[str, Any]:
+        """Format device information for response."""
+        return {
+            "id": device.get("id"),
+            "name": device.get("name"),
+            "device_type": device.get("device_type", {}).get("name") if isinstance(device.get("device_type"),
+                                                                                   dict) else device.get("device_type"),
+            "ip_address": device.get("ip"),
+            "port": device.get("port"),
+            "status": device.get("status"),
+            "is_online": device.get("is_online", False),
+            "firmware_version": device.get("firmware_version"),
+            "last_activity": device.get("last_activity")
+        }
+
+    async def move_device_to_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Move a device into a target device group.
+        - Resolves device by id or by name substring.
+        - Resolves group by id or by name substring using POST /api/v2/device_groups/search.
+        - Applies PUT /api/devices/{device_id} with {"Device":{"device_group_id":{"id": <gid>}}}.
+        - If ambiguous or not found, returns candidates and asks for selection.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ---------- 1) Resolve device ----------
+            device_id = args.get("device_id")
+            device_query = (args.get("device_name") or args.get("device_search_text") or "").strip()
+
+            if not device_id:
+                devices_all = await self._fetch_all_devices(headers)
+                if device_query:
+                    matches = self._filter_devices_by_query(devices_all, device_query)
+                else:
+                    matches = []
+
+                if len(matches) == 0:
+                    # No device matched → return all devices and stop
+                    return self.success_response({
+                        "message": "No device matched the query. Here is the full device list. Please pick one.",
+                        "status": "device_not_found",
+                        "needs_selection": True,
+                        "devices": [self.format_device_info(d) for d in devices_all]
+                    })
+                if len(matches) > 1:
+                    # Ambiguous → return candidates
+                    return self.success_response({
+                        "message": "Multiple devices matched. Please pick one device.",
+                        "status": "ambiguous_device",
+                        "needs_selection": True,
+                        "candidates": [self.format_device_info(d) for d in matches]
+                    })
+                device_id = matches[0].get("id")
+
+            # ---------- 2) Resolve group ----------
+            target_group_id = args.get("target_group_id")
+            target_group_name = (args.get("target_group_name") or args.get("group_search_text") or "").strip()
+
+            if not target_group_id:
+                groups_all = await self._search_all_device_groups_v2(headers)
+                if target_group_name:
+                    g_matches = self._filter_groups_by_name(groups_all, target_group_name)
+                else:
+                    g_matches = []
+
+                if len(g_matches) == 0:
+                    # No group matched → return all groups and stop
+                    return self.success_response({
+                        "message": "No device group matched the query. Here is the full group list. Please pick one.",
+                        "status": "group_not_found",
+                        "needs_selection": True,
+                        "groups": [{"id": g.get("id"), "name": g.get("name"), "depth": g.get("depth")} for g in
+                                   groups_all]
+                    })
+                if len(g_matches) > 1:
+                    # Ambiguous → return candidates
+                    return self.success_response({
+                        "message": "Multiple device groups matched. Please pick one group.",
+                        "status": "ambiguous_group",
+                        "needs_selection": True,
+                        "candidates": [{"id": g.get("id"), "name": g.get("name"), "depth": g.get("depth")} for g in
+                                       g_matches]
+                    })
+                target_group_id = g_matches[0].get("id")
+
+            # ---------- 3) PUT update ----------
+            payload = {"Device": {"device_group_id": {"id": int(target_group_id)}}}
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{int(device_id)}",
+                    headers=headers,
+                    json=payload
+                )
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "device_id": int(device_id)}
+                )
+
+            return self.success_response({
+                "message": f"Device {int(device_id)} moved to group {int(target_group_id)} successfully",
+                "device_id": int(device_id),
+                "target_group_id": int(target_group_id),
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def remove_device_from_group(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Move a device to the root group (id=1).
+        - Resolves device by id or by name substring (same 3-case logic).
+        - Applies PUT /api/devices/{device_id} with {"Device":{"device_group_id":{"id":1}}}.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # Resolve device
+            device_id = args.get("device_id")
+            device_query = (args.get("device_name") or args.get("device_search_text") or "").strip()
+
+            if not device_id:
+                devices_all = await self._fetch_all_devices(headers)
+                matches = self._filter_devices_by_query(devices_all, device_query) if device_query else []
+
+                if len(matches) == 0:
+                    return self.success_response({
+                        "message": "No device matched the query. Here is the full device list. Please pick one.",
+                        "status": "device_not_found",
+                        "needs_selection": True,
+                        "devices": [self.format_device_info(d) for d in devices_all]
+                    })
+                if len(matches) > 1:
+                    return self.success_response({
+                        "message": "Multiple devices matched. Please pick one device.",
+                        "status": "ambiguous_device",
+                        "needs_selection": True,
+                        "candidates": [self.format_device_info(d) for d in matches]
+                    })
+                device_id = matches[0].get("id")
+
+            # PUT to root group (id=1)
+            payload = {"Device": {"device_group_id": {"id": 1}}}
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{int(device_id)}",
+                    headers=headers,
+                    json=payload
+                )
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "device_id": int(device_id)}
+                )
+
+            return self.success_response({
+                "message": f"Device {int(device_id)} moved to root group (id=1) successfully",
+                "device_id": int(device_id),
+                "target_group_id": 1,
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # ------------------------ helpers (private) ------------------------
+    async def _fetch_all_devices(self, headers: Dict[str, str]) -> list:
+        """GET /api/devices and return rows list."""
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                r = await client.get(f"{self.session.config.biostar_url}/api/devices", headers=headers)
+            if r.status_code != 200:
+                return []
+            data = r.json() or {}
+            return data.get("DeviceCollection", {}).get("rows", []) or []
+        except Exception:
+            return []
+
+    def _filter_devices_by_query(self, rows: list, query: str) -> list:
+        """Case-insensitive substring match on name or exact id match if numeric."""
+        q = query.strip().lower()
+        numeric_id = None
+        try:
+            numeric_id = int(query)
+        except Exception:
+            pass
+        out = []
+        for d in rows:
+            name = str(d.get("name") or "").lower()
+            did = d.get("id")
+            if (q and q in name) or (numeric_id is not None and did == numeric_id):
+                out.append(d)
+        return out
+
+    async def _search_all_device_groups_v2(self, headers: Dict[str, str]) -> list:
+        """POST /api/v2/device_groups/search with {"order_by":"depth:false"}."""
+        try:
+            payload = {"order_by": "depth:false"}
+            async with httpx.AsyncClient(verify=False) as client:
+                r = await client.post(
+                    f"{self.session.config.biostar_url}/api/v2/device_groups/search",
+                    headers=headers,
+                    json=payload
+                )
+            if r.status_code != 200:
+                return []
+            data = r.json() or {}
+            return data.get("DeviceGroupCollection", {}).get("rows", []) or []
+        except Exception:
+            return []
+
+    def _filter_groups_by_name(self, rows: list, name_substring: str) -> list:
+        """Case-insensitive substring match on group name."""
+        q = name_substring.strip().lower()
+        return [g for g in rows if q in str(g.get("name") or "").lower()]
+
+    async def _resolve_device_id_from_args(self, args: Dict[str, Any], headers: Dict[str, str]) -> tuple[
+        Optional[int], Optional[Sequence]]:
+        """
+        Resolve device id from args.
+        Priority:
+        1) device_id
+        2) device_name (exact or best-match search if your implementation supports)
+        3) door_id -> entry_device_id
+        4) door_name -> entry_device_id
+        This function assumes existing endpoints/utilities in your codebase.
+        """
+        # If caller already passes device_id
+        if args.get("device_id") is not None:
+            try:
+                return int(args["device_id"]), None
+            except Exception:
+                return None, self.error_response("Invalid device_id")
+
+        # NOTE: Keep your original search order/logic. Below are safe fallbacks.
+        # 2) Resolve by device_name (exact)
+        device_name = str(args.get("device_name") or "").strip()
+        if device_name:
+            try:
+                async with httpx.AsyncClient(verify=False) as client:
+                    resp = await client.get(f"{self.session.config.biostar_url}/api/devices", headers=headers)
+                if resp.status_code == 200:
+                    data = resp.json() or {}
+                    rows = (data.get("DeviceCollection") or {}).get("rows") or data.get("devices") or []
+                    for d in rows:
+                        if str(d.get("name") or "").strip() == device_name:
+                            did = d.get("id")
+                            if did is not None:
+                                return int(did), None
+            except Exception:
+                pass  # fall through
+
+        # 3) Resolve via door_id -> entry_device_id
+        if args.get("door_id") is not None:
+            try:
+                door_id = int(args["door_id"])
+                async with httpx.AsyncClient(verify=False) as client:
+                    dresp = await client.get(f"{self.session.config.biostar_url}/api/doors/{door_id}", headers=headers)
+                if dresp.status_code == 200:
+                    dobj = dresp.json() or {}
+                    door = (dobj.get("Door") or {})
+                    entry = (door.get("entry_device_id") or {}).get("id")
+                    if entry is not None:
+                        return int(entry), None
+            except Exception:
+                pass  # fall through
+
+        # 4) Resolve via door_name -> entry_device_id
+        door_name = str(args.get("door_name") or "").strip()
+        if door_name:
+            try:
+                async with httpx.AsyncClient(verify=False) as client:
+                    dresp = await client.get(f"{self.session.config.biostar_url}/api/doors", headers=headers)
+                if dresp.status_code == 200:
+                    data = dresp.json() or {}
+                    rows = (data.get("DoorCollection") or {}).get("rows") or data.get("doors") or []
+                    for d in rows:
+                        if str(d.get("name") or "").strip() == door_name:
+                            entry = (d.get("entry_device_id") or {}).get("id")
+                            if entry is not None:
+                                return int(entry), None
+            except Exception:
+                pass  # fall through
+
+        # Nothing resolved
+        return None, self.error_response("Device not resolved from args")
+
+    def _online_status_from_device(self, device_obj: Dict[str, Any]) -> bool:
+        """
+        Determine online status consistently:
+        - Prefer 'status' == "1" as online.
+        - Fallback to 'is_online' boolean.
+        """
+        status = str(device_obj.get("status", "")).strip()
+        if status == "1":
+            return True
+        io = device_obj.get("is_online")
+        if isinstance(io, bool):
+            return io
+        return False
+
+    def _to_int(self, v) -> Optional[int]:
+        """Safe convert to int or return None."""
+        try:
+            return int(str(v).strip())
+        except Exception:
+            return None
+
+    # -----------------------------
+    # AUTH MODE UPDATE (with conflict & order policy)
+    # -----------------------------
+    async def update_device_auth_mode(self, args: Dict[str, Any]) -> Sequence:
+        """
+        Update authentication operation modes for a device.
+
+        Flow:
+        1) Resolve target device by device_id or name/door fallback.
+        2) GET /api/devices/{id} to read current 'authentication.operation_modes'.
+        3) Decide new set using 'action' (add/remove/set), 'conflict_policy' (overwrite/abort/merge).
+        4) PUT minimal payload: {"Device":{"authentication":{"operation_modes":[...]}}}
+
+        Business rules:
+        - 'add' that changes strictness may be considered a conflict.
+        - Default on conflict: overwrite (i.e., behave like 'set').
+        - If conflict_policy='abort', we return an error instead.
+        - schedule_id defaults to 1 and is applied to all rows.
+
+        Inputs:
+        - mode_codes: [int] direct extended mode codes (11..49) take precedence
+        - auth_specs: [str] human specs (e.g., "card+face+fingerprint") mapped to a single code
+                    Supports ordered forms like "card -> face -> fingerprint".
+        - action: "set" | "add" | "remove" (default "set")
+        - conflict_policy: "overwrite" | "abort" | "merge" (default "overwrite")
+        - ordered_sequence_policy: "collapse" | "abort" (default "collapse")
+        - schedule_id: int (default 1)
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # 1) Resolve
+            resolved_id, early = await self._resolve_device_id_from_args(args, headers)
+            if resolved_id is None:
+                return early
+            device_id = int(resolved_id)
+
+            # 2) Fetch current config
+            async with httpx.AsyncClient(verify=False) as client:
+                get_resp = await client.get(f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                                            headers=headers)
+            if get_resp.status_code != 200:
+                return self.error_response(f"Failed to get device: {get_resp.status_code} - {get_resp.text}")
+
+            body = get_resp.json() or {}
+            device = (body.get("Device") or {})
+            auth = device.get("authentication") or {}
+            current_ops = list(auth.get("operation_modes") or [])
+
+            # Track online, but do not block updates (only include in response)
+            is_online = self._online_status_from_device(device)
+
+            # Extract current numeric codes
+            current_codes: set[int] = set()
+            for row in current_ops:
+                code = self._to_int(row.get("mode"))
+                if code is not None:
+                    current_codes.add(code)
+
+            # 3) Resolve target codes
+            ordered_detected = False
+            target_codes: List[int] = []
+
+            # Prefer auth_specs if given (allows natural language + order syntax)
+            specs = args.get("auth_specs") or []
+            if isinstance(specs, (list, tuple)) and specs:
+                for spec in specs:
+                    code, was_ordered = self._map_auth_spec_to_code(spec)
+                    ordered_detected = ordered_detected or bool(was_ordered)
+                    if code is None:
+                        return self.error_response(
+                            "Unknown auth spec. Provide supported 'auth_specs' (e.g., 'card+face+fingerprint') or 'mode_codes'.",
+                            {"unknown_spec": spec}
+                        )
+                    if 11 <= int(code) <= 49:
+                        target_codes.append(int(code))
+
+            # If no specs or empty, accept raw mode codes
+            if not target_codes:
+                raw_codes = args.get("mode_codes")
+                if isinstance(raw_codes, (list, tuple)):
+                    for x in raw_codes:
+                        code = self._to_int(x)
+                        if code is not None and 11 <= code <= 49:
+                            target_codes.append(code)
+
+            if not target_codes:
+                return self.error_response("No valid mode codes resolved from 'auth_specs' or 'mode_codes' (11..49).")
+
+            action = (args.get("action") or "set").strip().lower()
+            conflict_policy = (args.get("conflict_policy") or "overwrite").strip().lower()
+            ordered_policy = (args.get("ordered_sequence_policy") or "collapse").strip().lower()
+            schedule_id = self._to_int(args.get("schedule_id")) or 1
+            target_set = set(target_codes)
+
+            # If ordered syntax was detected, either collapse (default) or abort
+            if ordered_detected and ordered_policy == "abort":
+                return self.error_response(
+                    "Ordered steps are not supported by device. Aborted per 'ordered_sequence_policy=abort'.",
+                    {"received_specs": specs}
+                )
+
+            # Conflict detection (simple guard; project-specific refinement possible)
+            def has_conflict_add(cur: set[int], tgt: set[int]) -> bool:
+                return len(tgt - cur) > 0
+
+            # Compute next codes
+            if action == "set":
+                new_codes = set(target_set)
+            elif action == "remove":
+                new_codes = set(current_codes) - target_set
+            elif action == "add":
+                if has_conflict_add(current_codes, target_set):
+                    if conflict_policy == "abort":
+                        return self.error_response(
+                            "Add operation conflicts with business rule. Use action='set' or conflict_policy='overwrite'.",
+                            {"current": sorted(current_codes), "target": sorted(target_set)}
+                        )
+                    elif conflict_policy in ("overwrite", "set"):
+                        new_codes = set(target_set)  # overwrite like 'set'
+                    elif conflict_policy == "merge":
+                        new_codes = set(current_codes) | target_set
+                    else:
+                        new_codes = set(target_set)  # default overwrite
+                else:
+                    new_codes = set(current_codes) | target_set
+            else:
+                return self.error_response("Invalid action. Use 'set', 'add', or 'remove'.")
+
+            # Short-circuit if nothing to change
+            if new_codes == current_codes:
+                return self.success_response({
+                    "message": "No changes to authentication.operation_modes.",
+                    "device_id": device_id,
+                    "online": is_online,
+                    "unchanged_modes": sorted(current_codes),
+                    "ordered_input_collapsed": bool(ordered_detected and ordered_policy == "collapse")
+                })
+
+            # Build minimal payload (keep other fields intact server-side)
+            def _row(m: int) -> Dict[str, Any]:
+                return {"mode": int(m), "schedule_id": {"id": str(schedule_id)}}
+
+            final_ops = [_row(m) for m in sorted(new_codes)]
+            payload = {"Device": {"authentication": {"operation_modes": final_ops}}}
+
+            # 4) PUT
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "device_id": device_id}
+                )
+
+            return self.success_response({
+                "message": f"Updated authentication.operation_modes via action='{action}', conflict_policy='{conflict_policy}'",
+                "device_id": device_id,
+                "online": is_online,
+                "before_codes": sorted(current_codes),
+                "after_codes": sorted(new_codes),
+                "ordered_input_collapsed": bool(ordered_detected and ordered_policy == "collapse"),
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    def _snap_face_max(self, max_cm: Any) -> Optional[int]:
+        """
+        Snap requested face detection max distance to supported steps:
+        30,40,50,60,70,80,90,100,110,120,130 or 255 (for >130).
+        """
+        if max_cm is None:
+            return None
+        # Special hint keys
+        if isinstance(max_cm, str) and max_cm.strip().lower() in ("over_130", "over130", ">130", "gt130"):
+            return 255
+        val = self._to_int(max_cm)
+        if val is None:
+            return None
+        if val <= 30:
+            return 30
+        if val >= 131:
+            return 255
+        steps = [30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130]
+        for s in steps:
+            if val <= s:
+                return s
+        return 130
+
+    # -----------------------------
+    # FACE DISTANCE UPDATE (leave UNCHANGED as requested)
+    # -----------------------------
+    async def update_device_face_distance(self, args: Dict[str, Any]) -> Sequence:
+        """
+        Update face detection distance window ONLY.
+        (UNCHANGED per user's request)
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # 1) Resolve device
+            resolved_id, early = await self._resolve_device_id_from_args(args, headers)
+            if resolved_id is None:
+                return early
+            device_id = int(resolved_id)
+
+            # Parse target distance
+            max_cm = self._snap_face_max(args.get("max_cm"))
+            if max_cm is None:
+                # Support legacy argument name
+                max_cm = self._snap_face_max(args.get("target_max_cm"))
+            if max_cm is None:
+                return self.error_response("Provide 'max_cm' (30..130) or 'over_130' to use 255.")
+
+            # 2) Fetch current device
+            async with httpx.AsyncClient(verify=False) as client:
+                get_resp = await client.get(f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                                            headers=headers)
+            if get_resp.status_code != 200:
+                return self.error_response(f"Failed to get device: {get_resp.status_code} - {get_resp.text}")
+
+            body = get_resp.json() or {}
+            device = (body.get("Device") or {})
+            is_online = self._online_status_from_device(device)
+
+            # Prefer cloning existing 'face' block to keep all fields intact
+            face = {}
+            if isinstance(device.get("face"), dict):
+                face = dict(device["face"])  # shallow clone
+
+            # Apply only the two fields (strings as per API examples)
+            face["detection_distance_min"] = "30"
+            face["detection_distance_max"] = str(max_cm)
+
+            payload = {"Device": {"face": face}}
+
+            # 3) PUT minimal update
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "device_id": device_id}
+                )
+
+            return self.success_response({
+                "message": "Updated face detection distance.",
+                "device_id": device_id,
+                "online": is_online,
+                "applied": {
+                    "detection_distance_min": 30,
+                    "detection_distance_max": max_cm
+                },
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    # -----------------------------
+    # Normalization + Mapping (ASCII-only), order-aware
+    # -----------------------------
+    def _normalize_and_canonicalize_auth_spec(self, spec: str) -> tuple[Optional[str], bool]:
+        """
+        Normalize a human auth spec into a canonical ASCII form and detect if it carried an order.
+        Returns (canonical_string, ordered_detected).
+        Canonical form uses:
+        - '+' for AND between steps
+        - '/' for OR within a step
+        - tokens: face, fingerprint, card, id, pin
+        Examples:
+        "card -> (face or fingerprint) -> pin"  -> "card+face/fingerprint+pin", ordered=True
+        "card++face+fingerprint"                -> "card+face+fingerprint",    ordered=True
+        "fingerprint + face / pin"              -> "face/pin+fingerprint",     ordered=False
+        """
+        if not spec:
+            return None, False
+
+        s_in = str(spec)
+        s = s_in.strip().lower()
+
+        # Detect order connectors
+        ordered_connectors = ["->", "→", "⇒", ">>", "≫", "then", "next"]
+        ordered_detected = any(tok in s for tok in ordered_connectors) or ("++" in s)
+
+        # Unify connectors
+        s = (s.replace("＋", "+")
+             .replace("／", "/")
+             .replace("→", "->")
+             .replace("⇒", "->")
+             .replace("≫", ">>"))
+
+        s = s.replace(" or ", "/")
+        s = s.replace("||", "/").replace("|", "/")
+        s = s.replace(" then ", "->").replace(" next ", "->")
+
+        # Collapse ordered connectors to '+'
+        for tok in ["->", ">>"]:
+            s = s.replace(tok, "+")
+        s = s.replace("++", "+")
+        s = s.replace(" ", "")
+
+        # Numeric-only short-circuit
+        if s.isdigit():
+            return s, ordered_detected
+
+        # Synonyms -> canonical tokens
+        synonyms = {
+            "facial": "face",
+            "faceid": "face",
+            "finger": "fingerprint",
+            "fp": "fingerprint",
+            "badge": "card",
+            "rfid": "card",
+            "uid": "id",
+            "userid": "id",
+            "passcode": "pin",
+            "password": "pin",
+        }
+        for k, v in synonyms.items():
+            s = s.replace(k, v)
+
+        # Remove parentheses (we keep OR within a step)
+        s = s.replace("(", "").replace(")", "")
+
+        TOKENS = {"face", "fingerprint", "card", "id", "pin"}
+        AND_ORDER = ["card", "id", "face", "fingerprint", "pin"]
+        OR_ORDER = ["face", "fingerprint", "pin"]
+
+        # Split into AND steps
+        raw_and_terms = [t for t in s.split("+") if t]
+        if not raw_and_terms:
+            return None, ordered_detected
+
+        def normalize_or_group(term: str) -> str:
+            parts = [p for p in term.split("/") if p]
+            if not parts:
+                return ""
+            if not all(p in TOKENS for p in parts):
+                return ""
+
+            # Canonical OR order
+            def or_key(x: str) -> int:
+                return OR_ORDER.index(x) if x in OR_ORDER else 99
+
+            parts_sorted = sorted(parts, key=or_key)
+            return "/".join(parts_sorted)
+
+        # Normalize each AND term (each may be an OR group)
+        norm_terms = []
+        for term in raw_and_terms:
+            norm = normalize_or_group(term)
+            if not norm:
+                return None, ordered_detected
+            norm_terms.append(norm)
+
+        # Canonical AND ordering by head token
+        def head_token(t: str) -> str:
+            return t.split("/")[0]
+
+        def and_key(t: str) -> int:
+            ht = head_token(t)
+            return AND_ORDER.index(ht) if ht in AND_ORDER else 99
+
+        norm_terms_sorted = sorted(norm_terms, key=and_key)
+        canonical = "+".join(norm_terms_sorted)
+        return canonical, ordered_detected
+
+    def _map_auth_spec_to_code(self, spec: str) -> tuple[Optional[int], bool]:
+        """
+        Map a (possibly ordered) human-readable auth spec to the extended mode code (11..49).
+        Returns (code, ordered_detected).
+        Canonicalization ensures that permutations like "card+fingerprint+face" map to the same
+        code as "card+face+fingerprint" (29).
+        """
+        canonical, ordered = self._normalize_and_canonicalize_auth_spec(spec)
+        if not canonical:
+            return None, ordered
+
+        # If canonical is numeric string (e.g., "29"), accept directly if valid
+        if canonical.isdigit():
+            val = int(canonical)
+            return (val if 11 <= val <= 49 else None), ordered
+
+        # Canonical dictionary: one key per semantic combination
+        MAP = {
+            # Face family
+            "face": 11,
+            "face+fingerprint": 12,
+            "face+pin": 13,
+            "face+fingerprint/pin": 14,
+            "face+fingerprint+pin": 15,
+
+            # Fingerprint family
+            "fingerprint": 16,
+            "fingerprint+face": 17,  # normalized order collapses to face+fingerprint
+            "fingerprint+pin": 18,
+            "fingerprint+face/pin": 19,
+            "fingerprint+face+pin": 20,  # fingerprint+face+pin -> face+fingerprint+pin
+
+            # Card family (use a single canonical triple-AND -> 29)
+            "card": 21,
+            "card+face": 22,
+            "card+fingerprint": 23,
+            "card+pin": 24,
+            "card+face/fingerprint": 25,
+            "card+face/pin": 26,
+            "card+fingerprint/pin": 27,
+            "card+face/fingerprint/pin": 28,
+            "card+face+fingerprint": 29,
+            "card+face+pin": 30,
+            "card+fingerprint+pin": 32,
+            "card+face/fingerprint+pin": 33,
+            "card+face+fingerprint/pin": 34,
+
+            # ID family
+            "id+face": 36,
+            "id+fingerprint": 37,
+            "id+pin": 38,
+            "id+face/fingerprint": 39,
+            "id+face/pin": 40,
+            "id+fingerprint/pin": 41,
+            "id+face/fingerprint/pin": 42,
+            "id+face+fingerprint": 43,
+            "id+face+pin": 44,
+            "id+fingerprint+pin": 46,
+            "id+face/fingerprint+pin": 47,
+            "id+face+fingerprint/pin": 48,
+        }
+
+        # Direct hit
+        if canonical in MAP:
+            # Enforce canonical triple-AND mapping: any "card+face+fingerprint" order -> 29
+            if canonical == "card+face+fingerprint":
+                return 29, ordered
+            if canonical == "id+face+fingerprint":
+                return 43, ordered
+            if canonical == "card+face+fingerprint/pin":
+                return 34, ordered
+            if canonical == "id+face+fingerprint/pin":
+                return 48, ordered
+            return MAP[canonical], ordered
+
+        # Common alias fallback (after canonicalization this is rarely needed)
+        aliases = {
+            "face+card": "card+face",
+            "fingerprint+card": "card+fingerprint",
+            "pin+card": "card+pin",
+            "face+id": "id+face",
+            "fingerprint+id": "id+fingerprint",
+            "pin+id": "id+pin",
+        }
+        if canonical in aliases and aliases[canonical] in MAP:
+            return MAP[aliases[canonical]], ordered
+
+        # Not mappable
+        return None, ordered
+
+    async def update_device_date_type(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update only display.date_type for a resolved device.
+        - Resolution: device_id straight-through, else device/door name via internal resolver.
+        - Accepts 'date_type' (0|1|2) or 'date_format' (YYYY/MM/DD | MM/DD/YYYY | DD/MM/YYYY).
+        - Sends a minimal PUT payload: {"Device":{"display":{"date_type":"<code>"}}}.
+        - Leaves all other fields untouched (server will only apply provided fields).
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # ---- Resolve target device id using the project's resolver ----
+            # (Supports: device_id, device_name, device_search_text, door_name, q + edge/prefer_entry)
+            device_id, early = await self._resolve_device_id_from_args(args, headers)
+            if device_id is None:
+                return early  # either needs_selection or error already formatted
+
+            # ---- Determine desired date_type code (string "0"/"1"/"2") ----
+            mapping = {
+                "YYYY/MM/DD": "0",
+                "MM/DD/YYYY": "1",
+                "DD/MM/YYYY": "2",
+            }
+
+            dt_raw = args.get("date_type")
+            df = args.get("date_format")
+
+            if df is not None:
+                df_str = str(df).strip().upper()
+                if df_str not in mapping:
+                    return self.error_response(
+                        "Invalid date_format. Use one of: YYYY/MM/DD, MM/DD/YYYY, DD/MM/YYYY."
+                    )
+                code = mapping[df_str]
+            else:
+                # dt_raw is required when date_format is not provided
+                dt_str = str(dt_raw).strip()
+                if dt_str not in ("0", "1", "2"):
+                    # Allow integers 0/1/2 as well
+                    try:
+                        if int(dt_str) not in (0, 1, 2):
+                            raise ValueError()
+                        dt_str = str(int(dt_str))
+                    except Exception:
+                        return self.error_response("Invalid date_type. Use 0|1|2.")
+                code = dt_str
+
+            # ---- Build minimal payload and PUT ----
+            payload = {"Device": {"display": {"date_type": code}}}
+
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{int(device_id)}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "device_id": int(device_id)}
+                )
+
+            # Optionally parse body for confirmation, but success on HTTP 200 is consistent with other handlers
+            return self.success_response({
+                "message": "display.date_type updated successfully",
+                "device_id": int(device_id),
+                "applied_date_type": code,
+                "applied_date_format": {"0": "YYYY/MM/DD", "1": "MM/DD/YYYY", "2": "DD/MM/YYYY"}[code],
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_device_timezone(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Steps:
+        1) Resolve target device (id/name or via door).
+        2) Resolve timezone offset seconds from args.
+        3) GET /api/devices/{id} to fetch current Device payload.
+        4) Merge Device.system.timezone only; PUT back the full payload.
+        """
+        self.check_auth()
+
+        headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+        device_id, early = await self._resolve_device_id_from_args(args, headers)
+        if device_id is None:
+            return early
+
+        # 2) Resolve timezone
+        offset, note = _lookup_tz_offset(args)
+        if offset is None:
+            return self.error_response(
+                f"Failed to resolve timezone. Hint: provide offset_seconds (int), "
+                f"or utc_offset like '+09:00', or tz_label such as '(UTC+9:00) Seoul/Tokyo' / 'Seoul' / 'PST'."
+            )
+
+        # 3) Fetch current device
+        headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+        async with httpx.AsyncClient(verify=False) as client:
+            get_resp = await client.get(f"{self.session.config.biostar_url}/api/devices/{device_id}", headers=headers)
+        if get_resp.status_code != 200:
+            return self.error_response(f"GET device failed: {get_resp.status_code} - {get_resp.text}")
+
+        dev_payload = get_resp.json()
+        if "Device" not in dev_payload:
+            return self.error_response("Malformed device payload from server (missing 'Device').")
+
+        # 4) Merge only timezone
+        dev_payload["Device"].setdefault("system", {})
+        before = dev_payload["Device"]["system"].get("timezone", None)
+        dev_payload["Device"]["system"]["timezone"] = offset
+
+        if args.get("dry_run"):
+            return {
+                "message": "Dry-run: computed timezone only.",
+                "device_id": device_id,
+                "resolved_offset_seconds": offset,
+                "resolution_note": note,
+                "before": before,
+                "after": offset
+            }
+
+        # 5) PUT back (full merged payload)
+        async with httpx.AsyncClient(verify=False) as client:
+            put_resp = await client.put(
+                f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                headers=headers,
+                json=dev_payload
+            )
+        if put_resp.status_code != 200:
+            return self.error_response(f"PUT device failed: {put_resp.status_code} - {put_resp.text}")
+
+        return {
+            "message": "Device timezone updated.",
+            "device_id": device_id,
+            "resolved_offset_seconds": offset,
+            "resolution_note": note,
+            "before": before,
+            "after": offset
+        }
+
+    async def factory_reset_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Factory-reset a device with preflight door linkage check.
+
+        Behavior:
+        - Resolve target device id via the existing resolver (id/name/door-based).
+        - Preflight: GET /api/doors and check if this device appears as entry/exit.
+          If linked, return a failure (do NOT call factory_reset API).
+        - If not linked:
+            POST /api/devices/factory_reset with:
+              {
+                "DeviceCollection":{"total":1,"rows":[{"id":"<id>"}]},
+                "isResetWithoutNetwork": <bool>
+              }
+        - Supports dry_run: when true, do not call POST; just report the outcome.
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # 1) Resolve device id using existing resolver
+            device_id, early = await self._resolve_device_id_from_args(args, headers)
+            if device_id is None:
+                return early  # already formatted error/needs_selection
+
+            # 2) Preflight: check door linkage
+            #    We fetch doors (client-side filter) to see if device_id is used.
+            linked_doors = []
+            async with httpx.AsyncClient(verify=False) as client:
+                # Note: If your project exposes a v2 search or filters by device,
+                # you can replace this with more selective queries.
+                doors_resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/doors",
+                    headers=headers
+                )
+
+            if doors_resp.status_code != 200:
+                return self.error_response(
+                    f"Failed to fetch doors: {doors_resp.status_code} - {doors_resp.text}"
+                )
+
+            try:
+                doors_json = doors_resp.json()
+            except Exception:
+                return self.error_response("Failed to parse doors response JSON")
+
+            rows = (doors_json or {}).get("DoorCollection", {}).get("rows", [])
+            dev_id_str = str(int(device_id))
+            for d in rows or []:
+                # Each door may have {"entry_device_id":{"id":"..."},"exit_device_id":{"id":"..."}}
+                entry_id = str(((d or {}).get("entry_device_id") or {}).get("id") or "")
+                exit_id = str(((d or {}).get("exit_device_id") or {}).get("id") or "")
+                if entry_id == dev_id_str or exit_id == dev_id_str:
+                    linked_doors.append({
+                        "door_id": str((d or {}).get("id") or ""),
+                        "door_name": (d or {}).get("name") or "",
+                        "edge": "entry" if entry_id == dev_id_str else "exit"
+                    })
+
+            if linked_doors:
+                # Spec requirement: if device is linked to a door, respond failure.
+                return self.error_response(
+                    "Factory reset blocked: device is linked to one or more doors.",
+                    {"device_id": int(device_id), "linked_doors": linked_doors}
+                )
+
+            # 3) Resolve options
+            dry_run = bool(args.get("dry_run") or False)
+            is_reset_wo_net = bool(args.get("is_reset_without_network") or False)
+
+            # 4) Build request body
+            payload = {
+                "DeviceCollection": {
+                    "total": 1,
+                    "rows": [{"id": dev_id_str}]
+                },
+                "isResetWithoutNetwork": is_reset_wo_net
+            }
+
+            if dry_run:
+                return self.success_response({
+                    "message": "[dry_run] factory reset would be invoked",
+                    "device_id": int(device_id),
+                    "payload": payload
+                })
+
+            # 5) POST factory_reset
+            async with httpx.AsyncClient(verify=False) as client:
+                reset_resp = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices/factory_reset",
+                    headers=headers,
+                    json=payload
+                )
+
+            if reset_resp.status_code != 200:
+                return self.error_response(
+                    f"Factory reset failed: {reset_resp.status_code} - {reset_resp.text}",
+                    {"request_body": payload, "device_id": int(device_id)}
+                )
+
+            # Try to parse a body if useful, but 200 OK is success by contract
+            body = None
+            try:
+                body = reset_resp.json()
+            except Exception:
+                body = {"raw": reset_resp.text}
+
+            return self.success_response({
+                "message": "Factory reset completed successfully",
+                "device_id": int(device_id),
+                "isResetWithoutNetwork": is_reset_wo_net,
+                "response": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_device_auth_and_display(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update five fields only (minimal payload PUT /api/devices/:id):
+          - authentication.auth_timeout (3–20)
+          - authentication.enable_server_matching
+          - authentication.enable_full_access
+          - display.display_userid_option
+          - display.display_username_option
+
+        Resolves device by id or name inside this method (no external helpers).
+        Coerces types to API's expected string booleans/numerics.
+        """
+        # ---------- -1) Auth check ----------
+        try:
+            if hasattr(self, "check_auth"):
+                self.check_auth()
+        except Exception as e:
+            return [TextContent(type="text", text=str({
+                "status": "error",
+                "error": f"Authentication required: {type(e).__name__}: {e}"
+            }))]
+
+        # ---------- 0) Basic validations ----------
+        device_id_raw = args.get("device_id")
+        device_name = (args.get("device_name") or "").strip()
+        if device_id_raw is None and not device_name:
+            return [
+                TextContent(type="text", text=str({"status": "error", "error": "Missing device_id or device_name"}))]
+
+        # ---------- 1) Resolve device id ----------
+        device_id: Optional[int] = None
+        if device_id_raw is not None:
+            try:
+                device_id = int(device_id_raw)
+            except Exception:
+                return [TextContent(type="text", text=str({"status": "error", "error": "Invalid device_id"}))]
+        else:
+            try:
+                headers: Dict[str, str] = {"Content-Type": "application/json"}
+                if hasattr(self, "_auth_headers"):
+                    try:
+                        ah = self._auth_headers() or {}
+                        if isinstance(ah, dict):
+                            headers.update(ah)
+                    except Exception:
+                        pass
+                else:
+                    if hasattr(self, "get_session_id"):
+                        sid = self.get_session_id()
+                        if sid:
+                            headers["bs-session-id"] = sid
+                    if hasattr(self, "headers") and isinstance(self.headers, dict):
+                        headers.update(self.headers)
+
+                payload_search = {"name_contains": device_name, "limit": 5}
+                async with httpx.AsyncClient(base_url=self.session.config.biostar_url, verify=False,
+                                             timeout=30.0) as client:
+                    r = await client.post("/api/v2/devices/search", json=payload_search, headers=headers)
+                    r.raise_for_status()
+                    j = r.json()
+
+                rows = j.get("DeviceCollection", {}).get("rows", []) if isinstance(j, dict) else []
+                exact = [row for row in rows if str(row.get("name", "")).strip() == device_name]
+                take = exact[0] if exact else (rows[0] if rows else None)
+                if not take or "id" not in take:
+                    return [TextContent(type="text", text=str(
+                        {"status": "error", "error": "Device not found by name", "name": device_name}))]
+                device_id = int(take["id"])
+            except Exception as e:
+                logger.exception("device search failed")
+                return [TextContent(type="text", text=str(
+                    {"status": "error", "error": "Device search failed", "details": f"{type(e).__name__}: {e}"}))]
+
+        # ---------- 2) Build minimal payload ----------
+        as_bool_str = lambda b: "true" if bool(b) else "false"
+
+        def normalize_display_opt(v) -> Optional[str]:
+            if v is None:
+                return None
+            if isinstance(v, str):
+                m = {"all": "0", "first": "1", "none": "2"}
+                if v.lower() in m:
+                    return m[v.lower()]
+                if v in {"0", "1", "2"}:
+                    return v
+                return None
+            if isinstance(v, int) and v in (0, 1, 2):
+                return str(v)
+            return None
+
+        def normalize_auth_timeout(v) -> Optional[str]:
+            """Accept only 3..20; return None if invalid (so we can raise a clear error)."""
+            if v is None:
+                return None
+            try:
+                iv = int(v)
+            except Exception:
+                return None
+            if iv < 3 or iv > 20:
+                return None
+            return str(iv)
+
+        auth_timeout = args.get("auth_timeout")
+        norm_auth_timeout = normalize_auth_timeout(auth_timeout)
+        if auth_timeout is not None and norm_auth_timeout is None:
+            return [TextContent(type="text", text=str({
+                "status": "error",
+                "error": "auth_timeout must be between 3 and 20 seconds"
+            }))]
+
+        enable_server_matching = args.get("enable_server_matching")
+        enable_full_access = args.get("enable_full_access")
+        display_userid_option = normalize_display_opt(args.get("display_userid_option"))
+        display_username_option = normalize_display_opt(args.get("display_username_option"))
+
+        authentication: Dict[str, Any] = {}
+        display: Dict[str, Any] = {}
+
+        if norm_auth_timeout is not None:
+            authentication["auth_timeout"] = norm_auth_timeout
+        if enable_server_matching is not None:
+            authentication["enable_server_matching"] = as_bool_str(enable_server_matching)
+        if enable_full_access is not None:
+            authentication["enable_full_access"] = as_bool_str(enable_full_access)
+
+        if display_userid_option is not None:
+            display["display_userid_option"] = display_userid_option
+        if display_username_option is not None:
+            display["display_username_option"] = display_username_option
+
+        device_payload: Dict[str, Any] = {}
+        if authentication:
+            device_payload["authentication"] = authentication
+        if display:
+            device_payload["display"] = display
+
+        if not device_payload:
+            return [TextContent(type="text", text=str({"status": "error", "error": "No updatable fields provided"}))]
+
+        final_payload = {"Device": device_payload}
+
+        # ---------- 3) Dry-run ----------
+        if args.get("dry_run") is True:
+            return [TextContent(type="text", text=str({
+                "status": "dry-run", "device_id": device_id, "payload": final_payload
+            }))]
+
+        # ---------- 4) PUT /api/devices/:id ----------
+        try:
+            headers: Dict[str, str] = {"Content-Type": "application/json"}
+            if hasattr(self, "_auth_headers"):
+                try:
+                    ah = self._auth_headers() or {}
+                    if isinstance(ah, dict):
+                        headers.update(ah)
+                except Exception:
+                    pass
+            else:
+                if hasattr(self, "get_session_id"):
+                    sid = self.get_session_id()
+                    if sid:
+                        headers["bs-session-id"] = sid
+                if hasattr(self, "headers") and isinstance(self.headers, dict):
+                    headers.update(self.headers)
+
+            async with httpx.AsyncClient(base_url=self.session.config.biostar_url, verify=False,
+                                         timeout=30.0) as client:
+                resp = await client.put(f"/api/devices/{device_id}", json=final_payload, headers=headers)
+                if resp.status_code >= 400:
+                    try:
+                        j = resp.json()
+                    except Exception:
+                        j = {"raw_text": resp.text}
+                    return [TextContent(type="text", text=str({
+                        "status": "error", "http_status": resp.status_code,
+                        "request_payload": final_payload, "response": j
+                    }))]
+
+                try:
+                    body: Any = resp.json()
+                except Exception:
+                    body = {"raw_text": resp.text or ""}
+
+                return [TextContent(type="text", text=str({
+                    "status": "success", "device_id": device_id,
+                    "request_payload": final_payload, "response": body
+                }))]
+
+        except Exception as e:
+            logger.exception("PUT /api/devices/:id failed")
+            return [TextContent(type="text", text=str({
+                "status": "error", "error": f"{type(e).__name__}: {e}",
+                "device_id": device_id, "request_payload": final_payload
+            }))]
+
+    async def update_device_network(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update device network (TCP/IP) settings only, mapped from the UI:
+        - DHCP toggle (enable_dhcp)
+        - IP address, subnet mask, gateway, DNS server (used only when DHCP=false)
+        - Device port
+
+        Behavior:
+        - Fetch current device -> merge "Device.lan" only -> PUT back minimal payload.
+        - When dhcp_enabled=true: static fields (ip/subnet/gateway/dns) are ignored.
+        - When dhcp_enabled=false: ip_address and subnet_mask are required; gateway/dns optional.
+        - String booleans ("true"/"false") are used to match API conventions.
+
+        Input:
+        - Resolve target with the existing resolver:
+          device_id | device_name | device_search_text | door_id | door_name (+ edge)
+        - Fields:
+          dhcp_enabled: bool (required)
+          ip_address: str (IPv4)          # used only if dhcp_enabled=false
+          subnet_mask: str (IPv4)         # used only if dhcp_enabled=false
+          gateway: str (IPv4, optional)   # used only if dhcp_enabled=false
+          dns_server: str (IPv4, optional)# used only if dhcp_enabled=false
+          device_port: int (optional)
+
+        Returns: success_response/error_response with applied fields echo.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ---- 1) Resolve target device id ----
+            device_id, early = await self._resolve_device_id_from_args(args, headers)
+            if device_id is None:
+                return early
+
+            # ---- 2) Validate/normalize inputs ----
+            def as_bool_str(b: bool) -> str:
+                return "true" if bool(b) else "false"
+
+            def is_ipv4(s: str) -> bool:
+                try:
+                    parts = [int(p) for p in str(s).split(".")]
+                    return len(parts) == 4 and all(0 <= x <= 255 for x in parts)
+                except Exception:
+                    return False
+
+            if "dhcp_enabled" not in args:
+                return self.error_response("Missing required field: dhcp_enabled")
+
+            dhcp_enabled = bool(args.get("dhcp_enabled"))
+
+            ip_address = args.get("ip_address")
+            subnet_mask = args.get("subnet_mask")
+            gateway = args.get("gateway")
+            dns_server = args.get("dns_server")
+            device_port = args.get("device_port")
+
+            if not dhcp_enabled:
+                # When static addressing, ip and mask are mandatory
+                if not ip_address or not subnet_mask:
+                    return self.error_response("When dhcp_enabled=false, 'ip_address' and 'subnet_mask' are required.")
+                for label, val in (("ip_address", ip_address), ("subnet_mask", subnet_mask)):
+                    if not is_ipv4(val):
+                        return self.error_response(f"Invalid IPv4 value for {label}.")
+                # gateway/dns are optional but validate if provided
+                for label, val in (("gateway", gateway), ("dns_server", dns_server)):
+                    if val is not None and not is_ipv4(val):
+                        return self.error_response(f"Invalid IPv4 value for {label}.")
+
+            if device_port is not None:
+                try:
+                    device_port = int(device_port)
+                    if device_port <= 0 or device_port > 65535:
+                        raise ValueError()
+                except Exception:
+                    return self.error_response("device_port must be a valid integer (1..65535).")
+
+            # ---- 3) GET current device ----
+            async with httpx.AsyncClient(verify=False) as client:
+                get_resp = await client.get(f"{self.session.config.biostar_url}/api/devices/{int(device_id)}",
+                                            headers=headers)
+            if get_resp.status_code != 200:
+                return self.error_response(f"GET device failed: {get_resp.status_code} - {get_resp.text}")
+
+            body = get_resp.json() or {}
+            dev = body.get("Device") or {}
+            lan = dict(dev.get("lan") or {})
+
+            # ---- 4) Merge only LAN fields (keep other keys intact) ----
+            # alias helper to write into existing/expected keys
+            def assign_with_alias(d: Dict[str, Any], value: Any, aliases: List[str]) -> None:
+                """
+                Write value into the first key that already exists in d; otherwise use the first alias.
+                """
+                key = None
+                for k in aliases:
+                    if k in d:
+                        key = k
+                        break
+                if key is None:
+                    key = aliases[0]
+                d[key] = value
+
+            # DHCP toggle
+            assign_with_alias(lan, as_bool_str(dhcp_enabled), ["enable_dhcp", "dhcp", "use_dhcp"])
+
+            applied: Dict[str, Any] = {"dhcp_enabled": dhcp_enabled}
+
+            # Static fields only when DHCP is disabled
+            if not dhcp_enabled:
+                assign_with_alias(lan, ip_address, ["ip", "ip_addr", "ip_address"])
+                assign_with_alias(lan, subnet_mask, ["subnet_mask", "netmask", "subnet"])
+                if gateway is not None:
+                    assign_with_alias(lan, gateway, ["gateway", "gw", "router"])
+                    applied["gateway"] = gateway
+                if dns_server is not None:
+                    assign_with_alias(lan, dns_server, ["dns_server", "dns", "primary_dns", "dns1"])
+                    applied["dns_server"] = dns_server
+                applied["ip_address"] = ip_address
+                applied["subnet_mask"] = subnet_mask
+
+            # Device port (optional)
+            if device_port is not None:
+                assign_with_alias(lan, str(device_port), ["device_port", "port"])
+                applied["device_port"] = device_port
+
+            payload = {"Device": {"lan": lan}}
+
+            # ---- 5) PUT minimal payload ----
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{int(device_id)}",
+                    headers=headers,
+                    json=payload
+                )
+
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "device_id": int(device_id)}
+                )
+
+            # ---- 6) Done ----
+            return self.success_response({
+                "message": "Network (TCP/IP) updated successfully.",
+                "device_id": int(device_id),
+                "applied": applied,
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_device_serial_comm(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update RS-485 serial communication settings while preserving all other device fields.
+        - API: GET /api/devices/{id}  -> take baseline (UI-like payload)
+               PUT /api/devices/{id} with merged body (only RS-485 + showosdpresult changed)
+        - Input:
+            device_id?: int
+            device_name?: str (exact or contains; resolves to unique device)
+            rs485_mode?: "master"|"slave"|"default" or 1|2|3
+            baud_rate?: 9600|19200|38400|57600|115200  (int or str)
+            show_osdp_result?: "controller"|"device" or 0|1  (0=show controller result, 1=show device result)
+            dry_run?: bool
+        - Behavior:
+            * Preserves every field from GET payload and applies only requested changes.
+            * Validates OSDP result option is applicable (mode != master) when possible.
+            * Returns a concise preview when dry_run=True.
+        """
+        try:
+            # ---------- 0) auth ----------
+            self.check_auth()
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            # ---------- 1) tiny inline helpers (method-local; no external deps) ----------
+            def _norm_mode(v) -> Optional[int]:
+                """Map input to RS-485 mode code: master=1, slave=2, default=3."""
+                if v is None:
+                    return None
+                if isinstance(v, (int, float)) and int(v) in (1, 2, 3):
+                    return int(v)
+                s = str(v).strip().lower()
+                if s in ("master",):
+                    return 1
+                if s in ("slave",):
+                    return 2
+                if s in ("default", "device_default", "auto", "장치 기본값"):
+                    return 3
+                return None
+
+            def _norm_baud(v) -> Optional[int]:
+                """Allow only supported baud rates."""
+                if v is None:
+                    return None
+                try:
+                    b = int(str(v))
+                except Exception:
+                    return None
+                return b if b in (9600, 19200, 38400, 57600, 115200) else None
+
+            def _norm_show(v) -> Optional[int]:
+                """Map to 0(controller) or 1(device)."""
+                if v is None:
+                    return None
+                if isinstance(v, (int, float)) and int(v) in (0, 1):
+                    return int(v)
+                s = str(v).strip().lower()
+                if s in ("controller", "0"):
+                    return 0
+                if s in ("device", "1"):
+                    return 1
+                return None
+
+            async def _http_with_retry(method: str, url: str, **kwargs) -> httpx.Response:
+                last_exc = None
+                for attempt in range(3):
+                    try:
+                        async with httpx.AsyncClient(
+                                verify=False,
+                                timeout=httpx.Timeout(10.0, read=20.0)
+                        ) as client:
+                            resp = await client.request(method, url, **kwargs)
+                        if resp.status_code >= 500:
+                            await asyncio.sleep(0.6 * (attempt + 1))
+                            continue
+                        return resp
+                    except Exception as e:
+                        last_exc = e
+                        await asyncio.sleep(0.6 * (attempt + 1))
+                raise RuntimeError(f"HTTP temporary failure: {repr(last_exc)}")
+
+            # ---------- 2) resolve target device (id > name) ----------
+            device_id = None
+            if args.get("device_id") is not None:
+                try:
+                    device_id = int(args["device_id"])
+                except Exception:
+                    return self.error_response("Invalid 'device_id'.")
+            elif args.get("device_name"):
+                # list all -> exact/contains (case-insensitive) -> must be unique
+                resp = await _http_with_retry(
+                    "GET",
+                    f"{self.session.config.biostar_url}/api/devices",
+                    headers=headers,
+                    params={"limit": "0", "order_by": "id:true"}
+                )
+                if resp.status_code != 200:
+                    return self.error_response(f"Failed to list devices: {resp.status_code} - {resp.text}")
+                rows = ((resp.json().get("DeviceCollection") or {}).get("rows") or [])
+                q = str(args["device_name"]).strip().casefold()
+                hits = []
+                for r in rows:
+                    nm = str(r.get("name") or "").casefold()
+                    if nm == q or q in nm:
+                        try:
+                            hits.append({"id": int(r.get("id")), "name": r.get("name")})
+                        except Exception:
+                            pass
+                if not hits:
+                    return self.error_response("Device with given name not found.", {"query": args["device_name"]})
+                if len(hits) > 1:
+                    return self.error_response("Multiple devices matched. Please specify 'device_id'.",
+                                               {"candidates": hits})
+                device_id = hits[0]["id"]
+            else:
+                return self.error_response("Either 'device_id' or 'device_name' is required.")
+
+            # ---------- 3) normalize inputs ----------
+            mode_code = _norm_mode(args.get("rs485_mode"))
+            baud = _norm_baud(args.get("baud_rate"))
+            show_val = _norm_show(args.get("show_osdp_result"))
+
+            if args.get("rs485_mode") is not None and mode_code is None:
+                return self.error_response("Invalid 'rs485_mode'. Use master|slave|default or 1|2|3.")
+            if args.get("baud_rate") is not None and baud is None:
+                return self.error_response("Invalid 'baud_rate'. Use one of 9600,19200,38400,57600,115200.")
+            if args.get("show_osdp_result") is not None and show_val is None:
+                return self.error_response("Invalid 'show_osdp_result'. Use controller|device or 0|1.")
+
+            # ---------- 4) GET current device (baseline to preserve) ----------
+            get_r = await _http_with_retry(
+                "GET",
+                f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                headers=headers
+            )
+            if get_r.status_code != 200:
+                return self.error_response(f"Failed to get device: {get_r.status_code} - {get_r.text}")
+            raw = get_r.json() or {}
+            base = (raw.get("Device") or raw)  # accept either shape
+
+            # Make sure rs485 structure exists (non-destructive)
+            if "rs485" not in base or not isinstance(base.get("rs485"), dict):
+                base["rs485"] = {}
+            if "channels" not in base["rs485"] or not isinstance(base["rs485"].get("channels"), list):
+                base["rs485"]["channels"] = [{}]
+            if not base["rs485"]["channels"]:
+                base["rs485"]["channels"].append({})
+
+            # Current mode (for validation of show_osdp_result)
+            current_mode = None
+            try:
+                current_mode = int(str((base.get("rs485") or {}).get("mode")))
+            except Exception:
+                current_mode = None
+            final_mode = mode_code if mode_code is not None else current_mode
+
+            # ---------- 5) Apply requested changes only ----------
+            changed_fields = []
+
+            if mode_code is not None:
+                base["rs485"]["mode"] = mode_code
+                changed_fields.append("rs485.mode")
+
+            if baud is not None:
+                base["rs485"]["channels"][0]["baudrate"] = baud
+                changed_fields.append("rs485.channels[0].baudrate")
+
+            if show_val is not None:
+                # Optional applicability check: show result only when slave/auto(default)
+                # If we know the resulting mode and it's master(1), block; otherwise allow.
+                if final_mode == 1:
+                    return self.error_response(
+                        "show_osdp_result is not applicable when RS-485 mode is 'master'. Change mode first or omit this field."
+                    )
+                # Write to whichever key exists; default to 'showosdpresult'
+                if "showosdpresult" in base or "show_osdp_result" not in base:
+                    base["showosdpresult"] = show_val
+                if "show_osdp_result" in base:
+                    base["show_osdp_result"] = show_val
+                changed_fields.append("showosdpresult")
+
+            if not changed_fields:
+                return self.error_response(
+                    "Nothing to update. Provide at least one of rs485_mode, baud_rate, show_osdp_result.")
+
+            body = {"Device": base}
+
+            # ---------- 6) dry-run preview ----------
+            if bool(args.get("dry_run", False)):
+                return self.success_response({
+                    "message": "Dry-run preview. No update performed.",
+                    "device_id": device_id,
+                    "changed_fields": changed_fields,
+                    "payload_preview": body
+                })
+
+            # ---------- 7) PUT update ----------
+            put_r = await _http_with_retry(
+                "PUT",
+                f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                headers=headers,
+                json=body
+            )
+            if put_r.status_code not in (200, 204):
+                return self.error_response(
+                    f"API call failed: {put_r.status_code} - {put_r.text}",
+                    {"request_body": body}
+                )
+
+            return self.success_response({
+                "message": "RS-485 serial settings updated.",
+                "device_id": device_id,
+                "changed_fields": changed_fields,
+                "request_body": body
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_device_server_comm(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update only 'Server Communication' related settings while preserving all other device fields.
+
+        Flow:
+          1) Resolve target device (id/name/door) using the project's resolver.
+          2) GET /api/devices/{id} to obtain the baseline payload.
+          3) Merge only these fields:
+             - connect_from_device -> Device.lan.connection_mode (or aliases)
+             - server_address      -> lan.server_ip/server_address or Device.server.{ip/address}/server_connected.ip_addr
+             - server_port         -> lan.server_port or Device.server.port
+          4) PUT /api/devices/{id} with {"Device": <merged>} (minimal change).
+        All messages, comments, and return payloads are in English by request.
+        """
+        try:
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # ---- 1) Resolve target device ----
+            device_id, early = await self._resolve_device_id_from_args(args, headers)
+            if device_id is None:
+                return early
+
+            # ---- 2) Validate inputs ----
+            if not any(k in args for k in ("connect_from_device", "server_address", "server_port")):
+                return self.error_response(
+                    "No updatable fields provided (connect_from_device/server_address/server_port).")
+
+            server_addr = args.get("server_address")
+            if server_addr is not None:
+                if not isinstance(server_addr, str) or not server_addr.strip():
+                    return self.error_response("server_address must be a non-empty string.")
+                server_addr = server_addr.strip()
+
+            server_port = args.get("server_port")
+            if server_port is not None:
+                try:
+                    server_port = int(server_port)
+                    if not (1 <= server_port <= 65535):
+                        raise ValueError()
+                except Exception:
+                    return self.error_response("server_port must be an integer between 1 and 65535.")
+
+            connect_from_device = args.get("connect_from_device")
+            if connect_from_device is not None:
+                connect_from_device = bool(connect_from_device)
+
+            # ---- 3) GET current device ----
+            async with httpx.AsyncClient(verify=False) as client:
+                get_resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices/{int(device_id)}",
+                    headers=headers
+                )
+            if get_resp.status_code != 200:
+                return self.error_response(f"GET device failed: {get_resp.status_code} - {get_resp.text}")
+
+            base_json = get_resp.json() or {}
+            device_obj = base_json.get("Device") or {}
+
+            # ---- 4) Small helpers for safe merge ----
+            def assign_with_alias(d: Dict[str, Any], value: Any, aliases: List[str]) -> None:
+                """Write into the first existing key in d; otherwise use the first alias."""
+                key = None
+                for k in aliases:
+                    if k in d:
+                        key = k
+                        break
+                if key is None:
+                    key = aliases[0]
+                d[key] = value
+
+            # Copy blocks to avoid mutating references unexpectedly
+            lan = dict(device_obj.get("lan") or {})
+            server_block = dict(device_obj.get("server") or {})
+            server_connected = dict(device_obj.get("server_connected") or {})
+
+            applied: Dict[str, Any] = {}
+
+            # ---- 5) connect_from_device -> connection_mode (preserve existing representation) ----
+            if connect_from_device is not None:
+                existing = lan.get("connection_mode")
+
+                def to_same_type(flag: bool, exemplar) -> Any:
+                    """If exemplar looks numeric -> 0/1; if string -> 'device_to_server'/'server_to_device'."""
+                    if isinstance(exemplar, (int, float)) or (isinstance(exemplar, str) and exemplar.isdigit()):
+                        return 1 if flag else 0
+                    if isinstance(exemplar, str):
+                        return "device_to_server" if flag else "server_to_device"
+                    return "device_to_server" if flag else "server_to_device"
+
+                new_mode = to_same_type(connect_from_device, existing)
+                assign_with_alias(lan, new_mode, ["connection_mode", "conn_mode", "mode", "connectionType"])
+                applied["connect_from_device"] = connect_from_device
+
+            # ---- 6) server address / port mapping (write to multiple likely shapes) ----
+            if server_addr is not None:
+                assign_with_alias(lan, server_addr, ["server_ip", "server_address", "server_host"])
+                assign_with_alias(server_block, server_addr, ["ip", "address", "ip_addr", "host"])
+                assign_with_alias(server_connected, server_addr, ["ip_addr", "ip"])
+                applied["server_address"] = server_addr
+
+            if server_port is not None:
+                assign_with_alias(lan, str(server_port), ["server_port", "port_to_server"])
+                assign_with_alias(server_block, str(server_port), ["port", "server_port"])
+                assign_with_alias(server_connected, str(server_port), ["port"])
+                applied["server_port"] = server_port
+
+            # Merge back
+            out_dev = dict(device_obj)
+            if lan:
+                out_dev["lan"] = lan
+            if server_block:
+                out_dev["server"] = server_block
+            if server_connected:
+                out_dev["server_connected"] = server_connected
+
+            payload = {"Device": out_dev}
+
+            # ---- 7) dry-run ----
+            if bool(args.get("dry_run", False)):
+                return self.success_response({
+                    "message": "Dry-run preview. No update performed.",
+                    "device_id": int(device_id),
+                    "applied": applied,
+                    "payload_preview": payload
+                })
+
+            # ---- 8) PUT ----
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{int(device_id)}",
+                    headers=headers,
+                    json=payload
+                )
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"API call failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": payload, "device_id": int(device_id)}
+                )
+
+            return self.success_response({
+                "message": "Server communication settings updated.",
+                "device_id": int(device_id),
+                "applied": applied,
+                "request_body": payload
+            })
+
+        except Exception as e:
+            return await self.handle_api_error(e)
+
+    async def update_device_fingerprint(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update fingerprint settings only (and authentication.matching_timeout) using a minimal merged payload.
+        API flow:
+          1) Resolve target device id from args
+          2) GET /api/devices/{id} to fetch baseline
+          3) Merge only provided fields into {"Device":{"fingerprint":{...}, "authentication":{"matching_timeout":...}}}
+          4) PUT /api/devices/{id}
+        All comments, messages, and returned strings are in English.
+        """
+        try:
+            import re  # local import to ensure availability
+
+            # --- 0) auth / headers ---
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # --- 1) resolve device id ---
+            device_id, early = await self._resolve_device_id_from_args(args, headers)
+            if device_id is None:
+                return early
+
+            # --- 2) helpers / normalizers (EN-only labels) ---
+            def _norm_str(v: Any) -> str:
+                # unify underscores to spaces, squeeze spaces, lowercase
+                return " ".join(str(v).replace("_", " ").split()).strip().lower()
+
+            def _norm_token(v: Any) -> str:
+                s = str(v).strip().lower()
+                s = re.sub(r'[_\-]+', ' ', s)   # underscores/hyphens -> spaces
+                s = re.sub(r'\s+', ' ', s)      # collapse spaces
+                return s
+
+            def _bool_str(v: Any) -> Optional[str]:
+                # return "true"/"false" (server accepts these as strings)
+                if v is None:
+                    return None
+                if isinstance(v, bool):
+                    return "true" if v else "false"
+                s = _norm_str(v)
+                if s in {"true", "1", "yes", "y", "on", "enable", "enabled"}:
+                    return "true"
+                if s in {"false", "0", "no", "n", "off", "disable", "disabled"}:
+                    return "false"
+                return None
+
+            def _int_in_range(v: Any, lo: int, hi: int) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                except Exception:
+                    return None
+                return iv if lo <= iv <= hi else None
+
+            # 1:N Security Level: 0=Normal,1=Secure,2=Most Secure
+            def _security(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1, 2):
+                        return iv
+                except Exception:
+                    pass
+                s = _norm_str(v)
+                m = {"normal": 0, "secure": 1, "most secure": 2, "mostsecure": 2, "highest": 2}
+                return m.get(s)
+
+            # Fast Mode: 0=Auto,1=Normal,2=Fast,3=Fastest
+            def _fast(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1, 2, 3):
+                        return iv
+                except Exception:
+                    pass
+                s = _norm_str(v)
+                m = {"auto": 0, "normal": 1, "fast": 2, "fastest": 3}
+                return m.get(s)
+
+            # Sensor Mode (F2 actual behavior): 0=Always On, 1=Auto On  ← NOTE: reversed from our initial assumption
+            def _sensor_mode(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                # accept ints and numeric strings
+                try:
+                    iv = int(str(v).strip())
+                    if iv in (0, 1):
+                        return iv
+                except Exception:
+                    pass
+                s = _norm_token(v)
+                # accept common spellings
+                m = {
+                    "always on": 0, "always": 0, "always_on": 0, "always-on": 0,
+                    "auto on":   1, "auto":   1, "auto_on":   1, "auto-on":   1,
+                }
+                return m.get(s)
+
+            # LFD: 0=Off,1=Normal,2=Strong,3=Very Strong
+            def _lfd(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1, 2, 3):
+                        return iv
+                except Exception:
+                    pass
+                s = _norm_str(v)
+                m = {"off": 0, "normal": 1, "strong": 2, "very strong": 3, "verystrong": 3}
+                return m.get(s)
+
+            # --- 3) normalize requested values ---
+            f_security  = _security(args.get("security_level"))
+            f_fast      = _fast(args.get("fast_mode"))
+            f_sense     = _int_in_range(args.get("sensitivity"), 1, 7)
+            f_scan      = _int_in_range(args.get("scan_wait_time"), 1, 20)
+            f_show_img  = _bool_str(args.get("show_image"))
+            f_sensor    = _sensor_mode(args.get("sensor_mode"))
+            f_adv_enr   = _bool_str(args.get("advanced_enrollment"))
+            f_lfd       = _lfd(args.get("lfd_level"))
+            f_dup       = _bool_str(args.get("duplicate_check"))
+            a_match     = _int_in_range(args.get("matching_wait_time"), 1, 20)
+
+            invalids = []
+            def _chk(name: str, val: Any, raw: Any):
+                if raw is None:
+                    return
+                if val is None:
+                    invalids.append(name)
+
+            _chk("security_level", f_security, args.get("security_level"))
+            _chk("fast_mode", f_fast, args.get("fast_mode"))
+            _chk("sensitivity", f_sense, args.get("sensitivity"))
+            _chk("scan_wait_time", f_scan, args.get("scan_wait_time"))
+            _chk("show_image", f_show_img, args.get("show_image"))
+            _chk("sensor_mode", f_sensor, args.get("sensor_mode"))
+            _chk("advanced_enrollment", f_adv_enr, args.get("advanced_enrollment"))
+            _chk("lfd_level", f_lfd, args.get("lfd_level"))
+            _chk("duplicate_check", f_dup, args.get("duplicate_check"))
+            _chk("matching_wait_time", a_match, args.get("matching_wait_time"))
+
+            if invalids:
+                return self.error_response(f"Invalid values for: {', '.join(invalids)}")
+
+            if all(v is None for v in (f_security, f_fast, f_sense, f_scan, f_show_img, f_sensor, f_adv_enr, f_lfd, f_dup, a_match)):
+                return self.error_response("No fingerprint fields provided.")
+
+            # --- 4) GET baseline ---
+            async def _req(method: str, url: str, **kwargs):
+                last_exc = None
+                for attempt in range(3):
+                    try:
+                        async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                            resp = await client.request(method, url, **kwargs)
+                        if resp.status_code >= 500:
+                            await asyncio.sleep(0.4 * (attempt + 1))
+                            continue
+                        return resp
+                    except Exception as e:
+                        last_exc = e
+                        await asyncio.sleep(0.4 * (attempt + 1))
+                raise last_exc or RuntimeError("HTTP request failed")
+
+            base_url = self.session.config.biostar_url.rstrip("/")
+            get_resp = await _req("GET", f"{base_url}/api/devices/{device_id}", headers=headers)
+            if get_resp.status_code != 200:
+                return self.error_response(f"GET /api/devices/{device_id} failed: {get_resp.status_code} {get_resp.text}")
+
+            try:
+                device_cur = get_resp.json().get("Device", {})
+            except Exception:
+                return self.error_response("Malformed JSON from GET /api/devices/{id}.")
+
+            # --- 5) merge minimal changes ---
+            # NOTE: Keep existing fingerprint block but override only provided fields.
+            fp: Dict[str, Any] = dict(device_cur.get("fingerprint") or {})
+            # keep string numerics for consistency with UI payloads
+            if f_security is not None:         fp["security_level"]      = str(f_security)
+            if f_fast is not None:             fp["fast_mode"]           = str(f_fast)
+            if f_sense is not None:            fp["sensitivity"]         = str(int(f_sense))
+            if f_scan is not None:             fp["scan_timeout"]        = str(int(f_scan))
+            if f_show_img is not None:         fp["show_image"]          = f_show_img  # "true"/"false"
+            if f_sensor is not None:           fp["sensor_mode"]         = str(f_sensor)  # << 0=Always On, 1=Auto On
+            if f_adv_enr is not None:          fp["advanced_enrollment"] = f_adv_enr
+            if f_lfd is not None:              fp["lfd_level"]           = str(int(f_lfd))
+            if f_dup is not None:              fp["duplicate_check"]     = f_dup
+
+            payload: Dict[str, Any] = {"Device": {"fingerprint": fp}}
+            if a_match is not None:
+                auth = dict(device_cur.get("authentication") or {})
+                auth["matching_timeout"] = str(int(a_match))
+                payload["Device"]["authentication"] = auth
+
+            # --- 6) dry-run preview ---
+            if bool(args.get("dry_run")):
+                return [TextContent(type="text", text=str({
+                    "status": "dry-run",
+                    "device_id": device_id,
+                    "request_payload": payload
+                }))]
+
+            # --- 7) PUT update ---
+            put_resp = await _req("PUT", f"{base_url}/api/devices/{device_id}", headers=headers, json=payload)
+            try:
+                body = put_resp.json()
+            except Exception:
+                body = {"raw_text": put_resp.text}
+
+            if put_resp.status_code >= 400:
+                return [TextContent(type="text", text=str({
+                    "status": "error",
+                    "http_status": put_resp.status_code,
+                    "request_payload": payload,
+                    "response": body
+                }))]
+
+            return [TextContent(type="text", text=str({
+                "status": "success",
+                "device_id": device_id,
+                "request_payload": payload,
+                "response": body
+            }))]
+
+        except Exception as e:
+            logger.exception("update_device_fingerprint failed")
+            return self.error_response(f"Exception: {type(e).__name__}: {e}")
+
+    async def update_device_face(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Update face settings only using a minimal merged payload, with a dedicated
+        device-id resolver that NEVER PUTs using device_name. It will:
+          1) Use device_id directly if present
+          2) Else, search devices by device_name or device_search_text via GET /api/devices
+             and bind the resolved id
+          3) Else, if door_id/door_name is provided, fall back to the generic resolver
+        Keys supported (English-only):
+          - security_level: 0=Normal,1=Secure,2=Most Secure                     -> face.security_level
+          - motion_sensor (alias: sensitivity): 0=Off,1=Low,2=Medium,3=High      -> face.sensitivity
+          - lfd_level: 0=Normal,1=Secure,2=More Secure,3=Most Secure            -> face.lfd_level
+          - enroll_timeout: 10..20 (step 1)                                      -> face.scan_wait_time
+          - max_rotation: one of {15,30,45,60,75,90}                             -> face.max_rotation
+          - detect_distance_min: {30..130 step10}                                -> face.detection_distance_min
+          - detect_distance_max: {30..130 step10} or 255 ('over_130', ...)       -> face.detection_distance_max
+          - operation_mode: 0/1 or "normal"/"fusion"                             -> face.operation_mode
+          - wide_search (bool)                                                   -> face.face_wide_search
+          - fast_enroll (bool)                                                   -> face.quick_enrollment
+          - save_image (bool)                                                    -> face.store_visual_face_image
+          - duplicate_check (bool)                                               -> face.duplicate_check
+          - light_brightness (aliases: light_condition, light)
+                "normal"→0, "high"→1, "off"/"not use"→3                          -> face.proximity_level
+        Returns dry-run preview if args['dry_run'] is truthy.
+        """
+        try:
+            # --- auth ---
+            self.check_auth()
+            headers = {"bs-session-id": self.get_session_id(), "Content-Type": "application/json"}
+
+            # --- dedicated resolver (name -> id first, no PUT by name) ---
+            async def _resolve_face_target_device_id() -> Tuple[Optional[int], Optional[Sequence[TextContent]]]:
+                # 1) device_id wins
+                raw_id = args.get("device_id")
+                if raw_id not in (None, ""):
+                    try:
+                        return int(raw_id), None
+                    except Exception:
+                        pass  # fall through to name search
+
+                # 2) name / search_text lookup
+                q = args.get("device_name") or args.get("device_search_text")
+                if isinstance(q, str) and q.strip():
+                    try:
+                        rows = await self._fetch_all_devices(headers)
+                    except Exception as e:
+                        return None, self.error_response(f"Failed to list devices: {type(e).__name__}: {e}")
+                    if not rows:
+                        return None, self.error_response("No devices found while resolving device_name.")
+
+                    def norm(s: str) -> str:
+                        s = s.lower()
+                        s = re.sub(r'[\s\-_]+', ' ', s).strip()
+                        return s
+
+                    qn = norm(q)
+                    # exact match first
+                    exact = [r for r in rows if norm(str(r.get("name", ""))) == qn]
+                    if len(exact) == 1 and str(exact[0].get("id", "")).isdigit():
+                        return int(exact[0]["id"]), None
+
+                    # substring contains
+                    subs = [r for r in rows if qn in norm(str(r.get("name", "")))]
+                    if len(subs) == 1 and str(subs[0].get("id", "")).isdigit():
+                        return int(subs[0]["id"]), None
+                    if len(subs) > 1:
+                        # pick the closest length match as a simple tie-breaker
+                        subs.sort(key=lambda r: abs(len(norm(r.get("name", ""))) - len(qn)))
+                        if str(subs[0].get("id", "")).isdigit():
+                            return int(subs[0]["id"]), None
+
+                    return None, self.error_response(f"Device not uniquely resolved from name '{q}'.")
+
+                # 3) fall back to generic only for door-based resolution
+                if args.get("door_id") is not None or args.get("door_name") is not None:
+                    dev_id, early = await self._resolve_device_id_from_args(args, headers)
+                    if dev_id is None:
+                        return None, early
+                    return dev_id, None
+
+                return None, self.error_response("Device not resolved from args")
+
+            device_id, early = await _resolve_face_target_device_id()
+            if device_id is None:
+                return early
+
+            # ---------- helpers ----------
+            def _norm_token(v: Any) -> str:
+                s = str(v).strip().lower().replace("_", " ").replace("-", " ")
+                return " ".join(s.split())
+
+            def _bool(v: Any) -> Optional[bool]:
+                if v is None:
+                    return None
+                if isinstance(v, bool):
+                    return v
+                s = _norm_token(v)
+                if s in {"true", "1", "yes", "on", "enable", "enabled"}:
+                    return True
+                if s in {"false", "0", "no", "off", "disable", "disabled"}:
+                    return False
+                return None
+
+            def _int_in_range(v: Any, lo: int, hi: int) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                except Exception:
+                    return None
+                return iv if lo <= iv <= hi else None
+
+            def _int_in_set(v: Any, allowed: Iterable[int]) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    return iv if iv in allowed else None
+                except Exception:
+                    return None
+
+            # enums
+            def _security(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1, 2):
+                        return iv
+                except Exception:
+                    pass
+                m = {"normal": 0, "secure": 1, "most secure": 2}
+                return m.get(_norm_token(v))
+
+            def _motion(v: Any) -> Optional[int]:
+                # 0=Off,1=Low,2=Medium,3=High → face.sensitivity
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1, 2, 3):
+                        return iv
+                except Exception:
+                    pass
+                m = {"off": 0, "low": 1, "medium": 2, "high": 3}
+                return m.get(_norm_token(v))
+
+            def _lfd(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1, 2, 3):
+                        return iv
+                except Exception:
+                    pass
+                m = {"normal": 0, "secure": 1, "more secure": 2, "most secure": 3}
+                return m.get(_norm_token(v))
+
+            def _op_mode(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1):
+                        return iv
+                except Exception:
+                    pass
+                m = {"normal": 0, "fusion": 1}
+                return m.get(_norm_token(v))
+
+            def _brightness_to_proximity(v: Any) -> Optional[int]:
+                """
+                Light brightness (preview) mapped to face.proximity_level:
+                  normal -> 0
+                  high   -> 1
+                  off / not use -> 3
+                Only these three values are valid; value '2' is intentionally not used.
+                """
+                if v is None:
+                    return None
+                try:
+                    iv = int(v)
+                    if iv in (0, 1, 3):
+                        return iv
+                except Exception:
+                    pass
+                t = _norm_token(v)
+                m = {"normal": 0, "high": 1, "not use": 3, "off": 3}
+                return m.get(t)
+
+            # ---------- normalize requested values ----------
+            sec   = _security(args.get("security_level"))
+            mot   = _motion(args.get("motion_sensor") if args.get("motion_sensor") is not None else args.get("sensitivity"))
+            lfd   = _lfd(args.get("lfd_level"))
+            etime = _int_in_range(args.get("enroll_timeout"), 10, 20)  # step 1, no snapping
+            rot   = _int_in_set(args.get("max_rotation"), {15, 30, 45, 60, 75, 90})
+            dmin  = _int_in_set(args.get("detect_distance_min"), {30,40,50,60,70,80,90,100,110,120,130})
+            # accept int 255 or string aliases for over 130
+            ddmax_raw = args.get("detect_distance_max")
+            dmax  = None
+            if ddmax_raw is not None:
+                if str(ddmax_raw).strip() == "255":
+                    dmax = 255
+                else:
+                    tok = _norm_token(ddmax_raw)
+                    if tok in {"over 130", "above 130", "over-130", "130 plus", "130plus", "over 130cm", "above 130cm"}:
+                        dmax = 255
+                    else:
+                        dmax = _int_in_set(ddmax_raw, {30,40,50,60,70,80,90,100,110,120,130})
+
+            op    = _op_mode(args.get("operation_mode"))
+            wide  = _bool(args.get("wide_search"))
+            fast  = _bool(args.get("fast_enroll"))
+            save  = _bool(args.get("save_image"))
+            dup   = _bool(args.get("duplicate_check"))
+
+            # brightness source keys (do NOT use preview_option; we map to proximity_level)
+            lb_src = (
+                args.get("light_brightness")
+                if args.get("light_brightness") is not None else
+                args.get("light_condition")
+                if args.get("light_condition") is not None else
+                args.get("light")
+            )
+            prox = _brightness_to_proximity(lb_src)
+
+            # validate provided-but-invalid
+            invalids = []
+            def _chk(name: str, val: Any, raw: Any):
+                if raw is not None and val is None:
+                    invalids.append(name)
+
+            _chk("security_level", sec, args.get("security_level"))
+            _chk("motion_sensor",  mot, args.get("motion_sensor") if args.get("motion_sensor") is not None else args.get("sensitivity"))
+            _chk("lfd_level",      lfd, args.get("lfd_level"))
+            _chk("enroll_timeout", etime, args.get("enroll_timeout"))
+            _chk("max_rotation",   rot, args.get("max_rotation"))
+            _chk("detect_distance_min", dmin, args.get("detect_distance_min"))
+            _chk("detect_distance_max", dmax, ddmax_raw)
+            _chk("operation_mode", op, args.get("operation_mode"))
+            _chk("wide_search",    wide, args.get("wide_search"))
+            _chk("fast_enroll",    fast, args.get("fast_enroll"))
+            _chk("save_image",     save, args.get("save_image"))
+            _chk("duplicate_check", dup, args.get("duplicate_check"))
+            _chk("light_brightness", prox, lb_src)
+
+            if invalids:
+                return self.error_response(f"Invalid values for: {', '.join(invalids)}")
+
+            if all(v is None for v in (sec, mot, lfd, etime, rot, dmin, dmax, op, wide, fast, save, dup, prox)):
+                return self.error_response("No face fields provided.")
+
+            # ---------- GET baseline ----------
+            async def _req(method: str, url: str, **kwargs):
+                last_exc = None
+                for attempt in range(3):
+                    try:
+                        async with httpx.AsyncClient(verify=False, timeout=httpx.Timeout(10.0, read=20.0)) as client:
+                            resp = await client.request(method, url, **kwargs)
+                        if resp.status_code >= 500:
+                            await asyncio.sleep(0.4 * (attempt + 1))
+                            continue
+                        return resp
+                    except Exception as e:
+                        last_exc = e
+                        await asyncio.sleep(0.4 * (attempt + 1))
+                raise last_exc or RuntimeError("HTTP request failed")
+
+            base_url = self.session.config.biostar_url.rstrip("/")
+            get_resp = await _req("GET", f"{base_url}/api/devices/{device_id}", headers=headers)
+            if get_resp.status_code != 200:
+                return self.error_response(f"GET /api/devices/{device_id} failed: {get_resp.status_code} {get_resp.text}")
+
+            try:
+                device_cur = get_resp.json().get("Device", {})
+            except Exception:
+                return self.error_response("Malformed JSON from GET /api/devices/{id}.")
+
+            # ---------- merge minimal changes ----------
+            face: Dict[str, Any] = dict(device_cur.get("face") or {})
+            if sec   is not None: face["security_level"] = str(sec)
+            if mot   is not None: face["sensitivity"]    = str(mot)          # maps to motion sensor level
+            if lfd   is not None: face["lfd_level"]      = str(lfd)
+            if etime is not None: face["scan_wait_time"] = int(etime)
+            if rot   is not None: face["max_rotation"]   = int(rot)
+            if dmin  is not None: face["detection_distance_min"] = int(dmin)
+            if dmax  is not None: face["detection_distance_max"] = int(dmax)
+            if op    is not None: face["operation_mode"] = int(op)
+            if wide  is not None: face["face_wide_search"] = "true" if wide else "false"
+            if fast  is not None: face["quick_enrollment"] = "true" if fast else "false"
+            if save  is not None: face["store_visual_face_image"] = "true" if save else "false"
+            if dup   is not None: face["duplicate_check"] = "true" if dup else "false"
+            if prox  is not None: face["proximity_level"] = str(prox)  # brightness -> proximity_level (0/1/3)
+
+            payload: Dict[str, Any] = {"Device": {"face": face}}
+
+            # dry-run
+            if bool(args.get("dry_run")):
+                return [TextContent(type="text", text=str({
+                    "status": "dry-run",
+                    "device_id": device_id,
+                    "request_payload": payload
+                }))]
+
+            # PUT
+            put_resp = await _req("PUT", f"{base_url}/api/devices/{device_id}", headers=headers, json=payload)
+            try:
+                body = put_resp.json()
+            except Exception:
+                body = {"raw_text": put_resp.text}
+
+            if put_resp.status_code >= 400:
+                return [TextContent(type="text", text=str({
+                    "status": "error",
+                    "http_status": put_resp.status_code,
+                    "request_payload": payload,
+                    "response": body
+                }))]
+
+            return [TextContent(type="text", text=str({
+                "status": "success",
+                "device_id": device_id,
+                "request_payload": payload,
+                "response": body
+            }))]
+
+        except Exception as e:
+            logger.exception("update_device_face failed")
+            return self.error_response(f"Exception: {type(e).__name__}: {e}")
+
+    # ---------------------------------------------------------------------------------
+    # UPDATED: auto-enable csn when sub-options imply CSN usage,
+    # and if CSN is on with neither EM/MIFARE chosen, auto-enable both.
+    # ---------------------------------------------------------------------------------
+    async def update_device_card_csn(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        UI-aligned CSN updater: fetch full Device, mutate required fields, PUT full Device back.
+
+        Why this approach:
+          - The device may ignore a minimal patch for 'use_csn'. The UI sends a full snapshot payload.
+          - Turning CSN OFF in UI also puts wiegand.wiegand_csn_id.id = "-1" (based on your captured payload).
+          - We replicate that behavior exactly while preserving all other fields.
+
+        Inputs (at least one target resolver + csn_enabled are required):
+          - Target: device_id | device_name | device_search_text | door_id | door_name (+ edge when needed)
+          - csn_enabled: bool (required)
+          - em4100_enabled?: bool            -> Device.card.use_em
+          - mifare_felica_enabled?: bool     -> Device.card.use_mifare_felica
+          - byte_order?: "LSB"|"MSB"|0|1     -> Device.card.byte_order (LSB="1", MSB="0")
+          - format_type?: "wiegand"|"normal" -> Device.card.use_wiegand_format (UI toggle only; no format-id change)
+          - wiegand_format?: string          -> Human-friendly name (mapped via WIEGAND_CSN_FORMATS)
+          - wiegand_format_id?: int|string   -> Device.wiegand.wiegand_csn_id (format row or {"id": "<n>"})
+          - also_clear_wiegand_csn?: bool    -> If true and csn_enabled=false, force wiegand_csn_id to "-1" (UI behavior)
+          - dry_run?: bool                   -> Preview without PUT
+
+        Runtime rules added:
+          - If any CSN sub-option is enabled or a Wiegand format is selected, csn_enabled is auto-forced to True.
+          - If resulting csn_enabled is True and neither EM4100 nor MIFARE/Felica is selected, both will be auto-enabled.
+        """
+        try:
+            # 0) session/auth
+            self.check_auth()
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json",
+            }
+
+            # 1) resolve target device id using your existing resolver
+            device_id, early = await self._resolve_device_id_from_args(args, headers)
+            if device_id is None:
+                return early
+            device_id = int(device_id)
+
+            # 2) helpers (unchanged + small additions)
+            def to_bool(v: Any) -> bool:
+                if isinstance(v, bool):
+                    return v
+                s = str(v).strip().lower()
+                return s in {"1", "true", "yes", "y", "on", "enabled"}
+
+            def to_bs_bool(v: Any) -> str:
+                return "true" if to_bool(v) else "false"
+
+            def map_byte_order(v: Any) -> Optional[str]:
+                """Return '1' for LSB, '0' for MSB; None if not provided/invalid."""
+                if v is None:
+                    return None
+                s = str(v).strip().lower()
+                if s in {"lsb", "1"}:
+                    return "1"
+                if s in {"msb", "0"}:
+                    return "0"
+                return None
+
+            def is_true_like(v: Any) -> bool:
+                """Robust truthy check for existing device snapshot fields ('true'/'false', 1/0, etc.)."""
+                if isinstance(v, bool):
+                    return v
+                s = str(v).strip().lower()
+                return s in {"true", "1", "yes", "y", "on", "enabled"}
+
+            if "csn_enabled" not in args:
+                return self.error_response("Missing required argument: csn_enabled")
+
+            # --- auto-enable decision before GET baseline
+            fmt = args.get("format_type")
+            auto_enable_from_fmt = bool(fmt) and str(fmt).strip().lower() in {"wiegand", "wg", "on", "true", "1"}
+            auto_enable = any([
+                to_bool(args.get("em4100_enabled")),
+                to_bool(args.get("mifare_felica_enabled")),
+                auto_enable_from_fmt,
+                args.get("wiegand_format") is not None,
+                args.get("wiegand_format_id") is not None,
+                args.get("byte_order") is not None,
+            ])
+
+            want_csn_input = to_bool(args["csn_enabled"])
+            want_csn = bool(want_csn_input or auto_enable)  # requirement #1
+
+            also_clear_wg = bool(args.get("also_clear_wiegand_csn", True))  # default True to mirror UI
+            dry_run = bool(args.get("dry_run"))
+
+            # 3) GET full device (baseline snapshot)
+            async with httpx.AsyncClient(verify=False) as client:
+                get_resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                    headers=headers,
+                )
+            if get_resp.status_code != 200:
+                return self.error_response(
+                    f"GET device failed: {get_resp.status_code} - {get_resp.text}"
+                )
+
+            base = get_resp.json() or {}
+            device_obj = base.get("Device") or base  # accept {Device:{...}} or flat
+            if not isinstance(device_obj, dict):
+                return self.error_response("Malformed device payload from GET.")
+
+            # Ensure required nested structures exist
+            device_obj.setdefault("card", {})
+            device_obj.setdefault("wiegand", {})
+
+            card = device_obj["card"]
+            wiegand = device_obj["wiegand"]
+
+            # 4) Apply changes (UI semantics)
+            # Always set the desired CSN flag (with auto-enable applied)
+            card["use_csn"] = to_bs_bool(want_csn)
+
+            # Optional subtype toggles: if provided, overwrite; else preserve as-is
+            if "em4100_enabled" in args:
+                card["use_em"] = to_bs_bool(args["em4100_enabled"])
+            if "mifare_felica_enabled" in args:
+                card["use_mifare_felica"] = to_bs_bool(args["mifare_felica_enabled"])
+
+            # Optional byte order: LSB='1', MSB='0'
+            bo = map_byte_order(args.get("byte_order"))
+            if bo is not None:
+                card["byte_order"] = bo
+
+            # Optional format type: only toggles card.use_wiegand_format (do NOT touch wiegand.* formats here)
+            if fmt is not None:
+                ft = str(fmt).strip().lower()
+                if ft in {"wiegand", "wg", "on", "true", "1"}:
+                    card["use_wiegand_format"] = "true"
+                elif ft in {"normal", "off", "false", "0"}:
+                    card["use_wiegand_format"] = "false"
+                else:
+                    return self.error_response("Invalid format_type. Use 'wiegand' or 'normal'.")
+
+            # ---------------- human-name → id mapping for Wiegand CSN ----------------
+            name_arg = args.get("wiegand_format")
+            id_arg = args.get("wiegand_format_id")
+
+            resolved_wf_id: Optional[str] = None
+            if name_arg is not None:
+                key = str(name_arg).strip()
+                resolved_wf_id = WIEGAND_CSN_FORMATS.get(key)
+                if resolved_wf_id is None:
+                    for k, v in WIEGAND_CSN_FORMATS.items():
+                        if k.lower() == key.lower():
+                            resolved_wf_id = v
+                            break
+                if resolved_wf_id is None:
+                    return self.error_response(f"Unknown wiegand_format: {name_arg}")
+
+            if id_arg is not None:
+                try:
+                    id_norm = str(int(str(id_arg).strip()))
+                except Exception:
+                    return self.error_response(
+                        "Invalid wiegand_format_id. It must be an integer or integer-like string.")
+                if resolved_wf_id is not None and id_norm != resolved_wf_id:
+                    return self.error_response(
+                        f"wiegand_format ('{name_arg}') conflicts with wiegand_format_id ('{id_norm}')."
+                    )
+                resolved_wf_id = id_norm
+
+            if resolved_wf_id is not None:
+                card["use_wiegand_format"] = "true"
+                row = await self._fetch_wiegand_format_row(headers, resolved_wf_id)
+                if row:
+                    wiegand["wiegand_csn_id"] = row
+                else:
+                    wiegand["wiegand_csn_id"] = {"id": resolved_wf_id}
+
+            # Crucial: When turning CSN OFF, UI snapshot shows wiegand_csn_id.id = "-1".
+            if not want_csn and also_clear_wg:
+                wg_id = (wiegand.get("wiegand_csn_id") or {}).get("id")
+                if str(wg_id) != "-1":
+                    wiegand["wiegand_csn_id"] = {"id": "-1"}
+
+            # --- requirement #2 (revised): if CSN is on and neither EM/MIFARE is selected, auto-enable both.
+            em_effective = is_true_like(card.get("use_em"))
+            mifare_effective = is_true_like(card.get("use_mifare_felica"))
+            if want_csn and not (em_effective or mifare_effective):
+                # Auto-fix: enable both when user didn't choose either
+                card["use_em"] = "true"
+                card["use_mifare_felica"] = "true"
+                em_effective = True
+                mifare_effective = True
+
+            full_payload = {"Device": device_obj}
+
+            # 5) Dry-run
+            if dry_run:
+                return self.success_response({
+                    "message": "[dry_run] Would PUT full Device snapshot aligned with UI behavior.",
+                    "device_id": device_id,
+                    "request_payload": full_payload
+                })
+
+            # 6) PUT full snapshot (UI-like)
+            async with httpx.AsyncClient(verify=False) as client:
+                put_resp = await client.put(
+                    f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                    headers=headers,
+                    json=full_payload,
+                )
+            if put_resp.status_code != 200:
+                return self.error_response(
+                    f"PUT failed: {put_resp.status_code} - {put_resp.text}",
+                    {"request_body": full_payload, "device_id": device_id}
+                )
+
+            # 7) Verify by GET (keep as-is)
+            verify = {}
+            try:
+                async with httpx.AsyncClient(verify=False) as client:
+                    v = await client.get(
+                        f"{self.session.config.biostar_url}/api/devices/{device_id}",
+                        headers=headers,
+                    )
+                if v.status_code == 200:
+                    vv = (v.json() or {}).get("Device", {}) or {}
+                    vc = vv.get("card", {}) or {}
+                    verify = {
+                        "use_csn": str(vc.get("use_csn")),
+                        "use_em": str(vc.get("use_em")),
+                        "use_mifare_felica": str(vc.get("use_mifare_felica")),
+                        "byte_order": str(vc.get("byte_order")),
+                        "use_wiegand_format": str(vc.get("use_wiegand_format")),
+                    }
+            except Exception:
+                pass
+
+            return self.success_response({
+                "message": "Device CSN settings updated successfully.",
+                "device_id": device_id,
+                "request_payload": full_payload,
+                "verify": verify
+            })
+
+        except Exception as e:
+            logger.exception("update_device_card_csn failed")
+            return self.error_response(f"Exception: {type(e).__name__}: {e}")
+
+    async def _fetch_wiegand_format_row(self, headers: Dict[str, str], format_id: str) -> Optional[Dict[str, Any]]:
+        """
+        GET /api/wiegand_formats and return the matching row object by id.
+
+        Returns:
+            - dict: Full row object of the selected Wiegand format (mirrors what the UI sends)
+            - None: If not found or on any error
+        """
+        try:
+            async with httpx.AsyncClient(verify=False) as client:
+                resp = await client.get(
+                    f"{self.session.config.biostar_url}/api/wiegand_formats",
+                    headers=headers
+                )
+            if resp.status_code != 200:
+                # Best-effort: UI sometimes sends only {"id": "<n>"}.
+                # We'll fall back to id-only if collection fetch fails.
+                return None
+
+            data = resp.json() or {}
+            rows = (data.get("WiegandFormatCollection") or {}).get("rows", []) or []
+            for row in rows:
+                if str(row.get("id")) == str(format_id):
+                    return row
+        except Exception:
+            # Swallow and let caller fall back to id-only form.
+            pass
+        return None
+
+    async def list_waiting_devices(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        List devices waiting to be added to BioStar 2 server.
+        GET /api/devices/waiting
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices/waiting",
+                    headers=headers
+                )
+
+            if response.status_code != 200:
+                return self.error_response(f"Failed to retrieve waiting devices: {response.status_code} - {response.text}")
+
+            data = response.json()
+            device_collection = data.get("DeviceCollection", {})
+            rows = device_collection.get("rows", [])
+            
+            # Apply filters
+            ip_filter = args.get("ip_filter")
+            device_type_id = args.get("device_type_id")
+            
+            filtered_rows = rows
+            if ip_filter:
+                filtered_rows = [r for r in filtered_rows if ip_filter in r.get("lan", {}).get("ip", "")]
+            if device_type_id:
+                filtered_rows = [r for r in filtered_rows if str(r.get("device_type_id", {}).get("id", "")) == str(device_type_id)]
+
+            result = {
+                "total": len(filtered_rows),
+                "devices": []
+            }
+
+            for device in filtered_rows:
+                device_info = {
+                    "id": device.get("id"),
+                    "device_type_id": device.get("device_type_id", {}).get("id"),
+                    "ip": device.get("lan", {}).get("ip"),
+                    "connection_mode": device.get("lan", {}).get("connection_mode"),
+                    "status": device.get("connection", {}).get("status"),
+                    "support_alphanumeric": device.get("capacity", {}).get("support_alphanumeric"),
+                    "follower_server_id": device.get("follower_server_id")
+                }
+                result["devices"].append(device_info)
+
+            return self.success_response(result)
+
+        except Exception as e:
+            logger.exception("list_waiting_devices failed")
+            return self.error_response(f"Exception: {type(e).__name__}: {e}")
+
+    async def add_waiting_device(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Add a device from the waiting list to BioStar 2 server.
+        POST /api/devices with waiting device details.
+        """
+        try:
+            self.check_auth()
+
+            headers = {
+                "bs-session-id": self.get_session_id(),
+                "Content-Type": "application/json"
+            }
+
+            waiting_device_id = str(args["waiting_device_id"])
+            
+            # First, get the waiting device details
+            async with httpx.AsyncClient(verify=False) as client:
+                waiting_response = await client.get(
+                    f"{self.session.config.biostar_url}/api/devices/waiting",
+                    headers=headers
+                )
+
+            if waiting_response.status_code != 200:
+                return self.error_response(f"Failed to retrieve waiting devices: {waiting_response.status_code}")
+
+            waiting_data = waiting_response.json()
+            waiting_devices = waiting_data.get("DeviceCollection", {}).get("rows", [])
+            
+            # Find the target device
+            target_device = None
+            for device in waiting_devices:
+                if str(device.get("id")) == waiting_device_id:
+                    target_device = device
+                    break
+
+            if not target_device:
+                return self.error_response(f"Device ID {waiting_device_id} not found in waiting list. Use list-waiting-devices first.")
+
+            # Extract device information
+            device_type_id = args.get("device_type_id") or target_device.get("device_type_id", {}).get("id")
+            ip_address = args.get("ip_address") or target_device.get("lan", {}).get("ip")
+            connection_mode = target_device.get("lan", {}).get("connection_mode", "1")
+            status = target_device.get("connection", {}).get("status", "3")
+            support_alphanumeric = target_device.get("capacity", {}).get("support_alphanumeric", "true")
+            use_alphanumeric = str(args.get("use_alphanumeric", True)).lower()
+            follower_server_id = str(args.get("follower_server_id", target_device.get("follower_server_id", "1")))
+            device_group_id = args.get("device_group_id", 1)
+            pktversion = target_device.get("pktversion", "3")
+            
+            # Generate device name if not provided
+            device_name = args.get("name")
+            if not device_name:
+                # Get device type name mapping
+                device_type_map = {
+                    "35": "BioStation 3",
+                    "34": "BioStation 2a",
+                    "33": "FaceStation F2",
+                    "8": "BioStation 2",
+                    "9": "BioStation A2"
+                }
+                device_type_name = device_type_map.get(str(device_type_id), f"Device Type {device_type_id}")
+                device_name = f"{device_type_name} {waiting_device_id} ({ip_address})"
+
+            # Build payload following the user's example
+            payload = {
+                "FollowerServer": {
+                    "id": follower_server_id
+                },
+                "Device": {
+                    "id": waiting_device_id,
+                    "device_type_id": {
+                        "id": str(device_type_id)
+                    },
+                    "connection": {
+                        "status": status
+                    },
+                    "lan": {
+                        "ip": ip_address,
+                        "connection_mode": connection_mode
+                    },
+                    "system": {
+                        "use_alphanumeric": use_alphanumeric
+                    },
+                    "capacity": {
+                        "support_alphanumeric": support_alphanumeric
+                    },
+                    "support_occupancy": target_device.get("support_occupancy", "false"),
+                    "pktversion": pktversion,
+                    "follower_server_id": follower_server_id,
+                    "name": device_name,
+                    "device_group_id": {
+                        "id": device_group_id
+                    }
+                },
+                "set_alphanumeric": use_alphanumeric
+            }
+
+            # POST to add device
+            async with httpx.AsyncClient(verify=False) as client:
+                response = await client.post(
+                    f"{self.session.config.biostar_url}/api/devices",
+                    headers=headers,
+                    json=payload
+                )
+
+            if response.status_code not in [200, 201]:
+                return self.error_response(f"Failed to add device: {response.status_code} - {response.text}")
+
+            response_data = response.json()
+            
+            return self.success_response({
+                "message": f"Device '{device_name}' added successfully from waiting list",
+                "device_id": waiting_device_id,
+                "device_name": device_name,
+                "ip_address": ip_address,
+                "response": response_data
+            })
+
+        except Exception as e:
+            logger.exception("add_waiting_device failed")
+            return self.error_response(f"Exception: {type(e).__name__}: {e}")
+
+    async def bulk_add_waiting_devices(self, args: Dict[str, Any]) -> Sequence[TextContent]:
+        """
+        Add multiple devices from the waiting list in bulk.
+        Iterates through each device and calls add_waiting_device logic.
+        """
+        try:
+            self.check_auth()
+            
+            waiting_device_ids = args.get("waiting_device_ids", [])
+            if not isinstance(waiting_device_ids, (list, tuple)) or not waiting_device_ids:
+                return self.error_response("Provide 'waiting_device_ids' as a non-empty array")
+
+            continue_on_error = bool(args.get("continue_on_error", True))
+            device_group_id = args.get("device_group_id", 1)
+            name_prefix = args.get("name_prefix", "")
+            use_alphanumeric = args.get("use_alphanumeric", True)
+
+            results = []
+            success_count = 0
+
+            for idx, device_id in enumerate(waiting_device_ids):
+                try:
+                    # Build individual device args
+                    device_args = {
+                        "waiting_device_id": device_id,
+                        "device_group_id": device_group_id,
+                        "use_alphanumeric": use_alphanumeric
+                    }
+                    
+                    if name_prefix:
+                        device_args["name_prefix"] = name_prefix
+
+                    # Call add_waiting_device for this device
+                    single_result = await self.add_waiting_device(device_args)
+                    
+                    # Parse result
+                    import ast
+                    parsed = None
+                    if isinstance(single_result, (list, tuple)) and single_result:
+                        t = getattr(single_result[0], "text", None)
+                        if isinstance(t, str) and t.strip():
+                            try:
+                                parsed = ast.literal_eval(t)
+                            except Exception:
+                                parsed = {"raw": t}
+                    else:
+                        parsed = {"raw": single_result}
+
+                    ok = isinstance(parsed, dict) and str(parsed.get("status")) == "success"
+                    if ok:
+                        success_count += 1
+                        results.append({
+                            "index": idx,
+                            "status": "success",
+                            "device_id": device_id,
+                            "message": parsed.get("message")
+                        })
+                    else:
+                        results.append({
+                            "index": idx,
+                            "status": "error",
+                            "device_id": device_id,
+                            "response": parsed
+                        })
+                        if not continue_on_error:
+                            break
+
+                except Exception as e:
+                    results.append({
+                        "index": idx,
+                        "status": "error",
+                        "device_id": device_id,
+                        "error": str(e)
+                    })
+                    if not continue_on_error:
+                        break
+
+            return self.success_response({
+                "message": f"Bulk add completed: {success_count}/{len(waiting_device_ids)} devices added",
+                "total": len(waiting_device_ids),
+                "success": success_count,
+                "failed": len(waiting_device_ids) - success_count,
+                "results": results
+            })
+
+        except Exception as e:
+            logger.exception("bulk_add_waiting_devices failed")
+            return self.error_response(f"Exception: {type(e).__name__}: {e}")
+
+
+WIEGAND_CSN_FORMATS = {
+    "26 bit SIA Standard-H10301": "0",
+    "HID 37 bit-H10302": "1",
+    "HID 37 bit-H10304": "2",
+    "HID Corporate 1000": "3",
+    "HID Corporate 1000 48bit": "4",
+    "MIFARE CSN 32bit": "5",
+    "MIFARE CSN 34bit (Parity)": "6",
+    "DESFire 56bit": "7",
+    "DESFire 58bit (Parity)": "8",
+}