View source for Writing the USRP File System Disk Image to a SD Card

==Application Note Number==
'''AN-630'''
<!-- Internal use only: please do keep this updated!
==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2018-12-12
|style="text-align:center;"| Nate Temple
|style="text-align:center;"| Initial creation
|}
-->

==Abstract==
This application note will provide step-by-step instructions on writing a file system disk image to a SD card using Linux.

==Required Tools==
* Computer with USB2/3 Interface 
* UHD Installation
* microSD card to USB Adapter

==Downloading the File System Image==
To obtain the file system SD card image for your USRP device, run the command in the next step on the host computer with UHD installed and Internet access. 

===N3xx===

    $ sudo uhd_images_downloader -t sdimg -t n3xx

Example Output for UHD 3.15.0.0:

    $ sudo uhd_images_downloader -t sdimg -t n3xx
    [INFO] Images destination: /usr/local/share/uhd/images
    [INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
    845962 kB / 845962 kB (100%) n3xx_common_sdimg_default-v3.15.0.0.zip
    [INFO] Images download complete.

===E31x===

The Release 4 image comes in two varieties: SG1 and SG3. The variety that you will need depends on the product number of your E310. To see which version you need look over at [https://kb.ettus.com/E310/E312#SD_Card_Images E310/E312 - Ettus Knowledge Base]

    $ sudo uhd_images_downloader -t sdimg -t e310 -t sg1

or
    $ sudo uhd_images_downloader -t sdimg -t e310 -t sg3

Example Output for UHD 3.15.0.0 for E310 SG3:

    $ sudo uhd_images_downloader -t sdimg -t e310 -t sg3
    [INFO] Images destination: /usr/local/share/uhd/images
    [INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
    561236 kB / 561236 kB (100%) e3xx_e310_sg3_sdimg_default-v3.15.0.0.zip
    [INFO] Images download complete.

===E320===

    $ sudo uhd_images_downloader -t sdimg -t e320

Example Output for UHD 3.15.0.0:

    $ sudo uhd_images_downloader -t sdimg -t e320
    [INFO] Images destination: /usr/local/share/uhd/images
    [INFO] No inventory file found at /usr/local/share/uhd/images/inventory.json. Creating an empty one.
    795674 kB / 795674 kB (100%) e3xx_e320_sdimg_default-v3.15.0.0.zip
    [INFO] Images download complete.

==Identifying UHD Installation Prefix==

In the output of the <code>uhd_images_downloader</code> command above, the folder destination where the images are saved is printed out.

An alternative method to identify your installation prefix is to run the command:

    $ uhd_config_info --install-prefix

Example Output:

    Install prefix: /usr/local

The default folder location for FPGA and SD card images is:

    <UHD_INSTALL_PREFIX>/share/uhd/images/


==Writing the File System Image with Linux==

===Identifying SD Card Mount Location===

Insert the microSD card into the host computer.

To identify the device where the microSD card is, run the command:

    dmesg | tail

Example Output (partially truncated for readability):

    [21265.575488] usb-storage 1-2:1.0: USB Mass Storage device detected
    [21266.586983] scsi 0:0:0:0: Direct-Access     Generic  Mass-Storage     1.11 PQ: 0 ANSI: 2
    [21266.588024] sd 0:0:0:0: Attached scsi generic sg0 type 0
    [21267.299812] sd 0:0:0:0: [sdb] 31116288 512-byte logical blocks: (15.9 Gb/14.8 GiB)
    [21267.302687]  sdb: sdb1 sdb2 sdb3 sdb4

NOTE: In this specific example configuration, the SD card has been attached to <code>sdb</code>.

Another method to finding the device node the disk is attached at is to use the Linux utility <code>lsblk</code>:

Example Output:

    $ lsblk
    NAME           MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
    sdb      8:16   1 14.9G  0 disk
    ├─sdb1   8:17   1   16M  0 part /media/user/boot
    ├─sdb2   8:18   1  1.9G  0 part /media/user/primary
    ├─sdb3   8:19   1  1.9G  0 part /media/user/secondary
    └─sdb4   8:20   1   11G  0 part /media/user/data

===Unmount Auto-mounted Partitions===

Some operating systems by default will auto-mount the partitions on a block device when it is attached. Before writing a new disk image to the SD card, you should first unmount any mounted partitions. This can be done with the Linux utility <code>umount</code> as shown below:

    $ sudo umount /media/user/data
    $ sudo umount /media/user/primary
    $ sudo umount /media/user/secondary
    $ sudo umount /media/user/boot

Running the command <code>lsblk</code> again will show these partitions have been unmounted:

Example Output:

    $ lsblk
    NAME           MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
    sdb      8:16   1 14.9G  0 disk
    ├─sdb1   8:17   1   16M  0 part
    ├─sdb2   8:18   1  1.9G  0 part
    ├─sdb3   8:19   1  1.9G  0 part
    └─sdb4   8:20   1   11G  0 part

===Writing the SD Card Image===

====Using dd to write the disk image====

'''WARNING:''' The Linux utility <code>dd</code> can cause unrecoverable data loss if the incorrect disk is selected, or if the parameters are input incorrectly. Ensure you have selected the correct input and output parameters for your system configuration.

NOTE: You must use a 16 Gb or larger SD card for the N3xx and E320 file system images.

The <code><SD_CARD_DEV_NAME></code> device node depends on your operating system and which other devices are plugged in. Typical values are <code>sdb</code> or <code>mmcblk0</code>.

The <code><IMAGE></code> value will depend upon which file system image you're writing. Examples for the N300/N310 and E320 are listed below:

'''N3xx'''
    <IMAGE>=/usr/local/share/uhd/images/usrp_n3xx_fs.sdimg

'''E320'''
    <IMAGE>=/usr/local/share/uhd/images/usrp_e320_fs.sdimg

Write the disk image with the command:

    $ sudo dd if=<IMAGE> of=<SD_CARD_DEV_NAME> bs=1M

This step of writing the disk image to the SD card can take several minutes to complete.

Example Output:

    $ sudo dd if=/usr/local/share/uhd/images/usrp_<deivce>_fs.sdimg of=/dev/sdb bs=1M
    15160+0 records in
    15160+0 records out
    15896412160 bytes (16 Gb, 15 GiB) copied, 1160.93 s, 13.7 MB/s

To ensure the disk is synchronized, run the <code>sync</code> command:

    $ sync

You can now remove the microSD card from your host computer and insert it into the USRP.

[[Category:Application Notes]]