Metadata-Version: 2.4
Name: asgard-fus
Version: 3.5.0
Summary: Samsung Firmware Update Server client
Author: ducthoe
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/ducthoe/asgard
Project-URL: Source, https://github.com/ducthoe/asgard
Project-URL: Issues, https://github.com/ducthoe/asgard/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Brotli>=1.1.0
Requires-Dist: bsdiff4>=1.2.6
Requires-Dist: indexed-gzip>=1.10.3
Requires-Dist: lz4>=4.3.2
Requires-Dist: pycryptodomex>=3.20.0
Requires-Dist: requests>=2.0.0
Dynamic: license-file

<!--
Copyright (C) 2026 ducthoe
SPDX-License-Identifier: GPL-3.0-only
-->

# 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:

```console
python3 -m pip install asgard-fus
```

Verify the installation:

```console
asgard --help
```

## Quick start

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

```console
asgard checkupdate SM-S721B EUX
```

Download and decrypt the latest firmware:

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

List the files in the remote firmware package:

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

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

```console
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 retain
up to 32 MiB per worker in RAM, spilling additional data to temporary storage.
Individual patch operations also need working memory. `--ota-work-dir DIR` places
overflow buffers on another disk or RAM storage. Temporary data is removed automatically.
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:

```console
asgard checkupdate SM-S721B EUX
```

Display the release history:

```console
asgard history SM-S721B EUX
asgard history SM-S721B EUX --json
```

Compare the histories of two CSCs:

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

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

Download and decrypt the package in one operation:

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

Download a specific firmware version:

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

```console
asgard download SM-S721B EUX --list-entries
```

List the files in the AP archive:

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

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

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

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

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

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

Extract selected logical partitions:

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

Extract every logical partition:

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

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

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

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

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

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

Remove a profile when it is no longer required:

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

```toml
[[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:

```console
asgard batch firmware.toml
```

Validate the jobs without downloading any files:

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

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

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

Generate a manifest when downloading or decrypting firmware:

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

```console
ruff check asgard
```

## License

Asgard is licensed under the GNU General Public License v3.0 only. See
[`LICENSE`](LICENSE) for the complete license text.
