1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Flashing Images Using ``bmaptool``
4**********************************
5
6A fast and easy way to flash an image to a bootable device is to use
7bmaptool, which is integrated into the OpenEmbedded build system.
8bmaptool is a generic tool that creates a file's block map (bmap) and
9then uses that map to copy the file. As compared to traditional tools
10such as dd or cp, bmaptool can copy (or flash) large files like raw
11system image files much faster.
12
13.. note::
14
15   -  If you are using Ubuntu or Debian distributions, you can install
16      the ``bmap-tools`` package using the following command and then
17      use the tool without specifying ``PATH`` even from the root
18      account::
19
20         $ sudo apt install bmap-tools
21
22   -  If you are unable to install the ``bmap-tools`` package, you will
23      need to build bmaptool before using it. Use the following command::
24
25         $ bitbake bmaptool-native
26
27Following, is an example that shows how to flash a Wic image. Realize
28that while this example uses a Wic image, you can use bmaptool to flash
29any type of image. Use these steps to flash an image using bmaptool:
30
31#. *Update your local.conf File:* You need to have the following set
32   in your ``local.conf`` file before building your image::
33
34      IMAGE_FSTYPES += "wic wic.bmap"
35
36#. *Get Your Image:* Either have your image ready (pre-built with the
37   :term:`IMAGE_FSTYPES`
38   setting previously mentioned) or take the step to build the image::
39
40      $ bitbake image
41
42#. *Flash the Device:* Flash the device with the image by using bmaptool
43   depending on your particular setup. The following commands assume the
44   image resides in the :term:`Build Directory`'s ``deploy/images/`` area:
45
46   -  If you have write access to the media, use this command form::
47
48         $ oe-run-native bmaptool-native bmaptool copy build-directory/tmp/deploy/images/machine/image.wic /dev/sdX
49
50   -  If you do not have write access to the media, set your permissions
51      first and then use the same command form::
52
53         $ sudo chmod 666 /dev/sdX
54         $ oe-run-native bmaptool-native bmaptool copy build-directory/tmp/deploy/images/machine/image.wic /dev/sdX
55
56For help on the ``bmaptool`` command, use the following command::
57
58   $ bmaptool --help
59
60