#!/usr/bin/env python3
"""Transmit-side DC offset and quadrature pre-distortion for the CaribouLite.

A zero-IF transmitter puts two unwanted things on the air alongside your
signal:

  * a carrier at the tuned frequency, from DC offset in the baseband and
    LO leakage in the mixer -- about -26 dBc here, uncorrected;
  * an image of your signal mirrored about the carrier, from gain and
    phase mismatch between the I and Q paths -- about -36.5 dBc.

Both are fixed properties of the hardware at a given frequency and gain,
so both can be cancelled by pre-distorting the samples. Measured on this
board the carrier comes down 13-19 dB and the image 4-13.

Do not bother with k on its own: it moves the image by 0.2 dB. What the
image responds to is d -- and not through the radiated carrier, which is
the easy and wrong conclusion to draw. Nulling the carrier 26 dB in the
modem's own TXCI/TXCQ trim leaves the image exactly where it was
(-36.3 dBc), while a digital d drops it to -49 dBc with the carrier
anywhere. So the offset that feeds the image sits UPSTREAM of that trim,
and only a correction in the samples reaches it. The mechanism that fits
is a second-order product of the baseband offset with the signal, which
lands at 2*f_carrier - f_tone -- exactly the image frequency -- but that
is a hypothesis consistent with the measurements, not something measured
here.

d is an absolute offset in units of full scale, NOT scaled by amp. On its
own it therefore radiates a carrier at 20*log10(|d|/amp), which is -34 dBc
for the |d| = 0.0097 measured here at amp = 0.5. Two consequences. The
achievable carrier suppression in dBc depends on amp. And a d larger than
the offset it is cancelling makes the carrier worse, not better, so a set
measured against one trim code must not be reused at another -- see
calibrate.py's model check, which catches exactly this. The impairment
model is

    y = alpha * x  +  beta * conj(x)  +  D

and the inverse is applied before transmission as

    x' = x + k * conj(x) + d,        k = -beta/alpha,  d = -D/alpha

which in real terms is a 2x2 matrix on (I, Q) plus an offset:

    I' = (1 + kr) * I  +      ki  * Q  + dr
    Q' =      ki  * I  + (1 - kr) * Q  + di

This module holds that transform and nothing else; calibrate.py measures
the coefficients, and the generators apply them.

Coefficients are per frequency and per gain. A set measured at 445.68 MHz
and -g 24 is not valid at 915 MHz or at full power.
"""
import json
import os

import numpy as np

DEFAULT_PATH = os.path.expanduser("~/.cariboulite_iqcal.json")

IDENTITY = {"kr": 0.0, "ki": 0.0, "dr": 0.0, "di": 0.0,
            "freq_hz": None, "gain": None, "rate_hz": None}


def load(path=DEFAULT_PATH):
    """Read a coefficient set, or the identity transform if there is none."""
    try:
        with open(path) as fh:
            c = json.load(fh)
    except (OSError, ValueError):
        return dict(IDENTITY)
    out = dict(IDENTITY)
    out.update({k: c[k] for k in c if k in out})
    return out


def save(coef, path=DEFAULT_PATH):
    with open(path, "w") as fh:
        json.dump(coef, fh, indent=2, sort_keys=True)
    return path


def describe(coef):
    k = complex(coef["kr"], coef["ki"])
    d = complex(coef["dr"], coef["di"])
    s = "k = %+.5f%+.5fj (|k| = %.5f, %.2f dBc)" % (
        k.real, k.imag, abs(k),
        20 * np.log10(abs(k)) if abs(k) > 0 else -np.inf)
    s += "\nd = %+.5f%+.5fj (|d| = %.5f)" % (d.real, d.imag, abs(d))
    if coef.get("freq_hz"):
        s += "\nvalid at %.4f MHz, -g %s, %.3f Msps" % (
            coef["freq_hz"] / 1e6, coef.get("gain"),
            (coef.get("rate_hz") or 0) / 1e6)
    return s


def apply_cal(x, coef):
    """Pre-distort a complex baseband array. Returns complex128."""
    k = complex(coef["kr"], coef["ki"])
    d = complex(coef["dr"], coef["di"])
    return x + k * np.conj(x) + d


def peak_growth(coef):
    """How much headroom the correction costs, as a linear factor.

    x + k conj(x) can be as large as (1 + |k|)|x| + |d|, so a waveform
    already at full scale will clip once corrected. The generators scale
    by the reciprocal of this.
    """
    k = abs(complex(coef["kr"], coef["ki"]))
    d = abs(complex(coef["dr"], coef["di"]))
    return (1.0 + k) + d


def to_int16_iq(x, amp=0.7, coef=None, headroom=True):
    """Pre-distort, scale and interleave to int16 I/Q for tx_test.

    amp is the amplitude *before* correction, so a given amp means the
    same power whether or not calibration is applied.
    """
    if coef is None:
        coef = dict(IDENTITY)
    y = apply_cal(x * amp, coef)
    if headroom:
        g = peak_growth(coef)
        if g > 1.0:
            y = y / g
    out = np.empty(y.size * 2, dtype=np.int16)
    out[0::2] = np.clip(np.real(y) * 32767.0, -32768, 32767).astype(np.int16)
    out[1::2] = np.clip(np.imag(y) * 32767.0, -32768, 32767).astype(np.int16)
    return out


def tone(rate_hz, offset_hz, seconds):
    """Unit-amplitude complex tone, phase-continuous."""
    n = int(round(seconds * rate_hz))
    ph = 2.0 * np.pi * offset_hz * np.arange(n, dtype=np.float64) / rate_hz
    return np.exp(1j * ph)


if __name__ == "__main__":
    import sys
    c = load(sys.argv[1] if len(sys.argv) > 1 else DEFAULT_PATH)
    print(describe(c))
    print("peak growth: x%.4f (%.2f dB of headroom given up)"
          % (peak_growth(c), 20 * np.log10(peak_growth(c))))
