ASL3 and SimpleUSB setup documentation improvements needed - esp. when CTCSS tone is not used

[csylvain]

Describe the bug
the default value for ctcssfrom is usbinvert and causes an issue when no CTCSS tone is selected.
installation instructions do not indicate what to do in asl-menu if a SimpleUSB device is used with its default CTCSS setting.
the default duplex type is 2 [full-duplex] although SimpleUSB dongles are unlikely to be anything other than half-duplex.

To Reproduce
0. create a new ASL3 appliance (see https://allstarlink.github.io/install/pi-appliance/pi-detailed/) and use a never before programmed SA818 USB dongle. use web interface and select Terminal in Administrative access mode

1. use sa818-menu to program the SA818 USB dongle - set the Receive and Transmit frequencies. Note the default for Sub-audible tone is None
2. follow appliance configuration instructions at https://allstarlink.github.io/install/pi-appliance/pi-detailed/#quick-config-via-asl-menu, and run asl-menu
3. Node Settings -> Allstar Node Setup Menu -> Add Node
4. enter Node Number, Node Password, Node Callsign, leave Radio Interface set to SimpleUSB, change Duplex type to 1 [half-duplex], recommend setting Post node status to Yes

Expected behavior
kerchunking the newly setup appliance should cause it to emit a courtesy beep. it does not. it will not until the node settings are updated and the ctcssfrom setting is changed to no when the default SA818 Sub-audible tone is left set to None

Software versions (listed in asl-menu, option 4)

OS            : Debian GNU/Linux 13 (trixie)                                                       
                               │ OS Kernel     : 6.12.62+rpt-rpi-v8                                                                 
                               │                                                                                                    
                               │ Asterisk      : 22.7.0+asl3-3.7.1-1.deb13                                                          
                               │ ASL [app_rpt] : 3.7.1                                                                              
                               │                                                                                                    
                               │ Installed ASL packages :                                                                           
                               │                                                                                                    
                               │   Package                         Version                                                          
                               │   ==============================  ==============================                                   
                               │   allmon3                         1.7.0-1.deb13                                                    
                               │   asl3                            3.13-1.deb13                                                     
                               │   asl3-appliance                  2.1.0-2.deb13                                                    
                               │   asl3-appliance-pi               2.1.0-2.deb13                                                    
                               │   asl3-asterisk                   2:22.7.0+asl3-3.7.1-1.deb13                                      
                               │   asl3-asterisk-config            2:22.7.0+asl3-3.7.1-1.deb13

Have you run a software update and rebooted?
yes

What is the platform - e.g. Raspberry Pi 4, Raspberry Pi 5, Virtual Machine, Desktop, etc.
raspi 4B

Suggested Installation Instructions Additions
at the end of the section Quick Config via ASL-Menu add a note to use Interface Tune CLI and set Change CTCSS From from usbinvert to no if SA818 was programmed with Sub-audible tone None

[Allan-N]

the default value for ctcssfrom is usbinvert and causes an issue when no CTCSS tone is selected.

The default settings have not been tailored for any specific type of interface. Changing the default value might be one less value that you need to change but would end up being one more value that someone else needs to adjust. For this reason, we need to be very careful about making any changes to the template/default configuration.

installation instructions do not indicate what to do in asl-menu if a SimpleUSB device is used with its default CTCSS setting.

When you use the asl-menu "Node Setup Menu" to add your first node you should have seen a screen with :

The "Node Setup Menu" allows you to change (or "tune") the configuration of the radio interface.
    
Do you want to view or adjust the settings for this nodes interface?

How might this text be changed to ensure that folks are aware that some of the settings may need to be changed?

the default duplex type is 2 [full-duplex] although SimpleUSB dongles are unlikely to be anything other than half-duplex.

Again, the default settings have not been tailored for any specific type of interface.

Also, what type of interface were you trying to setup/configure? Did the vendor providing this interface provide any documentation? Did that documentation provide any suggested settings?

[csylvain]

hello! ah, i see you're thinking of changes in the menu scripts.

this issue is more about the initial setup guidance in the Wiki - specifically in the section https://allstarlink.github.io/install/pi-appliance/pi-detailed/#quick-config-via-asl-menu

what guidance there is in the Wiki appears to indicate issues with the documentation should be discussed here.

the need to change the default ctcssfrom value is a gotcha impeding the setup process of a new functioning node using a Raspi and a SA818 USB dongle (in this case, a dongle from AURSINC). the ctcssfrom value also needs to be changed if the operator later decides to no longer require a CTCSS tone in incoming RF transmissions.

i attempted to describe the pain points encountered when never before having setup an ASL3 appliance using new never before configured system components.

the vendor did provide a one page, printed on both sides, set of instructions but they are almost entirely not applicable to the ASL3 appliance. the instructions are for FM wireless network installed Shari SA818A UHF with Raspi images using a raspi image obtained from callsign DB0HTV's XLX169 server.

as i was now necessarily freestyling, given the vendor's instructions, i encountered some surprises while studiously following the Pi Appliance installation instructions in the Wiki. my intent is to be a faithful crash-test dummy in this context.

possible improvement could be an additional breadcrumb offered in sa818-menu when Sub-audible tone is left with its default None setting (this would be to direct the operator to make the appropriate change to ctcssfrom via asl-menu) and a breadcrumb in asl-menu to explain the default ctcssfrom value should not be left unchanged if no CTCSS tone has been set for the radio interface. these suggestions are offered in case you are still contemplating changes to asl-menu and sa818-menu.

aside from breadcrumbs in the setup scripts, a few more instructions in the Wiki on how to navigate the installation and initial setup to avoid the showstopper of a seeming inert node would be quite helpful, and i have tried to write a few words to document it.

i would also suggest the Wiki instruct the operator before running asl-menu the first time and when intending to use a SA818 interface, to be certain to have run sa818-menu successfully to program the dongle in preparation for all the rest of the initial appliance setup that follows in asl-menu.

[Allan-N]

I think you may be a bit confused about the ctcssfrom= variable. From the ASL3 Manual : simpleusb.conf page you will see that this variable sets the source of the external CTCSS signal. Some hardware provides a separate hardware indication that the CTCSS signal is present. For your AURSINC dongle, this is not the case. You would always use ctcssfrom = no.

As I've been commenting, ASL3 does not target one specific type of hardware. Not every node is a "repeater". Not every node is a "personal hotspot". Some nodes are connected to radios, some use the SA818 chipset, some are cloud hubs, and some are radio-less. Because of this, the instructions, menus, scripts, etc need to be a bit generic. This is why we rely on the vendors to provide documentation for the common use cases of their products.

Note: we have worked with a few of the "active" vendors to simplify the configuration of their devices through the menus. Other interested vendors can certainly reach out to us.

I will ponder, and am certainly open to suggestions about, ways to improve our documentation but we're mostly talking about adding generic notes/steps like "Ensure that your RF/radio hardware has been correctly setup (frequencies, CTCSS/DCS tones)" and "Ensure that the SimpleUSB/USBRadio configuration settings match those of your specific interface".

Again, for device/interface specific information, you are really going to work with the vendor ... and be sure to let them know if their documentation needs to be lacking.

[csylvain]

i tested the SA818 dongle signalling using the interface tune View COS, CTCSS and PTT Status function, and sure enough, i observe no change in the CTCSS signal while the COS signal toggles during incoming transmissions. this done with CTCSS set and unset.

the AURSINC instruction sheet doesn't even mention ctcssfrom at all and documents a variety of file edits, so i guess it's for ASL earlier than rev 3. furthermore, at the bottom of their sheet, it says

AURSINC: If you need further support, please feel free to contact us

but that's all it says. sleuthing required to accomplish 'contact'.

how about some words in the SA818 part of the Wiki?

[Allan-N]

the AURSINC instruction sheet doesn't even mention ctcssfrom at all and documents a variety of file edits, so i guess it's for ASL earlier than rev 3. furthermore, at the bottom of their sheet, it says

I suspect that the doc doesn't mention ANY of the SimpleUSB channel driver settings. You are just expected to "know" what they should be based on other/related products.

how about some words in the SA818 part of the [ASL3 Manual]?

What are you thinking? and, know that the ctcssfrom= setting relates to the CM108 (the USB audio interface) and not the SA818 (the RF module).

Note: I understand your frustration. We just can't be the authoritative source for information and support for every vendors (and individuals homegrown) products.

[csylvain]

authoritative? i didn't say anything about that. you do want to be helpful, though, yes?
until such time that AllStarLink Inc. endorses or produces radio interfaces, it would never claim to be authoritative.

i understand what you're saying from the point of view of an electrical engineer regarding CM108 versus SA818.

however, for every one of these sold as AURSINC Allstar RF Node UHF SR-FRS Radio Programming Module Pi-hat for Allstar, Echolink, APRS, Digital Modes Compatible for Raspberry Pi 2/3/4, Pin to Pin Replace SA-818 Module, UHF Freq 400-470, i get a CM108B and a SA818S

from the point of view of an operator seeking to setup a new node and participate in the AllStarLink network, these are not separate. the combination is a module. in this case module meaning a USB dongle using a RF module and a USB audio chip.

any radio interface using these chips are going to be more the same than different, are they not? guidance in the Wiki would be helpful.

also, no, from the point of view of a new node operator, i did not know precisely which chip the ctcssfrom relates to, as there is presently no guidance about such details in Quick Config via asl-menu

referring individuals like me to the in-depth details of simpleusb.conf at the beginning of setting up a node seems backward (in the sense of reverse-ordered), given the time and attention given to creating sa818-menu and asl-menu to assist navigating the details and process of node configuration.

[Allan-N]

First off, I do want to thank you for the feedback. I will be pondering how/where to add some extra documentation and menu prompts/hints that can guide folks during the node setup process.

But, do keep in mind that we can't guess what time of device/radio/configuration you are trying to setup ahead and the settings vary. You are going to need to provide us (or update the configuration files) with the some of the details.

[jxmx]

I think adding more documentation about "picking your COS and CTCSS combination" would be an "Advanced Topic", if we were to spend time creating one at all. I the current strategy of asl-menu having the various "customization" options based on hardware type is cleaner and more user-friendly.

I'm transferring this ticket to asl3-manual.