Blackmagic firmware reverse engineering tools

This repository contains tools aid reverse engineering Blackmagic Design (ATEM, Web Presenter, etc.) devices' firmware/gateware update packages.

There are two parts to this software:

• libbmfw: library for parsing update packages
• bmfw: CLI tool for inspecting and extracting update packages

As this software is for reverse engineering undocumented file formats and has a pre-1.0 version label, its APIs, interfaces and MSRV should be considered unstable and subject to change at any time.

This is not intended to be a complete "solution" for reverse engineering or reflashing these devices. Other tools like Ghidra (with plugins) may help you here.

Getting started

There are no official binary builds of this software, so you'll need to install a recent Rust compiler toolchain with rustup.

You can then build everything with:

cargo build --release

The binary will be in target/release/bmfw or target/release/bmfw.exe.

You can then extract an update package with:

./target/release/bmfw extract /path/to/data-bde6.bin -o /tmp/bde6

Finding update packages

Update packages are named data-${PID}.bin, matching the device's USB product ID in lower case.

Some devices like the ATEM Television Studio have extra files for UI translations, which are suffixed with a language code.

These packages can be found in a few places:

• macOS:
  • /Applications/Blackmagic ATEM Switchers/ATEM Setup.app/Contents/Resources
  • /Library/Application Supports/Blackmagic Design/*/AdminUtility/Plugins/*/Resources
• Windows:
  • Program Files/Blackmagic Design/*/Setup/AdminUtility/Plugins/*/Resources
  • Program Files (x86)/Blackmagic Design/*/Atem Setup/PlugIns/*/Resources

You can find which firmware versions are included with a Blackmagic setup tool via its debug window: hold the Shift key and double-click the lower left corner of the window where you have a normal mouse cursor (rather than a resize handle).

The debug window cannot be accessed by pressing Tab or using accessibility tools.

Extract update packages from installers without installing

Blackmagic's software only allows one version to be installed at a time. This can be troublesome when comparing versions.

It is possible to extract update packages from the macOS and Windows installers without installing the software.

Extract macOS installers

Blackmagic software on macOS is distributed as a ZIP file containing a .dmg file containing one or more Installer .pkg files. .pkg files are XAR files, which can be extracted with the 7-Zip CLI (7z).

First, find the Payload segment of the main part of the .pkg file:

7z l "/Volumes/Blackmagic .../Install ....pkg" | grep Payload

For example, the main part of the ATEM Switchers package is in Switchers.pkg/Payload.

Next, extract that part:

mkdir /tmp/extract
cd /tmp/extract
7z e "/Volumes/Blackmagic .../Install ....pkg" PackageNameHere.pkg/Payload

Payload is a cpio file, which can also be inspected and extracted with 7z. To find files named like update packages (data-[0-9a-f]{4}(-[^/]+)?\.bin):

7z l Payload | egrep "data-[0-9a-f]{4}(-[^/]+)?\\.bin"

Entries will have the full path on disk where it'd be normally installed.

Once you've found the update package(s) you're interested in, extract with:

7z e Payload "./Applications/....app/Contents/Resources/data-ABCD.bin

Extract Windows installers

Blackmagic software on Windows is distributed as a ZIP file containing an .msi file, and sometimes also with one or more hidden .cab files. All files can be extracted with the 7-Zip GUI or its CLI (7z).

You can check if a .cab contains update packages by looking for files named like update packages with a shell script:

7z l ExampleSupportFile.cab | egrep "data_[0-9a-f]{4}(_[^/]+)?\\.bin"

For .msi files, the file names are a litle bit different:

7z l ExampleInstaller.msi | egrep -i "Data[0-9a-f]{4}"

You can extract these using similar steps to the macOS instructions (above).

Doing this with PowerShell is left as an exercise for the reader (as the Windows COM APIs for inspecting archives are not easy to use). Alternatively, you could run those shell scripts in MSYS2 or WSL. 😉

Data structure descriptions

There are notes for each data structure available as rustdoc comments. You can access these via:

• docs.rs of the latest tagged release
• Build the current docs locally with cargo doc -p libbmfw
• Read source file comments starting with /// in ./libbmfw/src

Update package structure

Blackmagic update package files consist of one or more resources:

• FPGA gateware, which is used for SDI/HDMI capture/switching and runs a MicroBlaze or PowerPC softcore
• ELF with software for the MicroBlaze (32-bit BE or LE) or PowerPC core
• tar archive containing non-executable resources (eg: fonts, images, strings)
• tar archive containing (encrypted?) gateware / software

Blackmagic device list

All devices have USB VID 0x1edb (Blackmagic Design).

"Family" refers to the setup / admin utility plugin used to configure and/or update the device.