How to Configure Motion Detection Sensitivity and Detection Zones in AtomCam Tools

AtomCam Tools exposes motion detection settings through the property command interface, where motionLevel sets sensitivity (low/mid/high) and motionArea defines detection zones as either the full frame or a rectangular sub-region.

The mnakada/atomcam_tools repository provides a TCP command socket for managing Wyze/AtomCam firmware features. You can configure motion detection sensitivity and detection zones by issuing text commands that the firmware translates into specific configuration items stored in non-volatile memory.

Property Command Architecture

AtomCam Tools implements a generic property system to abstract firmware configuration. The PropertyCommandTable in libcallback/property.c maps textual command names to their corresponding configuration identifiers and handler functions.

Each entry in the table defines:

• The text command exposed to users
• The firmware configuration key (e.g., MMALevel, MAT)
• The item number used in the proprietary protocol
• A handler function that validates and converts arguments

Motion Detection Entries

Two entries handle motion settings:

1. Sensitivity control (line 35):

   { "motionLevel", "MMALevel", 10, &Level3 }

2. Zone control (line 48):

   { "motionArea", "MAT", 15, &MotionArea }

Configuring Motion Detection Sensitivity

Sensitivity is controlled by the MMALevel configuration item (item 10). The Level3 handler (lines 91-103 in libcallback/property.c) translates human-readable labels into numeric codes required by the firmware:

• Low sensitivity → value 1
• Mid sensitivity → value 128
• High sensitivity → value 255

The handler uses case-insensitive string comparison to map the input, then calls setItemProp(item, val) to commit the change:

if (!strcasecmp(p, "low"))  val = 1;
else if (!strcasecmp(p, "mid"))  val = 128;
else if (!strcasecmp(p, "high")) val = 255;
return setItemProp(item, val) ? "error" : "ok";

Set the sensitivity to high by sending:

echo "property motionLevel high" | nc <camera-ip> 12345

Defining Detection Zones

Detection zones are managed through the MAT configuration item (item 15). The MotionArea handler (lines 53-78) supports two modes:

Full frame monitoring (all): Sets item 15 to value 3, monitoring the entire image.

Rectangular region (rect): Sets item 15 to value 1 and stores coordinates in items 16-19:

• Item 16: Start X (sx)
• Item 17: Start Y (sy)
• Item 18: Width
• Item 19: Height

The handler parses four integer arguments following the rect keyword:

if (!strcasecmp(p, "all")) return setItemProp(item, 3) ? "error" : "ok";
// rect case
int sx = atoi(p); // ... parse sy, width, height
err |= setItemProp(16, sx);
err |= setItemProp(17, sy);
err |= setItemProp(18, width);
err |= setItemProp(19, height);
setItemProp(item, 1);

To restrict detection to a 100×80 pixel area starting at coordinates (50, 40):

echo "property motionArea rect 50 40 100 80" | nc <camera-ip> 12345

Runtime Motion Event Handling

When the camera detects motion within the configured zone, the local_sdk_video_osd_update_rect hook in libcallback/wait_motion.c (lines 78-80) formats the detection payload. This function constructs a response string containing the detection rectangle and current camera orientation:

sprintf(CommandResBuf, "detect %d %d %d %d %d %d\n",
        rectInfo->left, rectInfo->right,
        rectInfo->top, rectInfo->bottom,
        lroundf(pan), lroundf(tilt));

The hook only executes when a motion-area has been defined, ensuring clients waiting on motion events receive precise coordinate data matching the configured detection zone.

Practical Configuration Examples

Connect to the camera's command socket (default port 12345) to configure settings:

# Set high sensitivity

$ echo "property motionLevel high" | nc 192.168.1.50 12345
ok

# Define a detection zone covering the center 200x150 area

$ echo "property motionArea rect 220 165 200 150" | nc 192.168.1.50 12345
ok

# Query current settings

$ echo "property motionLevel" | nc 192.168.1.50 12345
motionLevel = high

$ echo "property motionArea" | nc 192.168.1.50 12345
motionArea = rect 220 165 200 150

Summary

• Sensitivity is controlled by the motionLevel command, which maps to MMALevel (item 10) with values 1 (low), 128 (mid), or 255 (high) via the Level3 handler in libcallback/property.c.
• Detection zones are controlled by the motionArea command, which maps to MAT (item 15). Use all (value 3) for full-frame detection or rect (value 1) with four coordinates stored in items 16-19.
• All configuration changes route through setItemProp() to update the firmware's non-volatile storage.
• Runtime motion events are reported by local_sdk_video_osd_update_rect() in libcallback/wait_motion.c, which formats detection rectangles according to the active zone configuration.

Frequently Asked Questions

What firmware configuration keys store motion detection settings?

The camera firmware stores sensitivity in the MMALevel key (configuration item 10) and zone mode in the MAT key (item 15). When using rectangular detection zones, the specific coordinates are stored in configuration items 16 (start X), 17 (start Y), 18 (width), and 19 (height).

How do I set a custom rectangular detection zone?

Send the command property motionArea rect <sx> <sy> <width> <height> through the TCP command socket. The MotionArea handler parses these four integers, stores them in items 16-19, and sets item 15 to value 1 to enable rectangle mode. Replace the port and IP in the netcat example with your camera's actual network parameters.

What numeric sensitivity values does the AtomCam firmware expect?

The firmware uses 8-bit unsigned values where 1 represents low sensitivity, 128 represents medium sensitivity, and 255 represents high sensitivity. The Level3 handler automatically translates the text labels "low", "mid", and "high" into these numeric codes when processing motionLevel commands.

Where does motion detection data go when an event is triggered?

When motion is detected within the configured zone, the local_sdk_video_osd_update_rect hook in libcallback/wait_motion.c formats a detection string containing the rectangle coordinates and camera pan/tilt values. This string is written to the command response buffer for any client that has issued a wait motion command, enabling real-time event monitoring via the same TCP socket used for configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}