FirmwareKit.Payload

A .NET Standard library for parsing and extracting Android OTA (Over-The-Air) payload files.

Features

• Parse and extract Android OTA payload.bin files
• Support for both local files and remote URLs
• Handle ZIP-wrapped payloads
• Extract specific partitions or all partitions
• Support for HTTP range requests for efficient remote access
• Comprehensive error handling with custom exceptions

Project Structure

FirmwareKit.Payload/
├── Core/                 # Core functionality for payload parsing
│   ├── PayloadParser.cs  # Main public API for parsing and extraction
│   ├── PayloadExtractor.cs# Handles partition extraction
│   ├── OperationProcessor.cs# Processes individual install operations
│   ├── PayloadHeader.cs   # Reads payload header
│   └── BigEndianReader.cs # Big-endian data reading utilities
├── IO/                   # Input/output utilities
│   ├── HttpOffsetStream.cs# Seekable stream over HTTP resource section
│   └── HttpRangeStream.cs # Seekable stream over entire HTTP resource
├── Remote/               # Remote resource handling
│   ├── RemotePayloadReader.cs # Utilities for remote payloads
│   └── RemoteZipReader.cs     # Utilities for remote ZIP files
├── Exceptions/           # Custom exception types
│   └── PayloadExceptions.cs   # Payload-related exceptions
├── Models/               # Data models
│   ├── PayloadMetadata.cs     # Parsed payload metadata
│   └── UpdateMetadata.cs      # Auto-generated Protobuf types
└── Payload.cs            # Public API entry point

Installation

NuGet Package

Install-Package FirmwareKit.Payload

Build from Source

git clone https://github.com/Uotan-Dev/FirmwareKit.Payload.git
cd FirmwareKit.Payload
dotnet build FirmwareKit.Payload/FirmwareKit.Payload.csproj -c Release

Usage

Basic Usage

using FirmwareKit.Payload;

// Get payload metadata from local file
var metadata = PayloadParser.GetPayloadMetadata("payload.bin");

// Get partition information
var partitions = PayloadParser.GetPartitionInfo("payload.bin");

// Extract all partitions
PayloadParser.Extract("payload.bin", outputDir: "./output");

// Extract specific partitions
PayloadParser.Extract("payload.bin", new[] { "boot", "system" }, "./output");

Remote URL Support

// Get metadata from remote URL
var metadata = await PayloadParser.GetPayloadMetadataFromUrlAsync("https://example.com/update.zip");

// Extract partitions from remote URL
await PayloadParser.ExtractFromUrlAsync("https://example.com/update.zip", outputDir: "./output");

// Extract only boot partitions
await PayloadParser.ExtractBootFromUrlAsync("https://example.com/update.zip", "./output");

API Reference

PayloadParser Class

Method	Description
GetPayloadMetadata(string filepath)	Reads payload metadata from a local file
GetPayloadMetadataAsync(string filepath)	Asynchronously reads payload metadata
GetPartitionInfo(string filepath)	Gets partition size information
Extract(string filepath, string[]? extractFiles, string? outputDir)	Extracts partitions from local file
ExtractAsync(string filepath, string[]? extractFiles, string? outputDir)	Asynchronously extracts partitions
ExtractAndroidMetadata(string filepath, string? outputPath)	Extracts Android metadata file
GetPayloadMetadataFromUrlAsync(string url)	Gets metadata from remote URL
ExtractFromUrlAsync(string url, string[]? extractFiles, string? outputDir)	Extracts partitions from remote URL
ExtractBootFromUrlAsync(string url, string? outputDir)	Extracts boot partitions from remote URL

Dependencies

• Google.Protobuf - Protobuf serialization
• BrotliSharpLib - Brotli decompression
• BsDiff - BsDiff patch support
• SharpCompress - BZip2/XZ decompression
• ZstdSharp.Port - Zstd decompression

License

This project is licensed under the MIT License - see the LICENSE file for details.