# o-gs/dji-firmware-tools architecture

> Architecture diagram of the GitHub repository o-gs/dji-firmware-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/o-gs/dji-firmware-tools
- Repository: https://github.com/o-gs/dji-firmware-tools
- Video tour (about a minute): https://gitdiagram.com/o-gs/dji-firmware-tools/video

## Overview

dji-firmware-tools is a collection of DJI drone firmware research, modification, and device-communication utilities. The main file workflow extracts xV4 packages, decrypts or unpacks firmware layers, edits or analyzes modules, and repackages them. Separate branches handle live drone and smart-battery communication, plus capture and protocol analysis. The README documents several format workflows; source excerpts are partial, so uncertain internal calls are not shown.

Main entry points: [`amba_fwpak.py`](https://github.com/o-gs/dji-firmware-tools/blob/master/amba_fwpak.py) (Ambarella partitions), [`comm_sbs_bqctrl.py`](https://github.com/o-gs/dji-firmware-tools/blob/master/comm_sbs_bqctrl.py) (Battery control), [`dji_xv4_fwcon.py`](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_xv4_fwcon.py) (xV4 container), [`dji_imah_fwsig.py`](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_imah_fwsig.py) (IMaH signing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware formats"]
  node_xv4["xV4 container<br/>[dji_xv4_fwcon.py]"]
  node_imah["IMaH signing<br/>[dji_imah_fwsig.py]"]
  node_mvfc["MVFC decryptor<br/>[dji_mvfc_fwpak.py]"]
  node_amba["Ambarella partitions<br/>[amba_fwpak.py]"]
  node_romfs["ROMFS filesystem<br/>[amba_romfs.py]"]
  node_ubifs["UBIFS filesystem<br/>[amba_ubifs.sh]"]
  node_modules["Firmware modules"]
end

subgraph group_binary["Binary analysis"]
  node_elfconvert["ELF converters<br/>[amba_sys2elf.py]"]
  node_armconvert["ARM binary converter<br/>[arm_bin2elf.py]"]
  node_hardcoders["Firmware editors"]
  node_paramedit["Parameter editor"]
  node_nofly["No-fly editor"]
  node_flightlog["Flight log parser<br/>[comm_dat2pcap.py]"]
end

subgraph group_device["Device communication"]
  node_service["Service commands"]
  node_serial["Serial tools<br/>[comm_serialtalk.py]"]
  node_battery["Battery control<br/>[comm_sbs_bqctrl.py]"]
  node_chips["Gauge definitions"]
end

subgraph group_protocol["Protocol research"]
  node_capture["Packet capture"]
  node_dissector["Wireshark dissectors"]
  node_protocoltools["Dissector helpers"]
end

node_engineer(("Engineer"))
node_package["Firmware package"]
node_drone(("DJI drone"))
node_pcap["Capture file"]

node_engineer -->|"extract or build"| node_xv4
node_package -->|"read package"| node_xv4
node_xv4 -->|"extract modules"| node_modules
node_engineer -->|"decrypt or sign"| node_imah
node_modules -->|"read IMaH module"| node_imah
node_imah -.->|"remove first layer"| node_mvfc
node_mvfc -->|"decrypt module"| node_modules
node_engineer -->|"extract or merge"| node_amba
node_modules -->|"read Ambarella firmware"| node_amba
node_amba -->|"extract filesystem"| node_romfs
node_amba -.->|"process UBIFS"| node_ubifs
node_engineer -->|"convert binary"| node_elfconvert
node_modules -->|"convert SYS partition"| node_elfconvert
node_engineer -->|"convert binary"| node_armconvert
node_engineer -->|"edit firmware values"| node_hardcoders
node_elfconvert -->|"supply ELF"| node_hardcoders
node_armconvert -.->|"supply ELF"| node_hardcoders
node_engineer -->|"modify parameters"| node_paramedit
node_engineer -->|"edit no-fly data"| node_nofly
node_engineer -->|"request service action"| node_service
node_service -->|"send commands"| node_drone
node_engineer -->|"communicate"| node_serial
node_serial -->|"serial exchange"| node_drone
node_engineer -->|"read or control"| node_battery
node_battery -->|"use chip definitions"| node_chips
node_battery -->|"SMBus or I2C"| node_drone
node_engineer -->|"capture traffic"| node_capture
node_drone -->|"serial traffic"| node_capture
node_capture -->|"write capture"| node_pcap
node_pcap -->|"analyze packets"| node_dissector
node_engineer -->|"inspect protocols"| node_dissector
node_protocoltools -->|"generate dissectors"| node_dissector
node_engineer -->|"parse flight logs"| node_flightlog

click node_xv4 "https://github.com/o-gs/dji-firmware-tools/blob/master/dji_xv4_fwcon.py"
click node_imah "https://github.com/o-gs/dji-firmware-tools/blob/master/dji_imah_fwsig.py"
click node_mvfc "https://github.com/o-gs/dji-firmware-tools/blob/master/dji_mvfc_fwpak.py"
click node_amba "https://github.com/o-gs/dji-firmware-tools/blob/master/amba_fwpak.py"
click node_romfs "https://github.com/o-gs/dji-firmware-tools/blob/master/amba_romfs.py"
click node_ubifs "https://github.com/o-gs/dji-firmware-tools/blob/master/amba_ubifs.sh"
click node_elfconvert "https://github.com/o-gs/dji-firmware-tools/blob/master/amba_sys2elf.py"
click node_armconvert "https://github.com/o-gs/dji-firmware-tools/blob/master/arm_bin2elf.py"
click node_hardcoders "https://github.com/o-gs/dji-firmware-tools/blob/master/dji_flyc_hardcoder.py"
click node_paramedit "https://github.com/o-gs/dji-firmware-tools/blob/master/dji_flyc_param_ed.py"
click node_nofly "https://github.com/o-gs/dji-firmware-tools/blob/master/dji_flyc_nofly_ed.py"
click node_flightlog "https://github.com/o-gs/dji-firmware-tools/blob/master/comm_dat2pcap.py"
click node_service "https://github.com/o-gs/dji-firmware-tools/blob/master/comm_og_service_tool.py"
click node_serial "https://github.com/o-gs/dji-firmware-tools/blob/master/comm_serialtalk.py"
click node_battery "https://github.com/o-gs/dji-firmware-tools/blob/master/comm_sbs_bqctrl.py"
click node_chips "https://github.com/o-gs/dji-firmware-tools/tree/master/comm_sbs_chips"
click node_capture "https://github.com/o-gs/dji-firmware-tools/blob/master/comm_serial2pcap.py"
click node_dissector "https://github.com/o-gs/dji-firmware-tools/tree/master/comm_dissector/wireshark"
click node_protocoltools "https://github.com/o-gs/dji-firmware-tools/tree/master/comm_dissector/helpers"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_xv4,node_imah,node_mvfc,node_amba,node_romfs,node_ubifs,node_modules toneBlue
class node_elfconvert,node_armconvert,node_hardcoders,node_paramedit,node_nofly,node_flightlog toneAmber
class node_service,node_serial,node_battery,node_chips toneMint
class node_capture,node_dissector,node_protocoltools toneRose
class node_engineer,node_package,node_drone,node_pcap toneIndigo
```

## Components

### Firmware formats

- [xV4 container](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_xv4_fwcon.py): `dji_xv4_fwcon.py`
- [IMaH signing](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_imah_fwsig.py): `dji_imah_fwsig.py`
- [MVFC decryptor](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_mvfc_fwpak.py): `dji_mvfc_fwpak.py`
- [Ambarella partitions](https://github.com/o-gs/dji-firmware-tools/blob/master/amba_fwpak.py): `amba_fwpak.py`
- [ROMFS filesystem](https://github.com/o-gs/dji-firmware-tools/blob/master/amba_romfs.py): `amba_romfs.py`
- [UBIFS filesystem](https://github.com/o-gs/dji-firmware-tools/blob/master/amba_ubifs.sh): `amba_ubifs.sh`
- **Firmware modules**

### Binary analysis

- [ELF converters](https://github.com/o-gs/dji-firmware-tools/blob/master/amba_sys2elf.py): `amba_sys2elf.py`
- [ARM binary converter](https://github.com/o-gs/dji-firmware-tools/blob/master/arm_bin2elf.py): `arm_bin2elf.py`
- [Firmware editors](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_flyc_hardcoder.py): `dji_flyc_hardcoder.py`
- [Parameter editor](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_flyc_param_ed.py): `dji_flyc_param_ed.py`
- [No-fly editor](https://github.com/o-gs/dji-firmware-tools/blob/master/dji_flyc_nofly_ed.py): `dji_flyc_nofly_ed.py`
- [Flight log parser](https://github.com/o-gs/dji-firmware-tools/blob/master/comm_dat2pcap.py): `comm_dat2pcap.py`

### Device communication

- [Service commands](https://github.com/o-gs/dji-firmware-tools/blob/master/comm_og_service_tool.py): `comm_og_service_tool.py`
- [Serial tools](https://github.com/o-gs/dji-firmware-tools/blob/master/comm_serialtalk.py): `comm_serialtalk.py`
- [Battery control](https://github.com/o-gs/dji-firmware-tools/blob/master/comm_sbs_bqctrl.py): `comm_sbs_bqctrl.py`
- [Gauge definitions](https://github.com/o-gs/dji-firmware-tools/tree/master/comm_sbs_chips): `comm_sbs_chips`

### Protocol research

- [Packet capture](https://github.com/o-gs/dji-firmware-tools/blob/master/comm_serial2pcap.py): `comm_serial2pcap.py`
- [Wireshark dissectors](https://github.com/o-gs/dji-firmware-tools/tree/master/comm_dissector/wireshark): `comm_dissector/wireshark`
- [Dissector helpers](https://github.com/o-gs/dji-firmware-tools/tree/master/comm_dissector/helpers): `comm_dissector/helpers`

### Other components

- **Engineer**
- **Firmware package**
- **DJI drone**
- **Capture file**

## Connections

- Engineer → xV4 container: extract or build
- Firmware package → xV4 container: read package
- xV4 container → Firmware modules: extract modules
- Engineer → IMaH signing: decrypt or sign
- Firmware modules → IMaH signing: read IMaH module
- IMaH signing → MVFC decryptor: remove first layer
- MVFC decryptor → Firmware modules: decrypt module
- Engineer → Ambarella partitions: extract or merge
- Firmware modules → Ambarella partitions: read Ambarella firmware
- Ambarella partitions → ROMFS filesystem: extract filesystem
- Ambarella partitions → UBIFS filesystem: process UBIFS
- Engineer → ELF converters: convert binary
- Firmware modules → ELF converters: convert SYS partition
- Engineer → ARM binary converter: convert binary
- Engineer → Firmware editors: edit firmware values
- ELF converters → Firmware editors: supply ELF
- ARM binary converter → Firmware editors: supply ELF
- Engineer → Parameter editor: modify parameters
- Engineer → No-fly editor: edit no-fly data
- Engineer → Service commands: request service action
- Service commands → DJI drone: send commands
- Engineer → Serial tools: communicate
- Serial tools → DJI drone: serial exchange
- Engineer → Battery control: read or control
- Battery control → Gauge definitions: use chip definitions
- Battery control → DJI drone: SMBus or I2C
- Engineer → Packet capture: capture traffic
- DJI drone → Packet capture: serial traffic
- Packet capture → Capture file: write capture
- Capture file → Wireshark dissectors: analyze packets
- Engineer → Wireshark dissectors: inspect protocols
- Dissector helpers → Wireshark dissectors: generate dissectors
- Engineer → Flight log parser: parse flight logs