Initial commit

Author: NT7S

README.md

@@ -0,0 +1,132 @@
+Morse Arduino
+=============
+This library sends Morse Code via toggling a specified output pin and/or toggling a boolean member variable which indicates the key state of the output.
+
+**Please feel free to use the Issues feature of GitHub if you run into problems or have suggestions for important features to implement. This is the best way to get in touch.**
+
+Thanks For Your Support!
+------------------------
+If you would like to support my library development efforts, please consider a [PayPal donation](https://paypal.me/NT7S) or purchasing something from the [Etherkit Store](https://www.etherkit.com). Thank you!
+
+Library Installation
+---------------------
+The best way to install the library is via the Arduino Library Manager, which is available if you are using Arduino IDE version 1.6.2 or greater. To install it this way, simply go to the menu Sketch > Include Library > Manage Libraries..., and then in the search box at the upper-right, type "Etherkit Morse". Click on the entry in the list below, then click on the provided "Install" button. By installing the library this way, you will always have notifications of future library updates, and can easily switch between library versions.
+
+If you need to or would like to install the library in the old way, then you can download a copy of the library in a ZIP file. Download a ZIP file of the library from the GitHub repository by using the "Download ZIP" button at the right of the main repository page. Extract the ZIP file, then rename the unzipped folder as "Etherkit_Morse". Finally, open the Arduino IDE, select menu Sketch > Import Library... > Add Library..., and select the renamed folder that you just downloaded. Restart the IDE and you should have access to the new library.
+
+Hardware Requirements and Setup
+-------------------------------
+This library has been written for the Arduino platform, to be processor agnostic. It has been successfully tested on the Arduino Uno, an Uno clone, and an Empyrean (Arduino Zero derivative). In order to be platform independent, it requires that the end user call on the class _update()_ member function one time per millisecond. The details of the implementation are left up to the user, but it is best done using a timer interrupt service routine.
+
+Example
+-------
+First, install the Morse library into your instance of the Arduino IDE as described above.
+
+There two simple examples named **morse_example_avr.ino** and **morse_example_samd.ino** that are placed in your examples menu under the Etherkit Morse folder. Open one corresponding to the Arduino variant on which you will be running the example.
+
+In order to use the Morse library in your sketch, you must first instantiate an object of class Morse:
+
+    Morse morse(LED_BUILTIN, 15);
+
+The class constructor takes two parameters: the desired Morse code output pin and sending speed.
+
+Each example implements a method for calling the Morse class _update()_ method every one millisecond so that Morse code can be sent with the proper timing. See each sketch for details and note that these examples are only one possible way to implement the update function. As long as the _update()_ method is called reliably every one millisecond, the Morse library will function as intended.
+
+Now all that one has to do to send Morse code in real-time is to use the _send()_ method with the desired message to send as a string literal or C-type string (null delimited character array).
+
+    morse.send("HELLO WORLD");
+
+Note that this library can accept lower or uppercase letters in the message buffer. The maximum message size is 100 characters.
+
+Further Details
+---------------
+If you need to check to see if the Morse library is currently sending the contents of its message buffer, check the boolean _busy_ class member. Should you call the _send()_ method before the library is done sending a current message, the old buffer will be overwritten with the new message and sending of the new message will start immediately.
+
+The sending speed can be changed on-the-fly by using the _setWPM()_ method. The parameter is typed using a _float_ so that fractional words per minute can be specified. Why would you want to do this? In case you need to send Morse code using a very long integration time such as with the QRSS operating mode. For example, a setting of 0.2 WPM sets a Morse code "dit" length of 6 seconds.
+
+If you don't want to have the library directly control a digital I/O pin, you may have your sketch poll the boolean _tx_ member variable and act on it accordingly within their periodic 1 ms function.
+
+Startup Conditions and Constraints
+----------------------------------
+The default output pin is defined as LED_BUILTIN while the default sending speed is 25 words per minute.
+
+The maximum transmit buffer size is 100 characters.
+
+Public Methods
+--------------
+### Morse() [class constructor]
+```
+/*
+ * Morse::Morse(uint8_t tx_pin, float init_wpm) : output_pin(tx_pin)
+ *
+ * Create an instance of the Morse class.
+ *
+ * tx_pin - Arduino pin used as the output by this library.
+ * init_wpm - Sending speed in words per minute.
+ *
+ */
+Morse::Morse(uint8_t tx_pin, float init_wpm) : output_pin(tx_pin)
+```
+### update()
+```
+/*
+ * void Morse::update()
+ *
+ * State machine for the Morse library.
+ *
+ * This must be called by the client sketch every one millisecond in order
+ * for the library to accurately send Morse code.
+ *
+ */
+void Morse::update()
+```
+### setWPM()
+```
+/*
+ * void Morse::setWPM(float new_wpm)
+ *
+ * Set the Morse code sending speed.
+ *
+ * new_wpm - Sending speed in words per minute.
+ *
+ */
+void Morse::setWPM(float new_wpm)
+```
+### send()
+```
+/*
+ * void Morse::send(char * message)
+ *
+ * Send the specified message in Morse code on the output pin.
+ *
+ * message - String literal or zero-delimited string to transmit.
+ *
+ */
+void Morse::send(char * message)
+```
+
+Public Variables
+----------------
+    float wpm;
+    bool tx;
+    bool tx_enable;
+    uint8_t output_pin;
+    bool busy;
+
+Valid Characters
+----------------
+The standard uppercase and lowercase letters 'A' through 'Z' and digits '0' through '9' are of course supported, along with a handful of punctuation and special characters. The following table indicates the special characters supported along with the corresponding Morse code. Other input characters are ignored.
+
+| Input Character   | Morse Character |
+|-------------------|-----------------|
+| - (minus sign)    | ➖➖ (M)          |
+| / (slash)         | ➖••➖•           |
+| = (equal sign)    | ➖•••➖ (BT)      |
+| ? (question mark) | ••➖➖••          |
+
+Changelog
+---------
+
+* v1.0.0
+
+    * Initial release

examples/morse_example_avr/morse_example_avr.ino

@@ -0,0 +1,44 @@
+/*
+ * morse_example_avr.ino - Simple example of using the Etherkit Morse library
+ *                         on an AVR-based Arduino
+ *
+ * Copyright (C) 2018 Jason Milldrum <milldrum@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+ #include <SimpleTimer.h>
+ #include <Morse.h>
+
+ // Class declaration
+ Morse morse(LED_BUILTIN, 15);
+ SimpleTimer timer;
+
+ // a function to be executed periodically
+ void repeatMe()
+ {
+   morse.update();
+ }
+
+ void setup()
+ {
+   timer.setInterval(1, repeatMe);
+
+   delay(1000);
+   morse.send("HELLO WORLD");
+ }
+
+ void loop() {
+   timer.run();
+ }

examples/morse_example_samd/morse_example_samd.ino

@@ -0,0 +1,101 @@
+/*
+ * morse_example_samd.ino - Simple example of using the Etherkit Morse library
+ *                          on a SAMD-based Arduino
+ *
+ * Copyright (C) 2018 Jason Milldrum <milldrum@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+ #include <Morse.h>
+
+ // Constant expressions
+ constexpr uint16_t TIMER_PRESCALER_DIV = 1024;
+
+ // Class declaration
+ Morse morse(LED_BUILTIN, 15);
+
+ void setup()
+ {
+   startTimer(1000); // 1 ms ISR
+   delay(1000);
+   morse.send("HELLO WORLD");
+ }
+
+ void loop()
+ {
+   // Let the ISR have all the fun
+ }
+
+ // Timer code derived from:
+ // https://github.com/nebs/arduino-zero-timer-demo
+
+ void setTimerFrequency(int frequencyHz)
+ {
+   int compareValue = (VARIANT_MCK / (TIMER_PRESCALER_DIV * frequencyHz)) - 1;
+   TcCount16* TC = (TcCount16*) TC5;
+   // Make sure the count is in a proportional position to where it was
+   // to prevent any jitter or disconnect when changing the compare value.
+   TC->COUNT.reg = map(TC->COUNT.reg, 0, TC->CC[0].reg, 0, compareValue);
+   TC->CC[0].reg = compareValue;
+   while (TC->STATUS.bit.SYNCBUSY == 1);
+ }
+
+ /*
+ This is a slightly modified version of the timer setup found at:
+ https://github.com/maxbader/arduino_tools
+  */
+ void startTimer(int frequencyHz)
+ {
+   REG_GCLK_CLKCTRL = (uint16_t) (GCLK_CLKCTRL_CLKEN | GCLK_CLKCTRL_GEN_GCLK0 | GCLK_CLKCTRL_ID (GCM_TC4_TC5)) ;
+   while ( GCLK->STATUS.bit.SYNCBUSY == 1 );
+
+   TcCount16* TC = (TcCount16*) TC5;
+
+   TC->CTRLA.reg &= ~TC_CTRLA_ENABLE;
+
+   // Use the 16-bit timer
+   TC->CTRLA.reg |= TC_CTRLA_MODE_COUNT16;
+   while (TC->STATUS.bit.SYNCBUSY == 1);
+
+   // Use match mode so that the timer counter resets when the count matches the compare register
+   TC->CTRLA.reg |= TC_CTRLA_WAVEGEN_MFRQ;
+   while (TC->STATUS.bit.SYNCBUSY == 1);
+
+   // Set prescaler to 1024
+   TC->CTRLA.reg |= TC_CTRLA_PRESCALER_DIV1024;
+   while (TC->STATUS.bit.SYNCBUSY == 1);
+
+   setTimerFrequency(frequencyHz);
+
+   // Enable the compare interrupt
+   TC->INTENSET.reg = 0;
+   TC->INTENSET.bit.MC0 = 1;
+
+   NVIC_EnableIRQ(TC5_IRQn);
+
+   TC->CTRLA.reg |= TC_CTRLA_ENABLE;
+   while (TC->STATUS.bit.SYNCBUSY == 1);
+ }
+
+ void TC5_Handler()
+ {
+   TcCount16* TC = (TcCount16*) TC5;
+
+   if (TC->INTFLAG.bit.MC0 == 1)
+   {
+     TC->INTFLAG.bit.MC0 = 1;
+     morse.update();
+   }
+ }

keywords.txt

@@ -0,0 +1,78 @@
+Morse	KEYWORD1
+
+init	KEYWORD2
+reset	KEYWORD2
+set_freq	KEYWORD2
+set_freq_manual	KEYWORD2
+set_pll	KEYWORD2
+set_ms	KEYWORD2
+output_enable	KEYWORD2
+drive_strength	KEYWORD2
+update_status	KEYWORD2
+set_correction	KEYWORD2
+set_phase	KEYWORD2
+get_correction	KEYWORD2
+pll_reset	KEYWORD2
+set_ms_source	KEYWORD2
+set_int	KEYWORD2
+set_clock_pwr	KEYWORD2
+set_clock_invert	KEYWORD2
+set_clock_source	KEYWORD2
+set_clock_disable	KEYWORD2
+set_clock_fanout	KEYWORD2
+set_pll_input	KEYWORD2
+set_vcxo	KEYWORD2
+si5351_write_bulk	KEYWORD2
+si5351_write	KEYWORD2
+si5351_read	KEYWORD2
+dev_status	KEYWORD2
+dev_int_status	KEYWORD2
+pll_assignment	KEYWORD2
+clk_freq	KEYWORD2
+plla_freq	KEYWORD2
+pllb_freq	KEYWORD2
+xtal_freq	KEYWORD2
+
+SI5351_PLL_FIXED	LITERAL1
+SI5351_FREQ_MULT	LITERAL1
+SI5351_DEFAULT_CLK	LITERAL1
+SI5351_CRYSTAL_LOAD_0PF	LITERAL1
+SI5351_CRYSTAL_LOAD_6PF	LITERAL1
+SI5351_CRYSTAL_LOAD_8PF	LITERAL1
+SI5351_CRYSTAL_LOAD_10PF	LITERAL1
+SI5351_CLK0	LITERAL1
+SI5351_CLK1	LITERAL1
+SI5351_CLK2	LITERAL1
+SI5351_CLK3	LITERAL1
+SI5351_CLK4	LITERAL1
+SI5351_CLK5	LITERAL1
+SI5351_CLK6	LITERAL1
+SI5351_CLK7	LITERAL1
+SI5351_PLLA	LITERAL1
+SI5351_PLLB	LITERAL1
+SI5351_DRIVE_2MA	LITERAL1
+SI5351_DRIVE_4MA	LITERAL1
+SI5351_DRIVE_6MA	LITERAL1
+SI5351_DRIVE_8MA	LITERAL1
+SI5351_CLK_SRC_XTAL	LITERAL1
+SI5351_CLK_SRC_CLKIN	LITERAL1
+SI5351_CLK_SRC_MS0	LITERAL1
+SI5351_CLK_SRC_MS	LITERAL1
+SI5351_CLK_DISABLE_LOW	LITERAL1
+SI5351_CLK_DISABLE_HIGH	LITERAL1
+SI5351_CLK_DISABLE_HI_Z	LITERAL1
+SI5351_CLK_DISABLE_NEVER	LITERAL1
+SI5351_FANOUT_CLKIN	LITERAL1
+SI5351_FANOUT_XO	LITERAL1
+SI5351_FANOUT_MS	LITERAL1
+SI5351_PLL_INPUT_XO	LITERAL1
+SI5351_PLL_INPUT_CLKIN	LITERAL1
+SYS_INIT	LITERAL1
+LOL_B	LITERAL1
+LOL_A	LITERAL1
+LOS	LITERAL1
+REVID	LITERAL1
+SYS_INIT_STKY	LITERAL1
+LOL_B_STKY	LITERAL1
+LOL_A_STKY	LITERAL1
+LOS_STKY	LITERAL1

library.properties

@@ -0,0 +1,9 @@
+name=Etherkit Morse
+version=1.0.0
+author=Jason Milldrum <milldrum@gmail.com>
+maintainer=Jason Milldrum <milldrum@gmail.com>
+sentence=Generate Morse Code for transmission on an digital I/O pin.
+paragraph=Provide this library with a function that calls every one millisecond, and it will generate Morse code for you on the digital pin and at the sending speed that you desire.
+category=Data Processing
+url=https://github.com/etherkit/MorseArduino
+architectures=*