reCamera Intellisense

reCamera Intellisense

Drive one or more reCamera Pro (Pending Release) devices: device registration, AI detection configuration, rule-based recording, event polling, on-demand capture, storage/records management, and GPIO control. The skill bundles a Python SDK (scripts/recamera_intellisense/) that is the single source of truth for every command's parameters; the same package backs the MCP server, so CLI and MCP schemas are identical.

Requirements

Security

Invocation

The bundled SDK runs without installation. From {baseDir} (the skill root):

# One-shot
PYTHONPATH="{baseDir}/scripts" python3 -m recamera_intellisense  ''
Convenience alias for a session
export PYTHONPATH="{baseDir}/scripts"
alias rci='python3 -m recamera_intellisense'
rci list_devices

Calling convention (uniform across every command):

Python use (in-process, preferred for loops):

import sys, time
sys.path.insert(0, "{baseDir}/scripts")
from recamera_intellisense import (
    list_devices, set_detection_rules, get_detection_events,
    capture_image, fetch_file,
)

Command catalogue

All commands accept device_name (string) unless noted. device_name resolves against ~/.recamera/devices.json; run list_devices to see what is registered. Selector commands (get_device, remove_device, everything that takes device_name) also accept the alias name, so a record emitted by list_devices can be forwarded verbatim.

Device registry

add_device / update_device probe /api/v1/recamera-generate-204 before persisting; a bad token or host fails fast.

Detection (high-level facade, AI-only)

set_detection_rules installs an inference_set record trigger and, by default, enables the rule pipeline with a JPG writer and a ready storage slot — override only if the caller already configured them. get_detection_rules returns [] whenever the current trigger is not inference_set.

Rule system (low-level, all trigger kinds)

Capture (independent of rule pipeline)

capture_image is the one-shot helper: it starts a JPG, polls until terminal, fetches the file, and returns {event, path, size, content_base64} (where event is the terminal capture event with status == "COMPLETED"). For MP4, drive the pipeline manually: start_capture → poll get_capture_status until last_capture.status is terminal (COMPLETED / FAILED / INTERRUPTED / CANCELED) → fetch_file using the event's output_directory + file_name. stop_capture is only meaningful for in-flight video.

Storage

Records (relay-backed browsing, recommended for recordings)

Files (daemon, arbitrary absolute paths)

GPIO

Key schemas

Detection rule

{
  "name": "front-door-person",
  "debounce_times": 3,
  "confidence_range_filter": [0.25, 1.0],
  "label_filter": ["person"],
  "region_filter": [[[0.1,0.1],[0.9,0.1],[0.9,0.9],[0.1,0.9]]]
}

Schedule range

Record trigger (tagged union, kind field)

{"kind":"inference_set", "rules":[ /* DetectionRule[] */ ]}
{"kind":"timer", "interval_seconds": 60}
{"kind":"gpio", "num":1, "state":"PULL_UP", "signal":"FALLING", "debounce_ms":50}
{"kind":"tty",  "name":"tty0", "command":"SHOOT"}
{"kind":"http"}
{"kind":"always_on"}

Detection event

{"timestamp":"2026-04-20T12:34:56Z","timestamp_unix_ms":1745152496000,"rule_name":"front-door-person","snapshot_path":"/mnt/.../abcd.jpg"}

Agent rules

1. Always supply a complete JSON object; never prompt interactively. 2. Identify the target by device_name (preferred). list_devices is cheap — call it if unsure. 3. Token format must match sk_[A-Za-z0-9_\-]+; validation is enforced by add_device. 4. label_filter takes label names from get_detection_models_info. Do not translate names into numeric indexes — the MCP/SDK expects strings. 5. For AI-only use, prefer set_detection_rules (it ensures writer + storage). For hybrid triggers (GPIO, timer, TTY, HTTP, always-on), use set_record_trigger directly — only one record trigger is active at a time. 6. Poll get_detection_events with a checkpointed start_unix_ms (1–10 s cadence). Events accumulate on-device; clear_detection_events to reset. 7. Prefer event metadata first; fetch imagery only when the user needs it. Images/≤5 MiB inline; videos/larger return a URL + note. 8. When a storage slot is required (rules, timer, always-on), the facade's ensure_storage=true default will select the internal slot if none is enabled; for removable media the user must provision a slot beforehand.

Workflows

1 — Onboard a device

2 — Person/object detection by name

3 — Monitor events (long-running)

ckpt = int(time.time() * 1000)
while True:
    events = get_detection_events(device_name="cam1", start_unix_ms=ckpt)
    for e in events:
        ckpt = max(ckpt, e["timestamp_unix_ms"] + 1)
        if e.get("snapshot_path"):
            img = fetch_file(device_name="cam1", path=e["snapshot_path"])
            # img["content_base64"] or dispatch on img["url"] when oversized
    time.sleep(2)

4 — On-demand snapshot / video

5 — Browse and retrieve recordings

6 — Hybrid trigger (GPIO pulse → 5 s MP4)

{"device_name":"cam1","trigger":{"kind":"gpio","num":1,"state":"PULL_UP","signal":"FALLING","debounce_ms":50}}

7 — GPIO control

CLI quickstart

export PYTHONPATH="{baseDir}/scripts"
alias rci='python3 -m recamera_intellisense'
rci # list all commands
rci add_device '{"name":"cam1","host":"192.168.1.100","token":"sk_xxxx"}'
rci list_devices
rci get_detection_models_info '{"device_name":"cam1"}'
rci set_detection_model '{"device_name":"cam1","model_name":"yolo11n"}'
rci set_detection_rules '{"device_name":"cam1","rules":[{"name":"person","label_filter":["person"]}]}'
rci get_detection_events '{"device_name":"cam1","start_unix_ms":1745150000000}'
rci capture_image '{"device_name":"cam1"}'
rci list_records '{"device_name":"cam1"}'
rci fetch_record '{"device_name":"cam1","path":"2026-04-20/evt-001.jpg"}'
rci get_storage_status '{"device_name":"cam1"}'
rci set_gpio_value '{"device_name":"cam1","pin_id":1,"value":1}'

Execution checklist (copy for multi-step tasks)

reCamera Task Progress
[ ] Resolve device (list_devices, then device_name)
[ ] Validate JSON (required keys per command)
[ ] Ensure prerequisites (storage slot, schedule, model) when configuring rules
[ ] Run command; parse stdout or handle stderr
[ ] For polling, checkpoint start_unix_ms and rate-limit
[ ] On error, surface stderr + one concrete fix

Troubleshooting

| Symptom | Likely cause / fix | |---|---| | HTTP 401/403 | Token missing/invalid — re-copy from Web Console; confirm sk_ prefix. | | Connection refused / timed out | Wrong host/port/protocol; verify LAN reachability and device power. | | HTTPS certificate error | Add "allow_unsecured": true for self-signed LAN certs (not for the public Internet). | | get_detection_rules returns [] | Current trigger is not inference_set — call set_detection_rules (or inspect get_record_trigger). | | Rules set but no events | No storage slot configured (get_storage_status); schedule window inactive; region_filter/confidence_range_filter too tight; debounce_times too high. | | fetch_record returns only {url, note} | File is a video or exceeds max_inline_bytes (default 5 MiB). Fetch the URL directly or raise the budget. | | storage_task_submit rejects sync=true | FORMAT/FREE_UP must run async — resubmit with "sync": false and poll storage_task_status. | | Schedule rejected | Use Day HH:MM:SS with three-letter day; Day 24:00:00 valid. | | set_detection_model fails: "not installed" | Run get_detection_models_info and use one of the returned names/ids. | | detect_local_device returns null | No rcisd daemon is listening on the Unix socket (default /dev/shm/rcisd.sock) within 3 s. Start the daemon or pass a different socket_path. | | start_capture rejects output with code 30022 | output must be an on-device directory under a mounted storage slot (check get_storage_status.mount_path). Local paths like /tmp/... are not valid — omit output to use the default slot, then fetch_file the result. | | ImportError: recamera_intellisense | Set PYTHONPATH="{baseDir}/scripts" or cd {baseDir}/scripts before python3 -m recamera_intellisense. |

Reference pointers

| Symptom | Likely cause / fix | |---|---| | HTTP 401/403 | Token missing/invalid — re-copy from Web Console; confirm sk_ prefix. | | Connection refused / timed out | Wrong host/port/protocol; verify LAN reachability and device power. | | HTTPS certificate error | Add "allow_unsecured": true for self-signed LAN certs (not for the public Internet). | | get_detection_rules returns [] | Current trigger is not inference_set — call set_detection_rules (or inspect get_record_trigger). | | Rules set but no events | No storage slot configured (get_storage_status); schedule window inactive; region_filter/confidence_range_filter too tight; debounce_times too high. | | fetch_record returns only {url, note} | File is a video or exceeds max_inline_bytes (default 5 MiB). Fetch the URL directly or raise the budget. | | storage_task_submit rejects sync=true | FORMAT/FREE_UP must run async — resubmit with "sync": false and poll storage_task_status. | | Schedule rejected | Use Day HH:MM:SS with three-letter day; Day 24:00:00 valid. | | set_detection_model fails: "not installed" | Run get_detection_models_info and use one of the returned names/ids. | | detect_local_device returns null | No rcisd daemon is listening on the Unix socket (default /dev/shm/rcisd.sock) within 3 s. Start the daemon or pass a different socket_path. | | start_capture rejects output with code 30022 | output must be an on-device directory under a mounted storage slot (check get_storage_status.mount_path). Local paths like /tmp/... are not valid — omit output to use the default slot, then fetch_file the result. | | ImportError: recamera_intellisense | Set PYTHONPATH="{baseDir}/scripts" or cd {baseDir}/scripts before python3 -m recamera_intellisense. |