Morserino32 Serial Test

Specification

General

Sending commands to morserino

• Commands sent to the morserino start with "GET" (read values) or "PUT" (write values) and additional parameters.
• Commands are ended by a single carriage return ('\n' or ascii 10) shown in the examples below as "↵"
• All write commands return a json object with one or more keywords as property names ("menu", "menus", "config", "configs"). For example the command to change to a specific menu returns the selected menu as a result or an error object.

Receiving information from morserino

• Morserino sends a message for all actions executed manually by the user on the morserino (navigate to another menu, change of speed, etc.).
• It always sends a valid json object.
• Line breaks are optional.
• Different type of actions are defined (future).
• NOTE: we might need to define an end marker to know when the result object is finished???

Enable Morserino32 Protocol

Bidirectional communiation must be enabled by the following command:

PUT device/protocol/on↵

enables the bidirectional protocol and returns the device info:

{"device":{"hardware":"2nd edition","firmware":"5.0 beta","protocol":"0.9"}}

It can also be disabled again

PUT device/protocol/off↵

Error Feedback

In case of an error object is returned from Morserino:

{"error":{"name":"INVALID Value xxx"}}

Device Info

Returns information about morserino device (hardware, firmware, protocol version):

GET device↵

returns

{"device":{"hardware":"2nd edition","firmware":"5.0 beta","protocol":"0.9"}}

Navigation (Menu)

This returns the state of the currently selected menu.

• read the current menu entry. Returns a json object "menu" containing the currently selected menu:

  GET menu↵

  Submenues are separated by a slash, if it has submenus it cannot be executed:

  {"menu":{"content":"Echo Trainer/CW Abbrevs","menu number":11,"executable":true,"active":false}}

• read all possible menu entries. This will return an object "menus" holding an array of configurations (see below):

  GET menus↵

• navigate to a menu entry with a given id:

  PUT menu/set/n↵

  Examples:

  • PUT menu/set/n↵

• navigate to a menu entry and start it (either current menu or menu identified by id):

  PUT menu/start/n↵

  Examples:

  • PUT menu/start↵

  • PUT menu/start/n↵

The following json object is sent from morserino on a menu change (manually or by a write command ("PUT menu/set/n↵"))

{
    "menu": {"name": "menu as a path separated by slash" }
}

Examples:

• Top level menu:

  {"menu":{"content":"Echo Trainer/..","menu number":9,"executable":false,"active":false}}

• Action menu:

  {"menu":{"content":"Echo Trainer/CW Abbrevs","menu number":11,"executable":true,"active":false}}

• All menu items:

  GET menus↵
  {
      "menus": [
          {"content": "CW Keyer",                                "menu number":  1, "executable": true },
          {"content": "CW Generator/..",                         "menu number":  2, "executable": false},
          {"content": "CW Generator/Random",                     "menu number":  3, "executable": true },
          {"content": "CW Generator/CW Abbrevs",                 "menu number":  4, "executable": true },
          {"content": "CW Generator/English Words",              "menu number":  5, "executable": true },
          {"content": "CW Generator/Call Signs",                 "menu number":  6, "executable": true },
          {"content": "CW Generator/Mixed",                      "menu number":  7, "executable": true },
          {"content": "CW Generator/File Player",                "menu number":  8, "executable": true },
          {"content": "Echo Trainer/..",                         "menu number":  9, "executable": false},
          {"content": "Echo Trainer/Random",                     "menu number": 10, "executable": true },
          {"content": "Echo Trainer/CW Abbrevs",                 "menu number": 11, "executable": true },
          {"content": "Echo Trainer/English Words",              "menu number": 12, "executable": true },
          {"content": "Echo Trainer/Call Signs",                 "menu number": 13, "executable": true },
          {"content": "Echo Trainer/Mixed",                      "menu number": 14, "executable": true },
          {"content": "Echo Trainer/File Player",                "menu number": 15, "executable": true },
          {"content": "Koch Trainer/..",                         "menu number": 16, "executable": false},
          {"content": "Koch Trainer/Select Lesson",              "menu number": 17, "executable": true },
          {"content": "Koch Trainer/Learn New Chr",              "menu number": 18, "executable": true },
          {"content": "Koch Trainer/CW Generator/..",            "menu number": 19, "executable": false},
          {"content": "Koch Trainer/CW Generator/Random",        "menu number": 20, "executable": true },
          {"content": "Koch Trainer/CW Generator/CW Abbrevs",    "menu number": 21, "executable": true },
          {"content": "Koch Trainer/CW Generator/English Words", "menu number": 22, "executable": true },
          {"content": "Koch Trainer/CW Generator/Mixed",         "menu number": 23, "executable": true },
          {"content": "Koch Trainer/Echo Trainer/..",            "menu number": 24, "executable": false},
          {"content": "Koch Trainer/Echo Trainer/Random",        "menu number": 25, "executable": true },
          {"content": "Koch Trainer/Echo Trainer/CW Abbrevs",    "menu number": 26, "executable": true },
          {"content": "Koch Trainer/Echo Trainer/English Words", "menu number": 27, "executable": true },
          {"content": "Koch Trainer/Echo Trainer/Mixed",         "menu number": 28, "executable": true },
          {"content": "Koch Trainer/Echo Trainer/Adapt. Rand.",  "menu number": 29, "executable": true },
          {"content": "Transceiver/..",                          "menu number": 30, "executable": false},
          {"content": "Transceiver/LoRa Trx",                    "menu number": 31, "executable": true },
          {"content": "Transceiver/WiFi Trx",                    "menu number": 32, "executable": true },
          {"content": "Transceiver/iCW/Ext Trx",                 "menu number": 33, "executable": true },
          {"content": "CW Decoder",                              "menu number": 34, "executable": true },
          {                                                                                            }
      ]
  }
  

Activate

When the user triggers an action (like starting CW Decoder) the following message is sent by Morserino:

{"activate":{"state":"ON"}}

The following values are possible (not all are yet implemented): EXIT, ON, SET, CANCELLED, RECALLED, CLEARED Sometimes a message object is sent from the morserino that contains additional information:

{"message":{"content":"Generator     Start / Stop  press Paddle  "}}

Controls

• speed: speed in wpm: 5 - 60)

  GET control/speed↵

  returns the information about the currently used speed (wpm):

  {"control":{"name":"speed","value":46,"minimum":5,"maximum":60}}

  PUT control/speed/20↵

  also returns the result

  {"control":{"name":"speed","value":17}}

• volume: speaker volume: 0-19

  GET control/volume↵

  PUT control/volume/10↵

• Get all Controls

  GET controls↵

  returns

  {"controls":[{"name":"speed","value":17},{"name":"volume","value":19}]}

Configuration

• Reads all configuration parameters from morserino as a list of configuration objects: only name, value and if the value is mapped to a string, it is also returned:

  GET configs↵

• Reads a single detailed configuration parameter from morserino (key is case insensitive) or an error if an invalid key was sent: "name" (String), "value" (numeric), "description" (String), "minimum" (numeric), "maximum" (numeric), "step" (numeric), "isMapped" (bool), and String[] for the mappings, if applicable

  GET config/key↵

• Write a single configuration parameter. Will return the changed configuration or an error. The value is always numeric (?)

  PUT config/key/value↵

Returned object examples:

• GET config/Serial Ouput↵
  { 
      "config": {
          "name":"Serial Output",
          "value":7,
          "description":"Select what is sent to the serial (USB) port",
          "minimum":0,
          "maximum":5,
          "step":1,
          "isMapped":true,
          "mapped values":["Nothing","Keyed","Decoded","Keyed+Decoded","Generated","All"]
      }
  }

• Multiple/all config values returns a list of configuration objects (short version - only name and value and if the value is mapped to a string, it is also returned):

  GET configs↵
  { "configs": [
      {"name": "key1", "value": value1, "displayed": "Config Title"},
      {"name": "key2", "value": value2, "displayed": "Config Title2"}
  ]}

  Here is a full result of the command:

  {
      "configs": [
          {"name": "Headphone Output", "value":  0, "displayed": "Phones"       },
          {"name": "Encoder Click",    "value":  1, "displayed": "On"           },
          {"name": "Tone Pitch",       "value": 10, "displayed": "622 Hz E5"    },
          {"name": "External Pol.",    "value":  0, "displayed": "Normal"       },
          {"name": "Paddle Polar.",    "value":  1, "displayed": ".- dit dah"   },
          {"name": "Keyer Mode",       "value":  2, "displayed": "Iambic B"     },
          {"name": "CurtisB DahT%",    "value": 45, "displayed": "45"           },
          {"name": "CurtisB DitT%",    "value": 75, "displayed": "75"           },
          {"name": "AutoChar Spc",     "value":  0, "displayed": "Off"          },
          {"name": "Tone Shift",       "value":  1, "displayed": "Up 1 Half"    },
          {"name": "InterWord Spc",    "value":  6, "displayed": "6"            },
          {"name": "Interchar Spc",    "value":  3, "displayed": "3"            },
          {"name": "Random Groups",    "value":  0, "displayed": "All Chars"    },
          {"name": "Length Rnd Gr",    "value":  9, "displayed": "2 to 5"       },
          {"name": "Length Calls",     "value":  0, "displayed": "Unlimited"    },
          {"name": "Calls Region",     "value":  0, "displayed": "All"          },
          {"name": "Call Prefixes",    "value":  1, "displayed": "Common only"  },
          {"name": "Length Abbrev",    "value":  2, "displayed": "3"            },
          {"name": "Length Words",     "value":  0, "displayed": "Unlimited"    },
          {"name": "CW Gen Displ",     "value":  1, "displayed": "Char by char" },
          {"name": "Each Word 2x",     "value":  0, "displayed": "OFF"          },
          {"name": "Echo Prompt",      "value":  1, "displayed": "Sound only"   },
          {"name": "Echo Repeats",     "value":  3, "displayed": "3"            },
          {"name": "Confrm. Tone",     "value":  1, "displayed": "ON"           },
          {"name": "Key ext TX",       "value":  1, "displayed": "CW Keyer only"},
          {"name": "Generator Tx",     "value":  0, "displayed": "WiFi Tx OFF"  },
          {"name": "Bandwidth",        "value":  0, "displayed": "Wide"         },
          {"name": "Adaptv. Speed",    "value":  0, "displayed": "OFF"          },
          {"name": "Echo Speed Max",   "value":  0, "displayed": "No limit"     },
          {"name": "Koch Sequence",    "value":  0, "displayed": "M32"          },
          {"name": "LICW Carousel",    "value":  0, "displayed": "BC1: r e a"   },
          {"name": "Latency",          "value":  4, "displayed": "50%"          },
          {"name": "Randomize File",   "value":  0, "displayed": "OFF"          },
          {"name": "Decoded on IO",    "value":  0, "displayed": "OFF"          },
          {"name": "Time-out",         "value":  0, "displayed": "No time-out"  },
          {"name": "Quick Start",      "value":  0, "displayed": "OFF"          },
          {"name": "Output Case",      "value":  0, "displayed": "lower"        },
          {"name": "StopRep",    "value":  0, "displayed": "OFF"          },
          {"name": "Max # of Words",   "value": 20, "displayed": "20"           },
          {"name": "Trx Channel",      "value":  0, "displayed": "Standard"     },
          {"name": "BLT Kbd Output",   "value":  0, "displayed": "Nothing"      },
          {"name": "Theme",            "value":  1, "displayed": "Blues"        },
          {"name": "Invader Orient.",  "value":  0, "displayed": "Portrait"     },
          {"name": "Serial Output",    "value":  5, "displayed": "All"          }
      ]
  }
  

Snapshots

• GET snapshots↵

  returns a list of all currently stored snapshots (n = 1..8)

• PUT snapshot/store/n↵

  store parameters in snapshot n (n = 1..8)

• PUT snapshot/recall/n↵

  recall parameters from snapshot n

• PUT snapshot/clear/n↵

  clear (delete) snapshot n

File Upload

A text file can be uploaded that can then be played in CW:

• GET file/size↵

  usage of SPIFFS file system (used for player file) {"file":{"size":nnn, "free": nnn}} nnn in bytes

• GET file/first line↵

  get the first line of the text file

  {"file":{"first line":"contents of text file"}}

  See also below how to add a comment (to be used as title or description in first line).

• GET file/text↵

  get the contents of the text file

  {"file":{"text":"contents of text file"}}

• PUT file/new/line of text↵

  replace existing file with new file, place a line of text into new file

• PUT file/append/line of text↵

  append a line of text to the existing file

Comments

The text of a file can contain a comment that is not played: Starting with "\c" the rest of the line is treated as a comment. If used as first line of a file it can be used as a title/description of the file content and can be retrieved with

GET file↵

or

GET file/first line↵

Wifi Configuration

The wifi connections can be configured:

• GET wifi↵

  get currently set wifi entries (SSID and trxpeer, NOT passwords!) -

  {"wifi":[{"ssid“:“MyFD48","trxpeer":"cq.morserino.info"},{"ssid“:“mywifi ","trxpeer":"cq.morserino.info"},{"ssid":"","trxpeer":""}]}

• PUT wifi/select/n↵

  selects the wifi number n

• PUT wifi/ssid/n/ssid↵

  set SSID for WiFi setting n (n == 1..3) e.g.

  PUT wifi/ssid/2/MyHomeRouter

• PUT wifi/password/n/password↵

  set password for WiFi setting n e.g.

  PUT wifi/password/2/mySecret1234567

• PUT wifi/trxpeer/n/trxpeer↵

  set TRX Peer for WiFi setting n e.g.

  PUT wifi/trxpeer/2/cq.morserino.info

Koch Lesson

• GET kochlesson↵

  Info about the koch lesson and the currently selected lesson is returned:

  {"kochlesson":{"value":40,"minimum":1,"maximum":51,"characters":["m","k","r","s","u","a","p","t","l","o","w","i",".","n","j","e","f","0","y","v",",","g","5","/","q","9","z","h","3","8","b","?","4","2","7","c","1","d","6","x","-","=","","+","","","","","","@",":"]}}

• PUT kochlesson/n↵

  selects the koch lesson with the given number

Custom Chars

• GET customchars↵

  Info about customer characters to be used.

  {"customchars":{"active":true,"characters":"qwerty"}}

• PUT customchars/set/qwerty/n↵

  set the custom character to be used.

CW Player

In CW Keyer mode or in Tranceiver mode CW output can be generate (like a memory keyer). Player is stopped by manual keying or the stop command. /p, [p], or <p> add short pauses.

• PUT cw/play/cq cq cq de OE6CHD pse k↵

• Like play, but repeat until stopped.

  PUT cw/repeat/cq cq cq de OE6CHD pse k↵

• Stop cw playing

  PUT cw/stop↵

CW Memory

There are 8 memories to store text that can be played. Memory 1 and 2 are played in loops until the paddle is touched. Use /p, [p], or <p> for a pause (e.g. to listen to an answer).

• GET cw/memories↵

  returns a list of all currently stored memmories:

  {"CW Memories":{"cw memories in use":[1,2]}}

• PUT cw/store/n/text↵

  store text in cw memory n (n = 1..8)

  PUT cw/store/1/cq cq cq de OE6CHD pse k↵

• GET cw/memory/n↵

  returns the text for memory n (n = 1..8):

  {"CW Memory":{"number":1,"content":"cq cq cq de OE6CHD pse k"}}

• PUT cw/recall/n↵

  generate morse code from the content in memory number n; if <n> is 1 or 2, do this until stopped by touching a paddle, or by the PUT cw/stop command