[WIP] Kerminal: Terminal Interface to KSP via Telemachus

[SavinaRoja]

Introducing Kerminal: an open-source terminal interface to Kerbal Space Program (data tansmitted via Telemachus).

EDIT: Latest Demo

wwRjXRsmRN0xUCKko

This is a stand-alone program that acts as a client to Telemachus in order to live-stream data to your terminal. I've been working on the underlying technical aspects for a little while now and am pleased to say that the current code represents a working demo! Get the latest source here: https://github.com/SavinaRoja/Kerminal

The current demo UI looks absolutely atrocious (I'll put up a screenshot of it's current form); I haven't invested much at all in the UI design except for what I needed to prove the concept within my frameworks. So if the KSP community has any opinions on what they would like out of a terminal user interface, now is a great time for me to hear about it as I enter the planning stages of the UI. Think about all the great terminal program interfaces you've ever used, mutt, pine, irssi, vim, nano, etc., and tell me what you might envision for flying by telemetry!

One feature I am excited to add shortly is the ability to log the telemetry data to file at intervals as short as the KSP physics time-delta. This will enable a bunch of fun scientific data collection and processing; perhaps in the future Kerminal will even have (optional) integration with matplotlib, pandas, and other tools for data visualization and analysis. Since Kerminal relies on the Telemachus server and API, some limitations may be imposed over which I have no direct control, however a lot of stuff can be solved with good math.

I encourage people to try it out and I am happy to openly discuss any part of the project.

Some technical details:

Supports: Linux (of course), Mac (might need Xcode, not sure), Windows (with cygwin and some patience)

Requires: Python v3.4; Python libraries: npyscreen, autobahn, docopt; KSP Mods: Telemachus (optional, MechJeb for SmartASS integration)

No PyPI yet, just download the source and install to system or virtualenv. It will install a script "kerminal" so that you can start it with the command:

kerminal

see

kerminal --help

for the program's options and arguments.

License: GNU GPL v3

Source: https://github.com/SavinaRoja/Kerminal

Edited December 2, 2014 by SavinaRoja
Updating the latest demo

[SavinaRoja]

After some furious hacking, I have renovated the interface and bumped the version to 0.0.2!

The skeleton of the interface I currently envision is now partly in place. I'll try not to bore you with too much development details, instead I will describe what's new in the interface and a screenshot-assisted walkthrough.

The interface now has a "Kerminal Command Line" at the bottom, while the rest of the screen is consumed by the data field. Once you enter Kerminal, your user-input will either be sent to whatever is currently active in the data field or to the Kerminal Command Line; to move between the data field and the Kerminal Command Line you push TAB. This will allow users to interact with the data field's widgets to control the interface and the application underneath as well via commands.

Let's go ahead and move on to an introduction of the interface.

So if you've installed Kerminal correctly, you should be able to launch it by typing "kerminal" into your preferred terminal emulator. You should see a screen that looks something like this:

Here you can see the Kerminal Command Line down at the bottom, and the System Time up at the top should be live updating. So now I'm going to go ahead and connect to my server. I'll do this by first pushing TAB so that I can type my command, then type the command "connect <address>:<port>", shown below:

As you can see I redacted the address of my server for safey reasons! If you are running KSP on the same computer as Kerminal, the address should be "localhost". The default port for Telemachus is 8085, but change it if your configuration is different. After successfully connecting you should see the status bar at the top include the name of the Vessel currently transmitting for Telemachus like so:

So now that I have connected to Telemachus, let's see what commands Kerminal currently has to offer by entering the command "help". You should see this:

Since my window for Kerminal is too small to see the entire message, I push TAB and started moving down the page by pushing the DOWN ARROW. Once I scroll down to "- more -" the Kerminal window displays:

So now we know the commands that are currently available in Kerminal, they are (in alphabetical order): "demo", "disconnect", "help", "sub", "unsub", and "quit". We also know how they should used based on their descriptions, excellent. As you can see in the above image, I have entered "demo" into the Kerminal Command Line to see what I have currently coded as a way of demonstrating live updates in the data field; I push ENTER and see this:

It doesn't look beautiful by any means, but it's good enough for tonight and I'd like to go home and relax. I've learned a lot about how I can develop the interface on top of my ncurses library (the very wonderful npyscreen) and think I'm in good shape for refactoring and moving ahead. Finally you can see that I typed "quit" into the Kerminal Command Line which will close the program. I could have also used "disconnect" if I were planning on "connect"ing to another server.

As always, I welcome absolutely any feedback and am happy to help provide some technical advice to those that need it (I need testers!). Discussion is also welcome on GitHub.

Pro-tip for the python and tech savvy who might want to tinker with the source: Take advantage of logging with "kerminal -l <level>"! Put in your logging statements wherever you like; run "tail -f kerminal.log". Print statements are not useful when the screen is being used by the interface (logging is better anyway) and some exceptions may be swallowed so this is really the only good way to monitor the program as it runs.

[SavinaRoja]

Good news everyone! As of this morning before work I got the data logging facilities for Kerminal in place (mostly), and collected some data as a demonstration. I'll go ahead and talk about the data before walking you through how I collected the data in case you would like to try.

For the inaugural data logging test I recorded telemetry from the ascent of a probe at the KSC to an 80km equatorial orbit around Kerbin. The data was set to record at 5 Hz (0.2 second intervals) and saved as a CSV (with a semicolon as the separating character). I logged everything I possibly could using Telemachus from just before liftoff to when I reached orbit about 4.5 minutes later. The data file was 1.4M. You can get a copy of the data here: https://dl.dropboxusercontent.com/u/6424897/ascent0-kerminal.csv I also shared a Google Docs version of it on IRC a little while ago and some people contributed some nice charts, feel free to do the same: https://docs.google.com/spreadsheets/d/18Y2vN1gf7oPoBhTvRO_AHSQOuOGOuozFisVOp3UpRgw/edit?usp=sharing

Here begins the instructions:

I first want to say that while I am very happy that Kerminal can finally DO something, it is hella unfinished and unless you follow closely, it might not work. I unfortunately can't take any pictures of the interface right now as I am aware from my normal computer, but words should suffice.

1. Start by connecting to your Telemachus server using "connect <your-address> <your-port>". Because I was connecting to a computer on my local network, for me this happened to be "connect 192.168.1.4 8085".
   
2. Once you have verified that your connection is made, you can show the logging status using "log status". Since you have just started your connection and haven't turned logging on, it should show that logging is inactive and that you are only logging "t.universalTime", "v.missionTime", and "sys.time". The order in which these read is also the order in which they will appear in your log.
   
3. At this point, I set the Telemachus communication rate to 5Hz by the following "send {"rate":200}" (use or modify as desired).
   
4. To enable the logging of everything enter the following two commands: "log all", "sub --all". Eventually, the user will never have to worry about managing the background detail of Telemachus subscriptions, but you do for now...
   
5. If you would like to change the name of the log file, you are free to do so with "log file <desired-filename>", otherwise the default will be "kerminaldata.csv".
   
6. Enable the logging with "log on" and disable it when you are done with "log off". Since I was starting logging just before lift off I used the following command to stage (and thus initiate ascent) right after the logging was enabled: "log on; send{"run":["f.stage"]}"
   

That's it for now, let me know if you have any ideas, questions, bugs to report.

[SavinaRoja]

Here are some of my thoughts about where I will go with this in the near future:

1. Refactoring of the command interface and its interaction with the UI.
   
2. Implement automated control of Telemachus subscriptions; nobody should have to do this. You should only get the data you ask for from logging or from widgets in the data frame.
   
3. Now that I have a nice summary of the kinds of data which are relevant to ascents(/descents?) I shall work on creating a telemetry interface "page" for ascents; this will help establish a more mature widget interface in the data frame.
   
4. I would like to create a demo of a text file editor embedded in Kerminal, so that one could read/write/edit/manage kOS scripts. I would really like to somehow forge a collaboration between Kerminal, Telemachus, and kOS so that you could upload and activate kOS remotely.
   

[MSD]

Nice work!

[artwhaley]

This is fantastic! Are you using the websocket api from Telemachus, or the simple http request one?

[SavinaRoja]

This is fantastic! Are you using the websocket api from Telemachus, or the simple http request one?

I am using the websocket API. There's some prior work out there that uses http requests, but the websocket approach seems more straightforward for a non-browser application.

[Dunbaratu]

I would like to create a demo of a text file editor embedded in Kerminal, so that one could read/write/edit/manage kOS scripts. I would really like to somehow forge a collaboration between Kerminal, Telemachus, and kOS so that you could upload and activate kOS remotely.

A couple months ago we (current kOS devs who've taken over from the original Nivekk) had a video chat in which the topic of the kOS terminal window and it's strange implementation came up. One complaint had been that the current system is utterly un-remotable. It can't really work with terminal emulators on telnet or ssh because of the simple fact that the terminal "i/o" is implemented in a totally non-i/o way. It doesn't read a stream of keypresses, for example. It reacts to GUI keypress events. It doesn't use any sort of escape sequences to manipulate the screen. It just stuffs values directly into the screen's framebuffer when you do something like "print x at (30,10)." It also manages commandline editing with a sort of second framebuffer superimposed on top of the normal one.

We'd been talking about a pie-in-the-sky plan to gut the innards of the system and replace it with a true terminal emulation - a layer that traps keypress gui events going to the terminal and feeds them into a Stream object that the terminal reads from, plus a layer that forces all interaction to go through a Stream that has special control codes for terminal manipulation. That way the input/output Streams could be redirected to hook up with an internet socket and make external terminal programs work over something like ssh or telnet. As a bonus, since we'd be making up the terminal manipulation codes ourselves from scratch, there's no reason we couldn't use codes from an already well known terminal like VT100 or ANSI and therefore allow any one of the plethora of terminal emulators that uses that standard work with kOS.

One new potential developer expressed an interest in getting started on part of this but we never heard anything since from him so I don't think that's going anywhere right now.

There are a LOT of issues to deal with in kOS and at the moment only two people actively putting major amounts of time into it, so we have to do a lot of triage and stop a lot of pie-in-the-sky "wouldn't it be cool if...." projects while more important things are worked on. When dealing with a mod that is essentially an entire programming language and an entire virtual computer, the number of *potential* features is endless and just about anything that's NP-complete (*) is technically possible. So it would be very easy to get stuck trying to implement 100 different things and only getting each one 1% done.

So sadly the desire to have it use a stream-able i/o for internet use, while a valid concern, has fallen down below that cutoff mark.

But if you're offering to research the feature yourself and make pull requests to the kOS code to implement it..... I for one would be delighted. Or if you just want to talk about how you see potentially the bridge between kOS and your terminal working if it did something else a bit different from what I've described, that would be cool too.

(*) - I originally said "anything is technically possible" until I remembered a recent feature proposal that would have required the mod to know if a script has an infinite loop...

Edited September 28, 2014 by Steven Mading

[SavinaRoja]

This has been a long time in the making, but the time was not spent idle. I was hitting some limitations with npyscreen that were preventing me from providing some of the features that I wanted most. So I decided to rebuild it (mostly) from scratch and thus npyscreen2 was born. As a new library it is a bit sparse in terms of features but it gives me significantly more flexibility and safety in development, Kerminal's design should benefit greatly. Enough gabbing about that, let's talk about what is new in Kerminal.

I made a quick demo video of Kerminal in action, you may watch it here (text might be a little blurry unless in HD):

Kerminal now has a dynamically resizing telemetry window that will try to pack the displayed widgets into the available space. The current packing algorithm isn't too elaborate, I'll probably implement something a bit more powerful in the future. The whole interface in general is built to be safely resizable (one of the strengths of npyscreen2), so this is a major break from other statically sized interfaces. In the future I'd like for users to be able to dynamically modify/create/save special telemetry loadouts rather than have a static interface.

When executing a command which yields text output, e.g. "help", Kerminal goes into a text display mode in which you can scroll (arrow-up/arrow-down/page-up/page-down) if the text is too long to be seen all at once. In the future there may also be an editable text mode so that Kerminal may be used as a basic text editor (think scripts and automation). Of course, loading text files produced in other text editors will definitely be available.

Partial coverage of the Telemachus API allows the use of this Kerminal version for some basic telemetry, but does not make it easy to send commands to KSP. That's also on the future work agenda.

Feel free to ask any questions or make suggestions for improvements. Once again I'll note that the source for Kerminal is located here on GitHub: https://github.com/SavinaRoja/Kerminal and you may feel free to open issues there as well as post here in the forums.

Also, Kerminal requires Python 3.4.0 or greater, you won't be able to install it or use it with a lesser version. Because npyscreen2 is not yet up on PyPI (and is thus not pip-able), you will need to manually download and install a copy of npyscreen2 from it's source on GitHub here:https://github.com/SavinaRoja/npyscreen2

For those unfamiliar with installing python applications at this level, I have found this to be a pretty good and thorough guide.

Edited November 15, 2014 by SavinaRoja

[SavinaRoja]

Not much time I'm afraid to compose a lengthy post, but I wanted to note that I've increased the version of Kerminal in honor of the addition of gauges in the Resources field. The Resources element will dynamically resize itself and show/hide resources according to whether or not your vehicle has any capacity for that resource type.

Because this is something I appear to be doing now, here's a new demo video:

[SavinaRoja]

Rich put up a list of some alternative (to the standard browser-based one) Telemachus interfaces on the GitHub wiki for Telemachus, which are all really cool and definitely worth checking out if you have not seen them.

I love the creativity people have shown, and I definitely draw inspiration from the work of others as I am putting Kerminal together. I wanted to call attention to a few other projects I've encountered along the way which are not (at least currently) listed on the link above.

Compilation thread for custom controller hardware : Not directly relevant to Telemachus for many, but highly interesting to see how people create control and interface systems.

Control Panel by KK4TEE : Special mention for integrating custom hardware with Telemachus

RemoteView (terminated) by Deedo : Hybrid graphic and text interface to show orbits through Telemachus. Screenshot of interface

TeleKerbin (hiatus?) by eyecikjou567 : C# terminal interface native to Windows

Flight Overview(?) project by mjukis (and others?) : I enjoy their curated, info-dense interface system, though I went for dynamic over static (pros and cons for each).

Nausicaa by fixermark : An interface for Google Glass. I am in no position to try it myself, but it's intriguing

[SavinaRoja]

This is an overview guide to install and use Kerminal in Windows:

1. If you don't already have Python 3.4, download and install it from here: https://www.python.org/downloads/release/python-342/
   
2. Download and install the unofficial curses binary library for Python 3.4 from here: http://www.lfd.uci.edu/~gohlke/pythonlibs/#curses
   
3. Download the npyscreen2 source code from GitHub and unzip: https://github.com/SavinaRoja/npyscreen2/archive/master.zip
   
4. Download the Kerminal source code from GitHub and unzip: https://github.com/SavinaRoja/Kerminal/archive/master.zip
   
5. Open the command prompt (cmd.exe) and install both the npsycreen2 and Kerminal packages by executing their setup.py files with a command like "C:\Python34\python.exe setup.py install"
   

A script called "kerminal" will then be put in C:\Python34\Scripts which one will execute with C:\Python34\python.exe ("C:\Python34\python.exe kerminal") from the command prompt. This will start the Kerminal.

Edited November 30, 2014 by SavinaRoja

[SavinaRoja]

Although I silently added support for the Telemachus FlyByWire system via the "fbw" command a short while ago, controlling your craft in Kerminal has been very deficient (FlyByWire is not really suited for use as a command-line interface, so I'll have to whip up a nice Widget to really take advantage of that). This situation is greatly improved as the 0.1.2 version introduces the "sa" command for using the MechJeb SmartASS commands available in Telemachus.

This is what you will see if you type "help sa" into the Kerminal Command Line:

sa

 Utilize MechJeb SmartASS to lock orientation vector. Disable with the "off"
 subcommand.


 Usage:
   sa (off | node | prograde | retrograde | normalplus | normalminus |
       radialplus | radialminus | targetplus | targetminus | relativeplus |
       relativeminus | parallelplus | parallelminus)
   sa surface <heading> <pitch> <roll>


 Standard Commands (no target required):
   off            Disable SmartASS.
   node           Orient along next node.
   prograde       Orient along orbital velocity prograde.
   retrograde     Orient along orbital velocity retrograde.
   normalplus     Orient along orbital velocity normal plus.
   normalminus    Orient along orbital velocity normal minus.
   radialplus     Orient along the orbital velocity radial plus.
   radialminus    Orient along the orbital velocity radial minus.
   surface <heading> <pitch> <roll>    Set orientation based on surface angles.


 Targeted Commands (target required):
   targetplus       Orient towards the target.
   targetminus      Orient away from the target.
   relativeplus     Orient along relative velocity.
   relativeminus    Orient against relative velocity.
   parallelplus     Orient along parallel velocity component.
   parallelminus    Orient against parallel velocity component.


 Comments:
   When in a prograde orbit, "normalplus" corresponds to "up"/"north" while
   "normalminus" corresponds to "down"/"south". This is reversed in a retrograde
   orbit.


   Conversely, "radialplus" will correspond to "away from orbited body" in both
   prograde and retrograde orbits and "radialminus" will correspond to "towards
   orbited body".


   Targeted Commands will not work unless there is a target selected. Selecting
   a target with Telemachus is unfortunately impossible at this time and must be
   done manually in KSP. In the future, Kerminal may warn about the use of these
   commands while nothing is targeted.

This update also introduces proof-of-concept for a system of enabling per-command callbacks, in which Kerminal expects a response from Telemachus to inform it whether the command was un/successful. This is especially useful here to inform the user if there is a MechJeb part available on the craft, and may be applied generally to many commands to know if they failed (due to one of: game paused, no electric charge, antenna inactive, antenna out of reach).

Edited to add:

Thanks for the helpful discussion in IRC, especially suggestions and tips from Red5, Mjolnir, GreeningGalaxy, and others.

Edited December 2, 2014 by SavinaRoja
Gratitude

[SavinaRoja]

Made a demo for 0.1.2 wherein I send a spaceplane into orbit using telemetry and the new SmartASS commands. A bit longer than my other videos at ~4 minutes, any and all feedback is appreciated.

wwRjXRsmRN0xUCKko

[Yski]

Nice, definitely keeping an eye on this.

[chaoservices]

Prop SavinaRoja,

You've reduced me to a gibbering fanboy, and I've rewrote this post 3 times.

This is fantastic! This is 90% of how I want to play KSP! Please keep up the good work. You are inspiring!

Lets see if I can do that other 10% I want to see.

[postalbyke]

Yes! I've been looking for a (hopefully) lighter-weight approach to kerbalizing my RPi, so I'll shoot questions while I'm building python 3.4 thereupon.

1) I have an idea regarding rudimentary communication between kOS and telemachus, which involves the use of action groups as bits. Is there a way (easy or no) to activate/deactivate action groups and receive the status of action groups through your mod? (if you're interested in kOS/telemachus interaction, I seem to be the first on this bus).

2) Can one interact with your mod (and thus telemachus) by python scripting? (pulling variables out of Kerminal, moving control surfaces directly, etc)?

edit: Just like chaosservices (sp?), I'm freakin' pumped about this mod!

Thank you so much for your service to the community!

[Shurikeeen]

When I connect to the Telemachus address, gray text starts flashing over the window. What might cause this? Im using Linux, I use newest Telemachus and .90.

- - - Updated - - -

All the gauges say n/a.

Edited May 26, 2015 by Shurikeeen

[Rushin_Russian01]

Hi there! I'm trying to get this installed on Ubuntu 14.04, and I'm having some problems getting it up and running. Basically when I try to run kerminal, I get a traceback ending with

NameError: name '_formatter' is not defined

I'm not familiar with python at all, so I could have made a mistake somewhere along the way. I was also having problems before this with the _curses module not being found, but I was able to get that sorted out (I think) I'm not really sure what would be helpful here, so just let me know and I'll get it for you!

[Tandoori]

Evidently, the most recent version of Telemachus broke support for Kerminal. Sad, because I was excited to try it with Cool Retro Terminal.

EDIT: I got it working using an older version of telemachus. I am very happy with the results, despite some glitches (camera keeps zooming/resetting, some of the data seems off).

EDIT AGAIN: Rich fixed the issue with the previous upload. The latest version should work now.

Edited June 20, 2015 by Tandoori

[fatjoe2015]

I have no idea how to get this to work :S

Would someone be so kind and make video Tutorial ? would be awesome

Tank you

[2lean4]

i've followed the windows installation instructions but when i run the script i get "importerror: no module named 'termios'"

[Desert-Cow]

How where you able to resolve the _curses module not being found? Currently trying to run Kerminal on Pi (running python 3.4) but stuck on this error.

ImportError: No module named '_curses'

[Tandoori]

You need to download the Curses module (which is basically a simple terminal GUI interface), and then recompile and install Python with that module included. There are a number of tutorials available online, Google one for your distro.

[Makarismos]

I have no idea how to get this to work :S

Would someone be so kind and make video Tutorial ? would be awesome

Tank you

Yeah Im with you. Just having an atempt now, so if I have any luck I will post here how I got on.. I get the impression that because this is a part time hobby thing by programming dudes, its all a bit under the bonnet and a bit tricky if you hit a problem.

To make things interesting, I am running a recently updated windows 10 machine, but we will see how this works... In the meatime, if anyone actuall knows how to do this you can help us boh

Maka