EEPROM Usage
The available on board EEPROM is used to store some keyer parameters and the keyer memories.
The K3NG keyer software writes many user adjustable parameters to the on board non-volatile EEPROM in order to preserve those settings, even after power down of the keyer.
On powering up the keyer the parameters are read from the EEPROM so that the keyer starts up in the same state that it was when last used.
Every time the user makes a change to one of these parameters, the software sets a flag and the new parameter value is written to EEPROM.
EEPROM has a 'lifetime' that is specified in the number of EEPROM writes. So each write to EEPROM consumes a little of the EEPROM life. In the K3NG keyer these EEPROM writes are managed to try and prevent the 'wearing out' of the EEPROM. So EEPROM writes will not occur any more frequently than the time specified by the variable eeprom_write_time_ms which is set to a default value of 30,000 milliseconds (30 seconds) in the header file keyer_settings.h
EEPROM writes are also relatively slow (up to 3.3ms) and can impede the execution of other functions that need to be done by the code. Commencing with version 2019.05.17.01 the writes of the configuration data to EEPROM are done asynchronously, just one byte at a time, each time the code cycles around the main loop. This spreads out the time taken to complete the refresh of the EEPROM so as to have a minimal impact on the execution of other code modules.
Parameters stored in EEPROM
In version 2019.05.17.02 of the K3NG keyer code the parameters that are saved to EEPROM are –
magic_number; - used to determine if a fundamental change to the data structure has occurred and if an EEPROM reset is required
paddle_mode; - the paddle mode - normal, reverse
keyer_mode; - the keyer mode - iambic A, iambic B, single paddle, bug, straight key
sidetone_mode; - sidetone mode - off, on, paddle only
pot_activated; - potentiometer active - requires FEATURE_POTENTIOMETER
length_wordspace; - wordspace length
autospace_active; - autospace active
current_ptt_line; - currently selected ptt line
current_tx; - currently selected transmitter line
weighting; - weighting
dit_buffer_off; - dit buffer on, off
dah_buffer_off; - dah buffer on, off
cmos_super_keyer_iambic_b_timing_percent; - defaults to 33 - requires FEATURE_CMOS_SUPER_KEYER_IAMBIC_B_TIMING
cmos_super_keyer_iambic_b_timing_on; - requires FEATURE_CMOS_SUPER_KEYER_IAMBIC_B_TIMING
link_receive_enabled; - settings for a future release with ethernet connectivity - requires FEATURE_ETHERNET
paddle_interruption_quiet_time_element_lengths; - defaults to 0
wordsworth_wordspace; - wordspace when using the wordsworth feature
wordsworth_repetition; - wordsworth repetition speed when using the wordsworth feature
cli_mode; - command line interface mode
ptt_buffer_hold_active; - if the ptt buffer hold is active
wpm; - the words per minute setting of the keyer
hz_sidetone; - the sidetone frequency that is generated by the processor
dah_to_dit_ratio; - the ratio of a dit to a dah
wpm_farnsworth; - the words per minute setting when using the Farnsworth feature
memory_repeat_time; - the time between repeated playing of a memory when memory repeat is in use
wpm_command_mode; - the words per minute setting when the keyer is placed into Command Mode
link_receive_udp_port; - settings for a future release with ethernet connectivity - requires FEATURE_ETHERNET
wpm_ps2_usb_keyboard; - keyboard wpm - does not appear to be used
wpm_cli; - command line interface wpm - does not appear to be used
wpm_winkey; - winkey wpm - does not appear to be used
ip[4]; - settings for a future release with ethernet connectivity - requires FEATURE_ETHERNET
gateway[4]; - settings for a future release with ethernet connectivity - requires FEATURE_ETHERNET
subnet[4]; - settings for a future release with ethernet connectivity - requires FEATURE_ETHERNET
link_send_ip[4][FEATURE_INTERNET_LINK_MAX_LINKS]; - requires FEATURE_ETHERNET
link_send_enabled[FEATURE_INTERNET_LINK_MAX_LINKS]; - requires FEATURE_ETHERNET
link_send_udp_port[FEATURE_INTERNET_LINK_MAX_LINKS]; - requires FEATURE_ETHERNET
ptt_lead_time[6]; - an array of ptt lead times, for the 6 possible PTT lines
ptt_tail_time[6]; - an array of ptt tail times, for the 6 possible PTT lines
ptt_active_to_sequencer_active_time[5]; - time settings related to the sequencer - requires FEATURE_SEQUENCER
ptt_inactive_to_sequencer_inactive_time[5]; - time settings related to the sequencer - requires FEATURE_SEQUENCER
sidetone_volume; - the sidetone volume, this was planned for a future release, using DDS techniques to generate a sinusoidal sidetone - requires FEATURE_SINEWAVE_SIDETONE
Storage of memories in the onboard EEPROM
The K3NG keyer reserves the first 120 bytes of EEPROM for the saving of the keyer parameters listed above. The balance of the available EEPROM is divided up evenly amongst the number of memories specified. The number of memories is set by the variable number_of_memories and this is done in the header file keyer_settings.h.
The amount of available EEPROM memory will depend on the processor in use on the board. For example, the Arduino Nano and Arduino Uno using the ATMega328P processor have 1024 bytes of EEPROM, while the Arduino Mega using the ATMega2560 processor has 4096 byes of EEPROM. The amount available to the keyer is specified by the setting of memory_area_end in the header file keyer_settins.h. You need to set this variable so that it matches the amount of EEPROM on the board/processor in use. From 2020 the code versions now automatically determine the amount of EEPROM available in the processor.
For example, an ATMega2560 board with 4096 bytes of EEPROM, when configured for the maximum number of 12 memories, will permit each memory to store (4096-120)/12 = 331 characters (including spaces) per memory. If you configured that same keyer, using an ATmega2560 processor, with just 1 memory (say, to use the unit as a beacon), then that single memory could store up to (4096-120)/1 = 3976 characters (including spaces). An Arduino Uno or Arduino Nano board with 1024 bytes of EEPROM, when configured for 5 memories, will permit each memory to store (1024-120)/5 = 180 characters (including spaces) per memory.
Erasing/Resetting EEPROM
If new features are added to the software that require new keyer parameters to be stored in EEPROM, then the amount of EEPROM used for parameter storage could change. This affects the structure of the data saved to the EEPROM and could require more than the 113 bytes previously reserved for this purpose.
Should such a structural change be required the EEPROM will need to be reset. When an EEPROM reset occurs the default values for the various stored parameters are written to the EEPROM. Most of the default values are specified in the header file keyer_settings.h. This EEPROM reset could affect stored memories too, since the start and end address of the specified memories might have also been changed. An EEPROM reset might corrupt any previously stored memories and these memories might need to be stored again.
The user can also initiate a reset of the EEPROM and that will load the EEPROM with the default parameter values. Since this type of reset is user initiated and not triggered by a change in the parameter storage, it is unlikely that any stored memories will be corrupted. Only user modified parameter values will be overwritten by the default values.
A user initiated EEPROM reset is performed by holding both paddles together either when powering up the keyer or when resetting the processor board.
Flash Memory as EEPROM
Some Arduino boards have only Flash Memory instead of EEPROM storage. This generally includes SAMD21 boards (Cortex M0) and SAMD51 (Cortex M4) such as the ItsyBitsy, Feather M0, Feather M4, Grand Central M4, Feather rp2040, Metro rp2040, and more.
There is conditional code to substitute Flash memory instead of EEPROM. The K3NG project already contains conditional code that checks the target processor hardware and will automatically #include <FlashAsEEPROM_SAMD.h>. You don't need to add or edit this. However, you will need to install a support library such as https://github.com/khoih-prog/FlashStorage_SAMD