# How the AtomCam Tools Firmware Update Mechanism Works via GitHub Releases: A Technical Deep Dive > Explore the atomcam_tools firmware update mechanism that leverages GitHub Releases. Learn how the web UI, background daemon, and initramfs work together for seamless updates. - Repository: [Mitsuru Nakada/atomcam_tools](https://github.com/mnakada/atomcam_tools) - Tags: deep-dive - Published: 2026-03-07 --- **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`](https://github.com/mnakada/atomcam_tools/blob/main/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. ```javascript // From web/source/vue/Setting.vue ``` 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`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/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`. ```bash # 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. ```bash # 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`](https://github.com/mnakada/atomcam_tools/blob/main/web/source/vue/Setting.vue)**: Handles the frontend trigger and custom URL configuration. - **[`overlay_rootfs/scripts/webcmd.sh`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini)**: Configuration file (read by [`webcmd.sh`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/webcmd.sh) daemon. - **GitHub's latest release redirect** (`/releases/latest`) provides the canonical URL for automatic updates, though custom URLs via [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/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`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini) configuration file, [`webcmd.sh`](https://github.com/mnakada/atomcam_tools/blob/main/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.