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

> Configure AtomCam Tools motion detection sensitivity and zones using motionLevel and motionArea commands. Easily set detection sensitivity and define specific detection areas for your AtomCam.

- Repository: [Mitsuru Nakada/atomcam_tools](https://github.com/mnakada/atomcam_tools)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/mnakada/atomcam_tools/blob/main/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):
   ```c
   { "motionLevel", "MMALevel", 10, &Level3 }
   ```

2. **Zone control** (line 48):
   ```c
   { "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`](https://github.com/mnakada/atomcam_tools/blob/main/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:

```c
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:

```bash
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:

```c
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):

```bash
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`](https://github.com/mnakada/atomcam_tools/blob/main/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:

```c
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:

```bash

# 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`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/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.