Arduino Iambic Keyer 2016 – Part 3: Operation
Memory Keyer 2016
This describes the operation of an Arduino sketch and appropriate hardware that serves as an iambic morse code keyer. This version runs on a PJRC Teensy3.2 board and libraries. It will not compile to an Atmel (traditional Arduino) processor without major changes. I chose the Cortex M4 based Teensy because it has built in Real Time Clock, a real DAC, built in USB, and lots of memory. I added a 16×2 liquid crystal display and batteries for stand alone operation.
- Characters to be sent are buffered in an asynchronous circular queue so memory buttons or keyboard characters can be “typed ahead”.
- PS2 and serial terminal keyboards supported.
- Paddle generated morse is interpreted and printed as ASCII text.
- Seven 50 character memories. Each is programmable from keyboards or from paddles.
- Random code practice modes, letters only, letters and numbers, letters numbers and punctuation.
- Sending speed settable 10 to 45 WPM. Limits can be changed by recompiling.
- Sidetone frequency settable 100 to 1200 Hz. Limits can be changed by recompiling.
- Synthesized sine wave sidetone with leading and trailing edge envelope shaping.
- Memories and operating parameters stored in EEPROM, are easily reset to defaults.
- Stand alone operation from batteries. Based on tests, a 4400 MAH battery will last at least 36 hours.
- A Liquid Crystal Display.
Outside the Box
This keyer has five I/O connectors:
- A 3 conductor jack for the paddle or straight key.
- A 3 conductor jack for transmitter keying with an optocoupler open collector output on the tip. Line level sidetone audio is connected to the ring.
- An external speaker jack connected to a 2.5 watt audio amplifier.
- A mini DIN connector for PS2 keyboard. USB keyboards will work with an adapter.
- A micro USB port for programming and serial terminal connection. This also powers the unit and charges the battery.
There are eight push button switches, a volume control, and an LED:
- A Function button.
- Seven push buttons to activate individual memories.
- The volume control feeds a Class D amplifier for the speaker. It does not affect the level on the line output connection.
- The LED follows the transmit keying signal.
There is an on/off switch that also serves to reboot the processor into setup mode.
Liquid Crystal Displays have a limited space for messages so information has to be presented sequentially. Switching on power displays clock status then “Keyer Ready” is displayed on the LCD and on the serial port. The unit is then ready for normal operation.
Straight Key Operation
On power up, if the unit senses a two conductor plug in the paddle jack, it will go into Straight Key mode and just pass keying through to the transmit circuit, with side tone. Memories and other features are not available as the morse engine is never started.
Normal Iambic Operation
The dual paddle jack is wired dit paddle on tip, dah paddle on ring of the mini stereo connector. The external speaker jack will work with stereo headphones or a speaker. On the transmit jack, there is an open collector optocoupler connected to tip and line level side tone on the ring.
Software will attempt to translate paddle sent morse into ASCII which will display on the LCD and is also sent to the serial port. Decode success depends on how good your fist is. The keyer cannot decode morse received over the air.
The keyer will accept and send characters entered from a PS2 keyboard or from a terminal emulator program such as PuTTY, or even the Arduino IDE serial window. It’s better to use an emulator that supports line at a time transmission as that gives you an opportunity to fix typing mistakes. Opening a terminal window on a USB connected PC also lets you view and log status messages sent from the keyer. PS2 support also works with a USB keyboard and appropriate USB to PS2 adapter.
All characters in the Wikipedia morse code table are supported except the underscore and the dollar sign. From either serial or PS2 keyboards, enter normal text in lower case. Entering text in upper case will suppress the next intercharacter gap, thus running two characters together. This can be used to send prosigns. For example, As (wait) or Sk (end of contact). Message text entered from the paddles will always be treated as all lower case.
Serial or PS2 keyboards use a one at a time command mode, activated by typing a back slash followed by a single character. Keyboard commands are:
- \+ or \= increase sending speed one Word Per Minute
- \- decrease sending speed one Word Per Minute
- \u increase sidetone frequency by 5%
- \d decrease sidetone frequency by 5%
- \w save current sidetone frequency and WPM to EEPROM memory
- \1, \2 … \7 send stored text as though a memory button was pressed.
Seven programmable 50 character memories are available by pressing buttons. The sketch uses a 64 byte circular buffer to queue sendable text from either keyboard or from EEPROM memory, the buffer is asynchronous so memory messages can be stacked with interspersed keyboard text. Memory messages are read as needed from EEPROM so each consumes only a single byte of circular buffer space. Memories can also be queued from the keyboards by entering commands \1 … \7.
Message memory can be programmed from compiled defaults, from either keyboard, or directly from the paddles if your sending is good which is useful in stand alone operation. To program a message into memory, press and hold the Function button, then press and release the desired memory button, then release Function. Enter your text from paddles or keyboard, then exit programing mode by clicking Function again.
Normal Operation Display
Operating parameters can be viewed on the LCD by holding the Function button. Parameters also print to the serial port. The rotating menu display will show:
- Time and date both GMT and local
- Sending speed and side tone frequency
- Battery status
- The first 16 characters of each programmable message.
Each item will be on the LCD for one second. Releasing Function stops menu rotation but does not erase the LCD which allows more time to read a particular display.
Changing Words Per Minute
Since speed may need to be adjusted according to conditions, there is a provision to change WPM on the fly. Just hold the Function button down and close a paddle. Dits increase speed, dahs decrease. On releasing Function, the changed speed writes to EEPROM.
You can also change speed from the keyboards by entering \+ to increase or \- to decrease. Entering \= will also increase WPM if you forgot to shift. If adjusting by keyboard, you must enter \w to write the new setting to EEPROM.
Changing Side Tone Frequency
This can be done from the keyboards by sending \u to raise frequency or \d to lower frequency. As with WPM, enter the command \w to save the change. Tone frequency can be set in stand alone operation from the Startup Menu described below.
Software constantly monitors battery voltage and the PowerBoost charger status signals. These can be seen in the operating display. Voltage is shown in hundredths with no decimal point. A fully charged battery will show about 4.20 volts, if the battery drops below 3.40 volts “LOW BATT” will show on the battery status and the LCD back light will flash. If voltage drops below the boost regulator LB threshold, about 3.25 volts the status display will show “DEAD BATT”.
Arduino sketches have a separate startup() section for initializing things. It is executed once when the processor resets, just before entering the main event loop(). This keyer takes advantage of separate startup to recall and optionally change important system parameters. A normal power on sequence copies the following items from EEPROM to RAM:
- Words Per Minute
- Side Tone frequency
- LCD Back light brightness
- GMT – Local time offset
Memory messages are also stored in EEPROM but are not read into RAM. Startup then reads the Real Time Clock into the system clock.
Startup then checks to see if Code Practice mode (see below) is requested, if so, Code Practice begins as soon as the memory button is released.
If Startup sees the Function button held down, it enters Startup Menu mode. Eight parameters rotate on the LCD, seven of these can be entered and changed.
- Sending speed Words Per Minute
- Side Tone frequency
- LCD Back light brightness
- System clock time (GMT)
- System date (also GMT)
- GMT – Local offset in hours
- Reset all stored parameters to defaults
- Display battery voltage and charge status
For Startup Menu purposes, three of the memory buttons are redefined. M5 is Enter, M6 is Up, M7 is Down. Click the Enter (M5) button while a menu item is on the display to activate change mode for that item. For the first three menu items and for GMT offset, Up (M6) and Down (M7) act directly on the displayed number.
Once entered, Time and Date can be set by repeatedly pressing the Enter button until the cursor is beneath the digit needing change. Once there Up and Down operate as expected. The RTC will be updated when the Time or Date menu is exited.
After a change, exit the menu item by pressing and holding Enter (M5) for longer than 2 seconds. Menu rotation will continue where it left off.
Entering menu 7 will reset all EEPROM stored parameters including the seven memory messages to defaults specified in the file “canned.h”. You can change these defaults by editing that file with the Arduino IDE and recompiling. Canned.h appears as one of the tabs at the top of the Arduino editor window.
The last Startup Menu display shows the current battery voltage and charge status. This information is also sent to the serial connection, at the menu rate of rotation, about five times per minute. A terminal emulator program like PuTTY or Minicom on the PC, can log these battery messages in a text file, you can later load the text into a spread sheet and with some amount of fussing create a charge or discharge curve for the battery. To get a discharge curve though you have to disable charging through the USB connection by cutting the red wire in the USB cable.
Startup Menu mode is exited by clicking the Function button again. Changed parameters will write to EEPROM and normal operation starts.
Synchronize the Real Time Clock
Internal system time is maintained by software in the PJRC libraries. System time is initialized at bootup from the crystal controlled, battery backed Real Time Clock inside the processor chip. You can hack set the RTC from the Startup Menu, but there is a way to synchronize the RTC with a PC clock over a USB serial connection. If the PC is itself synchronized with an Internet NTP server, the result will be within 1 or 2 seconds of WWV.
Accurate clock synchronization requires the Arduino sketch be ready to accept and process a time update at the exact moment the PC sends it. Connect the keyer to the PC with a USB cable, power up the keyer while holding the Function button down, then while the LCD displays “Enter Setup Mode”, paste the following Linux command into a shell;
date +T%s\n > /dev/ttyACM0
Release the Function button and the RTC synchronizes. There is a processing sketch included with the PJRC Time library that can be used to synchronize the clock from a Windows computer.
Code Practice Mode
Holding one of the first three memory buttons down on boot up puts the keyer in Code Practice Mode. Characters generated are based on tables in the Wikipedia article on Morse Code.
- M1 Send letters only
- M2 Send letters and numbers
- M3 Send letters, numbers, and punctuation
Characters are sent in groups of five. If a serial terminal window is open it will display the sequential group number as well as the ASCII characters themselves.
Practice Mode Commands
In practice mode, the first four memory buttons adjust the delay between characters in increments of two element (dot width) times. M1 adjusts by zero, M2 by two, M3 by four, M4 by six elements giving a listener additional time to decode the sounds. Each step slows the average WPM by about 10 percent.
Pressing the M5 button pauses practice and the display back light will begin blinking. Pressing M5 again resumes but will likely have mutilated any character that was in progress. M6 increases sending speed and M7 lowers sending speed, one WPM per click. The changed speed is only effective until the keyer is reset, it is NOT written to EEPROM.
Normal Operating Displays are also available in Code Practice mode by pressing Function. The display will not start until the current five letter code group is completed.
If the battery voltage drops below 3.40 volts, the display back light will begin flashing.
Many thanks to Richard Chapman KC4IFB whose September 2009 QEX article provided the inspiration and base code for this sketch. His iambic keyer code feels exactly like my original WB4VVF Accukeyer. Also see Rarons Blog for a discussion of the tree method for decoding and encoding morse characters. It was very helpful in building efficient translation tables. The circular queue was implemented with help from examples at embeddedjournal.com. Paul Stoffregen encouraged me to try the Teensy3.2 on the PJRC forum.
February 25, 2016 MemoryKeyerTeensy3.2_V1.0 Initial sketch
March 9, 2016 MemoryKeyerTeensy3.2_V1.1.0 Rework battery alarm logic, bug fixes.
March 16, 2016 MemoryKeyerTeensy3.2 V1.1.1 Workaround fix LCD does not have backslash in its font.