Library

The RFzero library contains three sub-libraries and classes that again are divided into classes with functions. With the library also comes a modification of a third party library for LCD I2C use and three libraries for graphical displays.

  • The RFzero main library (RFzero.h)
    • EEPROM: eeprom.~
    • Frequency counter: freqCount.~
    • GPS: gps.~
    • MCU: mcu.~
    • RFzero: RFzero.~
    • Si5351A: si5351a.~
  • The RFzero Modes library (RFzero_modes.h) contains everything related to CW and MGM generation
    • Modes: modes.~
  • The RFzero utilities library (RFzero_util.h) is a collection of useful functions, that are not as such specific to the RFzero. The functions are not part of a class, so they are called directly without a class identifier
  • The RFzero LCD I2C library (RFzero_LCD_I2C.h) is a modification of the LiquidCrystal_I2C library by DFRobot and johnrickman
  • The libraries used for the graphical displays are made by Adafruit (Adafruit_ILI9341 and Adafruit-GFX-Library) and Jaret Burkett (ILI9488). Please consult those libraries for documentation

The RFzero main library

EEPROM

Usage
bool val = eeprom.isUnconfig();
Functionality
Returns true if the EEPROM contains improper values for the RFzero core parameters. Otherwise it returns true.

You should NOT use this function if you decide to use your own EEPROM map!
Parameters
None
Usage
uint32_t val = eeprom.getError();
Functionality
Returns the latest error code.

 0: last operation was a success
 1: Data too long (propagated from Wire.cpp)
 2: NACK on address transmit (propagated from Wire.cpp)
 3: NACK on data transmit (propagated from Wire.cpp)
 4: "other" error (propagated from Wire.cpp)
 8: bad configuration (unitialized or invalid)
 9: out of size (request address is beyond device end)
10: write data failed (probably full buffer)
11: read was short (less data than requested returned)
12: available data short (to little data available)
16: chip not implemented: device address
17: chip not implemented: read address
18: chip not implemented: write address
Parameters
None
Usage
eeprom.getSpecifications(uint32_t& type, uint32_t& size, uint8_t& addr);
Functionality
Returns the EEPROM reference type number, the total size and the I2C address in the parameters.
Parameters
uint32_t type: the EEPROM reference type number
uint32_t size: the EEPROM size
uint8_t addr: the EEPROM I2C address
Usage
byte val = eeprom.readByte(const uint32_t memAddr, const uint8_t alternate);
Functionality
Reads a byte from the EEPROM at the specified address. If reading fails the alternate value is returned.
Parameters
uint32_t memAddr: the EEPROM address
uint8_t alternate: the fall back value
Usage
double val = eeprom.readDouble(const uint32_t memAddr, const double alternate);
Functionality
Reads a double from the EEPROM at the specified address. If reading fails the alternate value is returned.
Parameters
uint32_t memAddr: the EEPROM address
uint8_t alternate: the fall back value
Usage
int val = eeprom.readInteger(const uint32_t memAddr, const int alternate);
Functionality
Reads an integer from the EEPROM at the specified address. If reading fails the alternate value is returned.
Parameters
uint32_t memAddr: the EEPROM address
uint8_t alternate: the fall back value
Usage
bool val = eeprom.readStr(const uint32_t memAddr, uint8_t* data, const uint32_t count);
Functionality
Reads a string from the EEPROM at the specified address and for a specified number of characters. If reading fails the alternate value is returned.
Parameters
uint32_t memAddr: the EEPROM address
uint8_t* data: the pointer to the data variable
uint32_t count: the number of characters to read
Usage
uint16_t val = eeprom.readWord(const uint32_t memAddr, const uint16_t alternate);
Functionality
Reads a word from the EEPROM at the specified address. If reading fails the alternate value is returned.
Parameters
uint32_t memAddr: the EEPROM address
uint16_t alternate: the fall back value
Usage
bool val = eeprom.saveReferenceStartFreq();
Functionality
Saves the Si5351A reference frequency to the EEPROM. Returns true if writing to the EEPROM was successful. Returns false is writing to the EEPROM was unsuccessful.
Parameters
None
Usage
bool val = eeprom.setType(eeprom_ref_t nbr);
Functionality
Selects the EEPROM configuration from the specification table. Returns true if the EEPROM type was found. Returns false if the EEPROM type was not found.
Parameters
eeprom_ref_t nbr: the EEPROM enum number
Usage
bool val = eeprom.writeByte(const uint32_t memAddr, const uint8_t data);
Functionality
Writes a byte to the EEPROM at the specified address. If writing is successful the function returns true otherwise false.
Parameters
uint32_t memAddr: the EEPROM address
uint8_t data: the value to write to the EEPROM
Usage
bool val = eeprom.writeDouble(const uint32_t memAddr, const double data);
Functionality
Writes a double to the EEPROM at the specified address. If writing is successful the function returns true otherwise false.
Parameters
uint32_t memAddr: the EEPROM address
double data: the value to write to the EEPROM
Usage
bool val = eeprom.writeInteger(const uint32_t memAddr, const int data);
Functionality
Writes an integer to the EEPROM at the specified address. If writing is successful the function returns true otherwise false.
Parameters
uint32_t memAddr: the EEPROM address
uint8_t data: the value to write to the EEPROM
Usage
bool val = eeprom.writeStr(const uint32_t memAddr, uint8_t* data, const uint32_t count);
Functionality
Writes a string to the EEPROM at the specified address and for a specified number of characters. Automatically takes page boundaries into account. If writing is successful the function returns true otherwise false.
Parameters
uint32_t memAddr: the EEPROM address
uint8_t* data: the pointer to the data variable
uint32_t count: the number of characters to read
Usage
bool val = eeprom.writeWord(const uint32_t memAddr, const uint16_t data);
Functionality
Writes a word to the EEPROM at the specified address. If writing is successful the function returns true otherwise false.
Parameters
uint32_t memAddr: the EEPROM address
uint16_t data: the value to write to the EEPROM

Frequency counter

typedef enum
{
    SRC_DISABLE, // we are not counting
    SRC_MAINCLOCK, // counting main CPU clock
    SRC_REFCLOCK, // counting si5351a reference clock
    SRC_EXT_PIN // counting some external pin
} FrqCountSource_t;
Usage
void init(void);
Functionality
Initializes the frequency counter.
Parameters
None
Usage
void resetCounter();
Functionality
Reset the frequency counter and metrics.
Parameters
None
Usage
bool val = countInputPin(unsigned int brd_pin);
Functionality
Sets the frequency counter to count the signal on a pin.
Parameters
unsigned int brd_pin: The pin with the signal to count
Usage
void countMCUFreq()
Functionality
Sets the frequency counter to count the MCU clock frequency.
Parameters
None
Usage
void countRefFreq();
Functionality
Sets the frequency counter to count the Si5351A clock frequency.
Parameters
None
Usage
double val = getAverage();
Functionality
Returns the average frequency counter over many samples. Might return a default value if the measurement is not available.
Parameters
None
Usage
uint32_t val = getBufferSize();
Functionality
Returns the number of samples in the averaging buffer. If the frequency counter was restarted for some reason, the number of samples may be low as it will take some minutes to build up. Restart may be due to disabling, change of frequency source, failed measurement, etc.
Parameters
None
Usage
uint32_t val = getLastFrequency();
Functionality
Get the last instantaneously captured frequency. Will return 0 if last PPS did not result in a valid measurement.
Parameters
None
Usage
FrqCountSource_t val = getMode();
Functionality
Returns the current frequency counter mode.
Parameters
None
Usage
double val = getReferenceFrequency();
Functionality
Returns the latest Si5351A average clock frequency.
Parameters
None
Usage
double val = getVariance();
Functionality
Returns the variance of the counted frequency. The square root of the variance is the standard deviation .
Parameters
None
Usage
void setDefaultRefFrequency(uint32_t freq);
Functionality
Sets the default frequency. This function is typically only used when starting.
Parameters
uint32_t freq: The default frequency.
Usage
void stopCount();
Functionality
Disables the frequency counter.
Parameters
None
Usage
bool val = TestClearPulse();
Functionality
Test if the counter gate pulse was there since last time this function was called. Returns true if there was a valid pulse otherwise it returns false.
Parameters
None

GPS

The GPS class consists of three sets of functions

  • General
  • NMEA specific
  • GPS receiver

But they are all accessed with the same gps.~ class identifier.

General functions
enum
{
    WAIT_MIN_EVEN = 65,
    WAIT_MIN_ODD = 66,
    WAIT_MIN_ANY = 67,
    WAIT_MIN_FIVE = 68,
    WAIT_MIN_TEN = 69,
    WAIT_MIN_FIFTEEN = 70,
    WAIT_MIN_TWENTY = 71,
    WAIT_MIN_THIRTY = 72
};

struct gpsSatData
{
    double latitude; // position: latitude (nord-south) in decimal degrees
    double longitude; // position: longitude (east-west) in decimal degrees
    int altitude; // position: alititude
    unsigned int satellites; // satellite count
    double hdop; // HDOP-valid (quality/satellite spread)
    int valid; // quality count
    bool foundLatLong; // is position valid

    unsigned int utcYear;
    unsigned int utcMonth;
    unsigned int utcDay;
    unsigned int utcHours;
    unsigned int utcMinutes;
    unsigned int utcSeconds;
};
Usage
void init();
Functionality
Sets up the serial port to the GPS receiver and enables the $GPGGA and $GPZDA frames. Sets the pinMode for the Valid LED.
Parameters
None
Usage
bool val = attachToPulse(void(*func)(void));
Functionality
Setup the automatic callback of a function at every PPS signal from the GPS. The function type must be void xyz(void), where xyz can be any name. Note that this function is called from an interrupt with interrupts disabled and should behave accordingly. This means returning as soon as at all possible and in general do as little work as possible. Also, any variable manipulated from this function should be declared volatile.
Returns true if a pulse arrived before timeout, otherwise false.
Parameters
(void(*func)(void): pointer to the function to be called back
Usage
int val = dayOfWeek(const uint32_t year, const uint32_t month, const uint32_t day);
Functionality
Calculates the day of the week based on the input year, month and day whether it being UTC or local. Returns 0 for Sunday, 1 for Monday, ... and 6 for Saturday. Use a switch case to print local day names:

switch (val)
{
    case 0: SerialUSB.println("Sunday"); break;
    case 1: SerialUSB.println("Monday"); break;
    case 2: SerialUSB.println("Tuesday"); break;
    case 3: SerialUSB.println("Wednesday"); break;
    case 4: SerialUSB.println("Thursday"); break;
    case 5: SerialUSB.println("Friday"); break;
    case 6: SerialUSB.println("Saturday"); break;
}
Parameters
uint32_t year: The year
uint32_t month: The month
uint32_t day: The day
Usage
void detachFromPulse(void);
Functionality
Turn of the PPS callback that was setup with attachToPulse().
Parameters
None
Usage
void getLocalTime(int &lclYear, int &lclMonth, int &lclDay, int &lclHours, int &lclMinutes);
Functionality
Calculates the local time in year, month, day, hours and minutes from UTC.
Parameters
lclYear: the local year lclMonth: the local month lclDay: the local day lclHours: the local hours lclMinutes: the local minutes
Usage
void getLocator(char* loc, const uint8_t len);
Functionality
Converts found latitude and longitude to a locator of variable length.
Parameters
char* loc: Pointer to the locator
uint8_t len: The length of the locator to be calculated. Valid values are 2, 4, 6, 8 or 10: JO (field), JO55 (square), JO55WM (locator), JO55WM54 (extended locator), or JO55WM54UA
Usage
bool val = getSatData(struct gpsSatData* target);
Functionality
Updates the getSatData struct pointed to with the data of the lastest parsed frame. Returns true if a valid frame was copied to the struct.
Parameters
struct gpsSatData* target: Pointer to the structure.
Usage
int val = getValid();
Functionality
Returns the GPS valid/invalid status. Actually it is the fix quality in the $GPGGA frame. 0 is the same as invalid.
Parameters
None
Usage
int val = getUtcSeconds();
Functionality
Returns the latest UTC second.
Parameters
None
Usage
int val = getUtcMinutes();
Functionality
Returns the latest UTC minute.
Parameters
None
Usage
int val = getUtcHours();
Functionality
Returns the latest UTC hour.
Parameters
None
Usage
void setLocalDST(const int dst);
Functionality
Enables Daylight Saving Time for local calculation.
Parameters
int dst: 0: disable DST, 1: enable DST
Usage
void setLocalTimeDiff(const int8_t hourOffset, const uint8_t minOffset);
Functionality
Sets the local time offset relative to UTC. West is negative.
Parameters
int8_t hourOffset: the number of hours offset to UTC, W is negative
uint8_t minOffset: the number of minutes offset to UTC, signed already in hourOffset
Usage
bool val = testSecond(unsigned short value);
Functionality
Compares the last parse frame 'second' value to the given number and returns true/false.
Parameters
unsigned short value: The second to compare with
Usage
void validLedEnableUpdate(bool updt);
Functionality
Enables/disables the GPS class from using, i.e. updating, the Valid LED. The Valid LED is updated by default when initializing the GPS class.
Parameters
bool updt: false: no updating, true: enable updating
Usage
bool val = waitForPulse(unsigned int maxwait = 1050);
Functionality
Waits for next PPS signal from the GPS. Where it returns, either there just was a pulse, or, there was a timeout first. The timeout is specified in milliseconds, and if not given will be set to 1050 ms. Note that the MCU tick clock is used to measure the timeout, and it may be off by more than 100 ppm, so be careful with strict timeouts.
Returns true if a pulse arrived before timeout, otherwise false.
Parameters
unsigned int maxwait: The maximum number of ms to wait. Default is 1050 ms
Usage
int val = waitUntilTime(const unsigned int minute, const unsigned int second);
Functionality
Waits until the exact second and minute given occur and returns exactly after the PPS signal from the GPS.
Note that the parsed NMEA frame is a little behind, so if the clock second is tested right after the function is back it will appear to be 1 second late when in reality the GPS has not emitted the corresponding frame yet.
Returns then current minute if the target second was found. If there was a timeout, an other error or invalid GPS it returns -1.
Parameters
const unsigned int minute: minut at which to return. Can also be WAIT_MIN_EVEN for even minutes, WAIT_MIN_ODD for odd minutes, WAIT_MIN_ANY for any minute, WAIT_MIN_FIVE for any 5 minutes, WAIT_MIN_TEN for any ten minutes, WAIT_MIN_FIFTEEN for any 15 minutes, WAIT_MIN_TWENTY for any 20 minutes or WAIT_MIN_THIRTY for any 30 minutes
const unsigned int second: second to return
NMEA
Usage
bool val = nmeaAutoParse();
Functionality
Checks for serial data from the GPS and, if any, processes them accordingly. Call this function regularly (every 50 ms or so), and the NMEA frames are processed automatically, making the all output available in the gpsSatData object.
It is recommended to use the yield() function for call nmeaAutoParse().
Returns true, if a new frame has just been processed, which means the gpsSatData object has just been updated otherwise false
Parameters
None
Usage
void nmeaClearParse();
Functionality
Reset the automatic NMEA frame parser. Call this function to prevent the parser from getting confused if there has been an abnormal break in serial data from the GPS.
Parameters
None
Usage
void nmeaClearParseFrame();
Functionality
Clear the internal parser. Call before restarting.
Parameters
None
Usage
bool val = nmeaInputFrameChar(char ch);
Functionality
Takes a single character from the GPS serial data and buffers it for parsing. Will automatically call the nmeaParseFrame() function when the line end appears.
When a frame has been feed to the parser, this function returns true, no matter what the result of the parsing was.
Returns true if the parser was called otherwise false.
Parameters
char ch: The next character from serial data
Usage
char* nmeaGetLastFrame();
Functionality
Returns a char pointer to the frame that was just received. This function should only be called after the frame was completed (when nmeaInputFrameChar() returned true) and before the next character is feed. Otherwise a NULL pointer is returned.
Returns pointer to the frame or NULL if no frame is ready.
Parameters
None
Usage
bool val = nmeaParseFrame(char* str);
Functionality
Parses the $GPGGA and $GPZDA frames and extracts UTC, satellites, valid status, locator, HDOP, latitude and longitude to the gpsSatData object.
Returns true if parsing was successful otherwise it returns false.
Parameters
char str: A pointer to the string to parse
Receiver
Usage
void command(const char* cmd);
Functionality
Sends a command string to the GPS receiver.
Parameters
char* cmd: a pointer to the command string
Usage
void end();
Functionality
Closes the serial port to the GPS receiver.
Parameters
None
Usage
void pause();
Functionality
Closes the serial port to the GPS receiver.
Parameters
None
Usage
void resetSoftware();
Functionality
Resets the GPS receiver software.
Parameters
None
Usage
void resume();
Functionality
(Re)opens the serial port connection at 9600 Baud.
Parameters
None
Usage
void sendFrame(uint8_t *frame, const uint8_t frameLength);
Functionality
Sends a frame to the GSP receiver. The function calculates the checksum itself.
Parameters
uint8_t *frame: pointer to the frame to send
uint8_t frameLength: the length of the frame to send
Usage
void setLeapSeconds(const uint8_t leapSeconds);
Functionality
Sets the UTC leap seconds relative to the GPS system time.
Parameters
uint8_t leapSecond: the leap seconds value

MCU

Usage
uint8_t val = mcu.digitalReadPort(const int portNbr)
Functionality
Returns the entire port value, but only for the number of bits for the relevant utility port U#.
Utility port and number of bits returned:
0: 6 bits
1: 8 bits
2: 6 bits
3: 2 bits
4: 2 bits
5: 2 bits
Parameters
int portNbr: the utility port number to read
Usage
bool val = mcu.disableCallback();
Functionality
Disables the timer interrupt used by the Modes library.
Parameters
None
Usage
bool val = mcu.enableCallback(unsigned);
Functionality
Enables the timer interrupt used by the Modes library.
Parameters
unsigned: value
Usage
bool val = mcu.setupTimerCallback(void(*func)(void), uint32_t scale, uint32_t ticks);
Functionality
Sets up the timer interrupt used by the Modes library with the relevant prescaler and timer ticks values.
Parameters
void(*func)(void): the call back function to call the interrupt occurs uint32_t scale: the prescaler value uint32_t ticks: the timer ticks value
Usage
mcu.txLed(const bool on);
Functionality
Turns on or off the TX LED.
Parameters
bool on: the on/off input value

RFzero

static const bool ON = true;
static const bool OFF = false;
Usage
bool val = RFzero.init(eeprom_ref_t eepType);
Functionality
Master initializing function and to be included with every RFzero program.
Sets up the TX LED, PPS and Valid LED pins, the I2C speed to 400 kHz, the EEPROM type, the GPS, the Si5351A and prepares the frequency counter for use by the program in general.
Parameters
eeprom_ref_t eepType: the EEPROM enum type name
Usage
RFzero.printLibPrgVer(const int captionType, char* program);
Functionality
Prints the library version and program name using different captions.
captionType:
0: no header but prints the UTC of the GPS is valid
1: "Software" header and no GPS time
Parameters
const int captionType: the type number
char* program: the program name

Si5351A

#define MAX_MGM_TONES 9

static const bool PORT0 = false;
static const bool PORT1 = true;

typedef enum
{
    HARDWARE_T1_TRANSFORMER = 0,
    HARDWARE_T1_COMBINER = 1,
    HARDWARE_T1_NONE = 2
} Hardware_T1_t;

typedef enum
{
    OUTPUT_MODE_PUSHPULL = 0,
    OUTPUT_MODE_TWOTONE = 1,
    OUTPUT_MODE_IQ = 2,
    OUTPUT_MODE_H3A = 3,
    OUTPUT_MODE_SWEEP = 4,
    OUTPUT_MODE_SPREAD = 5
} OutputMode_t;

typedef enum
{
    RF_LEVEL_OFF = 0,
    RF_LEVEL_ON = 1,
    RF_LEVEL_2 = 2,
    RF_LEVEL_4 = 3,
    RF_LEVEL_6 = 4,
    RF_LEVEL_8 = 5,
    RF_LEVEL_ERROR = -1
} RFLevel_t;

typedef enum
{
    CALC_FAST = 0,
    CALC_EPSILON = 1,
} CalcMode_t;

struct Multisynths
{
    double freq;
    CalcMode_t mode;
    unsigned int a;
    double b_c;
    unsigned int b;
    unsigned int c;
    unsigned d;
    unsigned r;
};
Usage
void init();
Functionality
Resets and initializes the Si5351A. Configures the output ports and prepares the Si5351A for operation. No RF output is made.
Parameters
None
Usage
void calcFmd(const double fout, Multisynths &divs);
Functionality
Calculates the Feedback Multisynth Divider values from the wanted frequency.
Parameters
double fout: The wanted frequency
Multisynths &divs: Structure with the multisynth divider values
Usage
void calcOmdR(const unsigned int fout, Multisynths &divs);
Functionality
Calculates the Output Multisynth Divider and R divider values from the wanted frequency.
Parameters
unsigned int fout: The wanted frequency
Multisynths &divs: Structure with the multisynth divider values
Usage
Hardware_T1_t mode = getHardwareT1();
Functionality
Returns the T1 hardware type.
Parameters
None
Usage
double val = getRefFreq();
Functionality
Returns the latest used Si5351A clock frequency.
Parameters
None
Usage
unsigned int getVcoStartFrequency();
Functionality
Returns the currently used start frequency for the VCO. Valid range is 440 MHz to 600 MHz.
Parameters
None
Usage
bool val = modifyRegister(uint8_t addr, uint8_t bit_and, uint8_t bit_or);
Functionality
Modifies a register in the Si5351A. First a mask value is and'ed with the current register value which is then or'ed. Returns trues if there was no error other false is returned.
Parameters
uint8_t addr: the Si5351A register
uint8_t bit_and: The and mask value
uint8_t bit_or: The or value
Usage
bool val = outputMode(const OutputMode_t mode);
Functionality
Sets the Si5351A to the specified output mode. Returns true if the mode is valid otherwise false is returned.
If the output mode is changed to OUTPUT_MODE_TWOTONE, OUTPUT_MODE_H3E or OUTPUT_MODE_SWEEP it may be relevant to set the frequency at port 1.
If changing output mode to OUTPUT_MODE_SPREAD the Output Multisynth Divider must be less than 128 before calling the function. Afterwards calling the setFrequencySpread() function is required when changing the frequency and/or the spread spectrum modulation amplitude.
Parameters
OutputMode_t mode: The wanted output mode
Usage
bool val = readRegister(uint8_t addr, uint8_t& value);
Functionality
Reads a register from the Si5351A. Returns trues if there was no error other false is returned.
Parameters
uint8_t addr: The Si5351A register
uint8_t& value: The register value
Usage
void refFreqLevel(const RFLevel_t level);
Functionality
Sets the reference clock frequency on, off or drive strength for port 2.
Parameters
RFLevel_t level: The wanted level
Usage
void refFreqRefresh();
Functionality
Updates the reference frequency with the latest average frequency from the frequency counter.
Parameters
None
Usage
bool val = retuneFrequency();
Functionality
Retunes the the output frequencies which is relevant if the Si5351A clock frequency has changes.
Parameters
None
Usage
void rfLevel(const RFLevel_t level);
Functionality
Sets the output on, off or drive strength for both port 0 and port 1.
Parameters
RFLevel_t level: The wanted level
Usage
void rfLevelPort(const RFLevel_t level, const bool port);
Functionality
Sets the output on, off or drive strength for either port 0 (false) and port 1 (true).
Parameters
RFLevel_t level: The wanted level
bool port: The port to change
Usage
bool val = setFrequency(const double fout, const CalcMode_t);
Functionality
Sets the output frequency for both ports. Returns true if the output mode is in single tone mode otherwise it returns false.
Parameters
double fout: The wanted frequency
const CalcMode_t: The calculation mode
Usage
bool val = setFrequencyPort(const double fout, const bool port, const CalcMode_t);
Functionality
Sets the output frequency for for either port 0 (false) and port 1 (true). Returns true if the output mode is in dual tone mode otherwise it returns false.
Parameters
double fout: The wanted frequency
bool port: The port to change
const CalcMode_t: The calculation mode
Usage
bool val = setFrequencySpread(const double fout, const double sscAmp, const CalcMode_t);
Functionality
Sets the output frequency and spread spectrum amplitude. Returns true if input parameters are valid otherwise it returns false.
Parameters
double fout: The wanted frequency
double sscAmp: The spread spectrum center amplitude
const CalcMode_t: The calculation mode
Usage
void setHardwareT1(const Hardware_T1_t mode);
Functionality
Sets the T1 hardware mode to either transformer, combiner or none.
Parameters
Hardware_T1_t mode: The wanted T1 mode
Usage
void setVcoStartFrequency(unsigned int freq = 600000000UL);
Functionality
Changes the VCO start frequency from the default 600 MHz. This may be used for under clocking purposes e.g. to enable I/Q output for 3,5 MHz. Valid range is 440 MHz to 600 MHz.
Parameters
unsigned int freq: The VCO frequency in Hz
Usage
int val = testRegisterMask(uint8_t addr, uint8_t mask);
Functionality
Test a register vs a mask value. Returns 1 if identical, returns -1 if different and returns 0 is there was an error.
Parameters
uint8_t addr: the Si5351A register
uint8_t mask: The mask value
Usage
bool val = writeRegister(uint8_t addr, uint8_t value);
Functionality
Writes a value to a register in the Si5351A. Returns trues if there was no error other false is returned.
Parameters
uint8_t addr: the Si5351A register
uint8_t value: The value

The RFzero Modes library

static const int KEYING_OOK = 0;
static const int KEYING_FSK = 1;
static const int KEYING_CAM = 2;
static const int KEYING_MOD = 2;

#define INDEX_PAUSE        MAX_MGM_TONES
#define INDEX_CW_KEY_UP    MAX_MGM_TONES
#define INDEX_CW_KEY_DOWN  MAX_MGM_TONES + 1
#define INDEX_CAR_MOD MAX_MGM_TONES + 2 // Dummy value for two tones, use only for comparison

typedef enum
{
    TONES_ALL = 0, // Calculate CW + MGM tones
    TONES_CW  = 1, // Calculate only CW tones
    TONES_MGM = 2, // Calculate only MGM tones
    TONES_CMM = 3  // Calculate carrier with 800 Hz CW modulation tone offset and MGM tones
} CalcTones_t;

typedef enum
{
    FST4_15 = 0,
    FST4_30 = 1,
    FST4_60 = 2,
    FST4_120 = 3,
    FST4_300 = 4,
    FST4_300 = 5,
    FST4_1800 = 6
} FST4modes_t;

typedef enum
{
    FST4W_120 = 0,
    FST4W_300 = 1,
    FST4W_300 = 2,
    FST4W_1800 = 3
} FST4Wmodes_t;
Usage
bool val = Modes.calculateTones(double fnom, CalcTones_t tones);
Functionality
Calculates the register values for the tones for entire sequence relative to the nominal frequency. The tones can be for the CW part only, the MGM part only, carrier with 800 Hz CW modulation tone offset and MGM tones or all of them.
Parameters
double fnom: the nominal frequency
CalcTones_t tones: the tones to calculate (TONES_ALL, TOMES_CMM, TONES_CW or TONES_MGM)
Usage
bool val = Modes.calculateTonesMulti(double fnom, CalcTones_t tones, uint8_t multiplier);
Functionality
Calculates the register values for the tones for entire sequence relative to the nominal frequency and taking the multiplier value into account. The tones can be for the CW part only, the MGM part only, carrier with 800 Hz CW modulation tone offset and MGM tones or all of them.
Parameters
double fnom: the nominal frequency
CalcTones_t tones: the tones to calculate (TONES_ALL, TONES_CMM, TONES_CW or TONES_MGM)
uint8_t multiplier: the multiplier value from 1 to 255
Usage
bool val = Modes.calculateTonesReversed(double fnom, CalcTones_t tones);
Functionality
Calculates the register values for the tones for entire sequence relative to the nominal frequency, but with the location of the tones reversed relative to the carrier. This is required if mixing the RFzero output with an LO signal which is above the wanted frequency. The tones can be for the CW part only, the MGM part only, carrier with 800 Hz CW modulation tone offset and MGM tones or all of them.
Parameters
double fnom: the nominal frequency
CalcTones_t tones: the tones to calculate (TONES_ALL, TONES_CMM, TONES_CW or TONES_MGM)
Usage
bool val = Modes.sendMGM();
Functionality
Sends the encoded MGM message. Prior to calling the function the right timer parameters and encoding must be set using the mcu.setupTimerCallback() and Modes.setup...() functions. When running the TX LED will automatically flash at half of the interrupt frequency.
Parameters
None
Usage
void Modes.sendMorse(const char* text, const uint32t dotDur, bool keying);
Functionality
Sends the text in Morse using keying style On-Off or FSK. The speed is set by the duration of a dot.
Parameters
char* text: pointer to the information to send
uint32t dotDur: the duration of a CW dot in ms
bool keying: the keying style
Usage
void Modes.setTone(const uint32_t toneIndex, bool rst = false);
Functionality
Loads the Si5351A with the register values set by the toneIndex. If relevant the PLL can be reset too.
Parameters
uint32_t toneIndex: the tone index number to load
bool rst: PLL reset. Default is false
Usage
bool val = Modes.setupFST4(FST4mode_t mode, const int kVal, char* msg);
Functionality
Encodes the message to FST4. The maximum length is 13 characters. If the encoding fails the function returns false otherwise true.
Parameters
FST4mode_t mode: the FST4 sub-mode enum
int kVal: the submode K value
char* msg: the free text message to encode
Usage
bool val = Modes.setupFST4W(FST4Wmode_t mode, const char* call, const char* loc, const uint8_t pwr);
Functionality
Encodes the message to FST4W. Only type 1 messages are supported. If the encoding fails the function returns false otherwise true.
Parameters
FST4Wmode_t mode: the FST4W sub-mode enum
char* call: the call sign of the station
char* loc: the locator of the station
uint8_t pwr: the power in dBm. Must end with 0, 3 or 7 and be form 0 dBm to 60 dBm
Usage
bool val = Modes.setupFT4(char* msg);
Functionality
Encodes the message to FT4. The maximum length is 13 characters. If the encoding fails the function returns false otherwise true.
Parameters
char* msg: the free text message to encode
Usage
bool val = Modes.setupFT8(char* msg);
Functionality
Encodes the message to FT8. The maximum length is 13 characters. If the encoding fails the function returns false otherwise true.
Parameters
char* msg: the free text message to encode
Usage
bool val = Modes.setupJS8(const char* call, const char* square);
Functionality
Encodes the message to into a JS8 Heart Beat message. If the encoding fails the function returns false otherwise true.
Parameters
char* call: the call sign of the station
char* square: the square of the station
Usage
bool val = Modes.setupJT9(char* msg);
Functionality
Encodes the message to JT9. The maximum length is 13 characters. If the encoding fails the function returns false otherwise true.
Parameters
char* msg: the free text message to encode
Usage
bool setupModeXMetrics(const uint8_t nbrSymbols, const uint8_t nbrTones, const uint32_t sampleRate, const uint32_t freqSamples, const uint32_t prescaler, const uint32_t timerCounts, const uint8_t k, const double offset);
Functionality
Sets up the metrics for ModeX.
Parameters
const uint8_t nbrSymbols: is the number of symbols
const uint8_t nbrTones: is the number of tones
const uint32_t sampleRate: is the sample rate
const uint32_t freqSamples: is the frequency samples
const uint32_t prescaler: is the MCU prescaler
const uint32_t timerCounts: is the MCU timer counts
const uint8_t k, const double offset: is the ModeX offset relative to the carrier frequency
Usage
bool loadModeXSymbols(const uint8_t count, const uint8_t value);
Functionality
Loads each of the ModeX symbols into the MGM array.
Parameters
const uint8_t count: is the symbol number
const uint8_t value: is the symbol value
Usage
bool val = Modes.setupPI4(char* msg);
Functionality
Encodes the message to PI4. The maximum length is eight characters. If the encoding fails the function returns false otherwise true.
Parameters
char* msg: the call sign or text to encode
Usage
bool val = Modes.setupWSPR(const char* call, const char* loc, const uint8_t pwr, const bool t3m);
Functionality
Encodes the message to WSPR. If the encoding fails the function returns false otherwise true.
Parameters
char* call: the call sign of the station
char* loc: the locator of the station
uint8_t pwr: the power in dBm. Must end with 0, 3 or 7 and be form 0 dBm to 60 dBm
bool t3m: enable type 3 message
Usage
void = Modes.txPause(const bool keying);
Functionality
If the keying is true (FSK) the key up frequency is sent. If the keying is false (OOK) the RF is switched off. The TX LED is switched off.
Parameters
const bool keying: the keying style

The RFzero Utilities library

This function has been removed in library v.0.9.4 and onwards. Please use the dtostrf() instead and add #include <avr/dtostrf.h> to the file where it is used.
Usage
void DoubleToString(const double value, const int decimals, char* str);
Functionality
In Arduino sprintf doesn't support doubles/floats so they have to be handled in a different way.
Parameters
double value: The value to format
int decimals: The number of decimals
char* str: A pointer to the string to return the formatted value in
Usage
void FormatFreqDots(const uint32_t value, char* str);
Functionality
Formats an integer frequency value to include dots as million and thousands separator, e.g. 123456789 becomes 123.456.789.
Parameters
uint32_t value: The value to format
char* str: A pointer to the string to return the formatted value in
Usage
void HexDump(const void* tgt, const unsigned int cnt);
Functionality
Prints a hex string on the serial USB port.
Parameters
void* tgt: The pointer to the hex string to print
unsigned int cnt: Number of hex values per line
Usage
uint32_t NearestPower(const uint32_t value, const uint32_t base);
Functionality
Returns the nearest power of a base of a value. The value is rounded upwards to the nearest integer.
Parameters
const uint32_t value: The value to convert
const uint32_t base: The base value
Usage
void TrimCharArray(char* str);
Functionality
Removes control characters and spaces from both ends of a char based string.
Parameters
char* str: The string to trim

The RFzero LCD I2C library

The changes to the library are

  • The I2C address, number of characters and lines have been removed from the object creation and moved to a begin() function enabling dynamic changes of the I2C address, number of characters and lines
  • The init() function has been removed

This also means that all other functions are the same and works in the same way. Thus they are not repeated below.

Usage
void begin(uint8_t lcd_Addr, uint8_t lcd_cols, uint8_t lcd_rows);
Functionality
Initializes the PCF8574 series of port expander and the LCD too.
Parameters
uint8_t lcd_Addr: the I2C address uint8_t lcd_cols: the number of characters uint8_t lcd_rows: the number of lines