CHIRP

This is a set of notes about complex driver situations to help with consistency.

## Implied modes

Some radios have an annoying behavior where they determine the mode for a channel based on frequency. This is most commonly used to allow AM for airband frequencies, where the radio does not actually store a bit for "mode is AM" but instead just forces the receiver into AM mode in that range.

Using the airband example, this should be handled by the driver with the following steps:

- Expose `AM` as an option in `valid_modes`.

- Coerce the `Memory.mode` value to `AM` when the frequency is with in the airband range.

- Implement `validate_memory()` to check that `Memory.mode` is `AM` in the airband range, and `FM` in all other ranges. If there is a mismatch, return a `chirp_common.ValidationWarning` to indicate to the user that the mismatch will be corrected by the driver.

Here is an example `validate_memory()` implementation. Try to re-use the same exact strings to minimize translation overhead:

```python

    AIRBAND = (118000000, 136000000)

    def validate_memory(self, mem):

        msgs = []

        in_range = chirp_common.in_range

        if in_range(mem.freq, [AIRBAND]) and not mem.mode == 'AM':

            msgs.append(chirp_common.ValidationWarning(

                _('Frequency in this range requires AM mode')))

        if not in_range(mem.freq, [AIRBAND]) and mem.mode == 'AM':

            msgs.append(chirp_common.ValidationWarning(

                _('Frequency in this range must not be AM mode')))

        return msgs + super().validate_memory(mem)

```

## Immutable memory fields

Immutable fields on a memory can be implemented by setting, for example, `mem.immutable = ['mode']` to prevent the `mode` from being changed. This should be used in cases where the radio has a special memory that has some required settings. Examples of where this is used:

- Some radios have a per-mode "call" special channel (i.e. `FM`, `DV`, etc) 

- Some radios have requirements that the first 22 channels be the GMRS channels where the name and power level are changeable by the user, but the frequency/duplex are not

Effectively, the decision to mark a field as immutable should generally come down to "is this immutable because of the *location* of the memory?" If the fixed nature is related to other *content* of the memory (i.e. channels in the airband range must be `AM`, see above), then it's best to use `validate_memory()` to check/warn about a required value.

## Radios that only support TX/RX frequency

CHIRP requires that drivers behave like a more conventional amateur radio and support Duplex/Offset at least. Supporting TX/RX frequencies with Duplex=split is also supported but Duplex=+/- is necessary. To do this, you should assume a TX/RX split of <= 70MHz to be a duplex mode. Greater separation should be implemented as Duplex=split. See `split_to_offset()` in source:chirp/chirp_common.py which you should use from your driver.

## Aliases

You will find legacy code in the tree that looks like this:

```python

class SomeOtherRadio(chirp_common.Alias):

    VENDOR = "Some"

    MODEL = "Other Radio"

@directory.register

class MyRadio:

    VENDOR = "Acme"

    MODEL = "WhizBang"

    ALIASES = [SomeOtherRadio]

```

This is the **wrong** way to do this job in modern chirp, and it is a pattern that existed from before we had stable metadata in the `.img` files. Please do not add new instances of this.

In modern times, this sort of thing should generally be added to source:chirp/share/model_alias_map.yaml . This source file is used to generate the radio listing on the front page of the site. Models listed here will be reported, along with the pointer to the alternate model the user should select. If the model is a direct clone of another, this is the proper way to denote it. In some cases where the clone is massively more popular than the original, then an empty subclass is to be used (which is normally preferred when there is an actual difference). So the above deprecated `ALIASES=` example would be:

```python

@directory.register

class MyRadio:

    VENDOR = "Acme"

    MODEL = "WhizBang"

    ALIASES = [SomeOtherRadio]

@directory.register

class SomeOtherRadio(MyRadio):

    VENDOR = "Some"

    MODEL = "Other Radio"

```