From 2cda91165f1ca27fe7edd4260c03cea10af54126 Mon Sep 17 00:00:00 2001 From: spaceneedle Date: Mon, 6 Jul 2015 17:02:06 -0700 Subject: [PATCH] Created HamShield Library Reference (markdown) --- HamShield-Library-Reference.md | 276 +++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 HamShield-Library-Reference.md diff --git a/HamShield-Library-Reference.md b/HamShield-Library-Reference.md new file mode 100644 index 0000000..c022b42 --- /dev/null +++ b/HamShield-Library-Reference.md @@ -0,0 +1,276 @@ +_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(shield identifier); + +If you have two HAMShields, this allows you to select which shield you would like to use. Please see the tricks and tips section on how to use this. + +#### 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.setModeTransmit(); + +Turns on the transmitter, as long as it is within a United States HAM radio band. See .dangerousMode() to override. + +#### 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_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); + + \ No newline at end of file