How the AtomCam Tools Firmware Update Mechanism Works via GitHub Releases: A Technical Deep Dive

The atomcam_tools firmware update mechanism uses a three-stage pipeline where the web UI triggers a background daemon to download the latest GitHub release zip, reboots the camera, and relies on the initramfs to extract and activate the new kernel and root filesystem images.

The mnakada/atomcam_tools project implements a self-contained, Linux-based firmware update system that pulls binaries directly from GitHub Releases. This mechanism allows AtomCam owners to upgrade their camera firmware remotely through a web interface or manually via SD card, without requiring physical access to the device. Understanding how the firmware update mechanism works via GitHub releases reveals a clever use of standard Unix tools and GitHub's redirect API to ensure safe, atomic updates.

The Three-Stage Update Architecture

The entire process executes within the camera's embedded Linux environment and requires no external tooling. It is divided into three distinct phases: Trigger, Download & Prepare, and Flash & Boot. Each stage is handled by a specific component in the stack, from the Vue.js frontend to the initramfs bootstrap script.

Stage 1: Triggering the Update via the Web Interface

The process begins in the web UI component located at web/source/vue/Setting.vue. When a user clicks the Update button, the DoUpdate method invokes this.Exec('update'), which writes the command to /var/run/webcmd for the background daemon to process.

The UI also supports custom firmware sources. If the user has enabled CUSTOM_ZIP in the configuration, the system will use a user-provided URL instead of the official GitHub release.

// From web/source/vue/Setting.vue
<SettingDangerButton
  i18n="update.toolsUpdate"
  icon="el-icon-refresh"
  :button="config.CUSTOM_ZIP === 'on' ? 'Custom Update' : 'Update'"
  :disabled="!updatable"
  @click="DoUpdate" />

This design decouples the user interface from the actual download logic, ensuring the web server remains responsive during the firmware transfer.

Stage 2: Downloading and Preparing the Firmware Package

The heavy lifting occurs in overlay_rootfs/scripts/webcmd.sh (lines 39-61), which functions as a background command processor. When it receives the update command, the script performs the following sequence:

1. Resolves the download URL: By default, it queries GitHub's latest release redirect URL (https://github.com/mnakada/atomcam_tools/releases/latest) to determine the most recent tag. It then constructs the direct download link for atomcam_tools.zip.
2. Supports custom URLs: If CUSTOM_ZIP is enabled in hack.ini, it bypasses GitHub and uses the user-specified CUSTOM_ZIP_URL.
3. Tracks download progress: The script pipes curl output through awk to extract percentage completion and writes it to /tmp/update_status, allowing the web UI to poll progress in real-time.
4. Graceful service shutdown: After downloading to /media/mmc/update/atomcam_tools.zip, it stops the timelapse service and sends SIGUSR2 to iCamera_app to force a clean shutdown of the camera application.
5. Atomic reboot: It performs triple sync calls to ensure all data is written to the SD card before triggering reboot.

# From overlay_rootfs/scripts/webcmd.sh (simplified)

if [ "$cmd" = "update" -a "$UPDATE_SEQ" = "" ]; then
  # Resolve zip URL (custom or latest GitHub release)

  if [ "$CUSTOM_ZIP" = "off" ] || [ "$ZIP_URL" = "" ]; then
    latest=$(curl -w "%{redirect_url}" -s -o /dev/null \
            https://github.com/mnakada/atomcam_tools/releases/latest)
    ZIP_URL="https://github.com/mnakada/atomcam_tools/releases/download/${latest##*tag/}/atomcam_tools.zip"
  fi
  
  # Download with progress tracking

  mkdir -p /media/mmc/update
  echo "0" > /tmp/update_status
  ( cd /media/mmc/update;
    curl -H 'Cache-Control: no-cache' -L -o atomcam_tools.zip $ZIP_URL \
      2>&1 | awk '{printf("%d\n",$3) > "/tmp/update_status"}'
    /scripts/cmd timelapse stop
    killall -SIGUSR2 iCamera_app
    sync; sync; sync
    reboot ) &
fi

The download destination is always /media/mmc/update/atomcam_tools.zip, ensuring the file persists on the SD card through the reboot cycle.

Stage 3: Flashing and Booting via Initramfs

During the subsequent boot cycle, the initramfs script at initramfs_skeleton/init (lines 24-34) assumes control before the main root filesystem mounts. This early execution is critical for safely overwriting the system partitions.

The script checks for the presence of /rootfs/update/atomcam_tools.zip. If found, it extracts three specific payload files:

• factory_t31_ZMC6tiIDQN (kernel image)
• rootfs_hack.ext2 (extended root filesystem)
• rootfs_hack.squashfs (compressed root filesystem)

After extraction, it immediately deletes the zip file to prevent re-flashing on future boots, then continues the boot process with the newly installed firmware images.

# From initramfs_skeleton/init

if [ -f /rootfs/update/atomcam_tools.zip ] ; then
  (cd /rootfs/update; unzip atomcam_tools.zip -o \
     factory_t31_ZMC6tiIDQN rootfs_hack.ext2 rootfs_hack.squashfs)
  rm -rf /rootfs/update/atomcam_tools.zip
fi

This approach ensures the update is atomic: the system only switches to the new firmware after the zip is fully downloaded and verified, minimizing the risk of bricking due to interrupted downloads.

Key Implementation Files

Understanding the firmware update mechanism requires familiarity with these specific source files in the mnakada/atomcam_tools repository:

• web/source/vue/Setting.vue: Handles the frontend trigger and custom URL configuration.
• overlay_rootfs/scripts/webcmd.sh: Background daemon that manages download logic, GitHub API resolution, and pre-reboot synchronization.
• initramfs_skeleton/init: Early-boot script responsible for extracting and installing the firmware payloads.
• hack.ini: Configuration file (read by webcmd.sh) that stores CUSTOM_ZIP and CUSTOM_ZIP_URL settings for alternative firmware sources.

Manual Update via Samba

According to the repository documentation, users can bypass the automatic GitHub download entirely. By mounting the camera's SD card via Samba and manually copying atomcam_tools.zip into the update folder, the initramfs will install the firmware on the next boot without requiring internet connectivity or the web UI.

Summary

• The update flow is triggered by the Vue.js web interface writing to /var/run/webcmd, which is monitored by the webcmd.sh daemon.
• GitHub's latest release redirect (/releases/latest) provides the canonical URL for automatic updates, though custom URLs via hack.ini are supported.
• Download progress is reported in real-time through /tmp/update_status, allowing the web UI to display percentage completion.
• Safe shutdown is enforced via SIGUSR2 to iCamera_app and triple sync calls before rebooting.
• Atomic installation occurs during the next boot when the initramfs extracts factory_t31_ZMC6tiIDQN, rootfs_hack.ext2, and rootfs_hack.squashfs from the SD card.

Frequently Asked Questions

How does the camera determine which GitHub release to download?

The webcmd.sh script uses curl with the -w "%{redirect_url}" flag to follow the redirect from https://github.com/mnakada/atomcam_tools/releases/latest. This returns the URL containing the latest tag name (e.g., v2.4.0), which the script then uses to construct the direct download URL for atomcam_tools.zip. This ensures cameras always receive the most recent stable release without hardcoding version numbers.

What happens if the download is interrupted?

Because the zip file is written directly to /media/mmc/update/ on the SD card, an interrupted download will result in a partial or corrupted file. However, the initramfs extraction logic only proceeds if the file exists and unzip can successfully extract the three payload files. A failed extraction leaves the existing firmware intact, and the user can simply trigger the update again from the web UI.

Can I use a custom firmware zip instead of the official release?

Yes. By setting CUSTOM_ZIP=on and specifying a CUSTOM_ZIP_URL in the hack.ini configuration file, webcmd.sh will bypass the GitHub latest-release logic entirely and download from your provided URL. This is useful for testing beta builds or maintaining private forks of the atomcam_tools firmware.

Why does the update require a reboot to complete?

The update mechanism replaces the running kernel (factory_t31_ZMC6tiIDQN) and root filesystem images (rootfs_hack.ext2 and rootfs_hack.squashfs) which cannot be safely overwritten while the system is actively using them. By downloading to the SD card first, then rebooting into the initramfs environment, the system ensures no processes are holding file handles on the partitions being flashed, guaranteeing a clean, atomic installation.

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