Provide decoding of communication status field in types 1, 2, 3, 4, 9, 11, 18

[velosol]

Looking at the ITU documentation it seems the 'radio' field for the message types in Table 13 starting on page 40 could be enhanced in pyais. The details of SOTDMA or ITDMA states is described on pages 36-38.

I'm not able to do this extension as a pull request at this time but wanted to document here as an enhancement if others could extend and M0r13n wanted it.

[M0r13n]

Hey @velosol,

I am not exactly sure what part may be improved. Did you take a look at the provided example:

msg = '!AIVDM,1,1,,A,B69Gk3h071tpI02lT2ek?wg61P06,0*1F'
decoded = decode(msg)

print("The raw radio value is:", decoded.radio)
print("Communication state is SOTMDA:", decoded.is_sotdma)
print("Communication state is ITDMA:", decoded.is_itdma)

pretty_json = functools.partial(json.dumps, indent=4)
print("Communication state:", pretty_json(decoded.get_communication_state()))

Which outputs the following text when run:

The raw radio value is: 393222
Communication state is SOTMDA: True
Communication state is ITDMA: False
Communication state: {
    "received_stations": null,
    "slot_number": null,
    "utc_hour": null,
    "utc_minute": null,
    "slot_offset": 6,
    "slot_timeout": 0,
    "sync_state": 3,
    "keep_flag": null,
    "slot_increment": null,
    "num_slots": null
}

[M0r13n]

I'm guessing that's the information you're referring to. So, the documentation still seems to be expandable. Perhaps a more prominent reference is missing? But technically the relevant functionality is already implemented.

[velosol]

My apologies! That's exactly it - I saw the decoded.radio value and naively expected the state to be labeled similarly (i.e. be an attr of .radio). Communication state is the correct name and were I looking for that I'm sure I would've seen the example (idle curiosity on how to interpret .radio led me to GPSd's docs and from there ITU, not a need to interpret the raw radio value).

I was unable to find 'communication state' on the readthedocs page but believe I could put together something there as a pull request to show that radio is decoded by pyais into the fields you showed. Something like the below for each of the messages with the CommunicationStateMixin

* `radio` - Further decoded by `.get_communication_state()` 
            * type: <class 'int'>
            * bit-width: 20
            * default: 0

[M0r13n]

I think that I am going to:

• [x] add a small hint in the readme of the project itself
• [x] add a paragraph to the readthedocs page with some background information
  • this hopefully gets indexed by Google & co. and future searchers may find the information by using a search engine
• [x] improve the message documentations as suggested by you

[M0r13n]

@velosol I added some more documentation that hopefully clarifies the usage of pyais in this regard. Feel free to check it out. If you find anything missing, feel free to reopen this issue.

Have a great day!