Init refactory and general doc update

ChangeLog.md

@@ -1,5 +1,12 @@
 # Si5351mcu Changelog File #
 
+## v0.3 (June 14, 2017) ##
+
+* Feature: the lib now handle the include and start of the I2C (Wire) library internally via the init procedures
+* Added a new generic init() procedure to handle the default parameters
+* The init() function is required from now on (MANDATORY)
+* Fixed the way we handled the base xtal and the correction factor
+
 ## v0.2rc (April 23, 2017) ##
 
 * Added power level support for each output independently, watch out!: setting the power level will enable the output.
@@ -21,8 +28,6 @@
 * Added Changelog and version files.
 * Extensive tests made to validate every function.
 
-
 ## Initial Release, v0.0 (April 9, 2017) ##
 
 * Basic functionality.
-

README.md

@@ -19,49 +19,50 @@ This are so far the implemented features (Any particular wish? use the Issues ta
 * Custom XTAL passing on init (default is 27.0MHz)
 * You are able to pass a correction to the xtal while running (as for your own calibration procedure)
 * You have a fast way to power off all outputs of the Chip.
-* You can enable/disable any output at any time.
+* You can enable/disable any output at any time (by default all outputs are off after the init procedure, you has to enable them)
 * You can only have 2 of the 3 outputs running at any moment, see "Two of three" below.
 * It's free of click noise while you move on frequency.
-* **NEW!**  Power control on each output independently (see setPower(clk, level) on the lib header, initial default is to lowest level: 2mA)
+* Power control on each output independently (see _setPower(clk, level)_ on the lib header, initial default is to lowest level: 2mA)
+* **NEW!** You don't need to include and configure the Wire (I2C) library.
 
 ## Click noise free ##
 
 The click noise while tunning the chip came from the following actions (stated in the datasheet & app notes):
 
 ```
 1 - Turn CLKx output off.
-2 - Reset the PLLx for the new calculations.
-3 - Turn CLKx output on.
+2 - Update the PLL and MultySynth registers
+3 - Reset the PLLx for the new calculations.
+4 - Turn CLKx output on.
 ```
 
 In my code I follow a strategy of just do that at the start of the freq output and move the PLLs and multisynths freely without reseting the PLLs or multisynths outputs.
 
-In my tests I can move across several Mhz (1 to 10, 28 to 150) without getting off frequency at least with +/- 5 Hz (my instrument tolerance).
-
 ## The start sequence is important ##
 
 Yes, in your setup code segment you must initialize it in the following sequence:
 
+* Initialize the library with the default or optional Xtal Clock.
 * Apply correction factor (if needed)
-* (Optional) power off all outputs
-* Set sweet spots frequencies to **both** clock outputs
+* Set sweet spots frequencies to **both** clock outputs.
 * Force a reset of the PLLs.
+* Enable the desired outputs.
 
-Here you have an example code of what I mean ("Si" is the lib instance): 
+Here you have an example code of what I mean ("Si" is the lib instance):
 
 ```
 setup() {
-    (... my great code here ...)
+    (... code here ...)
 
     //////////////////////////////////
-    // Si5351 functions
+    //        Si5351 functions       /
     //////////////////////////////////
 
-    // apply my calculated correction factor
-    Si.correction(-1250);
+    // Init the library, in this case with the defaults
+    Si.init();
 
-    // Optional, power off all outputs until needed
-    Si.off();
+    // Optional, apply my calculated correction factor
+    Si.correction(-1250);
 
     // set some sweet spot freqs
     Si.setFreq(0, 25000000);       // CLK0 output
@@ -70,7 +71,11 @@ setup() {
     // force the first reset
     Si.reset();
 
-    (... other great code here ...)
+    // enable only the needed outputs
+    Si.enable(0);
+    Si.enable(1);
+
+    (... other code here ...)
 }
 
 ```
@@ -84,9 +89,6 @@ For example if you use CLK0 for VFO and CLK1 for BFO for a 40m receiver with 10
     Si.setFreq(0, 17150000);  // VFO 7.150 Mhz (mid band) + 10.0 Mhz
     Si.setFreq(1, 10000000);  // BFO 10.0 Mhz
 
-    // force the first reset
-    Si.reset();
-
 ```
 
 If you need to apply/vary the correction factor **after** the setup process you will get a click noise on the next setFreq() to apply the changes.
@@ -95,7 +97,7 @@ If you need to apply/vary the correction factor **after** the setup process you
 
 Yes, there is a tittle catch here with CLK1 and CLK2: both share PLL_B and as we use math to produce an integer division you can only use one of them at a time.
 
-Note: _In practice you can, but the other will move from the frequency you set, which is odd, so I made them mutually exclusive._
+Note: _In practice you can, but the other will move from the frequency you set, which is an unexpected behavior, so I made them mutually exclusive._
 
 This are the valid combinations for independent clocks output.
 
@@ -112,7 +114,7 @@ The only author is Pavel Milanes, CO7WT, a cuban amateur radio operator; reachab
 
 Always download the latest version from the [github repository](https://github.com/pavelmc/Si5351mcu/)
 
-See ChangeLog.md on this repository to know what are the latest changes.
+See ChangeLog.md and Version files on this repository to know what are the latest changes and versions.
 
 ## If you like to give thanks... ##
 

examples/si5351_mcu/si5351_mcu.ino

@@ -1,5 +1,5 @@
 /*
- * si5351mcu - Si5351 library for Arduino MCU tuned for size and click-less
+ * si5351mcu - Si5351 library for Arduino, MCU tuned for size and click-less
  *
  * This is the packed example.
  *
@@ -39,12 +39,11 @@
  * Then make a sweep from 60 to 62 Mhz on CLK2, with an stop every 200Khz
  * and then a train of one second pulses will follow with varying power levels
  *
-  * Take into account your XTAL error, see Si.correction(###) below
+ * Take into account your XTAL error, see Si.correction(###) below
  *
  ***************************************************************************/
 
 #include "si5351mcu.h"
-#include "Wire.h"
 
 // lib instantiation as "Si"
 Si5351mcu Si;
@@ -61,12 +60,11 @@ long freq      = freqStart;
 
 
 void setup() {
-    // init the wire lib
-    Wire.begin();
-
     // init the Si5351 lib
-    // this lib doesn't need an init function unless you need to pass a
-    // different xtal (from the default of 27.00000 Mhz)
+    Si.init();
+
+    // For a different xtal (from the default of 27.00000 Mhz)
+    // just pass it on the init procedure, just like this
     // Si.init(26570000);
 
     // set & apply my calculated correction factor
@@ -75,9 +73,8 @@ void setup() {
     // pre-load some sweet spot freqs
     Si.setFreq(0, freqStart);
     Si.setFreq(1, freqStart);
-
-    // disable all outputs and reset the PLLs
-    Si.off();
+
+    // reset the PLLs
     Si.reset();
 
     // put a tone in the start freq on CLK0
@@ -89,17 +86,17 @@ void setup() {
     Si.enable(1);
     delay(3000);
     // Si.disable(1);   // no need to disable, enabling CLK2 disable this
-    
+
     Si.setFreq(2, freqStart + 1000000);      // CLK2 output
     Si.enable(2);
     delay(3000);
     //Si.disable(2);   // no need to disable, enabling CLK1 disable this
-    
+
     Si.setFreq(1, freqStart +  500000);      // CLK1 output
     Si.enable(1);
     delay(3000);
     //Si.disable(1);   // no need to disable, enabling CLK2 disable this
-    
+
     Si.setFreq(2, freqStart + 1000000);      // CLK2 output
     Si.enable(2);
     delay(3000);
@@ -116,7 +113,7 @@ void setup() {
 void loop() {
     // check for the stop to measure
     if ((freq % EVERY) == 0) {
-        // it's time to flip-flop it 
+        // it's time to flip-flop it
 
         for (byte i = 0; i < 4; i++) {
             // power off the clk2 output
@@ -130,8 +127,9 @@ void loop() {
             //
             // moreover, setting the power on an output will enable it
             // so I will explicit omit the enable here
-            Si.setPower(2,i);
+            Si.setPower(2, i);
             //Si.enable(2);
+
             delay(1000);
         }
 

library.properties

@@ -1,5 +1,5 @@
-name=Si5351mcd optimized for small size & click-less while tuning
-version=0.2rc
+name=Si5351mcu
+version=0.3
 author=Pavel Milanes <[email protected]>
 maintainer=Pavel Milanes <[email protected]>
 sentence=A MCU friendly library for the Si5351A clock generator ICs from Silicon Labs.