A remote access and remote shell program for communicating with Symbian devices running fshell. Muxcons is a more sophisticated alternative to the basic VT100-compatible terminal emulator (such as TeraTerm) that is usually used to communicate with fshell.
Muxcons supports a range of features that make it a powerful debugging tool. In addition to providing a platform-independant means of accessing an fshell prompt, it supports:
- file transfer and GUI remote file browser.
- remote screen sharing, including simulated pointer events.
- the ability to run programs on device from your PC's command-line (à la runonphone, but without needing TRK being installed)
- Drag-and-drop SIS file install.
- VT100 support, which can be used for talking to something other than fshell.
- Doesn't rely on any external setup or specific connection mechanism, other than the device must have fshell installed and listening on one of the protocols fshell supports (WIFI/GPRS, Bluetooth, USB, serial). In other words if you can connect to fshell with TeraTerm, you have everything required to use muxcons.
It is written in Qt, so runs (and has been tested on) Mac OS X, Windows and any reasonable flavour of linux. It is normally built as a stand-alone executable, but it can also be configured as a plug-in to Qt Creator. This allows fshell to be used over USB at the same time as debugging using CODA, without having to reconfigure one of the services to run over TCP instead of USB.
A demo video of muxcons in operation can be viewed here: http://muxcons.sourceforge.net/fshell-3.swf
- Make sure you have fshell version 4.1 or later installed on the device. See the fshell getting started guide for more information. (Update: version 4.2 is required if you're using the RnD build, or otherwise are signing for all capabilities)
- Download muxcons.exe from https://sourceforge.net/projects/muxcons/files/windows/
- If you want the latest version, or aren't running on windows, alternatively download the muxcons source from https://sourceforge.net/projects/muxcons/develop and build the Qt project <muxcons-dir>/src/muxcons.pro
- Start fshell on device, in the same way as described in the above Getting Started guide. Just instead of launching TeraTerm, launch muxcons.exe instead.
- You will see the connection dialog:
- Select the appropriate connection method that matches how you started fshell, and click OK. After a second or two (depending on the mechanism) you should see something like:
Building as a Qt Creator plugin
Building muxcons into Qt Creator is the only way of taking advantage of the CODA integration.
- Ensure you have the source for Qt Creator 2.2 or later from, for eg, Gitorious. Earlier versions lack the required CODA APIs.
- clone the repository to <creatorsrc>/src/plugins/fshell. Even though the project is called muxcons, the Qt Creator plugin is just called 'fshell'.
- Add the following to the bottom of <creatorsrc>/src/plugins/plugins.pro:
SUBDIRS += plugin_fshell plugin_fshell.subdir = fshell plugin_fshell.depends = plugin_coreplugin
- Build creator in the usual way, and launch it.
- You should now see an additional "fshell" submenu in the tools menu. If not, you may need to enable the plugin from Help->About plugins.
Additional requirements for using with CODA
As stated above, CODA connectivity is only available when muxcons is built as a Qt Creator plugin. Additionally, you need CODA 4.0.18 or later installed on the device and it must be the full non-TRK install, ie not the delta install.
Important note for people using RnD-signed fshell
There is a bug in fshell.004.1.N8.rnd.sis that means muxserver.exe (the device-side agent for muxcons) will not launch. Please update to version 4.2, ie fshell.004.2.N8.rnd.sis.
Mac OS X: It is necessary to install libusb separately before building muxcons. Mac OS X packages are available here. For Linux, the package libusb-dev is required.Update: libusb no longer needed.
- Linux: If muxcons UI doesn't show anything in the port selector, launch from the command-line using the syntax muxcons --port /dev/ttyACM1 to force port selection. Also see generic instructions on how to load drivers in the Qt docs here.
OS X: Bluetooth ports don't currently appear in the port selector, launch from the terminal using the command-line syntax muxcons.app/Contents/MacOS/muxcons --port /dev/tty.DEVICENAME-BluetoothSerial.Update: now fixed.
OS X: Some keyboard shortcuts don't work properly (I blame Qt...)Update: now fixed.
OS X: USB connection setup seems problematic unless you tick the "Connect via VT100" checkbox in the connection dialog, then after the fshell prompt has appeared, select "Mux this connection" from the "Console" menu.Update: VT100 handshake problems should now be fixed.
- Windows: If you're building against a Qt SDK (rather than having built Qt yourself), you may find you get compiler errors complaining about a missing header qwineventnotifier_p.h. I forgot that this header isn't included in the SDKs. As a temporary workaround you can download qwineventnotifier_p.h and save it into your SDK’s include\QtCore\private\ directory. Eg for me it goes into D:\QtSDK-1.1b\Desktop\Qt\4.7.2\mingw\include\QtCore\private\qwineventnotifier_p.h. I'll fix this properly in a future build.
General connection troubleshooting procedure
There are quite a few places where things can in theory go wrong, while setting up the initial connection. The following procedure helps narrow down where the problem lies:
Firstly, Try using basic USB connectivity (ie no bluetooth, no CODA) as this is the least problematic configuration.
- Unplug USB cable from device, plug back in (if necessary)
- Start fshell launcher app on device and press the USB button (or launch "fshell (USB)" if you don't have the launcher app in your version of fshell)
- It should say "Listening on ACM::1" on the device
- In muxcons/creator, in the "New connection" dialog, select the relevant port, and tick the "Connect via VT100" checkbox. Click ok.
- Hit return key if you see a blank window. Cursor should whiz around the window before displaying "c:\>".
- If you get this far, type "muxserver" and hit return.
- It should say "Muxserver v1.1 starting..."
- Select "Console->Mux this connection" from the main menu. The full muxcons UI should now appear.
- If this works, but it doesn't work if you unticked the checkbox in step (3), check you have the latest version of the muxcons source code.
If all else fails get in touch with tomsci on the #qt-symbian IRC channel.