11 HamShield Library Reference
Morgan Redfield edited this page 2019-03-15 12:33:37 -07:00

Advanced Users: Inside the Arduino library, you will find many methods that are not mentioned within this document. This is because higher level functions utilize several of these lower level functions in order to make the hardware easier to use. While they may look tempting, there are no secret features to unlock. It is best not to play with any of these functions, as they could cause the radio to stop functioning, or worse, cause interference and undesirable results.


In our method examples, we will be using the object 'radio'. You do not need to worry about what this all means, but just make sure you are using HamShield radio; at the top of your sketch.

HamShield radio();

Creates the HamShield radio object. This must exist in every HamShield sketch outside of loop() and setup(). You may also call radio any other name if you would like. For example, if we wanted our object called amateur, we would use HamShield amateur(). Then, to issue commmands to the HamShield, we would have to use amateur.frequency(446000). Confusing? We thought so too. Just use radio.

HamShield radio(ncs_pin, clk_pin, dat_pin, mic_pin);

If you want to use non-standard pins for the HamShield, you can pass the pins you're using here.

radio.initalize();

This performs some basic initialization steps on the HamShield. It performs required radio IC initialization commands and sets the radio to its default configuration state:

  • Frequency: 446.000MHz
  • Volume: 100%
  • Mode: Receive
  • Audio Source: Microphone / Arduino
  • Squelch: On, -80 dBm

radio.testConnection()

Tests the connection to the radio, waiting if needed. It returns when the radio is detected.

radio.frequency(frequency in KHz)

Sets the radio frequency, measured in KHz. Our method stores this in a unsigned 32bit int (uint32_t). Valid values are:

  • 134000 - 174000
  • 200000 - 260000
  • 400000 - 520000

radio.getFrequency()

Gets the current tuned frequency, returns an unsigned 32bit int (uint32_t) which represents the frequency in KHz.

radio.setChanMode(channel width)

Sets the channel bandwidth. This can be either 25KHZ or 12.5KHZ. Case sensitive. For example:

radio.setChanMode(25KHZ); radio.setChanMode(12.5KHZ);

radio.getChanMode();

Returns the current channel mode as a uint16_t.

radio.setRfPower(0-15);

Sets the output power for TX. A setting of 0 is lowest, a setting of 15 will give highest power output. RF PowerSpectrum RF 446 mhz

radio.setModeTransmit();

Turns on the transmitter, as long as it is within a United States ham radio band. See .dangerousMode() to override.

radio.morseOut("MY CALLSIGN IS ZZ6EXAMPL.");

Sends morse code during our transmissions for very easy identification. You can also change the morse_dot_millis = 60; value in HamShield.cpp to adjust speed to make this more convenient. The lower the value, the faster the words per minute.

radio.setModeReceive();

Turns on the receiver. This is also required to receive signal strength readings.

radio.setModeOff();

Turns off both transmit and receive mode. Places the radio IC into a powerdown state to save power.

radio.setTXSourceMic();

Sets the radio IC chip audio path to Arduino and Headset jack audio

radio.setTXSourceSine();

Sets the radio IC chip audio path to it's internal audio generator

radio.setTXSourceCode();

Sets the radio IC chip audio path to tx code from GPIO1 code_in (we do not know what this is)

radio.setTXSourceNone();

Sets the radio IC chip audio path to nothing, generating a silent carrier.

radio.getTxSource();

Returns the current source selection as a uint16_t.

radio.setInnerCtcssMode()

Turn on the configured CTCSS tone for received audio.

setInnerCdcssMode();

Turn on the configured CDCSS tone for received audio.

setOuterCtcssMode();

Turn on the configured CTCSS tone for transmitted audio.

setOuterCdcssMode();

Turn on the configured CDCSS tone for transmitted audio.

disableCtcssCdcss();

Disable all sub audio tone detection and generation.

//   Ctcss_sel
//      1 = ctcss_cmp/cdcss_cmp out via gpio
//      0 = ctcss/cdcss sdo out vio gpio
void setCtcssSel(bool cmp_nsdo);
bool getCtcssSel();

//   Cdcss_sel
//      1 = long (24 bit) code
//      0 = short(23 bit) code
void setCdcssSel(bool long_nshort);
bool getCdcssSel();
	// Cdcss neg_det_en
void enableCdcssNegDet();
void disableCdcssNegDet();
bool getCdcssNegDetEnabled();

// Cdcss pos_det_en
void enableCdcssPosDet();
void disableCdcssPosDet();
bool getCdcssPosDetEnabled();

// css_det_en
void enableCssDet();
void disableCssDet();
bool getCssDetEnabled();

// ctcss freq
    void setCtcss(float freq);
void setCtcssFreq(uint16_t freq);
uint16_t getCtcssFreq();
void setCtcssFreqToStandard(); // freq must be 134.4Hz for standard cdcss mode

// cdcss codes
void setCdcssCode(uint16_t code);
uint16_t getCdcssCode();
		
// SQ
void setSQOn();
void setSQOff();
bool getSQState();

// SQ threshold
void setSQHiThresh(uint16_t sq_hi_threshold); // Sq detect high th, rssi_cmp will be 1 when rssi>th_h_sq, unit 1/8dB
uint16_t getSQHiThresh();
void setSQLoThresh(uint16_t sq_lo_threshold); // Sq detect low th, rssi_cmp will be 0 when rssi<th_l_sq && time delay meet, unit 1/8 dB
uint16_t getSQLoThresh();

// SQ out select
void setSQOutSel();
void clearSQOutSel();
bool getSQOutSel();

// VOX
void setVoxOn();
void setVoxOff();
bool getVoxOn();

// Vox Threshold
void setVoxOpenThresh(uint16_t vox_open_thresh); // When vssi > th_h_vox, then vox will be 1(unit mV )
uint16_t getVoxOpenThresh();
void setVoxShutThresh(uint16_t vox_shut_thresh); // When vssi < th_l_vox && time delay meet, then vox will be 0 (unit mV )
uint16_t getVoxShutThresh();

// Tail Noise
void enableTailNoiseElim();
void disableTailNoiseElim();
bool getTailNoiseElimEnabled();

// tail noise shift select
//   Select ctcss phase shift when use tail eliminating function when TX
//     00 = 120 degree shift
//     01 = 180 degree shift
//     10 = 240 degree shift
//     11 = reserved
void setShiftSelect(uint16_t shift_sel);
uint16_t getShiftSelect();

// DTMF
void setDTMFC0(uint16_t freq);
uint16_t getDTMFC0();
void setDTMFC1(uint16_t freq);
uint16_t getDTMFC1();	
void setDTMFC2(uint16_t freq);
uint16_t getDTMFC2();
void setDTMFC3(uint16_t freq);
uint16_t getDTMFC3();
void setDTMFC4(uint16_t freq);
uint16_t getDTMFC4();
void setDTMFC5(uint16_t freq);
uint16_t getDTMFC5();
void setDTMFC6(uint16_t freq);
uint16_t getDTMFC6();
void setDTMFC7(uint16_t freq);
uint16_t getDTMFC7();

// TX FM deviation
void setFMVoiceCssDeviation(uint16_t deviation);
uint16_t getFMVoiceCssDeviation();
void setFMCssDeviation(uint16_t deviation);
uint16_t getFMCssDeviation();

// RX voice range
void setVolume1(uint16_t volume);
uint16_t getVolume1();
void setVolume2(uint16_t volume);
uint16_t getVolume2();

// GPIO
void setGpioMode(uint16_t gpio, uint16_t mode);
void setGpioHiZ(uint16_t gpio);
void setGpioFcn(uint16_t gpio);
void setGpioLow(uint16_t gpio);
void setGpioHi(uint16_t gpio);
uint16_t getGpioMode(uint16_t gpio);

// Int
void enableInterrupt(uint16_t interrupt);
void disableInterrupt(uint16_t interrupt);
bool getInterruptEnabled(uint16_t interrupt);

// ST mode
void setStMode(uint16_t mode);
uint16_t getStMode();
void setStFullAuto();
void setStRxAutoTxManu();
void setStFullManu();

// Pre-emphasis, De-emphasis filter
void bypassPreDeEmph();
void usePreDeEmph();
bool getPreDeEmphEnabled();

// Read Only Status Registers
int16_t readRSSI();
uint16_t readVSSI();
uint16_t readDTMFIndex(); // may want to split this into two (index1 and index2)
uint16_t readDTMFCode();

    // set output power of radio
    void setRfPower(uint8_t pwr);

    // channel helper functions
    bool setGMRSChannel(uint8_t channel);
    bool setFRSChannel(uint8_t channel);
    bool setMURSChannel(uint8_t channel);
    bool setWXChannel(uint8_t channel);
    uint8_t scanWXChannel();


    // restrictions control
    void dangerMode();
    void safeMode();

    // utilities
    uint32_t scanMode(uint32_t start,uint32_t stop, uint8_t speed, uint16_t step, uint16_t threshold);
    uint32_t findWhitespace(uint32_t start,uint32_t stop, uint8_t dwell, uint16_t step, uint16_t threshold);
    uint32_t scanChannels(uint32_t buffer[],uint8_t buffsize, uint8_t speed, uint16_t threshold);
    uint32_t findWhitespaceChannels(uint32_t buffer[],uint8_t buffsize, uint8_t dwell, uint16_t threshold);
    void buttonMode(uint8_t mode);
    void isr_ptt();
    void isr_reset();
void morseOut(char buffer[HAMSHIELD_MORSE_BUFFER_SIZE]);
char morseLookup(char letter);
    bool waitForChannel(long timeout, long breakwindow);
    void SSTVVISCode(int code);
    void SSTVTestPattern(int code);
    void toneWait(uint16_t freq, long timer);
    void toneWaitU(uint16_t freq, long timer);
    bool parityCalc(int code);