Expanded NRPN common core

[recri]

Steve just merged my first pass at a common core of NRPN controls. The idea is that we build a family of keyer firmwares which have a common core of functionality so that allows remote programs to figure out what the firmware is good for and use it.

The original proposal was:

    NRPN_NOTHING  = 0,   // not a nrpn nrpn value, where a null pointer is needed
    NRPN_ID_KEYER = 1,   // identify this keyer for the correspondent
    NRPN_ID_VERSION  = 2,   // identify this keyer version for the correspondent

The updated proposal just merged adds:

    NRPN_NNRPN = 3,   // return how many NRPNs are allocated
    NRPN_NRPN_QUERY = 4,   // take the value as a nrpn number and send that nrpns value, if any    
    NRPN_NRPN_UNSET = 5,   // take the value as a nrpn number and make that nrpn unset

We don't need a NRPN to set a NRPN because that's what NRPNs do by default.

Now I'm thinking to add a few more:

   NRPN_MIDI_CHANNEL = 6, // set the MIDI channel
   NRPN_ID_JSON = 7, // send JSON description of the keyer as a string
   NRPN_STRING_BEGIN = 8, // start a string transfer
   NRPN_STRING_END = 9, // finish a string transfer
   NRPN_STRING_BYTE = 10, // transfer a byte for a string

NRPN_MIDI_CHANNEL should be in the common core. It can be mirrored to/from the CC version. But the current CC version has the option to brick the device by setting an invalid MIDI channel number. Which requires an exception clause in the MIDI handler to unbrick the device. I think that MIDI_CHANNEL specifies one of the valid MIDI channels, 1 .. 16. If you ask for a valid channel, then the NRPN echoes back a confirmation of your request. If you ask to brick the device, you're ignored and nothing is echoed back.

NRPN_ID_JSON should be in the common core. There are two SDR applications which seem happy to accept a JSON description of the keyer interface. I generate JSON-like descriptions of hasak for cwkeyer.elf.org. If a keyer can produce a JSON description on demand, then these sorts of programs can configure themselves on the fly and adapt to new versions as they turn up on the wire. So this seems very useful. And it will encourage keyers to document their interfaces.

If JSON, or any other string serialized object format, then we would need a mechanism for transferring the serialized string. STRING_START, STRING_END, and STRING_BYTE are my solution for this, and other string transfers, but consider it a starting point.

The string NRPNs all transfer a string endpoint identifier in the high byte of the value so that multiple strings can be transferred without interference. The low bytes of NRPN_STRING_START and NRPN_STRING_END specify the string target. The low byte of NRPN_STRING_BYTE specifies a 7 bit ASCII value.

To accomodate WinKey encapsulation, we could restrict the endpoint identifier to 6 bits and send the 8th bit of 8 bit ASCII in the high byte. Hmm, that would also encode UNICODE [Basic Latin (ASCII)], and [Latin-1 Supplement], which gives us all the common european latin characters.

The string endpoints on the keyer are max 128 byte ring buffers. A successful NRPN_STRING_BYTE sent to the either side echoes the endpoint identifier in the high byte of the response and the min(number of remaining writeable bytes in the ring buffer, 127) in the low byte. If there is no room for the byte received, it will be discarded and there will be no response echoed.

The string target byte is used to identify different producers and consumers of strings. But we can leave this undefined, the JSON for the keyer should enumerate the implemented targets, the number of endpoints, the maximum size of the endpoints, and so on. The NRPN_ID_JASON request will echo back with a string endpoint in the high byte and a string target in the low byte, or not respond if the keyer doesn't know its JSON descriptor.

The string targets on the keyer side are text keyers and winkey emulators, so they will usually be draining the endpoint ring buffer as fast as keyer speed allows. Those endpoints may remain open for the length of the session.separate

Does all that make sense? Did I miss anything essential? Is there a better way to do accomplish these ends.

[ahopper]

At first glance this all makes sense to me, I shall try and prototype the other end of it from the spark perspective tomorrow and report back.

[recri]

Okay, it will be a while before I can protoype my end, got a bunch of loose ends on my hands right now.