FreeSwitch

One thing I feel I've learned in the world of systems administration is that although there is such a thing as good documentation, it's much like good food. It's only good right after you make it, or if you take very good care of it. Depending on how you made it, it might not keep very well. All this to say, FreeSWITCH's documentation left me lost and confused. The documentation seemed to me to be very fragmented, in that the valuable parts were scattered amongst various wiki articles and blog posts about how someone got FreeSWITCH working with specific hardware for specific purposes. It would have been nice to have seen an overview about some general conventions and a thorough description of what happens when you turn up FreeSWITCH out-of-the-box.

Compare this to Elastix (which is really just FreePBX + addons) where you can dig around in the GUI and get most of the configuration figured out fairly quickly. It's not an apt comparison or a very fair one, but it describes my predicament. I am attempting to use FusionPBX with FreeSWITCH but it seems like FusionPBX doesn't really take the bumps out of FreeSWITCH, rather just simplifies access to the configs.

In any case, here's what I have on FreeSWITCH so far:

• It's [very important]{style="text-decoration: underline;"} to understand that the XML configuration files are all interpolated into a [single file]{style="text-decoration: underline;"} at runtime. This file is located at <tt>/var/log/freeswitch/freeswitch.xml.fsxml</tt> on FreeBSD. I had problems with redundant tags and nesting that were happening because documentation and HOWTO snippets weren't explicit in how to specifically apply each example. (in other words Copy & Paste fail.)
• When configuring POTS hardware, it's important to note that DAHDI drivers instruct you to configure your analog ports with the signalling [you expect to see from the far endpoint]{style="text-decoration: underline;"} (on an FXO port, you would configure FXS signalling, as the CO side will use that signalling.) FreeTDM does the opposite -- you configure the port with the signalling [that the port will use]{style="text-decoration: underline;"}. (On and FXO port, you would configure FXO signalling.) I didn't see this in any of the documentation until after I found it mentioned in an e-mail to the freeswitch-users mailing list. I then found it on an FAQ/troubleshooting page. I lost two days to figuring this out. Mostly because I was doing this at 3am those days.
• Internally, FreeSWITCH seems to refer to endpoints using a nomenclature like this: module/instance/counter. For example, (FreeTDM/trunk/1) or (sofia/internal/1000\@example.com). There also seems to be an alternative nomenclature which causes some sort of internal resolver process to be used to identify the specific endpoint: "extension dialplan_type dialplan_context". For example "1000 XML default". Examples in the documentation didn't appear to explain this at all. I had lots of trouble getting my FreeTDM extensions to work properly, to an extent that I began to believe that I wouldn't be able to use my hardware under FreeBSD. It turned out that I was putting them in the configuration wrong. I had "FreeTDM/1/2" or "FreeTDM/exten/1/2" (meaning module/span_number/channel_number" or "module/span_name/span_number/channel_number" instead of the correct nomenclature above.

I'm sure there's more, but I'm more interested in getting this posted for now, and getting something more formalized up later. I've been working with FreeSwitch more over the past few days since I started writing this post on the 30th and things are coming along, slowly. I at least have the PSTN stuff fairly well down, and got voicemail and SIP registrations partially working as well. The next steps are to smooth eveything out and get some better logging and UI in place (e.g. error reports when lines are busy, etc.)