Tested and working with the emulator

Author: PaulZC

examples/Example01_AlternateAddress/Example01_AlternateAddress.ino

@@ -5,7 +5,7 @@
 
   By: Paul Clark
   SparkFun Electronics
-  Date: 2024/8/1
+  Date: 2024/11/21
   SparkFun code, firmware, and software is released under the MIT License.
   Please see LICENSE.md for further details.
 
@@ -31,9 +31,9 @@ void setup()
   Wire.begin(); // Begin the I2C bus
 
   bool begun;
-  begun = myOCXO.begin(Wire, 0x60); // Initialize the SiT5811 - using a custom bus and address
-  begun = myOCXO.begin(0x60); // This is also possible. It defaults to Wire
-  begun = myOCXO.begin(); // This is also possible. It defaults to Wire and address 0x60
+  begun = myOCXO.begin(Wire, 0x50); // Initialize the SiT5811 - using a custom bus and address
+  begun = myOCXO.begin(0x50); // This is also possible. It defaults to Wire
+  begun = myOCXO.begin(); // This is also possible. It defaults to Wire and address 0x50
 
   if (!begun)
   {
@@ -42,14 +42,13 @@ void setup()
   }
 
   // Read the frequency control word - should be zero initially
-  int32_t fcw = myOCXO.getFrequencyControlWord();
+  int64_t fcw = myOCXO.getFrequencyControlWord();
   Serial.print("The frequency control word is: ");
   Serial.println(fcw);
 
-  // Read the pull range control
-  uint8_t prc = myOCXO.getPullRangeControl();
-  Serial.print("Pull range control is: ");
-  Serial.println(myOCXO.getPullRangeControlText(prc));
+  // Read the available (clipped) pull range
+  double pullAvailable = myOCXO.getMaxPullAvailable();
+  Serial.printf("Maximum frequency pull is: %e\r\n", pullAvailable);
 }
 
 void loop()

examples/Example02_setFrequencyHz/Example02_setFrequencyHz.ino

@@ -3,7 +3,7 @@
 
   By: Paul Clark
   SparkFun Electronics
-  Date: 2024/8/1
+  Date: 2024/11/21
   SparkFun code, firmware, and software is released under the MIT License.
   Please see LICENSE.md for further details.
 
@@ -40,18 +40,14 @@ void setup()
   Serial.print(myOCXO.getBaseFrequencyHz());
   Serial.println(" Hz");
 
-  myOCXO.setPullRangeControl(SiT5811_PULL_RANGE_200ppm); // Set the pull range control to 200ppm
-
-  Serial.print("Pull range control set to ");
-  Serial.println(myOCXO.getPullRangeControlText(myOCXO.getPullRangeControl()));
-
-  myOCXO.setFrequencyHz(10001000.0); // Set the frequency to 10.001MHz (+100ppm)
+  myOCXO.setFrequencyHz(10000010.0); // Set the frequency to 10.000010MHz (+1ppm)
 
   Serial.print("Frequency set to ");
   Serial.print(myOCXO.getFrequencyHz());
   Serial.println(" Hz");
 
-  Serial.print("Frequency control word should be 16777215. It is ");
+  // Frequency control word should be 1ppm / 800ppm * (2^38 - 1) , rounded down
+  Serial.print("Frequency control word should be 343597383. It is ");
   Serial.println(myOCXO.getFrequencyControlWord());
 }
 

examples/Example03_IllegalFrequency/Example03_IllegalFrequency.ino

@@ -5,7 +5,7 @@
 
   By: Paul Clark
   SparkFun Electronics
-  Date: 2024/8/1
+  Date: 2024/11/21
   SparkFun code, firmware, and software is released under the MIT License.
   Please see LICENSE.md for further details.
 
@@ -42,18 +42,28 @@ void setup()
   Serial.print(myOCXO.getBaseFrequencyHz());
   Serial.println(" Hz");
 
-  myOCXO.setPullRangeControl(SiT5811_PULL_RANGE_200ppm); // Set the pull range control to 200ppm
+  // Read the available (clipped) pull range
+  double pullAvailable = myOCXO.getMaxPullAvailable();
+  Serial.printf("Maximum frequency pull is: %e\r\n", pullAvailable);
 
-  Serial.print("Pull range control set to ");
-  Serial.println(myOCXO.getPullRangeControlText(myOCXO.getPullRangeControl()));
+  double lowestFrequency = 10e6 - (10e6 * pullAvailable);
+  Serial.print("The lowest frequency available is ");
+  Serial.print(lowestFrequency);
+  Serial.println(" Hz");
 
   myOCXO.setFrequencyHz(9900000.0); // Try to set the frequency to 9.9MHz (-10000ppm)
 
   Serial.print("Frequency set to ");
   Serial.print(myOCXO.getFrequencyHz());
   Serial.println(" Hz");
 
-  Serial.print("Frequency control word should be -33554432. It is ");
+  double fractionalPull = pullAvailable / 800e-6; // Fractional pull compared to 800ppm
+  fractionalPull *= pow(2, 38); // Convert to expected control word
+  int64_t expectedControlWord = 0 - fractionalPull;
+
+  Serial.print("Frequency control word should be ");
+  Serial.print(expectedControlWord);
+  Serial.print(". It is ");
   Serial.println(myOCXO.getFrequencyControlWord());
 }
 

examples/Example04_setFrequencyByBiasMillis/Example04_setFrequencyByBiasMillis.ino

@@ -6,24 +6,24 @@
 
   By: Paul Clark
   SparkFun Electronics
-  Date: 2024/8/1
+  Date: 2024/11/21
   SparkFun code, firmware, and software is released under the MIT License.
   Please see LICENSE.md for further details.
 
-  Consider the SiT5811AI-FS033IT-10.000000 used on the SparkFun RTK mosaic-T:
+  Consider the SiT5811AI-KYG33IV-10.000000:
   The operating temperature range is Industrial, -40 to 85°C (option "I").
   LVCMOS output (option "-").
-  Frequency stability +/-50ppb (option "S").
-  It is OCXO with an I2C address of 0x60 (option "0").
+  Frequency stability +/-1ppb (option "Y").
+  It is DCOCXO with a configurable I2C address (option "G").
   Supply voltage 3.3V (option "33").
   Pin 1 is Output Enable (option "I"). (No software OE control).
-  The default pull range is 6.25ppm (option "T").
+  The pull range limit is 3.125ppm (option "V").
   Base frequency is 10.000000MHz.
 
   Consider this example:
   * The OCXO frequency has not yet been changed. It is running at the default 10.000000 MHz.
   * 10.000000 MHZ is the library default base frequency. But we could set it with setBaseFrequencyHz(10000000.0)
-  * The pull range is read during begin. But we could set it with setPullRangeControl(SiT5811_PULL_RANGE_6ppm25)
+  * The available pull range is read during begin.
   * The mosaic-T manual states that the oscillator frequency should be changed by no more than 3ppb per second.
   * We tell the library this using setMaxFrequencyChangePPB(3.0)
   * The GNSS RxClkBias reports that receiver time is ahead of system time by 200 nanoseconds (+200ns).
@@ -33,8 +33,8 @@
   * To remove that bias in one second, the oscillator frequency would need to be reduced to 9.999998 MHz.
   * That is a change of 2 parts in 10000000, or 0.2ppm, or 200ppb.
   * The frequency change will be limited to 3ppb.
-  * Since the SiT5811 Pull Range is set to 6.25ppm, and the Pull Register is 26-bit signed, 3ppb corresponds to 16106 LSB.
-  * The firmware writes the value -16106 to the Frequency Control Register, reducing the frequency to 9.99999997 MHz.
+  * Since the SiT5811 maximum Pull Range is 800ppm, and the Pull Register is 39-bit signed, 3ppb corresponds to 1030792 LSB.
+  * The firmware writes the value -1030792 to the Frequency Control Register, reducing the frequency to 9.99999997 MHz.
   * getFrequencyHz will return 9999999.97
 
 */
@@ -70,24 +70,25 @@ void setup()
   Serial.print(myOCXO.getBaseFrequencyHz());
   Serial.println(" Hz");
 
-  myOCXO.setPullRangeControl(SiT5811_PULL_RANGE_6ppm25); // Set the pull range control to 6.25ppm
-
-  Serial.print("Pull range control set to ");
-  Serial.println(myOCXO.getPullRangeControlText(myOCXO.getPullRangeControl()));
-
   myOCXO.setMaxFrequencyChangePPB(3.0); // Set the maximum frequency change in PPB
 
   Serial.print("Maximum frequency change set to ");
   Serial.print(myOCXO.getMaxFrequencyChangePPB());
   Serial.println(" PPB");
 
-  myOCXO.setFrequencyByBiasMillis(200.0e-6); // Set the frequency by clock bias (+200ns, +200e-6ms)
+  Serial.print("Frequency control word should be 0. It is ");
+  Serial.println(myOCXO.getFrequencyControlWord());
+
+  Serial.println("Applying a clock bias of +200ns");
+  // Set the frequency by clock bias (+200ns, +200e-6ms)
+  // For this test, set the P term to 1.0 and the I term to 0.0
+  myOCXO.setFrequencyByBiasMillis(200.0e-6, 1.0, 0.0);
 
   Serial.print("Frequency should be 9999999.97 Hz. It is ");
   Serial.print(myOCXO.getFrequencyHz());
   Serial.println(" Hz");
 
-  Serial.print("Frequency control word should be -16106. It is ");
+  Serial.print("Frequency control word should be -1030792. It is ");
   Serial.println(myOCXO.getFrequencyControlWord());
 }
 

examples/SiT5358_Emulator/SiT5358_Emulator.ino

@@ -0,0 +1,107 @@
+/*
+  Emulate the SiT5811 OCXO.
+
+  By: Paul Clark
+  SparkFun Electronics
+  Date: 2024/11/21
+  SparkFun code, firmware, and software is released under the MIT License.
+  Please see LICENSE.md for further details.
+
+  Note: This code doesn't update the registerAddress correctly - on ESP32 (3.0.1).
+        registerAddress is only updated _after_ the registers have been read...
+        SfeSiT5811Driver::begin() calls readClipRegister() and readRegisters()
+        twice, to ensure registerAddress points at 0x00 and 0x0C correctly.
+
+*/
+
+#include <Wire.h>
+
+#define I2C_DEV_ADDR 0x50
+
+// Emulate registers 0x00 (DCXO Clip) to 0x0E (DCXO LSW) (16-bit, MSB first)
+#define CLIP 0x00 // Change to (e.g.) 0x08 to emulate 200ppm clip range. 
+#define NUM_REG_BYTES (15*2)
+volatile uint8_t registerBytes[NUM_REG_BYTES];
+volatile uint8_t registerAddress = 0;
+
+// On Request:
+// Write bytes from registerBytes, starting at registerAddress * 2
+void requestHandler()
+{
+  int i = registerAddress * 2;
+  for (; i < NUM_REG_BYTES; i++)
+    Wire.write(registerBytes[i]);
+}
+
+// On Receive:
+// Copy the first incoming byte into registerAddress (see notes above)
+// Copy the remaining bytes into registerBytes, starting at registerAddress * 2
+void receiveHandler(int len)
+{
+  int count = -1;
+  while (Wire.available())
+  {
+    uint8_t b = Wire.read();
+    switch (count)
+    {
+      case -1:
+        registerAddress = b;
+        break;
+      default:
+        if (((registerAddress * 2) + count) < NUM_REG_BYTES)
+          registerBytes[((registerAddress * 2) + count)] = b;
+        break;
+    }
+    count++;
+  }
+}
+
+void setup()
+{
+  // Initialize the register bytes
+  for (int i = 0; i < NUM_REG_BYTES; i++)
+    registerBytes[i] = 0;
+  registerBytes[0] = CLIP; // Store in OCXO Clip MSB
+
+  delay(1000); // Allow time for the microcontroller to start up
+
+  Serial.begin(115200); // Begin the Serial console
+  while (!Serial)
+  {
+    delay(100); // Wait for the user to open the Serial Monitor
+  }
+  Serial.println("SparkFun SiT5811 Emulator");
+
+  Wire.onReceive(receiveHandler);
+  Wire.onRequest(requestHandler);
+  Wire.begin((uint8_t)I2C_DEV_ADDR);
+}
+
+void loop()
+{
+  static unsigned long lastPrint = 0;
+
+  if (millis() > (lastPrint + 1000))
+  {
+    lastPrint = millis();
+
+    // Extract the 39-bit Frequency Control Word
+    uint64_t freqControl = ((uint64_t)registerBytes[28]) >> 1;
+    freqControl |= ((uint64_t)registerBytes[27]) << 7;
+    freqControl |= ((uint64_t)registerBytes[26]) << 15;
+    freqControl |= ((uint64_t)registerBytes[25]) << 23;
+    freqControl |= ((uint64_t)registerBytes[24]) << 31;
+    if (freqControl & 0x0000004000000000) // Correct two's complement
+      freqControl |= 0xFFFFFFC000000000;
+    
+    union // Avoid any ambiguity when converting uint64_t to int64_t
+    {
+        uint64_t unsigned64;
+        int64_t signed64;
+    } unsignedSigned64;
+    unsignedSigned64.unsigned64 = freqControl;
+
+    Serial.print("Frequency control is ");
+    Serial.println(unsignedSigned64.signed64);
+  }
+}