Skip to content

Latest commit

 

History

History
221 lines (162 loc) · 11.1 KB

README.md

File metadata and controls

221 lines (162 loc) · 11.1 KB
Raw

An Opulent Voice MSK Modem for the ADALM-Pluto SDR Platform

Keywords: #MSK #SDR #Pluto #Opulent-Voice

This is a Minimum Shift Keying (MSK) modem for Opulent Voice (OPV) targeted to Analog Devices ADALM-Pluto SDR Platform. This repository provides a top-level design to be included in Pluto's AMD Zync Z-7010 SoC. The modem and supporting functions are included from ORI's RTL library, and can be used in any FPGA development as well as non-OPV protocols. This repository can serve as a starting point/guide for targeting the MSK modem to other FPGA based SDR platforms.

The following ORI library components are used as submodules to this repository:

  1. msk_modulator
  2. msk_demodulator
  3. nco
  4. pi_controller
  5. prbs

Building

In oder to build the FPGA bitstream, you first need to install Vivado. Recommended version is 2022.2. In this documentation and in the Makefile, the Vivado installation path is assumed to be /opt/Xilinx/Vivado. If it is in another directory, change the path in the steps below (for example, to /tools/Xilinx/Vivado) or create a symbolic link in /opt pointing to the actual installation directory. For example,

sudo ln -s /tools/Xilinx /opt/Xilinx

Such a symbolic link is already in place on chococat and keroppi.

First, clone this repo with all submodules

git clone --recursive https://github.com/OpenResearchInstitute/pluto_msk

building bitstream only

  1. cd pluto_msk/projects/pluto/
  2. source /opt/Xilinx/Vivado/2022.2/settings64.sh
    (See above about the Vivado installation path.)
  3. make

For reference, on the chococat VM, the main branch takes:

real	128m34.908s
user	20m41.893s
sys	11m9.086s

If you update the VHDL code or choose another branch and rebuild on chococat VM, the new branch takes:

Cleaning msk_top library ...
Building msk_top library [/home/abraxas3d/documentation-friday3/pluto_msk/library/msk_top_ip.log] ... OK
Building pluto project [/home/abraxas3d/documentation-friday3/pluto_msk/projects/pluto/pluto_vivado.log] ... OK

real	54m40.380s
user	13m58.697s
sys	5m10.603s

Same process on I7_9700 (not vm)

Cleaning msk_top library ...
Building msk_top library [/home/hp-z2-dev/prog/ori-opulent/plutosdr-fw/pluto_msk/library/msk_top_ip.log] ... OK
Building pluto project [/home/hp-z2-dev/prog/ori-opulent/plutosdr-fw/pluto_msk/projects/pluto/pluto_vivado.log] ... OK

real	6m6,197s
user	5m58,976s
sys	0m17,079s

If you update the firmware and rebuild on chococat VM, the new build takes:

real	111m34.245s
user	12m18.919s
sys	9m16.466s

complete firmware

  1. Check if your Vivado path is correct on this line

    pluto_msk/firmware/Makefile

    Line 19 in 871bd13

    VIVADO_SETTINGS ?= /opt/Xilinx/Vivado/$(VIVADO_VERSION)/settings64.sh

    See above about the Vivado installation path. If /opt/Xilinx does not contain the Vivado software, create the symbolic link described above. An alternative is to edit this line of Makefile every time you clone this repository.
  2. cd pluto_msk/firmware
  3. make

For reference, on the chococat VM, this takes:

real	370m53.093s
user	77m38.923s
sys	39m46.236s

MSK Modem Architecture

Pluto_MSK_Modem address map

  • Absolute Address: 0x0
  • Base Offset: 0x0
  • Size: 0x43C00060
Offset Identifier Name
0x43C00000 pluto_msk_regs Pluto MSK Registers

pluto_msk_regs address map

  • Absolute Address: 0x43C00000
  • Base Offset: 0x43C00000
  • Size: 0x60

MSK Modem Configuration and Status Registers

Offset Identifier Name
0x00 Hash_ID_Low Pluto MSK FPGA Hash ID - Lower 32-bits
0x04 Hash_ID_High Pluto MSK FPGA Hash ID - Upper 32-bits
0x08 MSK_Init MSK Modem Control 0
0x0C MSK_Control MSK Modem Control 1
0x10 MSK_Status MSK Modem Status 0
0x14 Tx_Bit_Count MSK Modem Status 1
0x18 Tx_Enable_Count MSK Modem Status 2
0x1C Fb_FreqWord Bitrate NCO Frequency Control Word
0x20 TX_F1_FreqWord Tx F1 NCO Frequency Control Word
0x24 TX_F2_FreqWord Tx F2 NCO Frequency Control Word
0x28 RX_F1_FreqWord Rx F1 NCO Frequency Control Word
0x2C RX_F2_FreqWord Rx F2 NCO Frequency Control Word
0x30 LPF_Config_0 PI Controller Configuration and Low-pass Filter Configuration
0x34 LPF_Config_1 PI Controller Configuration Configuration Register 1
0x38 Tx_Data_Width Modem Tx Input Data Width
0x3C Rx_Data_Width Modem Rx Output Data Width
0x40 PRBS_Control PRBS Control 0
0x44 PRBS_Initial_State PRBS Control 1
0x48 PRBS_Polynomial PRBS Control 2
0x4C PRBS_Error_Mask PRBS Control 3
0x50 PRBS_Bit_Count PRBS Status 0
0x54 PRBS_Error_Count PRBS Status 1
0x58 LPF_Accum_F1 F1 PI Controller Accumulator
0x5C LPF_Accum_F2 F2 PI Controller Accumulator
0x60 axis_xfer_count MSK Modem Status 3
0x64 Rx_Sample_Discard Rx Sample Discard
0x68 LPF_Config_2 PI Controller Configuration Configuration Register 2

See MSK Top Regs for detailed register definitions.

Development Quickstart

Here is a set of instructions for getting this minimum shift keying (MSK) transceiver implementation to work on a PLUTO SDR.

Clone this pluto_msk repository.

git clone --recursive https://github.com/OpenResearchInstitute/pluto_msk.git

The repository should clone to the latest stable PLUTO firmware release commit. Here is an example of how to change to another branch of the hdl reference design. hdl_2022_r2 was used for VHDL development. Don't change branches of hdl unless you have to.

/pluto_msk/hdl$ git checkout hdl_2022_r2 
Previous HEAD position was 1978df298 axi_dac_interpolate: Improve the ctrl logic
branch 'hdl_2022_r2' set up to track 'origin/hdl_2022_r2'.
Switched to a new branch 'hdl_2022_r2'

If you are working on ORI virtual machine, then source the version of Vivado needed as follows.

$ source /tools/Xilinx/Vivado/2022.2/settings.sh

You can check which version of Vivado is currently being used as follows.

$ which vivado
/tools/Xilinx/Vivado/2022.2/bin/vivado

Change directories to the PLUTO project directory and run make.

/hdl/projects/pluto$ make

A useful log file for information, warnings, and errors is pluto_vivado.log

This repository is organized as an out of tree module.

Key lines in system_bd.tcl are:

https://github.com/OpenResearchInstitute/pluto_msk/blob/942aa516f8cc30af73a5a0c9ce3f8266012989e8/projects/pluto/system_bd.tcl#L7-19

set_property ip_repo_paths [list $ad_hdl_dir/library ../../library]  [current_fileset]
update_ip_catalog

The ip_repo_paths property lets us create a custom IP catalog for use with Vivado. It defines the path to one or more directories containing user-defined intellectual property (IP), like our blocks. The specified directories, and any sub-directories, are searched for files to add to the Vivado IP catalog. The property is assigned to the current fileset of the current project.

ip_repo_paths will look for a .xml file, where is the name of the IP to add to the catalog. This XML file lists the files that define the module. Subdirectories are searched through. We don't have to list out each individual module's .xml.

Where does our component.xml file come from? It's create by the msk_top_ip.tcl file. A version can be found here: https://github.com/OpenResearchInstitute/pluto_msk/blob/main/library/msk_top_ip.tcl

Setting the ip_repo_paths property needs to be followed by update_ip_catalog.

Example syntax:

set_property IP_REPO_PATHS {c:/Data/Designs C:/myIP} [current_fileset]
update_ip_catalog

Theory of Operation

Modulated Waveform

Minimum-Shift-Keying (MSK) can be described as a combination of Frequency-Shift-Keying (FSK) and Offset-QPSK (OQPSK) modulations. FSK generally sends 1-bit per symbol as either a mark or space (represented by two frequencies $F_1$ and $F_2$, respectively) for each bit transmitted.

MSK transmits 2-bits per symbol, as does does OQPSK, and the bits are offset in time by one bit period, also the same as OQPSK. While MSK uses two frequencies like FSK, the phase of the two frequecies is modulated similarly to OQPSK, such that there are 4 distinct phase combinations for each symbol.

The main difference between MSK and OQPSK is that MSK is a continuous phase modulation (CPM) meaning there are no phase discontinuties in the time domain waveform. This differs from QQPSK. Since MSK has no phase discontinuties, it is more spectrally efficient than FSK and most other 2-ary modulations.

MSK modulation can be expressed mathmatically in several ways, but the most interesting and intuitive form is:

$s(t) = I(t)cos\Big(\frac{2\pi F_b t}{4}\Big)cos(2\pi F_c t) + Q(t)sin\Big(\frac{2\pi F_b t}{4}\Big)sin(2\pi F_c t)$

where I(t) and Q(t) are elements of the set {-1,1}, and are offset by one bit period.

Offset Bit Timing

In this expression we can see that I and Q samples are each modulating two sinusoids. The $cos(2\pi F_c t)$ and $sin(2\pi F_c t)$ sinusoids are the carrier-frequency (for the pluto_msk this an IF). The more interesting sinusoids are the $cos\Big(\frac{2\pi F_b t}{4}\Big)$ and $sin\Big(\frac{2\pi F_b t}{4}\Big)$ which represent a sinusoid at $\frac{1}{4}$ the bit-rate. The I(t) and Q(t) signals each multiply $\frac{1}{2}$ of their respective sinusoid period by 1 or -1, resulting in 180 degree phase modulated sinusoids as shown below.

Roadmap

Contributors

ADI add custom IP

https://wiki.analog.com/resources/fpga/docs/hdl/creating_new_ip_guide