View source for How to Upgrade X410-X440 MCU Firmware

== Application Note Number and Authors ==

'''AN-111''' by Michael Dickens (draft of 2024-07-15)
<!-- Internal use only: please do keep this updated!
==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2024-07-01
|style="text-align:center;"| Michael Dickens 
|style="text-align:center;"| Initial creation
|}
-->

== Abstract ==

This document details how to download, extract, and install the X410/X440 USRP microcontroller ("MCU") firmware updates. This specific guide shows how to do the update to MCU firmware version <code>0.0.13823-82c52e33a</code> for any revision X410/X440 USRP (currently 5, 6, or 7).

The Procedure for the Read Only (RO) MCU firmware can be done from a Linux host computer/server or on the USRP itself assuming the X410/X440 USRP boots and can stay active and running for a minimum of 20 minutes. The Read/Write (RW) MCU firmware ''must'' be loaded from the Linux host computer/server; hence we recommend starting with the first Procedure on Step (1) and if that works then both the RO and RW MCU firmware will be successfully update. If you start with the second Procedure at Step (15) then only the RO portion will be updated, so you would then need to run the installer from the Linux host computer/server to get the RW portion updated.

Both are covered here; select the one that matches your current X410/X440 USRP situation & if possible, start with the first Procedure to try to get both the RO and RW firmware updated in one set of commands.

== Procedure from Linux Host ==

NOTE: This guide assumes the following:

<ol style="list-style-type:lower-alpha">
  <li>A Linux host computer (we use Ubuntu / aptitude-based; others will work);</li>
  <li>The X410/X440 USRP is accessible to the Linux host computer via a USB cable connected to the USRP USB JTAG port;</li>
  <li>The X410/X440 USRP has power but is ''not'' powered on / is currently shut down;</li>
  <li>The X410/X440 USRP is the only USRP device connected in any form to the Linux host computer (just in case);</li>
  <li>This procedure ''should'' work regardless of whether the USRP can boot or not.</li>
</ol>

==== Procedure ====

<ol>
<li>Make sure <code>openocd</code> is installed on the Linux host computer/server. The following command works for Ubuntu / aptitude-based: <code>sudo apt-get -y install openocd</code>.
</li>

<li>Make sure the USRP and host computer are connected via the USB cable as noted in (b) above.
</li>

<li>Use <code>screen</code> to access the MCU on serial port 2:<br>
  <code>sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_XXXX-if02-port0 115200</code><br>
NOTE: <code>XXXX</code> will be some unique string for this specific serial device and Linux configuration, for example <code>25163520B2FE</code>. If you copy/paste the first part of the command, up to <code>usb-</code> and then press the <code><tab></code> key once or twice then all the options will be listed; use the entry for <code>if02</code> and then finish off the command as noted with <code>115200</code>. 
</li>

<li>Press the <code><return></code> key and the prompt <code>></code> should appear; assuming it does then enter the command:<br>
  <code>eepromdump mb</code><br>
NOTE: The first few lines of output will look something like the following<br>
For an X410 USRP:<br>
<code>
cache hit mb<br>
usrp_eeprom_board_info (0x10) pid: 0x0410, rev: 0x0005, compat_rev: 0x0005, serial: 320B2FE<br>
usrp_eeprom_module_info (0x11) pid: 0xa410, rev: 0x0003, serial: 32190B4<br>
</code>
  For an X440 USRP:<br>
<code>
cache hit mb<br>
usrp_eeprom_board_info (0x10) pid: 0x0440, rev: 0x0006, compat_rev: 0x0006, serial: 3284FCB<br>
usrp_eeprom_module_info (0x11) pid: 0xa440, rev: 0x0004, serial: 32896F8<br>
</code>
</li>

<li>Note the <code>compat_rev</code> part of <code>usrp_eeprom_board_info</code>, in this case for the X410 USRP <code>5</code> and for the X440 USRP <code>6</code>; this value can currently be 5, 6, or 7 and, in the future, higher numbers.<br>
</li>

<li>Detach from screen via pressing the keys <code>^a</code> (<code><control></code> then <code>a</code>) then <code>\</code>, then for the prompt (at the bottom) press the <code>y</code> key, which will come back to the usual shell prompt.
</li>

<li>Download and extract the archive to the Linux host computer to the <code>~/Downloads</code> directory:<br>
<code>
cd ~/Downloads<br>
wget https://files.ettus.com/binaries/misc/upgrade_mcu_titanium_v0.0.13823-82c52e33a.tar.gz<br>
tar zxf upgrade_mcu_titanium_v0.0.13823-82c52e33a.tar.gz<br>
cd upgrade_mcu_titanium_v0.0.13823-82c52e33a<br>
</code>
</li>

<li>Run the "from host" MCU updater script:<br>
<code>sudo ./flash-firmware-from-host.sh</code><br>
  NOTE: This script will print the following:<br>
<code>
This script updates the microcontroller firmware (RO and RW). The change is persistent across power cycles for the RO part. Running this script incorrectly can brick the device. This script may take upto a minute to run successfully.<br>
Ensure that only one X410/X440 device is connected to the host machine at a time.<br>
Steps:<br>
1. Power off the X410/X440 device by running "shutdown -h now" or "poweroff" command from the Linux console. But leave the power connected and turned on.<br>
2. Connect your X410/X440 device using the USB JTAG port to the host machine using a USB cable.<br>
3. Ensure that only one X440/X410 device is connected at a time. No other USRP device should be connected.<br>
4. Run this script.<br>
5. Do not disconnect USB cable while the script is running as it may result in bricking of the device.<br>
6. Power cycle the device after script has completed running successfully.<br>
Updating the microcontroller firmware (RO part) is only required if the Ettus<br>
Research support told you to do so.<br>
Press "y" to continue<br>
</code>
</li>

<li>Press the <code>y</code> key; the script will print:<br>
<code>Please enter the motherboard compat_rev number:</code><br>
</li>

<li>Enter the <code>#</code> from the <code>compat_rev</code> info from step (5) (in this case <code>5</code> for the X410 USRP or <code>6</code> for the X440 USRP but use whatever you determined & the printout below will change accordingly), then press the <code><return></code> key. The script will now print:
<code>
The compat_rev 5 is within the supported range.<br>
Hardare Rev: 5<br>
Will use firmware file /home/uhd/Desktop/upgrade_mcu_titanium_v0.0.13823-82c52e33a/ec-titanium-rev5.bin<br>
Press "y" to continue<br>
</code>
</li>

<li>Press the <code>y</code> key; the script will now print out something like the following then terminate as well as try to boot the USRP:<br>
<code>
Flashing ec-titanium-rev5.bin on hardware...<br>
Open On-Chip Debugger 0.11.0<br>
Licensed under GNU GPL v2<br>
For bug reports, read<br>
http://openocd.org/doc/doxygen/bugs.html<br>
titanium<br>
/home/uhd/Desktop/upgrade_mcu_titanium_v0.0.13823-82c52e33a<br>
DEPRECATED! use 'adapter driver' not 'interface'<br>
DEPRECATED! use 'adapter speed' not 'adapter_khz'<br>
Info : clock speed 2000 kHz<br>
Info : JTAG tap: stm32f4x.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)<br>
Info : JTAG tap: stm32f4x.bs tap/device found: 0x06441041 (mfg: 0x020 (STMicroelectronics), part: 0x6441, ver: 0x0)<br>
Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints<br>
Info : stm32f4x.cpu: external reset detected<br>
Info : starting gdb server for stm32f4x.cpu on 3121<br>
Info : Listening on port 3121 for gdb connections<br>
Info : JTAG tap: stm32f4x.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)<br>
Info : JTAG tap: stm32f4x.bs tap/device found: 0x06441041 (mfg: 0x020 (STMicroelectronics), part: 0x6441, ver: 0x0)<br>
target halted due to debug-request, current mode: Thread<br>
xPSR: 0x01000000 pc: 0x080001f8 msp: 0x20000400<br>
Info : device id = 0x30006441<br>
Info : flash size = 512 kbytes<br>
Info : JTAG tap: stm32f4x.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)<br>
Info : JTAG tap: stm32f4x.bs tap/device found: 0x06441041 (mfg: 0x020 (STMicroelectronics), part: 0x6441, ver: 0x0)<br>
target halted due to debug-request, current mode: Thread<br>
xPSR: 0x01000000 pc: 0x080001f8 msp: 0x20000400<br>
shutdown command invoked<br>
</code>
</li>

<li>After the USRP shuts down, power it back up. Repeat command (3) then at the <code>></code> prompt issue the command <code>version</code>; the output should look like the following for when the <code>compat_rev</code> is <code>5</code>; the # <code>rev5</code> will match that from Step (5):<br>
<code>
Chip:    stm stm32f412<br>
Board:   0<br>
RO:      titanium-rev5_v0.0.13823-82c52e<br>
RW:      titanium-rev5_v0.0.13823-82c52e<br>
Build:   titanium-rev5_v0.0.13823-82c52e<br>
2024-03-04 15:58:54 @c09af2c5ef57<br>
</code>
</li>

<li>Power on the USRP if it did not automatically do so after Step (12).
</li>

<li>Make sure that the USRP is connected to the host computer via a QSFP28 10/100 GbE link and/or the RJ-45 1 GbE link and that the networking is configured for your desired use-case, then run the following and see if the device comes up:<br>
<code>uhd_find_devices</code><br>
NOTE:<br>
<ol style="list-style-type:lower-alpha">
<li>If you followed Steps (1) through (12) and if this command successfully finds the USRP then you are done! Congratulations on successfully upgrading the MCU firmware on your X410/X440 USRP!
</li>
<li>If the USRP does not boot or if this command does not succeed in finding the USRP, then try this whole procedure section again starting at Step (3). If you tried this already and the X410/X440 USRP is still having issues, contact Ettus support for assistance.
</li>
</ol>

</ol>

== Procedure on USRP device ==

NOTE: This guide assumes the following:

<ol style="list-style-type:lower-alpha">
<li>The X410/X440 USRP has internet access, or is networked to the Linux host computer via the RJ-45 1 GbE or 10/100 GbE QSFP28 ports;</li>
<li>The X410/X440 USRR is powered on;
</ol>

==== Procedure ====

<ol start="15">

<li>Power on the USRP if it did not automatically do so after Step (13), or if jumping here because the USRP successfully boots.
</li>

<li>Make sure that the USRP is connected to the host computer via a QSFP28 10/100 GbE link and/or the RJ-45 1 GbE link and that the networking is configured for your desired use-case, then run the following and see if the device comes up:<br>
<code>uhd_find_devices</code><br>
NOTE: Assuming this command successfully finds the USRP note the <code>mgmt_addr</code>. Typical values are <code>192.168.10.2</code> through <code>192.168.40.2</code>, but this entirely depends on how the networking is configured. Let's call this value (whatever it actually is) <code>MGMT_ADDR</code>.
</li>

<li>Login to this USRP via the UHD-found <code>MGMT_ADDR</code>:<br>
<code>ssh root@MGMT_ADDR</code>
</li>

<li>Download the archive, either directly or from the networked host computer attached to the USRP:<br>
<code>wget https://files.ettus.com/binaries/misc/upgrade_mcu_titanium_v0.0.13823-82c52e33a.tar.gz</code>
</li>

<li>Extract the archive and move into the directory:<br>
<code>tar zxf upgrade_mcu_titanium_v0.0.13823-82c52e33a.tar.gz<br>
cd upgrade_mcu_titanium_v0.0.13823-82c52e33a</code>
</li>

<li>Run the "from device" MCU updater script:<br>
<code>./flash-firmware-from-device.sh</code><br>
NOTE: This script will print the following:<br>
<code>This script updates the microcontroller firmware (RO part). The change is persistent across power cycles. Incorrect updates may brick the device and may need you to use the host based update process. This script may take upto a minute to run successfully.<br>
Updating the microcontroller firmware (RO part) is only required if the Ettus Research support told you to do so.<br>
Press "y" to continue</code>
</li>

<li>Press the <code>y</code> key; the script will now print out something like the following:<br>
<code>This script will flash ec-titanium-rev5.RO.flat to the device<br>
old RO version:    titanium_v0.0.13797-11efcf3e6<br>
new RO:      titanium-rev5_v0.0.13823-82c52e<br>
Press "y" to continue</code>
</li>

<li>Press the <code>y</code> key (again); the script will now print out the following (note that the USRP here is <code>rev5</code>; <code>rev6</code>, <code>rev7</code> etc will show that revision number in the text instead of <code>5</code>; this revision number is automatically detected by the <code>device</code> version of the install script):<br>
<code># Disable periodic led control commands to reduce i2c activity to the controller.<br>
ledctrl led0 none<br>
/usr/sbin/ectool --interface=dev reboot_ec RW<br>
/usr/sbin/ectool --interface=dev flashread 0x0 262144 ec-titanium-rev5.RO.flat.old<br>
Reading 262144 bytes at offset 0...<br>
done.<br>
<nowiki>#</nowiki> This call may throw some i2c errors due to long erase times<br>
/usr/sbin/ectool --interface=dev flasheraseasync 0x0 262144<br>
Erasing 262144 bytes at offset 0...<br>
ioctl -1, errno 16 (Device or resource busy), EC result 255 (<unknown>)<br>
done.<br>
<nowiki>#</nowiki> Sleep and try erase again, this should succeed.<br>
sleep 3<br>
/usr/sbin/ectool --interface=dev flasheraseasync 0x0 262144<br>
Erasing 262144 bytes at offset 0...<br>
done.<br>
/usr/sbin/ectool --interface=dev flashwrite 0x0 ec-titanium-rev5.RO.flat<br>
Reading 84032 bytes from ec-titanium-rev5.RO.flat...<br>
Writing to offset 0...<br>
Write size 112...<br>
done.<br>
copying new firmware files<br>
'ec-titanium-rev5.bin' -> '/lib/firmware/ni/ec-titanium-rev5.bin'<br>
'ec-titanium-rev5.RW.bin' -> '/lib/firmware/ni/ec-titanium-rev5.RW.bin'</code>
</li>

<li>Reboot the USRP:<br>
<code>reboot</code>
</li>

<li>All done! If you want to verify that the firmware is updated, then repeat step (12) and the output for <code>RO</code> should now be the following for <code>rev5</code> USRPs; the other entries might still be different:<br>
<code>Chip:    stm stm32f411<br>
Board:   0<br>
RO:      titanium-rev5_v0.0.13823-82c52e<br>
RW:      titanium-rev5_v0.0.13823-82c52e<br>
Build:   titanium-rev5_v0.0.13823-82c52e<br>
         2024-03-04 15:58:54 @c09af2c5ef57</code><br>
<br>
For <code>rev6</code> and newer USRPs, the <code>rev#</code> text will not be present and the <code>Chip</code> might be different:<br>
<code>Chip:    stm stm32f412<br>
Board:   0<br>
RO:      titanium_v0.0.13823-82c52e<br>
RW:      titanium_v0.0.13823-82c52e<br>
Build:   titanium_v0.0.13823-82c52e<br>
         2024-03-04 15:58:54 @c09af2c5ef57</code>
</li>

</ol>

[[Category:Application Notes]]