Motion Detection Alarm Period Reduction in AtomCam Tools: How Throttling Works

Motion detection alarm period reduction works by enforcing a configurable minimum interval between cloud uploads, with a hard floor of 300 seconds that discards excess alarm traffic and returns dummy responses instead of performing HTTP transfers.

The mnakada/atomcam_tools firmware provides sophisticated motion detection capabilities for Atom and Wyze cameras. When motion events trigger alarms, the system must balance immediate alerting with server bandwidth conservation. This article explains the technical implementation of motion detection alarm period reduction, detailing how the firmware throttles upload frequency to prevent overwhelming cloud infrastructure.

The Architecture of Alarm Throttling

The reduction mechanism spans three core components that handle configuration, storage, and enforcement. When motion occurs, libcallback/wait_motion.c detects the event and triggers the alarm upload flow. Before the data reaches the cloud, it passes through a wrapped curl interface that implements the rate limiting logic.

Command Processing in alarm_interval.c

The AlarmInterval() function in libcallback/alarm_interval.c serves as the entry point for user configuration. This function parses the alarmInterval command, validates the input range (30–300 seconds), and updates the user configuration through SetUserConfig().

Crucially, the function sets the global throttle variable:

curl_minimum_alarm_cycle = (interval < 300) ? 300 : 0;

This logic enforces a hard minimum of 300 seconds (5 minutes) between uploads whenever the user configures an interval shorter than 5 minutes. If the interval is 300 seconds or greater, the throttle disables (set to 0).

Configuration Storage in alarm_config.c

The SetAlarmConfigInterval() function in libcallback/alarm_config.c propagates the interval value to every alarm configuration entry, covering both Atom and Wyze variants. This ensures the throttle setting persists across system components and remains accessible to the user interface and other subsystems.

Upload Enforcement in curl.c

The actual throttling occurs in libcallback/curl.c within the wrapped curl_easy_perform() function. When an alarm upload URL is detected (matching the alarmPath suffix), the function compares the current time against the last successful upload:

if (url && !strcmp(url + strlen(url) - strlen(alarmPath), alarmPath)) {
    static time_t lastAccess = 0;
    struct timeval now;
    gettimeofday(&now, NULL);
    if (disable || (now.tv_sec - lastAccess < curl_minimum_alarm_cycle)) {
        /* discard upload, return dummy response */
        memcpy(data->out, DummyRes, strlen(DummyRes));
        goto curl_ok;
    }
    /* real upload */
    CURLcode res = original_curl_easy_perform(data);
    if (!res) lastAccess = now.tv_sec;
    return res;
}

When the elapsed time since lastAccess is less than curl_minimum_alarm_cycle, the function discards the upload and returns a dummy JSON response (DummyRes) instead of executing the HTTP request. This effectively reduces the alarm period by preventing excessive cloud notifications.

Practical Configuration Examples

Setting a Short Alarm Interval

To configure a 45-second alarm interval (which triggers the 300-second minimum enforcement):

// Command sent via AT command interface
char *res = AlarmInterval(fd, "45");
printf("%s\n", res);   // prints "ok"

This sets curl_minimum_alarm_cycle to 300 seconds despite the 45-second request.

Verifying Current Throttle Settings

Check the active minimum cycle value:

extern int curl_minimum_alarm_cycle;
printf("Current minimum cycle: %d seconds\n", curl_minimum_alarm_cycle);

Simulating Throttled Uploads

When motion triggers within the throttle window:

CURLcode rc = curl_easy_perform(&session);
if (rc == CURL_OK) {
    printf("Upload succeeded or was throttled (dummy response)\n");
}

If throttled, the function returns CURL_OK but skips the actual HTTP transfer, returning the dummy response instead.

Summary

• Motion detection alarm period reduction prevents server overload by throttling cloud uploads through a configurable minimum interval enforced in the curl wrapper.
• The system enforces a hard floor of 300 seconds between uploads when users configure intervals shorter than 5 minutes, as implemented in libcallback/alarm_interval.c.
• Three components handle the logic: AlarmInterval() for command parsing, SetAlarmConfigInterval() for configuration storage, and curl_easy_perform() for upload enforcement.
• When throttled, the curl wrapper returns a dummy JSON response instead of performing the actual HTTP upload, effectively silencing redundant alarms during the cooldown period while maintaining local logging functionality.

Frequently Asked Questions

What is the minimum alarm interval I can configure?

While the alarmInterval command accepts values between 30 and 300 seconds, the firmware enforces a 300-second (5-minute) minimum between actual uploads. Setting any interval below 300 seconds triggers this hard floor in libcallback/alarm_interval.c, where the logic curl_minimum_alarm_cycle = (interval < 300) ? 300 : 0 ensures uploads cannot occur more frequently than every 5 minutes.

How does the system distinguish between alarm uploads and regular traffic?

The curl wrapper in libcallback/curl.c checks if the URL ends with the alarmPath suffix using string comparison: !strcmp(url + strlen(url) - strlen(alarmPath), alarmPath). Only URLs matching this pattern are subject to the curl_minimum_alarm_cycle throttle; other HTTP requests proceed normally without time-based restrictions.

What happens when an alarm is triggered during the throttle period?

When motion occurs within the minimum cycle window, curl_easy_perform() skips the HTTP upload and returns a dummy JSON response (DummyRes) to the caller. The function copies the dummy response into the output buffer and returns CURL_OK, preventing cloud notification spam while maintaining local logging functionality and avoiding error states in the calling code.

Where is the alarm configuration stored persistently?

The interval value is stored in the user configuration through SetUserConfig() and propagated to all alarm type entries via SetAlarmConfigInterval() in libcallback/alarm_config.c. This ensures the throttle setting persists across reboots and applies to both Atom and Wyze camera variants, with the global variable curl_minimum_alarm_cycle providing runtime access to the current throttle value.

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