Asgard

Asgard is a command-line client for downloading and inspecting Samsung firmware from the Firmware Update Server (FUS). It can decrypt firmware packages, inspect remote archives, extract individual files, and unpack logical partitions from Android super images without downloading the complete package first.

Features

• Query the latest firmware version for a model and CSC.
• Display and compare firmware release histories.
• Download encrypted or decrypted firmware with resume support.
• Inspect remote ZIP and TAR archives.
• Extract selected firmware archives or individual files.
• Decode LZ4-compressed and Android sparse images while extracting them.
• List and extract logical partitions from Android super images.
• Merge A/B payload and block OTAs with selectively downloaded base images.
• Verify local firmware files and generate JSON manifests.
• Save frequently used model and CSC combinations as profiles.
• Process multiple download jobs from TOML or JSON files.
• Produce machine-readable JSON output for automation.

Installation

Install the package from PyPI:

python3 -m pip install asgard-fus

Verify the installation:

asgard --help

Quick start

Check for the latest firmware available for a model and CSC:

asgard checkupdate SM-S721B EUX

Download and decrypt the latest firmware:

asgard download SM-S721B EUX --decrypt --resume --output ./downloads

List the files in the remote firmware package:

asgard download SM-S721B EUX --list-entries

Run asgard COMMAND --help for the complete set of options supported by a command.

Usage

OTA merging

Supply an OTA ZIP alongside a download to reconstruct its updated images:

asgard download SM-S938U VZW --ota update.zip --output ./updated

Asgard detects the OTA format and matches its AP/CSC versions against firmware history to obtain the complete base version, including the fourth component. If history has no unique complete match, supply a four-part --firmware explicitly. Asgard streams the required images from FUS, and verifies patch source data and available target hashes. Base images are located from archive contents and super metadata, including device-specific partition names; archive locations are not inferred from names. It merges all OTA partitions and full image files by default. It does not build a flashable Odin package or flash the device.

Inspect available targets or select only the outputs you need:

asgard ota-info update.zip
asgard download SM-S938U VZW --ota update.zip --ota-list-targets
asgard download SM-S938U VZW --ota update.zip --ota-partition 'system,vendor' --output ./updated
asgard download SM-S908B EUX --ota update.zip --ota-file 'vbmeta*' --output ./updated

--ota-partition and --ota-file accept repeated selectors, comma-separated names, and quoted glob patterns. Once either is supplied, only matching targets are produced. Full-replacement targets require no base download.

Downloaded images become the merge output in place. A/B operations are ordered to preserve their source data. A/B dependency buffers and block-OTA stashes stay entirely in RAM, without application-managed spill files. Individual patch operations also need working memory; reduce --ota-jobs or select fewer partitions if RAM is limited. The operating system may still swap memory according to its settings. Compressed firmware packages and super.img are not staged to disk.

Use --ota-base-dir DIR for existing base images, or repeat --ota-base-image PARTITION=PATH to supply individual images. Local raw images remain unchanged; LZ4 and Android sparse inputs are decoded automatically. Slotted base images prefer _a automatically; --ota-base-image overrides this. --ota-keep-base explicitly retains downloaded bases, using separate outputs.

--resume checks completed outputs before reusing them. Interrupted merges restart from their base; they do not resume from partially patched images. --ota-jobs N overrides automatic worker selection, and --ota-force permits replacing existing outputs or overriding the declared base version. Source hash checks still apply unless --ota-no-verify is explicitly supplied.

Supported payload operations are REPLACE, REPLACE_BZ, REPLACE_XZ, SOURCE_COPY, SOURCE_BSDIFF, BROTLI_BSDIFF, ZERO, and DISCARD. Block OTAs support BSDIFF patches, move, new, zero, erase, stash, and free commands. Unsupported operations and payloads requiring generated verity/FEC data are rejected before base downloads. ZIP contents and hashes are checked; OTA signing certificates are not authenticated.

Firmware information

Display the latest firmware version:

asgard checkupdate SM-S721B EUX

Display the release history:

asgard history SM-S721B EUX
asgard history SM-S721B EUX --json

Compare the histories of two CSCs:

asgard compare SM-S721B EUX ZTO
asgard compare SM-S721B EUX ZTO --json

Use --firmware-a and --firmware-b to compare specific releases instead of the latest releases.

Firmware downloads

Download the latest encrypted package:

asgard download SM-S721B EUX --output ./downloads --resume

Download and decrypt the package in one operation:

asgard download SM-S721B EUX --output ./downloads --decrypt --resume

Download a specific firmware version:

asgard download SM-S721B EUX \
  --firmware S721BXXSACZB2/S721BOXMACZB2/S721BXXSACZB2/S721BXXSACZB2 \
  --output ./downloads

The following options control download behavior:

Option	Description
--resume	Resume an interrupted download or extraction operation.
--threads N	Use a fixed limit of N download workers, or N decryption workers.
--timeout SECONDS	Set the network request timeout.
--limit-rate RATE	Limit the aggregate transfer rate, for example 500K, 10M, or 1GiB.
--quiet	Suppress informational and progress output.
--json	Write machine-readable JSON to standard output.

Full downloads use four workers by default; --threads overrides this limit. Workers share 16–128 MiB ranges based on remaining size and worker count, so faster connections can pick up more work. Larger requests reduce handoff pauses on large downloads. Adjacent unfinished ranges are combined when resuming.

Resume progress is independent of worker count. You can change --threads between runs; valid progress from older resume files is retained too. The partial data file and its .resume.json file must both be present.

Archive inspection and extraction

List the archives in a firmware package:

asgard download SM-S721B EUX --list-entries

List the files in the AP archive:

asgard download SM-S721B EUX --archive AP --list-entries

Download one or more archives. Archive selectors accept names and glob patterns:

asgard download SM-S721B EUX --archive BL --output ./downloads --resume
asgard download SM-S721B EUX --archive '*.zip' --output ./downloads --resume

Extract a single file from an archive:

asgard download SM-S721B EUX \
  --archive AP \
  --file super.img.lz4 \
  --output ./downloads \
  --resume

LZ4 and Android sparse images are decoded automatically. Pass --keep-sparse to retain the Android sparse representation:

asgard download SM-S721B EUX \
  --archive AP \
  --file super.img.lz4 \
  --keep-sparse \
  --output ./downloads \
  --resume

Super images

List the logical partitions in the super image contained in an archive:

asgard download SM-S721B EUX --archive AP --list-partitions

Extract selected logical partitions:

asgard download SM-S721B EUX \
  --archive AP \
  --partition system \
  --partition vendor \
  --output ./downloads \
  --resume

Extract every logical partition:

asgard download SM-S721B EUX \
  --archive AP \
  --unpack-super \
  --output ./downloads \
  --resume

When extraction is resumed, Asgard preserves the source stream locally. This allows transformed LZ4 and sparse outputs to be rebuilt without downloading the source data again.

Decryption

Decrypt an existing FUS package:

asgard decrypt SM-S721B EUX ./firmware.zip.enc4 \
  --output ./firmware.zip \
  --resume

Specify the firmware version when the package is not the latest release:

asgard decrypt SM-S721B EUX ./firmware.zip.enc4 \
  --firmware S721BXXSACZB2/S721BOXMACZB2/S721BXXSACZB2/S721BXXSACZB2 \
  --output ./firmware.zip

Use --enc-ver 2 for ENC2 packages. ENC2 decryption always requires an explicit firmware version.

Profiles

Profiles assign a name to a model and CSC combination:

asgard profile add my-phone SM-S721B EUX
asgard profile list
asgard profile show my-phone

The profile name can then be used in place of the model and CSC:

asgard checkupdate my-phone
asgard download my-phone --output ./downloads --resume

Remove a profile when it is no longer required:

asgard profile remove my-phone

Profiles are stored in $XDG_CONFIG_HOME/asgard when XDG_CONFIG_HOME is set, or in ~/.config/asgard otherwise.

Batch downloads

Batch files may be written in TOML or JSON. A TOML batch file uses one [[downloads]] table for each job:

[[downloads]]
profile = "my-phone"
output = "./downloads"
decrypt = true
resume = true
manifest = ""

[[downloads]]
model = "SM-S721B"
region = "ZTO"
firmware = "S721BXXSDDZG1/S721BOWODDZG1/S721BXXSDDZG1/S721BXXSDDZG1"
output = "./downloads"
threads = 4
limit_rate = "20M"

Run the batch:

asgard batch firmware.toml

Validate the jobs without downloading any files:

asgard batch firmware.toml --dry-run --json

A JSON batch file may contain either an array of job objects or an object with a downloads array.

Verification and manifests

Verify a local package or image:

asgard verify ./firmware.zip
asgard verify ./super.img --json

Verification calculates SHA-256 and MD5 digests. It also validates ZIP CRCs, TAR structure, AES block alignment for encrypted FUS packages, and Android sparse-image structure where applicable.

Generate a JSON manifest for an existing file:

asgard manifest ./firmware.zip \
  --model SM-S721B \
  --region EUX \
  --firmware S721BXXSACZB2/S721BOXMACZB2/S721BXXSACZB2/S721BXXSACZB2

Generate a manifest when downloading or decrypting firmware:

asgard download SM-S721B EUX --decrypt --output ./downloads --manifest

Manifests contain hashes and archive entry metadata. A manifest generated for super.img or super.img.lz4 also contains logical partition metadata.

Exit status

Asgard exits with status 0 when a command completes successfully. Invalid usage and missing input files return status 2; operational and network errors return status 1.

Contributing

Bug reports and pull requests are welcome. Before submitting a change, run the configured linter:

ruff check asgard

License

Asgard is licensed under the GNU General Public License v3.0 only. See LICENSE for the complete license text.