How to use this Bmap Tool Thing…

So someone said ‘use bmap tools instead of dd because it’s faster and better’.
It sounded good but as usual when I went searching for documentaion on how to simply use this tool I was left in another command line dizziness. You can check their read me file on the git repository here for yourself if you’d like. This blog here was also even better than the read me file, so thanks to whoever this is as well.

So, hopefully this blog will help you step by step setting things up because I can confirm indeed this thing is blazingly fast compared to dd or other direct image copying things!

Assumptions

• you are running Ubuntu
• You know how to find your terminal and type in it
• you want to flash / copy something to something 🙂

1. Get Bmap

sudo apt install bmap-tools if you have not done so already. This will install in ubuntu

2. Create your Bmap file

This is the thing that seemed to be not explained anywhere well. So what this step does it it creates a file formatted as ‘.bmap’. It’s an xml file. Somehow this file is what makes the magic work so if you create it with the bmap tool and use it in the bmap command line, copying is way faster.

Name your bmap file

You can name this file anything you want. I chose to call it something completely different from my image file so that I don’t accidentally type a wrong command. In my case I was flashing a pinephone image to a micro SD card so I named the bmap file ‘pphone.bmap’ and then the image file remained the way I downloaded it as ‘ubuntu-touch-pinephone.img.xz’.

Select a location

Next, select a nice directory on your computer where you want to run these commands. You can make your own directory or just use the Downloads directory – it’s up to you. I’ll use “Downloads’ for my example.

Run the bmap file creation command

This part here will create the bmap file now that you’ve thought everything through. Just open a terminal and enter this:

bmaptool create /path/to/your/image > /path/where/you/want/bmap/file/saved/bmapfilename.bmap

Here is my actual example with some filled in info:

bmaptool create ~/Downloads/ubuntu-touch-pinephone.img.xz > ~/Downloads/pphone.bmap

— PLAY BY PLAY COMMAND COMMENTARY —

• ‘bmaptool’ calls the app.
• ‘create’ : a bmap tool command that says ‘make a bmap file’
• ~/Downloads/ubuntu-touch-pinephone.img.xz: the location of your image
• ‘>’ thing is… who knows! But it does stuff
• ~/Downloads/pphone.bmap: destination of where you want your .bmap file to end up.

Press enter and you should see an output in your terminal something like this:

bmaptool: WARNING: all 826.3 MiB are mapped, no holes in ‘/home/wt/Downloads/ubuntu-touch-pinephone.img.xz’
bmaptool: WARNING: was the image handled incorrectly and holes were expanded?

wt@wt-Lemur:~$ cd Downloads/

Not sure what the warnings were but it seemed to be ok 🙂

3. Copy / Flash your image to your desintation drive, card, whatever

Now that you have your .bmap file created (and you should go to that directory to make sure before proceeding, by the way) you are ready to start blazingly fast copying! Woot woot. This is a simple change from the command above. If you look at my example, I think you’ll figure it out pretty quick.

Note 1: Sudo required for this one.
Note 2: Be CAREFUL before you hit the enter key because if you map this to the wrong desintation, you could damage stuff. I always remove any external drives I don’t want to accidentally kill 🙂

sudo bmaptool copy --bmap ~/path/where/your/bmap/file/is/located /path/where/your/image/is/located /path/to/memory/device

Here is my example with stuff filled in:

sudo bmaptool copy --bmap ~/Downloads/pphone.bmap ~/Downloads/ubuntu-touch-pinephone.img.xz /dev/mmcblk0

• — PLAY BY PLAY COMMAND COMMENTARY —
• ‘sudo’ -gives you super powers
• ‘bmaptool’ calls the app.
• ‘copy’ is the command to copy (smart name…)
• ‘–bmap’ : says ‘hey! here’s my bmap file so you copy this thing fast”
• ‘~/Downloads/pphone.bmap’ : this is the path to my bmap file
• ‘~/Downloads/ubuntu-touch-pinephone.img.xz’ : this is the location of my image that I want to flash onto something. In my example it’s the pinephone image
• ‘/dev/mmcblk0’ : the destination of where you want your .bmap file to end up. This this case it’s the SD memory card but yours could be /sdc /sda or whatever depending.

Here is the output of my terminal doing this. I find it’s helpful to see terminal stuff so you don’t think you’re going crazy if stuff looks bad in your opinion 🙂

bmaptool: info: block map format version 2.0
bmaptool: info: 211529 blocks of size 4096 (826.3 MiB), mapped 211529 blocks (826.3 MiB or 100.0%)
bmaptool: info: copying image ‘ubuntu-touch-pinephone.img.xz’ to block device ‘/dev/mmcblk0’ using bmap file ‘pphone.bmap’
bmaptool: WARNING: failed to enable I/O optimization, expect suboptimal speed (reason: cannot switch to the ‘noop’ I/O scheduler: [Errno 22] Invalid argument)
bmaptool: info: 100% copied

bmaptool: ERROR: checksum mismatch for blocks range 0-211528: calculated 92c113dde2f5836ccdfc756c2713965bcbd49e5fd9208f0ff89bba4df904f3e2, should be e8648c7193ae920c23de5dcbb23be9ecdca0c94dbfd16b4c003ec9f0511e4406 (image file /home/wt/Downloads/ubuntu-touch-pinephone.img.xz)

Well hopefully this blog was good payback for the nice guy who recommended it. Definitely it’s a time saver and ‘not so hard’ if you have some instruction.