dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2008 Free Software Foundation, Inc. |
| 3 | * |
| 4 | * This software is distributed under multiple licenses; see the COPYING file in the main directory for licensing information for this specific distribuion. |
| 5 | * |
| 6 | * This use of this software may be subject to additional restrictions. |
| 7 | * See the LEGAL file in the main directory for details. |
| 8 | |
| 9 | This program is distributed in the hope that it will be useful, |
| 10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| 12 | |
| 13 | */ |
| 14 | |
kurtis.heimerl | 8aea56e | 2011-11-26 03:18:30 +0000 | [diff] [blame] | 15 | #ifndef SIGPROCLIB_H |
| 16 | #define SIGPROCLIB_H |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 17 | |
| 18 | #include "Vector.h" |
| 19 | #include "Complex.h" |
Alexander Chemeris | d734e2d | 2013-06-16 14:30:58 +0400 | [diff] [blame] | 20 | #include "BitVector.h" |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 21 | |
| 22 | /** Indicated signalVector symmetry */ |
kurtis.heimerl | 3b8ad24 | 2011-11-26 03:18:19 +0000 | [diff] [blame] | 23 | enum Symmetry { |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 24 | NONE = 0, |
| 25 | ABSSYM = 1 |
| 26 | }; |
| 27 | |
| 28 | /** Convolution type indicator */ |
kurtis.heimerl | 3b8ad24 | 2011-11-26 03:18:19 +0000 | [diff] [blame] | 29 | enum ConvType { |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 30 | FULL_SPAN = 0, |
| 31 | OVERLAP_ONLY = 1, |
| 32 | START_ONLY = 2, |
| 33 | WITH_TAIL = 3, |
| 34 | NO_DELAY = 4, |
| 35 | CUSTOM = 5, |
| 36 | UNDEFINED = 255 |
| 37 | }; |
| 38 | |
| 39 | /** the core data structure of the Transceiver */ |
| 40 | class signalVector: public Vector<complex> |
| 41 | { |
| 42 | |
| 43 | private: |
| 44 | |
| 45 | Symmetry symmetry; ///< the symmetry of the vector |
| 46 | bool realOnly; ///< true if vector is real-valued, not complex-valued |
| 47 | |
| 48 | public: |
| 49 | |
| 50 | /** Constructors */ |
| 51 | signalVector(int dSize=0, Symmetry wSymmetry = NONE): |
| 52 | Vector<complex>(dSize), |
| 53 | realOnly(false) |
| 54 | { |
| 55 | symmetry = wSymmetry; |
| 56 | }; |
| 57 | |
| 58 | signalVector(complex* wData, size_t start, |
| 59 | size_t span, Symmetry wSymmetry = NONE): |
| 60 | Vector<complex>(NULL,wData+start,wData+start+span), |
| 61 | realOnly(false) |
| 62 | { |
| 63 | symmetry = wSymmetry; |
| 64 | }; |
| 65 | |
| 66 | signalVector(const signalVector &vec1, const signalVector &vec2): |
| 67 | Vector<complex>(vec1,vec2), |
| 68 | realOnly(false) |
| 69 | { |
| 70 | symmetry = vec1.symmetry; |
| 71 | }; |
| 72 | |
| 73 | signalVector(const signalVector &wVector): |
| 74 | Vector<complex>(wVector.size()), |
| 75 | realOnly(false) |
| 76 | { |
| 77 | wVector.copyTo(*this); |
| 78 | symmetry = wVector.getSymmetry(); |
| 79 | }; |
| 80 | |
| 81 | /** symmetry operators */ |
| 82 | Symmetry getSymmetry() const { return symmetry;}; |
| 83 | void setSymmetry(Symmetry wSymmetry) { symmetry = wSymmetry;}; |
| 84 | |
| 85 | /** real-valued operators */ |
| 86 | bool isRealOnly() const { return realOnly;}; |
| 87 | void isRealOnly(bool wOnly) { realOnly = wOnly;}; |
| 88 | }; |
| 89 | |
| 90 | /** Convert a linear number to a dB value */ |
| 91 | float dB(float x); |
| 92 | |
| 93 | /** Convert a dB value into a linear value */ |
| 94 | float dBinv(float x); |
| 95 | |
| 96 | /** Compute the energy of a vector */ |
| 97 | float vectorNorm2(const signalVector &x); |
| 98 | |
| 99 | /** Compute the average power of a vector */ |
| 100 | float vectorPower(const signalVector &x); |
| 101 | |
| 102 | /** Setup the signal processing library */ |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 103 | void sigProcLibSetup(int sps); |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 104 | |
| 105 | /** Destroy the signal processing library */ |
| 106 | void sigProcLibDestroy(void); |
| 107 | |
| 108 | /** |
| 109 | Convolve two vectors. |
| 110 | @param a,b The vectors to be convolved. |
| 111 | @param c, A preallocated vector to hold the convolution result. |
| 112 | @param spanType The type/span of the convolution. |
| 113 | @return The convolution result. |
| 114 | */ |
| 115 | signalVector* convolve(const signalVector *a, |
| 116 | const signalVector *b, |
| 117 | signalVector *c, |
| 118 | ConvType spanType, |
| 119 | unsigned startIx = 0, |
| 120 | unsigned len = 0); |
| 121 | |
| 122 | /** |
| 123 | Generate the GSM pulse. |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 124 | @param sps The number of samples per GSM symbol. |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 125 | @param symbolLength The size of the pulse. |
| 126 | @return The GSM pulse. |
| 127 | */ |
Thomas Tsou | 83e0689 | 2013-08-20 16:10:01 -0400 | [diff] [blame^] | 128 | void generateGSMPulse(int sps, int symbolLength); |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 129 | |
| 130 | /** |
| 131 | Frequency shift a vector. |
| 132 | @param y The frequency shifted vector. |
| 133 | @param x The vector to-be-shifted. |
| 134 | @param freq The digital frequency shift |
| 135 | @param startPhase The starting phase of the oscillator |
| 136 | @param finalPhase The final phase of the oscillator |
| 137 | @return The frequency shifted vector. |
| 138 | */ |
| 139 | signalVector* frequencyShift(signalVector *y, |
| 140 | signalVector *x, |
| 141 | float freq = 0.0, |
| 142 | float startPhase = 0.0, |
| 143 | float *finalPhase=NULL); |
| 144 | |
| 145 | /** |
| 146 | Correlate two vectors. |
| 147 | @param a,b The vectors to be correlated. |
| 148 | @param c, A preallocated vector to hold the correlation result. |
| 149 | @param spanType The type/span of the correlation. |
| 150 | @return The correlation result. |
| 151 | */ |
| 152 | signalVector* correlate(signalVector *a, |
| 153 | signalVector *b, |
| 154 | signalVector *c, |
| 155 | ConvType spanType, |
| 156 | bool bReversedConjugated = false, |
| 157 | unsigned startIx = 0, |
| 158 | unsigned len = 0); |
| 159 | |
| 160 | /** Operate soft slicer on real-valued portion of vector */ |
| 161 | bool vectorSlicer(signalVector *x); |
| 162 | |
| 163 | /** GMSK modulate a GSM burst of bits */ |
| 164 | signalVector *modulateBurst(const BitVector &wBurst, |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 165 | int guardPeriodLength, |
Thomas Tsou | 83e0689 | 2013-08-20 16:10:01 -0400 | [diff] [blame^] | 166 | int sps, bool emptyPulse = false); |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 167 | |
| 168 | /** Sinc function */ |
| 169 | float sinc(float x); |
| 170 | |
| 171 | /** Delay a vector */ |
| 172 | void delayVector(signalVector &wBurst, |
| 173 | float delay); |
| 174 | |
| 175 | /** Add two vectors in-place */ |
| 176 | bool addVector(signalVector &x, |
| 177 | signalVector &y); |
| 178 | |
| 179 | /** Multiply two vectors in-place*/ |
| 180 | bool multVector(signalVector &x, |
| 181 | signalVector &y); |
| 182 | |
| 183 | /** Generate a vector of gaussian noise */ |
| 184 | signalVector *gaussianNoise(int length, |
| 185 | float variance = 1.0, |
| 186 | complex mean = complex(0.0)); |
| 187 | |
| 188 | /** |
| 189 | Given a non-integer index, interpolate a sample. |
| 190 | @param inSig The signal from which to interpolate. |
| 191 | @param ix The index. |
| 192 | @return The interpolated signal value. |
| 193 | */ |
| 194 | complex interpolatePoint(const signalVector &inSig, |
| 195 | float ix); |
| 196 | |
| 197 | /** |
| 198 | Given a correlator output, locate the correlation peak. |
| 199 | @param rxBurst The correlator result. |
| 200 | @param peakIndex Pointer to value to receive interpolated peak index. |
| 201 | @param avgPower Power to value to receive mean power. |
| 202 | @return Peak value. |
| 203 | */ |
| 204 | complex peakDetect(const signalVector &rxBurst, |
| 205 | float *peakIndex, |
| 206 | float *avgPwr); |
| 207 | |
| 208 | /** |
| 209 | Apply a scalar to a vector. |
| 210 | @param x The vector of interest. |
| 211 | @param scale The scalar. |
| 212 | */ |
| 213 | void scaleVector(signalVector &x, |
| 214 | complex scale); |
| 215 | |
| 216 | /** |
| 217 | Add a constant offset to a vecotr. |
| 218 | @param x The vector of interest. |
| 219 | @param offset The offset. |
| 220 | */ |
| 221 | void offsetVector(signalVector &x, |
| 222 | complex offset); |
| 223 | |
| 224 | /** |
| 225 | Generate a modulated GSM midamble, stored within the library. |
| 226 | @param gsmPulse The GSM pulse used for modulation. |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 227 | @param sps The number of samples per GSM symbol. |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 228 | @param TSC The training sequence [0..7] |
| 229 | @return Success. |
| 230 | */ |
Thomas Tsou | 83e0689 | 2013-08-20 16:10:01 -0400 | [diff] [blame^] | 231 | bool generateMidamble(int sps, int tsc); |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 232 | /** |
| 233 | Generate a modulated RACH sequence, stored within the library. |
| 234 | @param gsmPulse The GSM pulse used for modulation. |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 235 | @param sps The number of samples per GSM symbol. |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 236 | @return Success. |
| 237 | */ |
Thomas Tsou | 83e0689 | 2013-08-20 16:10:01 -0400 | [diff] [blame^] | 238 | bool generateRACHSequence(int sps); |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 239 | |
| 240 | /** |
| 241 | Energy detector, checks to see if received burst energy is above a threshold. |
| 242 | @param rxBurst The received GSM burst of interest. |
| 243 | @param windowLength The number of burst samples used to compute burst energy |
| 244 | @param detectThreshold The detection threshold, a linear value. |
| 245 | @param avgPwr The average power of the received burst. |
| 246 | @return True if burst energy is above threshold. |
| 247 | */ |
| 248 | bool energyDetect(signalVector &rxBurst, |
| 249 | unsigned windowLength, |
| 250 | float detectThreshold, |
| 251 | float *avgPwr = NULL); |
| 252 | |
| 253 | /** |
| 254 | RACH correlator/detector. |
| 255 | @param rxBurst The received GSM burst of interest. |
| 256 | @param detectThreshold The threshold that the received burst's post-correlator SNR is compared against to determine validity. |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 257 | @param sps The number of samples per GSM symbol. |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 258 | @param amplitude The estimated amplitude of received RACH burst. |
| 259 | @param TOA The estimate time-of-arrival of received RACH burst. |
| 260 | @return True if burst SNR is larger that the detectThreshold value. |
| 261 | */ |
| 262 | bool detectRACHBurst(signalVector &rxBurst, |
| 263 | float detectThreshold, |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 264 | int sps, |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 265 | complex *amplitude, |
| 266 | float* TOA); |
| 267 | |
| 268 | /** |
| 269 | Normal burst correlator, detector, channel estimator. |
| 270 | @param rxBurst The received GSM burst of interest. |
| 271 | |
| 272 | @param detectThreshold The threshold that the received burst's post-correlator SNR is compared against to determine validity. |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 273 | @param sps The number of samples per GSM symbol. |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 274 | @param amplitude The estimated amplitude of received TSC burst. |
| 275 | @param TOA The estimate time-of-arrival of received TSC burst. |
| 276 | @param maxTOA The maximum expected time-of-arrival |
| 277 | @param requestChannel Set to true if channel estimation is desired. |
| 278 | @param channelResponse The estimated channel. |
| 279 | @param channelResponseOffset The time offset b/w the first sample of the channel response and the reported TOA. |
| 280 | @return True if burst SNR is larger that the detectThreshold value. |
| 281 | */ |
| 282 | bool analyzeTrafficBurst(signalVector &rxBurst, |
| 283 | unsigned TSC, |
| 284 | float detectThreshold, |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 285 | int sps, |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 286 | complex *amplitude, |
| 287 | float *TOA, |
| 288 | unsigned maxTOA, |
| 289 | bool requestChannel = false, |
| 290 | signalVector** channelResponse = NULL, |
| 291 | float *channelResponseOffset = NULL); |
| 292 | |
| 293 | /** |
| 294 | Decimate a vector. |
| 295 | @param wVector The vector of interest. |
| 296 | @param decimationFactor The amount of decimation, i.e. the decimation factor. |
| 297 | @return The decimated signal vector. |
| 298 | */ |
| 299 | signalVector *decimateVector(signalVector &wVector, |
| 300 | int decimationFactor); |
| 301 | |
| 302 | /** |
| 303 | Demodulates a received burst using a soft-slicer. |
| 304 | @param rxBurst The burst to be demodulated. |
| 305 | @param gsmPulse The GSM pulse. |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 306 | @param sps The number of samples per GSM symbol. |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 307 | @param channel The amplitude estimate of the received burst. |
| 308 | @param TOA The time-of-arrival of the received burst. |
| 309 | @return The demodulated bit sequence. |
| 310 | */ |
Thomas Tsou | 83e0689 | 2013-08-20 16:10:01 -0400 | [diff] [blame^] | 311 | SoftVector *demodulateBurst(signalVector &rxBurst, int sps, |
| 312 | complex channel, float TOA); |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 313 | |
| 314 | /** |
| 315 | Creates a simple Kaiser-windowed low-pass FIR filter. |
| 316 | @param cutoffFreq The digital 3dB bandwidth of the filter. |
| 317 | @param filterLen The number of taps in the filter. |
| 318 | @param gainDC The DC gain of the filter. |
| 319 | @return The desired LPF |
| 320 | */ |
| 321 | signalVector *createLPF(float cutoffFreq, |
| 322 | int filterLen, |
| 323 | float gainDC = 1.0); |
| 324 | |
| 325 | /** |
| 326 | Change sampling rate of a vector via polyphase resampling. |
| 327 | @param wVector The vector to be resampled. |
| 328 | @param P The numerator, i.e. the amount of upsampling. |
| 329 | @param Q The denominator, i.e. the amount of downsampling. |
| 330 | @param LPF An optional low-pass filter used in the resampling process. |
| 331 | @return A vector resampled at P/Q of the original sampling rate. |
| 332 | */ |
| 333 | signalVector *polyphaseResampleVector(signalVector &wVector, |
| 334 | int P, int Q, |
| 335 | signalVector *LPF); |
| 336 | |
| 337 | /** |
| 338 | Change the sampling rate of a vector via linear interpolation. |
| 339 | @param wVector The vector to be resampled. |
| 340 | @param expFactor Ratio of new sampling rate/original sampling rate. |
| 341 | @param endPoint ??? |
| 342 | @return A vector resampled a expFactor*original sampling rate. |
| 343 | */ |
| 344 | signalVector *resampleVector(signalVector &wVector, |
| 345 | float expFactor, |
| 346 | complex endPoint); |
| 347 | |
| 348 | /** |
| 349 | Design the necessary filters for a decision-feedback equalizer. |
| 350 | @param channelResponse The multipath channel that we're mitigating. |
| 351 | @param SNRestimate The signal-to-noise estimate of the channel, a linear value |
| 352 | @param Nf The number of taps in the feedforward filter. |
| 353 | @param feedForwardFilter The designed feed forward filter. |
| 354 | @param feedbackFilter The designed feedback filter. |
| 355 | @return True if DFE can be designed. |
| 356 | */ |
| 357 | bool designDFE(signalVector &channelResponse, |
| 358 | float SNRestimate, |
| 359 | int Nf, |
| 360 | signalVector **feedForwardFilter, |
| 361 | signalVector **feedbackFilter); |
| 362 | |
| 363 | /** |
| 364 | Equalize/demodulate a received burst via a decision-feedback equalizer. |
| 365 | @param rxBurst The received burst to be demodulated. |
| 366 | @param TOA The time-of-arrival of the received burst. |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 367 | @param sps The number of samples per GSM symbol. |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 368 | @param w The feed forward filter of the DFE. |
| 369 | @param b The feedback filter of the DFE. |
| 370 | @return The demodulated bit sequence. |
| 371 | */ |
| 372 | SoftVector *equalizeBurst(signalVector &rxBurst, |
| 373 | float TOA, |
Thomas Tsou | d24cc2c | 2013-08-20 15:41:45 -0400 | [diff] [blame] | 374 | int sps, |
dburgess | b3a0ca4 | 2011-10-12 07:44:40 +0000 | [diff] [blame] | 375 | signalVector &w, |
| 376 | signalVector &b); |
kurtis.heimerl | 8aea56e | 2011-11-26 03:18:30 +0000 | [diff] [blame] | 377 | |
| 378 | #endif /* SIGPROCLIB_H */ |