humpback-dds/src/lib.rs

#![no_std]
#![feature(str_strip)]
extern crate embedded_hal;
use embedded_hal::{
	blocking::spi::Transfer,
};

#[macro_use]
pub mod bitmask_macro;
pub mod spi_slave;
pub mod cpld;

pub mod config_register;
use crate::config_register::ConfigRegister;
use crate::config_register::CFGMask;
use crate::config_register::StatusMask;

pub mod attenuator;
use crate::attenuator::Attenuator;

pub mod dds;
use crate::dds::DDS;

// pub mod scpi;
// pub mod translation;
pub mod nal_tcp_client;
pub mod flash;

pub mod mqtt_mux;

/*
 *	Enum for structuring error
 */
#[derive(Debug)]
pub enum Error<E> {
	SPI(E),
	CSError,
	GetRefMutDataError,
	AttenuatorError,
	IOUpdateError,
	DDSError,
	ConfigRegisterError,
	DDSCLKError,
	DDSRAMError,
	ParameterError,
	MqttTopicError,
	MqttCommandError,
}

#[derive(Debug, Clone)]
pub enum ClockSource {
	OSC,
	SMA,
	MMCX,
}

/*
 *  Struct for Urukul master device
 */
pub struct Urukul<SPI> {
	config_register: ConfigRegister<SPI>,
	attenuator: Attenuator<SPI>,
	dds: [DDS<SPI>; 4],
	f_master_clk: f64,
}

impl<SPI, E> Urukul<SPI>
where
	SPI: Transfer<u8, Error = E>,
{
	/*
	 *  Master constructor for the entire Urukul device
	 *  Supply 7 SPI channels to Urukul and 4 reference clock frequencies
	 */
	pub fn new(spi1: SPI, spi2: SPI, spi3: SPI, spi4: SPI, spi5: SPI, spi6: SPI, spi7: SPI) -> Self {
		// Construct Urukul
		Urukul {
			config_register: ConfigRegister::new(spi1),
			attenuator: Attenuator::new(spi2),
			// Create 4 DDS instances with fixed 25MHz clock
			// Counter-intuitive to assign urukul clock before having a urukul
			dds: [
				DDS::new(spi4, 25_000_000.0),
				DDS::new(spi5, 25_000_000.0),
				DDS::new(spi6, 25_000_000.0),
				DDS::new(spi7, 25_000_000.0),
			],
			// Default clock selection: OSC, fixed 100MHz speed
			f_master_clk: 100_000_000.0,
		}
	}

	/*
	 *  Reset method. To be invoked by initialization and manual reset.
	 *  Only Urukul struct provides reset method.
	 *  DDS reset is controlled by Urukul (RST).
	 *  Attenuators only have shift register reset, which does not affect its data
	 *  CPLD only has a "all-zero" default state.
	 */
	pub fn reset(&mut self) -> Result<(), Error<E>> {
		// Reset DDS and attenuators
		self.config_register.set_configurations(&mut [
			(CFGMask::RST, 1),
			(CFGMask::IO_RST, 1),
			(CFGMask::IO_UPDATE, 0)
		])?;
		// Set 0 to all fields on configuration register.
		self.config_register.set_configurations(&mut [
			(CFGMask::RF_SW, 		0),
			(CFGMask::LED, 			0),
			(CFGMask::PROFILE, 		0),
			(CFGMask::IO_UPDATE, 	0),
			(CFGMask::MASK_NU, 		0),
			(CFGMask::CLK_SEL0, 	0),
			(CFGMask::SYNC_SEL, 	0),
			(CFGMask::RST, 			0),
			(CFGMask::IO_RST, 		0),
			(CFGMask::CLK_SEL1, 	0),
			(CFGMask::DIV, 			0),
		])?;
		// Init all DDS chips. Configure SDIO as input only.
		for chip_no in 0..4 {
			self.dds[chip_no].init()?;
		}
		// Clock tree reset. OSC clock source by default
		self.f_master_clk = 100_000_000.0;
		// CPLD divides clock frequency by 4 by default.
		for chip_no in 0..4 {
			self.dds[chip_no].set_ref_clk_frequency(self.f_master_clk / 4.0)?;
		}
		Ok(())
	}

	/*
	 *  Test method fo Urukul.
	 *  Return the number of test failed.
	 */
	pub fn test(&mut self) -> Result<u32, Error<E>> {
		let mut count = self.config_register.test()?;
		count += self.attenuator.test()?;
		for chip_no in 0..4 {
			count += self.dds[chip_no].test()?;
		}
		Ok(count)
	}
}

impl<SPI, E> Urukul<SPI>
where
	SPI: Transfer<u8, Error = E>
{

	fn get_channel_switch_status(&mut self, channel: u32) -> Result<bool, Error<E>> {
		if channel < 4 {
			self.config_register.get_status(StatusMask::RF_SW).map(|val| (val & (1 << channel)) != 0)
		} else {
			Err(Error::ParameterError)
		}
	}

	fn set_channel_switch(&mut self, channel: u32, status: bool) -> Result<(), Error<E>> {
		if channel < 4 {
			let prev = u32::from(self.config_register.get_status(StatusMask::RF_SW)?);
			let next = {
				if status {
					prev | (1 << channel)
				} else {
					prev & (!(1 << channel))
				}
			};
			self.config_register.set_configurations(&mut [
				(CFGMask::RF_SW, next),
			]).map(|_| ())
		} else {
			Err(Error::ParameterError)
		}
	}

	fn set_clock(&mut self, source: ClockSource, frequency: f64, division: u8) -> Result<(), Error<E>> {
		// Change clock source through configuration register
		self.set_clock_source(source)?;

		// Modify the master clock frequency
		// Prevent redundunt call to change f_ref_clk
		self.f_master_clk = frequency;

		self.set_clock_division(division)
	}

	fn set_clock_source(&mut self, source: ClockSource) -> Result<(), Error<E>> {
		// Change clock source through configuration register
		match source {
			ClockSource::OSC => self.config_register.set_configurations(&mut [
				(CFGMask::CLK_SEL0, 0),
				(CFGMask::CLK_SEL1, 0),
			]),
			ClockSource::MMCX => self.config_register.set_configurations(&mut [
				(CFGMask::CLK_SEL0, 0),
				(CFGMask::CLK_SEL1, 1),
			]),
			ClockSource::SMA => self.config_register.set_configurations(&mut [
				(CFGMask::CLK_SEL0, 1),
			]),
		}.map(|_| ())
	}

	fn set_clock_frequency(&mut self, frequency: f64) -> Result<(), Error<E>> {
		// Update master clock frequency
		self.f_master_clk = frequency;

		// Update all DDS f_ref_clk
		self.set_dds_ref_clk()
	}

	fn set_clock_division(&mut self, division: u8) -> Result<(), Error<E>> {
		match division {
			1 => self.config_register.set_configurations(&mut [
				(CFGMask::DIV, 1),
			]),
			2 => self.config_register.set_configurations(&mut [
				(CFGMask::DIV, 2),
			]),
			4 => self.config_register.set_configurations(&mut [
				(CFGMask::DIV, 3),
			]),
			_ => Err(Error::ParameterError),
		}?;

		self.set_dds_ref_clk()
	}

	fn set_dds_ref_clk(&mut self) -> Result<(), Error<E>> {
		// Calculate reference clock frequency after clock division from configuration register
		let f_ref_clk = self.f_master_clk / (self.get_master_clock_division() as f64);

		// Update all DDS chips on reference clock frequency
		for dds_channel in 0..4 {
			self.dds[dds_channel].set_ref_clk_frequency(f_ref_clk)?;
		}
		Ok(())
	}

	fn get_master_clock_division(&mut self) -> u8 {
		match self.config_register.get_configuration(CFGMask::DIV) {
			0 | 3 => 4,
			1 => 1,
			2 => 2,
			_ => panic!("Divisor out of range, when reading configuration register (CPLD)."),
		}
	}

	fn set_channel_attenuation(&mut self, channel: u8, attenuation: f32) -> Result<(), Error<E>> {
		if channel >= 4 || attenuation < 0.0 || attenuation > 31.5 {
			return Err(Error::ParameterError);
		}
		self.attenuator.set_channel_attenuation(channel, attenuation)
	}

	fn set_profile(&mut self, profile: u8) -> Result<(), Error<E>> {
		if profile >= 8 {
			return Err(Error::ParameterError);
		}
		self.config_register.set_configurations(&mut [
			(CFGMask::PROFILE, profile.into())
		]).map(|_| ())
	}

	fn set_channel_single_tone_profile(&mut self, channel: u8, profile: u8, frequency: f64, phase: f64, amplitude: f64) -> Result<(), Error<E>> {
		if channel >= 4 || profile >= 8 || frequency < 0.0 || phase >= 360.0 ||
			phase < 0.0 || amplitude < 0.0 || amplitude > 1.0 {
			return Err(Error::ParameterError);
		}
		self.dds[usize::from(channel)].set_single_tone_profile(profile, frequency, phase, amplitude)
	}

	fn set_channel_single_tone_profile_frequency(&mut self, channel: u8, profile: u8, frequency: f64)-> Result<(), Error<E>> {
		if channel >= 4 || profile >= 8 || frequency < 0.0 {
			return Err(Error::ParameterError);
		}
		self.dds[usize::from(channel)].set_single_tone_profile_frequency(profile, frequency)
	}

	fn set_channel_single_tone_profile_phase(&mut self, channel: u8, profile: u8, phase: f64)-> Result<(), Error<E>> {
		if channel >= 4 || profile >= 8 || phase >= 360.0 || phase < 0.0 {
			return Err(Error::ParameterError);
		}
		self.dds[usize::from(channel)].set_single_tone_profile_phase(profile, phase)
	}

	fn set_channel_single_tone_profile_amplitude(&mut self, channel: u8, profile: u8, amplitude: f64)-> Result<(), Error<E>> {
		if channel >= 4 || profile >= 8 || amplitude < 0.0 || amplitude > 1.0 {
			return Err(Error::ParameterError);
		}
		self.dds[usize::from(channel)].set_single_tone_profile_amplitude(profile, amplitude)
	}

	fn set_channel_sys_clk(&mut self, channel: u8, f_sys_clk: f64) -> Result<(), Error<E>> {
		self.dds[usize::from(channel)].set_sys_clk_frequency(f_sys_clk)
	}
}