Unpacking and repacking Elektron firmware
A quick start with elektron-firmware-tool - https://github.com/mischa85/elektron-firmware-tool
Elektron ships OS updates as a .syx file. It contains the firmware, wrapped in SysEx messages, compressed and protected by checksums. The open-source elektron-firmware-tool by mischa85 unpacks the firmware and, after you change something, packs it back into a valid file.
It works with practically every Elektron device: Digitakt, Digitone, Syntakt, Analog Rytm/Four/Heat, Octatrack, Model:Samples/Cycles, Machinedrum and Monomachine. Every screenshot in this tutorial shows real output.
All commands at a glance
1. Preparation
You need a C compiler and Git:
Create a working folder. All commands in this tutorial run inside it:
Along the way you will add the subfolders extracted/ (unpacked), work/ (your changes), build/ (new .syx) and verify/ (checks).
2. Install the tool
![[Image: 01-build.png]](https://i.ibb.co/JW5LnWWB/01-build.png)
① The program is built. There should be no warnings or errors.
② Makes the elektron-firmware-tool command available in the current terminal window. In a new window you need to run this line again, otherwise you get "command not found". To make it permanent, add it to ~/.zshrc or ~/.bashrc.
3. Get the firmware
Download the OS for your device from the Elektron website (Support & Downloads → your device → OS) and copy the .syx file into original/.
Tip:chmod a-w original/*.syx protects the original from being overwritten by accident.
Sound, pattern and project dumps are .syx files too, but they are not firmware. For those the tool reports "is not a recognizable Elektron OS .syx".
4. Inspect the firmware
![[Image: 02-inspect.png]](https://i.ibb.co/1tZS6pS3/02-inspect.png)
① Device and OS version.
② The firmware's sections with their IDs. You need these IDs for -d and -c. "(raw)" means stored uncompressed.
③ All checksums match, the file is fine.
More detail with -v
![[Image: 03-verbose.png]](https://i.ibb.co/XZTzYFwc/03-verbose.png)
① SysEx transport: the data is spread across 18,668 SysEx messages. Because MIDI carries only 7 bits per byte, it is "8-in-7" encoded. Every packet has its own checksum.
② Container (ELE3): model number, version and a checksum over the entire content.
③ Section table: position (off), packed length (clen) and load address in memory (dst) of each section.
④ MAIN OS is loaded at address 0x40000400. You will need this if you open the code in a disassembler later.
⑤ HMAC-SHA256: a signature over the whole container. The tool recomputes it automatically when repacking. We masked the key in the screenshot.
![[Image: 00-anatomy-en.png]](https://i.ibb.co/4R4txLFM/00-anatomy-en.png)
In short: mods almost always go into section 3 (MAIN OS), the actual operating system. Keep your hands off section 2 (bootstrap) and 4 (updater): the bootloader holds your device's recovery menu. The tool assigns the section names based on content. On other devices the IDs and sections can differ; the output of -i is always what counts.
Self-test (optional)
-r repacks the file without changes. If you get exactly the same file back, the tool handles your firmware losslessly. With Digitone II firmware 1.11 it does.
5. Extract the firmware
![[Image: 04-extract.png]](https://i.ibb.co/JWXpYjpY/04-extract.png)
①.raw was already uncompressed and was copied 1:1. .bin was decompressed.
② Section 8 has no known name, hence the "?" in the file name. Best rename it right away:
To extract single sections, use -d with the ID (repeatable). If the ID does not exist, the tool reports "no section id=…".
Important: don't edit anything in extracted/. These are your originals for comparison.
6. Edit a section
As an example, we replace the text UNTITLED in MAIN OS with ELEKMODS. This only demonstrates the workflow and was not tested on hardware.
Three rules
6.1 Find the location
![[Image: 05-find.png]](https://i.ibb.co/Dfg4yqjd/05-find.png)
① Position (offset) of the text in the file, as a decimal number.
② The same offset in hex. This is how hex editors show it.
③ The text in the hex dump, with the 00 byte at the end.
6.2 Change the bytes
With a hex editor such as Hex Fiend (macOS), HxD (Windows) or ImHex (all systems): open the file, jump to offset 0x211E37, type the new text in overwrite mode, save.
Or in the terminal:
![[Image: 06-patch.png]](https://i.ibb.co/9RDTQts/06-patch.png)
① Writes exactly 8 bytes at that position. Don't forget conv=notrunc, otherwise the file is cut off after it.
②cmp -l shows every changed byte (position counted from 1, values in octal). 8 lines means exactly 8 bytes changed and nothing else.
③ Double-check: ELEKMODS is in the right place.
7. Repack the firmware
![[Image: 07-rebuild.png]](https://i.ibb.co/Swk17PB4/07-rebuild.png)
① The original serves as the template (-i), section 3 is replaced with your file (-c 3), and the new file is written to -o. All other sections stay unchanged.
② The section is compressed again automatically.
③ Checksums and HMAC are recomputed.
④ The new file is smaller than the original. That is expected, because the tool compresses slightly better than Elektron. The content is still identical, see step 8.
Options when repacking
8. Verify the result
![[Image: 08-verify.png]](https://i.ibb.co/PvRfc2Y3/08-verify.png)
① All checksums of the new file are valid.
② The section from the new .syx is byte-for-byte identical to your edited file, so packing and unpacking were lossless.
Done!build/Digitone_II_OS1.11-mod.syx contains your change, and all checksums match.
Questions, additions or your own findings are welcome in this thread.
elektron-firmware-tool is written by mischa85 and released under the MIT licence (GitHub). Neither the tool nor this tutorial is affiliated with Elektron. Elektron, Digitone, Digitakt and other product names are trademarks of Elektron Music Machines MAV AB.
A quick start with elektron-firmware-tool - https://github.com/mischa85/elektron-firmware-tool
Elektron ships OS updates as a .syx file. It contains the firmware, wrapped in SysEx messages, compressed and protected by checksums. The open-source elektron-firmware-tool by mischa85 unpacks the firmware and, after you change something, packs it back into a valid file.
It works with practically every Elektron device: Digitakt, Digitone, Syntakt, Analog Rytm/Four/Heat, Octatrack, Model:Samples/Cycles, Machinedrum and Monomachine. Every screenshot in this tutorial shows real output.
Quote:Please read first
The tool is unofficial and not affiliated with Elektron. Modified firmware can brick your device; everything you do is at your own risk. Only work with devices you own and with firmware you downloaded officially from Elektron. Please do not post .syx files on the forum; the firmware is protected by copyright.
All commands at a glance
Code:
elektron-firmware-tool -i OS.syx summary, check checksums
elektron-firmware-tool -i OS.syx -v detailed report
elektron-firmware-tool -i OS.syx -o folder extract all sections
elektron-firmware-tool -i OS.syx -d 3 -o folder extract section 3 only
elektron-firmware-tool -i OS.syx -c 3 new.bin -o mod.syx replace section 3, repack
elektron-firmware-tool -i OS.syx -r -o copy.syx repack unchanged (self-test)
Extra options:
-V 1.11 set the version string (no longer than the old one)
-l 0..3 compression when packing: 0 = fast, 3 = small (default)
--emit-container c.bin also save the raw container to a file1. Preparation
You need a C compiler and Git:
- macOS: xcode-select --install
- Linux (Debian/Ubuntu): sudo apt install build-essential git xxd
- Windows: set up WSL with Ubuntu (wsl --install), then continue as on Linux. Work in your Linux home (~), not under /mnt/c, because one file name will contain a "?", which Windows does not allow.
Create a working folder. All commands in this tutorial run inside it:
Code:
mkdir -p ~/elektron-mods/original && cd ~/elektron-mods2. Install the tool
Code:
git clone https://github.com/mischa85/elektron-firmware-tool.git
cd elektron-firmware-tool && make
cd ..
export PATH="$PWD/elektron-firmware-tool:$PATH"① The program is built. There should be no warnings or errors.
② Makes the elektron-firmware-tool command available in the current terminal window. In a new window you need to run this line again, otherwise you get "command not found". To make it permanent, add it to ~/.zshrc or ~/.bashrc.
3. Get the firmware
Download the OS for your device from the Elektron website (Support & Downloads → your device → OS) and copy the .syx file into original/.
Tip:chmod a-w original/*.syx protects the original from being overwritten by accident.
Sound, pattern and project dumps are .syx files too, but they are not firmware. For those the tool reports "is not a recognizable Elektron OS .syx".
4. Inspect the firmware
Code:
elektron-firmware-tool -i original/Digitone_II_OS1.11.syx① Device and OS version.
② The firmware's sections with their IDs. You need these IDs for -d and -c. "(raw)" means stored uncompressed.
③ All checksums match, the file is fine.
More detail with -v
Code:
elektron-firmware-tool -i original/Digitone_II_OS1.11.syx -v① SysEx transport: the data is spread across 18,668 SysEx messages. Because MIDI carries only 7 bits per byte, it is "8-in-7" encoded. Every packet has its own checksum.
② Container (ELE3): model number, version and a checksum over the entire content.
③ Section table: position (off), packed length (clen) and load address in memory (dst) of each section.
④ MAIN OS is loaded at address 0x40000400. You will need this if you open the code in a disassembler later.
⑤ HMAC-SHA256: a signature over the whole container. The tool recomputes it automatically when repacking. We masked the key in the screenshot.
In short: mods almost always go into section 3 (MAIN OS), the actual operating system. Keep your hands off section 2 (bootstrap) and 4 (updater): the bootloader holds your device's recovery menu. The tool assigns the section names based on content. On other devices the IDs and sections can differ; the output of -i is always what counts.
Self-test (optional)
Code:
mkdir -p build
elektron-firmware-tool -i original/Digitone_II_OS1.11.syx -r -o build/repacked.syx
cmp original/Digitone_II_OS1.11.syx build/repacked.syx && echo "byte-identical"5. Extract the firmware
Code:
elektron-firmware-tool -i original/Digitone_II_OS1.11.syx -o extracted①.raw was already uncompressed and was copied 1:1. .bin was decompressed.
② Section 8 has no known name, hence the "?" in the file name. Best rename it right away:
Code:
mv "extracted/section_8_?.bin" extracted/section_8_unknown.binTo extract single sections, use -d with the ID (repeatable). If the ID does not exist, the tool reports "no section id=…".
Code:
elektron-firmware-tool -i original/Digitone_II_OS1.11.syx -d 3 -o extractedImportant: don't edit anything in extracted/. These are your originals for comparison.
6. Edit a section
As an example, we replace the text UNTITLED in MAIN OS with ELEKMODS. This only demonstrates the workflow and was not tested on hardware.
Three rules
- Only overwrite, never insert or delete bytes. The file must stay exactly the same size, otherwise every address after the change shifts.
- Keep strings the same length and only use characters that already appear there (here: capital letters). The 00 byte at the end of the text stays in place.
- Always work on a copy in work/.
6.1 Find the location
Code:
mkdir work
cp extracted/section_3_MAIN_OS.bin work/section_3_MAIN_OS.mod.bin
grep -obUa "UNTITLED" work/section_3_MAIN_OS.mod.bin
printf '0x%X\n' 2170423
xxd -s 0x211E27 -l 48 work/section_3_MAIN_OS.mod.bin① Position (offset) of the text in the file, as a decimal number.
② The same offset in hex. This is how hex editors show it.
③ The text in the hex dump, with the 00 byte at the end.
6.2 Change the bytes
With a hex editor such as Hex Fiend (macOS), HxD (Windows) or ImHex (all systems): open the file, jump to offset 0x211E37, type the new text in overwrite mode, save.
Or in the terminal:
Code:
printf 'ELEKMODS' | dd of=work/section_3_MAIN_OS.mod.bin bs=1 seek=2170423 conv=notrunc
cmp -l extracted/section_3_MAIN_OS.bin work/section_3_MAIN_OS.mod.bin
xxd -s 0x211E27 -l 48 work/section_3_MAIN_OS.mod.bin① Writes exactly 8 bytes at that position. Don't forget conv=notrunc, otherwise the file is cut off after it.
②cmp -l shows every changed byte (position counted from 1, values in octal). 8 lines means exactly 8 bytes changed and nothing else.
③ Double-check: ELEKMODS is in the right place.
7. Repack the firmware
Code:
mkdir -p build
elektron-firmware-tool -i original/Digitone_II_OS1.11.syx \
-c 3 work/section_3_MAIN_OS.mod.bin \
-o build/Digitone_II_OS1.11-mod.syx① The original serves as the template (-i), section 3 is replaced with your file (-c 3), and the new file is written to -o. All other sections stay unchanged.
② The section is compressed again automatically.
③ Checksums and HMAC are recomputed.
④ The new file is smaller than the original. That is expected, because the tool compresses slightly better than Elektron. The content is still identical, see step 8.
Options when repacking
- -l 0 to -l 3: compression level. The default 3 gives the smallest file (about 14 seconds here). -l 0 is roughly 18 times faster and about 3 % larger, good for experimenting.
- Several sections at once: repeat -c, e.g. -c 3 a.bin -c 7 b.bin.
- -V sets the version string. It must be no longer than the old one (here 4 characters like "1.11"), otherwise the tool reports "too long for field; unchanged".
8. Verify the result
Code:
elektron-firmware-tool -i build/Digitone_II_OS1.11-mod.syx
elektron-firmware-tool -i build/Digitone_II_OS1.11-mod.syx -d 3 -o verify
cmp verify/section_3_MAIN_OS.bin work/section_3_MAIN_OS.mod.bin && echo OK① All checksums of the new file are valid.
② The section from the new .syx is byte-for-byte identical to your edited file, so packing and unpacking were lossless.
Done!build/Digitone_II_OS1.11-mod.syx contains your change, and all checksums match.
Questions, additions or your own findings are welcome in this thread.
elektron-firmware-tool is written by mischa85 and released under the MIT licence (GitHub). Neither the tool nor this tutorial is affiliated with Elektron. Elektron, Digitone, Digitakt and other product names are trademarks of Elektron Music Machines MAV AB.