Updating Transceiver firmware

This section discusses the procedure required to update the Crimson TNG transceiver firmware. Broadly speaking, Crimson TNG has two primary firmware sources: the FPGA firmware (containing the Linux file system and FPGA firmware), and the MCU firmware (the Atmel processor code used to control and configure the radio and time boards)

Note

More information on the architecture behind Crimson TNG may be found in the section on System Architecture.

This section explains the procedure to update the MCU firmware, and configure the FPGA firmware to program the MCU.

MCU Firmware

The MCU code is responsible for controlling the various components on each radio board. When a command is issued from the digital board, the MCU interprets the command and configures or adjusts the various components on the board to the desired mode of operation.

The capability exists to update this code through the existing UART interface; the optimal update method takes advantage of the exposed SATA headers to directly update the Atmel Controller. The following provides the recommended procedure to update the MCU firmware.

Automatic MCU Update (Recommend)

Pre-requisites

In order to automatically update from Crimson TNG, you require;

  1. Firmware binaries (eg; rx.hex, tx.hex)
    • The actual MCU firmware and binaries are available from Per Vices. If you are updating from the MCU, you only require the application binaries (rx.hex, tx.hex, synth.hex). Please contact us for more information.
  2. A client terminal with SSH and SCP installed.

Update Procedure

Overview

Unless otherwise instructed, you should follow the automatic update instructions to help ensure a smooth update process.

Here is an overview of what this process entails:

  1. Clone the releases repository.
  2. Copy the release package to Crimson.
  3. Execute the update script and wait for it to be completed.
  4. (Optionally) Regenerate the look up table.
  5. Update to the corresponding UHD version.
  6. Reboot the device

Cloning the repository

You can use git to clone the latest releases repo as follows:

$ git clone https://github.com/pervices/releases.git

After cloning the releases repository, fetch all the remote tags by typing:

$ git fetch --all

In general, the latest release shall be available on the master branch, but you can see a list of previous releases using:

$ git tag -l

And you can check out to those releases by typing:

$ git checkout 1.6.7

After cloning and checking out to a specific release, enter into the release repository, to find appropriate binaries for RTM4 and RTM5 releases.

Copying the release package to Crimson

You may use SCP, from within the releases repo, to copy the appropriate release to Crimson. Assuming the default Crimson IP address of 192.168.10.2, and after selecting the appropriate RTM4/5 packages;

Crimson RTM4 users:

$ scp updateCrimsonRTM4 dev0@192.168.10.2:

Crimson RTM5 users:

$ scp updateCrimsonRTM5 dev0@192.168.10.2:

You will be prompted for a password, which is the same as the one you were previously provided with.

Executing the update script

Warning

Do not interrupt crimson during the update process. The update process takes some time. It is very important NOT to interupt this process.

To execute the update process, you will need to SSH into Crimson, and execute the update binary from within a root shell. To do this, type the following commands in sequence;

ssh dev0@192.168.10.2
sudo -s # allows you to pass a command as root, non-interactive
Revision Update Command
RTM 4 ./updateCrimsonRtm4
RTM 5 ./updateCrimsonRtm5
RTM 6 ./updateCrimsonRtm6

Note

If you are only using the low band stage, or would otherwise like to skip the LUT table generation process, you may append the “nolut” arguement to the update command. In doing so, you will skip LUT generation.

After the SDCard image and FPGA image have been update, and the server has come up again, (which can take up to 10minutes), you should see something similar to the the following output, but with version numbers that reflect your release;

Checking Version
RX 1f33a442
TX 1f33a442
SYNTH 1f33a442
FRIMWARE 4acd189d
FS-METAPV c64b534d25b6907292cd1bd2693b21fecbba6339
WEBPV 1aa775024abdff7481f973279959baa787b4f461
FPGA 9a10c7830
\=\=\=\=\=\=\=\=\=
VERSION GOOD
\=\=\=\=\=\=\=\=\=

The unit will now automatically start to re-generating the look up table.

Note

If you are only using the baseband (low frequency) chain, the update process should now be complete, and you may now reboot the Crimson unit;

Regenerating the lookup table

By default, after running the update utility, a look up table is re-generated.

The Look Up Table (LUT) generation process optimizes the high frequency chain of your particular Crimson unit and is unique to your specific Rx and Tx boards and radio chains.

The process to manually force the regeneration of the Look Up Table follows;

  1. SSH into the Crimson unit, using the dev0 user and the password provided by Per Vices.

  2. sudo to a root shell: $ sudo -s

  3. Delete the calibration data: # rm -rf /var/crimson/calibration-data/

  4. Regenerate the calibration data by enabling the lookup table (LUT) # echo 1 |sudo tee /var/crimson/state/{t,r}x/{a,b,c,d}/rf/freq/lut_en

Note

During the LUT generation processs, you will not be able to use Crimson.

Note

It will take approximately 30-45 min to fully complete this process.

The process is complete when the bottom LED on the crimson unit stops flashing.

While logged on to the Crimson unit, you may observe the current LUT generation process status by typing;

sudo systemctl status crimson-server

The log results will indicate the radio chain, frequency and offset you will need, and are automatically used in the calibration tables.

Updating the corresponding UHD version

After updating your Crimson unit, you should update to an appropriate version of UHD. Speaking broadly, if you compiled from master, then you should use the master UHD branch. If you compiled from a release branch, you should use the corresponding branch, unless otherwise specified.

To identify the correct version of UHD, select the branch or release that shares the same release tag as the one you selected when updating Crimson.

You can always determine what UHD version you have installed, by typing;

$ uhd_usrp_probe --version

Instructions on how to compile UHD from source can be found here.

Reboot device

For the changes to takle effect, you will need to reboot the device.

Manual MCU Update

If the automatic update doesn’t work for you, there are other options. Contact us for more help on these matters.

FPGA Firmware

The FPGA firmware used by Crimson TNG is stored on the provided Crimson TNG SD card and is loaded onto the FPGA during boot. This procedure describes how to replace or update the FPGA code stored on the SD card.

It is also possible to update the FPGA firmware using the command line, or directly over JTAG using a USB Blaster.

Note

Updating firmware using the USB Blaster is not recommended if you are also using the SoC, as it may adversely impact SoC operation.

FPGA Update

FPGA Update Pre-requisites

You require the following items prior to updating the FPGA firmware stored on the FPGA firmware:

  1. FPGA Binaries (soc_system.rbf)
    • This contains the FPGA firmware as a raw binary file (rbf) named soc_system.rbf. If you are compiling from source, or from within Quartus 2, you will have to convert the default output file (with an .sof extension - SRAM object file) to an appropriate RBF file. To do this, you must first compile the project. After compiling the project, open the Convert Programmer menu (File » Convert Programming Files) and use the settings.
  2. Crimson TNG SD Card
    • The SD Card shipped with your Crimson TNG platform.
  3. Mini SD Card Reader
    • All Crimson TNG transceivers ship with a USB card reader.
    • Alternatively, you may use your own.
  4. A computer to copy over the SD Card.
    • In order to copy over the SD Card, you will need a computer to copy the updated or generated FPGA firmware to the SD Card.

Figure 9.2: Quartus 2 IDE Convert Programming Files GUI.

The settings illustrate the conversion of the default (.sof) file format to the desired raw binary file (.rbf), with a mode of Passive Parallel x16, and an output filename of soc_system.rbf.

FPGA Update Procedure

  1. If you are generating from your own Quartus Project, ensure that you have converted the newly generated source code to a Raw Binary File.

  2. Confirm the file name is:

soc_system.rbf

  1. Power down Crimson TNG, and remove the mini SD Card.

  2. Insert the SD Card into the provided USB mini-SD Card reader, and insert the assembly into a computer.

  3. Identify the partition containing the existing soc_system.rbf file. The SD Card contains three partitions. Depending on your operating system, the number of viewable partitions may vary. Using a reasonable operating system, you should be able to view three partitions. For example:

      sdX1 - partition 1- type b - W95 FAT32 partition (This contains the RBF file!)
      sdX2 - partition 2 - type 83 - Linux ext3 partition (Contains SoC file system)
      sdX2 - partition 3 - type a3 - UBOOT and boot loader (It's best not to touch this)
    
  4. Once you identify the correct partition, replace the existing RBF file with the new one, and cleanly unmount the partition.

Note

You must ensure you cleanly unmount the partition. You risk corrupting the firmware image (and possibly even Crimson TNG) if you simply remove the USB key without first unmounting (safely removing) the USB key! For added security, type sync to flush file system buffers prior to removing the SDCard.

  1. Remove the USB mini-SD Card adapter from your computer and pull out the mini-SD Card. Insert the bare SD card back into the Crimson TNG mini-SD Card receptacle.

  2. Congratulations! You should have successfully updated the Crimson TNG FPGA code.