Difference between revisions of "Ettus USRP E300 Embedded Family Getting Started Guides"

From Ettus Knowledge Base
Jump to: navigation, search
(add section "Updating the Linux File System" ; various other tweaks / fixes)
(Updating the Linux File System: clarify mender starting with UHD4)
 
(One intermediate revision by the same user not shown)
Line 121: Line 121:
 
There are two ways to update the file system for the E310 USRP:  
 
There are two ways to update the file system for the E310 USRP:  
  
1. Mender
+
1. Mender, which is available starting with UHD 4.0.0.0 release only. If you are using UHD 3.15 or prior you'll need to update the microSD card to UHD4 before being able to use Mender to do updates.
  
 
2. Physically remove microSD card from device and write a new file system to the microSD card.
 
2. Physically remove microSD card from device and write a new file system to the microSD card.
Line 228: Line 228:
 
1) Connect to the [[E310/E312_Getting_Started_Guides#Serial_Console_Connectivity|E31x via serial]]
 
1) Connect to the [[E310/E312_Getting_Started_Guides#Serial_Console_Connectivity|E31x via serial]]
  
2) Boot the device and quickly enter "noautoboot" into the serial console. It can be helpful to have "notautoboot" copied to the clipboard. If completed successfully, you should have a prompt like this:
+
2) Boot the device and quickly enter "noautoboot" into the serial console. It can be helpful to have "noautoboot" copied to the clipboard. If completed successfully, you should have a prompt like this:
  
Automatic boot in 3s...
+
    Automatic boot in 3s...
Enter 'noautoboot' to enter prompt without timeout
+
    Enter 'noautoboot' to enter prompt without timeout
ni-e31x-uboot>
+
    ni-e31x-uboot>
  
 
If you don't get this prompt, restart the device and try again.
 
If you don't get this prompt, restart the device and try again.

Latest revision as of 11:04, 18 November 2020

Kit Contents

E310

  • E310 USRP
  • Power supply
  • 2x SMB-to-SMA adapter
  • 1 Gigabit Ethernet cable
  • USB2-to-microUSB cable
  • Imaged microSD card
  • Getting started guide
Product e310.png

E312

  • E312 USRP
  • Power supply
  • 2x SMB-to-SMA adapter
  • 1 Gigabit Ethernet cable
  • USB2-to-microUSB cable
  • Imaged microSD card
  • Getting started guide
Product e312.png

E313

  • Protective caps for input ports
  • Surface mounting accessory
  • Pole mounting accessory
  • End conduit interface for USB devices
  • Waterproof sleeve for DC power connector
  • Waterproof sleeve for PoE (RJ45) connector
  • Torx T-20 key
  • Mounting accessory assembly guide
  • Imaged microSD card
E313.png

The USRP E313 is a fully assembled device that includes an USRP E310.

Verify the Contents of Your Kit

Make sure that your kit contains all the items listed above. If any items are missing, please contact your sales agent or Ettus Research Technical support immediately.

You Will Need

  • A host computer with an available USB 2.0 or 3.0 port

Proper Care and Handling

All Ettus Research products are individually tested before shipment. The USRP™ is guaranteed to be functional at the time it is received by the customer. Improper use or handling of the USRP™ can easily cause the device to become non-functional. Listed below are some examples of actions which can prevent damage to the unit:

  • Never allow metal objects to touch the circuit board while powered.
  • Always properly terminate the transmit port with an antenna or 50Ω load.
  • Always handle the board with proper anti-static methods.
  • Never allow the board to directly or indirectly come into contact with any voltage spikes.
  • Never allow any water, or condensing moisture, to come into contact with the boards.
  • Always use caution with FPGA, firmware, or software modifications.
Caution.png
Never apply more than 0 dBm of power into any RF input.
Caution.png
Always use at least 30dB attenuation if operating in loopback configuration

Install and Setup the Software Tools on Your Host Computer

In order to use your Universal Software Radio Peripheral (USRP™), you must have the software tools correctly installed and configured on your host computer. A step-by-step guide for doing this is available at the Building and Installing the USRP Open-Source Toolchain (UHD and GNU Radio) on Linux, OS X and Windows Application Notes. See the Hardware Specifications section of the USRP Embedded Series Hardware Resources for additional details on which version of the USRP Hardware Driver, UHD, is required. It is recommended to use the latest stable version of UHD that is available.

If you have a USB stick with the Live SDR Environment installed on it, then you may boot your host computer from that. The LiveUSB SDR Environment does not require anything to be installed on your host computer, and contains a Linux-based environment with the UHD software and the GNU Radio framework already installed. More information about the Live SDR Environment is available at the Live SDR Environment Getting Started Guides page.

Powering On the Hardware

Connecting the USRP power supply to the devices will cause the unit to turn on and boot­up. If this is the first time powering on the device, allow the battery to fully charge before disconnecting the AC power source. Once the device has completed the boot process, you are ready to start using the device over your preferred method of connectivity (Serial Console, Network, or USB peripherals)!

Turning the Device Off/On

You can also power the device on and off by pressing the power button. To power the device off, hold the power button down until the button’s LED turns off (this will take a couple of seconds). To turn the device on, hold down the power button until the LED turns on.

To avoid damaging the file system and causing any corruption, do not turn the device off with the power button without first shutting down the system. Use this command to cleanly and properly shut the system down:

   shutdown ­-h now

Serial Console Connectivity

The easiest way to first communicate with your E31x device is by using the USB Serial Console. Connect a micro­USB cable to the Serial Console port on the E31x and connect the other end to a PC. The console will appear as an “FTDI Serial Device” ­ thus, it will likely appear as a ttyUSB device in Linux or a COM port on Windows. In Windows, you will need to edit the properties of the device in ‘Device Manager’ and ‘Enable VCP’. On the PC, open a serial terminal to the E31x using the following parameters: B​aud Rate:​115200, D​ata:​8­bit, P​arity: None, S​top:​1­bit, F​low Control:​None.

On Linux, the following command will typically handle the serial connection:

   sudo screen /dev/ttyUSB0 115200

You may have to change the device name.

For additional information about using the serial console and instructions for communicating with the device over other methods (such as connecting with SSH over the network or using and LCD screen, keyboard, and mouse), please refer to the UHD Manual online: https://files.ettus.com/manual/page_usrp_e3xx.html

Network Connectivity

By default, the E31x device will run a DHCP client on its 1 Gigabit Ethernet port. Assuming your network resolves hostnames (depends on your routers / switches), if you connect the device to your network, you should see it appear with the hostname e​ttus­e300.​You can then access the device over SSH.

If the hostname does not resolve, you can discover the IP address by logging into the device over the serial connection, or checking your network’s DHCP tables.

Once you have logged in to the device, you can reconfigure the network settings (e.g., you could configure it for a static IP address, if you wish).

Logging In

When you first log in to the device, the user is ‘root’ and the password is empty (no password).

Updating the Linux File System

Before operating the device, it is​ ​strongly​ recommended to update to the latest version of the Embedded Linux file system. If you are operating the device in Network Mode, the version of UHD running on the host machine and E310 USRP must match.

There are two ways to update the file system for the E310 USRP:

1. Mender, which is available starting with UHD 4.0.0.0 release only. If you are using UHD 3.15 or prior you'll need to update the microSD card to UHD4 before being able to use Mender to do updates.

2. Physically remove microSD card from device and write a new file system to the microSD card.

NOTE: File System Partition Layout

The SD Card is divided into four partitions. There are two root file system partitions, a "boot" partition and a "data" partition.

Any data you would like to preserve through Mender updates should be saved to the "data" partition, which is mounted at /data.

1. Updating the file system with Mender

Mender is third-party software that enables remote updating of the root file system without physically accessing the device (see also the Mender website https://mender.io/ ). Mender can be executed locally on the device, or a Mender server can be set up which can be used to remotely update an arbitrary number of USRP devices. Users can host their own local Mender server, or use servers hosted by Mender as a paid service; contact Mender for more information.

Mender Update Process

When updating the file system using Mender, the tool will overwrite the root file system partition that is not currently mounted. Any data stored in the root partitions will be permanently lost with a Mender update.

After updating a partition with Mender, it will reboot into the newly updated partition. Only if the update is confirmed by the user, the update will be made permanent. This means that if an update fails, the device will be always able to reboot into the partition from which the update was originally launched, which presumably is in a working state. Another update can be launched now to correct the previous, failed update, until it works.

You will need to know whether your USRP E31x is the SG1 or SG3 version.

The USRP E31x release 4 image comes in two varieties. The variety that you will need depends on the product number of your E31x, which is printed on the bottom of the device. You must use the appropriate files for your specific device. Incorrect files will not work, and will only boot as far as the U-Boot boot loader before stopping.

For the E310, the product number will be 156333X-01L, where X is a letter from A to Z. For devices where X is A, B, C, D, use the sg1 files. For devices where X is E or later, use the sg3 files.

For the E312, the product number will be 140605X-01L, where X is a letter from A to Z. All E312 USRPs use the sg3 files.

To obtain the file system Mender image (these are files with a .mender suffix), run the following command on the host computer with Internet access:

   $ sudo uhd_images_downloader -t mender -t e310 -t sg# --yes

where "sg#" is the correct file type as found above, with "#" being either 1 or 3. Example Output:

   $ sudo uhd_images_downloader -t mender -t e310 -t sg3 --yes
   [INFO] Using base URL: https://files.ettus.com/binaries/cache/
   [INFO] Images destination: /usr/local/share/uhd/images
   292014 kB / 292014 kB (100%) e3xx_e310_sg3_mender_default-v4.0.0.0.zip
   [INFO] Images download complete.

NOTE: In the output of the command, the folder destination where the images are saved is printed out.

NOTE: Regardless of which file type is specified, the extracted mender file will have the same name: usrp_e310_fs.mender.

Next, you will need to copy this Mender file system image to the USRP E310. This can be done with the Linux utility scp.

Example code to execute:

   $ scp /usr/local/share/uhd/images/usrp_e310_fs.mender root@192.168.1.51:~/. 

Note: The path and IP may different for your configuration, the command above assumes you're using the default installation path of /usr/local and that the E310's IP is 192.168.1.51.

After copying the Mender file system image to the E310, connect to the E310 using either the Serial Console, or via SSH to gain shell access.

On the E310, run mender -rootfs /path/to/latest.mender to update the file system:

   root@ni-e310-serial:~# mender -rootfs /home/root/usrp_e310_fs.mender

Example Output:

root@ni-e310-serial:~# mender -rootfs /home/root/usrp_e310_fs.mender                       
INFO[0000] Start updating from local image file: [/home/root/usrp_e310_fs.mender]  module=rootfs
Installing update from the artifact of size 399640064
INFO[0000] opening device /dev/mmcblk0p3 for writing     module=block_device
INFO[0000] partition /dev/mmcblk0p3 size: 2046820352     module=block_device
................................   0% 1024 KiB
................................   0% 2048 KiB
................................   0% 3072 KiB
[truncated for readability]
................................  99% 389120 KiB
................................  99% 390144 KiB
................................ 100% 390273 KiB
INFO[0740] wrote 2046820352/2046820352 bytes of update to device /dev/mmcblk0p3  module=device
INFO[0744] Enabling partition with new image installed to be a boot candidate: 3  module=device

The artifact can also be stored on a remote server:

   $ mender -rootfs <http://server.name/path/to/latest.mender>

This procedure will take a few minutes to complete. After mender has logged a successful update, reboot the device:

   $ reboot

If the reboot worked, and the device seems functional, commit the changes so that the boot loader knows to permanently boot into this partition:

   $ mender -commit

To identify the currently installed Mender artifact from the command line, the following file can be queried on the E310:

   $ cat /etc/mender/artifact_info

If you are using a Mender server, the updates can be initiated from a web dashboard. From there, you can start the updates without having to log into the device, and you can update groups of USRPs with a few clicks in a web GUI. The dashboard can also be used to inspect the state of USRPs. This is a simple way to update groups of rack-mounted USRPs with custom file systems.

For more information on updating the file-system, refer to the UHD Manual​.

Troubleshooting Mender Update

When updating an E31x USRP using mender, it is possible that the update will not apply. For example, if the E31x v3.15.0.0 bootloader is misconfigured then it will not boot into an upgraded mender image. There are 2 solutions to this:

A. Reimage SD card with full sdimg using dd or bmaptool

This is the recommended solution. Follow the steps to update using the sdimg. E31x v4.0.0.0 and later contains the bootloader fix to enable future mender updates.

B. Manually reconfigure bootloader

This solution requires some effort, but isn't too difficult. That said, because the SD card is easily accessible on most E31x this is not the recommended solution.

1) Connect to the E31x via serial

2) Boot the device and quickly enter "noautoboot" into the serial console. It can be helpful to have "noautoboot" copied to the clipboard. If completed successfully, you should have a prompt like this:

   Automatic boot in 3s...
   Enter 'noautoboot' to enter prompt without timeout
   ni-e31x-uboot>

If you don't get this prompt, restart the device and try again.

3) Configure the bootargs to support mender updates

   setenv bootargs 'root=${​​​​​​​mender_kernel_root}​​​​​​​ rw rootwait uio_pdrv_genirq.of_id=usrp-uio'
   saveenv

4) Reboot device and apply mender image

NOTE: This solution may brick the E31x USRP if done incorrectly. To unbrick the USRP, follow the solution of overwriting the full SD card image.

2. Updating the files system by writing the disk image

The microSD card is accessible directly on the Board-only version of the E310 USRP. The E310 Full Enclosure version must be opened with the included Torx wrench.

NOTE: This method will overwrite all data saved on the microSD card, including any data saved to the /data partition.

Please see this application note for step-by-step instructions on writing the file system image to the microSD card.

Subdevice Specification Mapping

E310/E312/E313

The USRP E31x contains 2 channels, each represented on the front panel as TRX-A / RX2-A and TRX-B / RX2-B. Below is the subdev mapping of RF

UHD <3.15.x.x

  • TRX-A / RX2-A = A:0
  • TRX-B / RX2-B = B:0

UHD 3.15.x.x+

  • TRX-A / RX2-A = A:0
  • TRX-B / RX2-B = A:1

Additional details of UHD Subdevice Specifications can be found here in the UHD Manual: http://files.ettus.com/manual/page_configuration.html#config_subdev

Example Programs

The UHD driver includes several example programs, which may serve as test programs or the basis for your application program. These example programs are already installed on the E31x device, and the source code can be obtained from the UHD repository on GitHub at: https://github.com/EttusResearch/uhd/tree/master/host/examples

Test and Verify the Operation of the USRP

You can quickly verify the operation of your USRP E31x by running the rx_ascii_art_dft UHD example program. The rx_ascii_art_dft utility is a simple console ­based, real­time FFT display tool. It is not graphical in nature, so it can be easily run over an SSH connection within a terminal window, and does not need any graphical capability, such as X Windows, to be installed. It can also be run over a serial console connection, although this is not recommended, as the formatting may not render correctly.

You can run a simple test of the E31x device by connecting an antenna and observing the spectrum of a commercial FM radio station in real­time. Please follow the steps listed below.

1. Attach an antenna to the RX2­A antenna port of the E31x.

2. Log into the E31x from an external host computer over Ethernet using an SSH client.

3. At a terminal prompt running on the E31x, run:

   /usr/lib/uhd/examples/rx_ascii_art_dft ­­--freq 88.1e6 ­­--rate 400e3 ­­--gain 30 ­­--ref­-lvl ­-30

4. Modify the command­line argument "freq" ​above to specify a tuning frequency for a strong local FM radio station.

5. You should see a real­time FFT display of 400 KHz of spectrum, centered at the specified tuning frequency.

6. Type "Q" or Ctrl­-C to stop the program and to return to the Linux command line.

7. You can adjust the size of your terminal window and then re­run the command to enlarge or shrink the FFT display.

8. You can run with the "​­­help"​option to see a description of all available command­line options.

Additional information is available at the Verifying the Operation of the USRP Using UHD and GNU Radio Application Note.

Battery (E312 Only)

The USRP E312 is equipped with an integrated 3.7V, 3200mAh lithium­ion battery cell. After unboxing the USRP E312 , plug in the power adapter to an AC power source and fully charge the battery. This process with take approximately 2 hours. Do not leave the USRP E312 unit plugged in for more than 24 hours.

The status LED in the power button indicates the power and charge status of the battery:

Off: Indicates device is off and not charging.

  • Slow Blinking Green: Indicates device is off and charging.
  • Fast Blinking Green: Indicates device is on and charging.
  • Solid Green: Indicates device is on and not charging (Battery is finished charging).
  • Solid Orange: Indicates device is on and discharging.
  • Fast Blinking Orange: Indicates device is on, discharging, and charge is below 10% charge.
  • Fast Blinking Red: Indicates an error code:
  1. Low Voltage Error
  2. Regulator Low Voltage Error
  3. FPGA Power Error
  4. DRAM Power Error
  5. 1.8V Power Rail Error
  6. 3.3V Power Rail Error
  7. Daughterboard / TX Power Error
  8. Charger Error
  9. Charger Temperature Error
  10. Battery Low Error
  11. Fuel Gauge Temperature Error
  12. Global (Enclosure) Temperature Error

The battery life of the USRP E312 in idle mode is approximately 5 1/2 hours. The battery will enable the USRP E312 to operate for approximately 2 hours 20 minutes, when transmitting and receiving on both channels (2x2 MIMO), with maximum gain settings, at 5 GHz center frequency, and 1 MS/s sample rate. When the power button status LED is in the “Fast Blinking Orange” mode, plug the USRP E312 into an AC power source as soon as possible to recharge the battery.

If the power button status LED indicates a “Low Voltage Error” (codes 1, 2, 3, 4, 5, 6, 7) or a “Battery Low Error” (code 10), plug the USRP E312 into an AC power source as soon as possible to recharge the battery.

When the power button status LED indicates at “Temperature Error” or “Charger Error” (codes 8, 9, 11, or 12), power off the USRP E312 unit and allow it to cool down to room temperature. Then, plug in the USRP E312 to and AC power source and fully charge the battery.

If error codes persist after cooling down and/or recharging the USRP E312, please contact support@ettus.com.

You can purchase a replacement battery for the E312 at https://www.ettus.com/product/details/E312-battery.

An Application Note covering the replacement of the E312 battery can be found at USRP E312 Battery Replacement Instructions.

Battery Calibration Procedure

In order for the battery gauge to give a usable indication of remaining charge it needs to be calibrated. The procedure for calibration is as follows:

  1. Completely charge the battery.
  2. Type: ​echo 3200000 >/sys/class/power_supply/BAT/charge_now
  3. Unplug AC power.
  4. Replug AC power, and wait until charging completes.

Battery Safety Information

To ensure proper use of the battery, please read the the battery specification sheet. This document is available at: Media:34118 datasheet.pdf

Because batteries utilize a chemical reaction, battery performance will deteriorate over time even if stored for a long period of time without being used. In addition, if the various usage conditions such as charge, discharge, ambient temperature, etc. are not maintained within the specified ranges, the life expectancy of the battery may be shortened or the device in which the battery is used may be damaged by electrolyte leakage.

Handling

  • Do not expose the battery to flame or dispose of it in a fire.
  • Do not put the battery in a charger or equipment with the wrong terminals connected.
  • Do not short circuit the battery.
  • Avoid excessive physical shock or vibration.
  • Do not disassemble or deform the battery.
  • Do not immerse in water.
  • Do not use the battery mixed with other different make, type, or model batteries.
  • Keep out of the reach of children.
  • Do not use the battery if it appears damaged.

Charge and Discharge

  • Always charge the battery while it is installed in the USRP E312 and only use the DC power supply provided in the USRP E312 kit.
  • Do not leave the battery charging for longer than 24 hours.
  • Never use a modified or damaged USRP E312 DC power supply to charge the battery.

Storage

  • Store the battery in a cool, dry, and well­-ventilated area.

Disposal

  • Regulations vary for different countries. Dispose of the battery in accordance with local regulations.

Technical Support and Community Knowledge Base

Technical support for USRP hardware is available through email only. If the product arrived in a non­functional state or you require technical assistance, please contact support@ettus.com. Please allow 24 to 48 hours for response by email, depending on holidays and weekends, although we are often able to reply more quickly than that.

We also recommend that you subscribe to the community mailing lists. The mailing lists have a responsive and knowledgeable community of hundreds of developers and technical users who are located around the world. When you join the community, you will be connected to this group of people who can help you learn about SDR and respond to your technical and specific questions. Often your question can be answered quickly on the mailing lists. Each mailing list also provides an archive of all past conversations and discussions going back many years. Your question or problem may have already been addressed before, and a relevant or helpful solution may already exist in the archive.

Discussions involving the USRP hardware and the UHD software itself are best addressed through the u​srp­-users ​mailing list at http://usrp-users.ettus.com.

Discussions involving the use of GNU Radio with USRP hardware and UHD software are best addressed through the d​iscuss­-gnuradio​ mailing list at https://lists.gnu.org/mailman/listinfo/discuss­gnuradio​.

Discussions involving the use of OpenBTS® with USRP hardware and UHD software are best addressed through the o​penbts­-discuss​ mailing list at https://lists.sourceforge.net/lists/listinfo/openbts­discuss​.​

The support page on our website is located at https://www.ettus.com/support​. The Knowledge Base is located at ​https://kb.ettus.com​.

Legal Considerations

Every country has laws governing the transmission and reception of radio signals. Users are solely responsible for insuring they use their USRP system in compliance with all applicable laws and regulations. Before attempting to transmit and/or receive on any frequency, we recommend that you determine what licenses may be required and what restrictions may apply.

  • NOTE: This USRP product is a piece of test equipment.

Sales and Ordering Support

If you have any non­-technical questions related to your order, then please contact us by email at orders@ettus.com​, or by phone at +1­408­610­6399 (Monday-Friday, 8 AM - 5 PM, Pacific Time). Please be sure to include your order number and the serial number of your USRP.

Terms and Conditions of Sale

Terms and conditions of sale can be accessed online at the following link: http://www.ettus.com/legal/terms-and-conditions-of-sale