From fb2076a026ceb4b938ce313bcd25024ccb23dcea Mon Sep 17 00:00:00 2001
From: Sebastien Bourdeauducq <sb@m-labs.hk>
Date: Sat, 21 Dec 2019 14:56:41 +0800
Subject: [PATCH] basemod_att: add dB functions, document

---
 artiq/coredevice/basemod_att.py       | 27 ++++++++++++++++++++++++++-
 doc/manual/core_drivers_reference.rst |  7 +++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/artiq/coredevice/basemod_att.py b/artiq/coredevice/basemod_att.py
index d68e9b7a9..a46625c28 100644
--- a/artiq/coredevice/basemod_att.py
+++ b/artiq/coredevice/basemod_att.py
@@ -11,7 +11,7 @@ class BaseModAtt:
 
     @kernel
     def reset(self):
-        # HMC's incompetence in digital design an interfaces means that
+        # HMC's incompetence in digital design and interfaces means that
         # the HMC542 needs a level low on RST_N and then a rising edge
         # on Latch Enable. Their "latch" isn't a latch but a DFF.
         # Of course, it also powers up with a random attenuation, and
@@ -27,6 +27,11 @@ class BaseModAtt:
 
     @kernel
     def set_mu(self, att0, att1, att2, att3):
+        """
+        Sets the four attenuators on BaseMod.
+        The values are in half decibels, between 0 (no attenuation)
+        and 63 (31.5dB attenuation).
+        """
         word = (
             (att0 <<  2) |
             (att1 << 10) | 
@@ -37,9 +42,29 @@ class BaseModAtt:
 
     @kernel
     def get_mu(self):
+        """
+        Retrieves the current settings of the four attenuators on BaseMod.
+        """
         word = self.shift_reg.get()
         att0 = (word >>  2) & 0x3f
         att1 = (word >> 10) & 0x3f
         att2 = (word >> 18) & 0x3f
         att3 = (word >> 26) & 0x3f
         return att0, att1, att2, att3
+
+    @kernel
+    def set(self, att0, att1, att2, att3):
+        """
+        Sets the four attenuators on BaseMod.
+        The values are in decibels.
+        """
+        self.set_mu(round(att0*2.0), round(att1*2.0), round(att2*2.0), round(att3*2.0))
+
+    @kernel
+    def get(self):
+        """
+        Retrieves the current settings of the four attenuators on BaseMod.
+        The values are in decibels.
+        """
+        att0, att1, att2, att3 = self.get_mu()
+        return 0.5*att0, 0.5*att1, 0.5*att2, 0.5*att3
diff --git a/doc/manual/core_drivers_reference.rst b/doc/manual/core_drivers_reference.rst
index fd6f36fca..bcdcd1a00 100644
--- a/doc/manual/core_drivers_reference.rst
+++ b/doc/manual/core_drivers_reference.rst
@@ -112,6 +112,13 @@ RF generation drivers
     :members:
 
 
+:mod:`artiq.coredevice.basemod_att` module
+++++++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: artiq.coredevice.basemod_att
+    :members:
+
+
 DAC/ADC drivers
 ---------------