[chirp_devel] Developers' wiki page

[Dan Smith]

> Write get_memory(number: int | str)
> 
> This is called to get your driver to populate the CHIRP memory model with the data for one radio memory. On startup, it’s called once for each memory register you’ve delimited for your radio and once for each special memory. Later it will be called as needed.
> 
> - get_memory() returns a populated CHIRP memory object that the driver creates as a new instance of the chirp_common.Memory structure. You’ll want to become familiar with the fields in the Memory structure (presently specified in the source tree in the source file chirp/chirp_common.py).
>   
> - The number of memories is specified in chirp_common.RadioFeatures.memory_bounds, which is a pair of numbers (first memory register number, last memory register number.) get_memory will be called with an integer parameter for regular memory with a value up to the last memory register number.
> 
> - Special memories are radio-specific registers that can hold special meaning in the radio (such as scan limits, home registers, skip registers, etc.) They are specified in your driver as members of the list that you set at chirp_common.RadioFeatures.valid_special_chans. get_memory() will be called with a string containing the name of the special register, and you must set the Memory.number field of the resulting memory object to an index that is greater than the last memory register number and different than other special memories without holes in the sequence. Subsequent calls to get_memory() may receive either the index or the name.
> 
> Do read the example driver at chirp/chirp/drivers/template.py. There is a commented stub version of this routine in chirp/chirp.common.py. Your driver is expected to overload it.
> 
> 
> 
> Write set_memory(memory: chirp_common.Memory)
> 
> This is called whenever CHIRP wants your driver to set the radio’s memory according to the fields described in the specific chirp_common.Memory parameter. The driver will presumably need to determine the specific radio memory based upon the value of memory.number (e.g. integer less than or greater than last memory number.) The driver should not change the memory structure.
> 
> There is no special return to CHIRP required.
> 
> Do read the example driver at chirp/chirp/drivers/template.py. There is a commented stub version of this routine in chirp/chirp.common.py. Your driver is expected to overload it.

I added this with a few minor tweaks.

> Radio memory settings that are not included in CHIRP chirp_common.Memory.
> 
> CHIRP can (optionally) manage and display other settings for each memory.  These are stored in a separate subject chirp_common.Memory.extra, and are handled during the get_memory and set_memory by calling _get_mem_extra(mem, _mem) and _set_mem_extra(mem, _mem), respectively. “mem” is the CHIRP memory structure, and “_mem” is the corresponding radio memory structure. You’ll get to write code to handle them similar to “RadioSettings.”

This is not correct information - these _get_mem_extra and related routines are for the image metadata and have nothing to do with Memory.extra. I tweaked this to be correct and added the result to the page as well.

> Run tests
> 
> Read the wiki page at https://chirp.danplanet.com/projects/chirp/wiki/DevelopersPython3Environment
> 
> Tox is a separate application used to run tests for CHIRP. (I got it by “pip install tox” and it installed into my Python instance.) It will check syntax and stylistic features of the python source. It will also run many logic tests on all drivers that have changed in your tree since the last time it was run. Use:
> 
> $ tox -e style
> 
> You may then wish to run the driver test only on your driver. It appears that you can do so by executing 
> 
> $ tox -e driver -- -k Vendor_Model
> Or (to only test drivers with changes:)
> $ tox -e fast-driver

I think this is covered on the environment page, but I provided a link in this section.

> Things not said elsewhere:
> 
> Some of the following are hinted at in the example driver “chirp/chirp/drivers/template.py.”
> 
> CHIRP has a “directory” structure of all the radios it should know about. Your driver will have one or more “@directory.register” statement, wherein a class is defined for each radio you’re working on. They can inherit from each other (even other models and vendors) once the classes are read by CHIRP. The directory is sorted by text (vendor, model) pairs.
> 
> That class will have definitions (and some redefinitions) for your radio. It will also implement a function
> get_features() -> chirp_common.RadioFeatures()
> You get to return basic information about your radio in the structure that CHIRP defines in chirp/chirp_common.py and you instantiate. Any existing driver should have one for you to copy and modify. CHIRP calls it fairly often when starting, so it’s expected to be lightweight. You probably don’t want this function to be querying the radio each time it’s called.

I broke this up a bit and added it.

> Modes:
> CHIRP has a predefined set of “modes” available for each memory entry. Whatever your radio defines as modes, they MUST map into the CHIRP model. If the radio’s modes don’t fit into CHIRP’s model, you’ll get to add some translation into your driver. The current list (as of 2023-07-28 from chirp/chirp_common.py) is:
> 
> MODES = ("WFM", "FM", "NFM", "AM", "NAM", "DV", "USB", "LSB", "CW", "RTTY",
>          "DIG", "PKT", "NCW", "NCWR", "CWR", "P25", "Auto", "RTTYR",
>          "FSK", "FSKR", "DMR", "DN")

We probably need a new page like the ToneModes page for these. I'll see about doing that.

> Live drivers
> A more-official description can be found at https://chirp.danplanet.com/projects/chirp/wiki/FAQ.
> Most radios seem to have a mode for which memory can be read or written as a large block, and their drivers reflect that. A few radios can only be accessed on what is effectively memory-by-memory reads/writes. These radios will almost surely need to be written as “live”. An example driver is at chirp/chirp/drivers/kenwood_live.py. Several other Kenwood drivers inherit from that one (at least ts480.py, tmd710.py, ts2000.py.) These drivers do not use the same radio-memory model as most of the others, but can keep a kind of cache.

I added this to the top of the page as a sort of decision point before going into the protocol stuff.

Thanks!

--Dan