From 93a7796023b680abee16081b17d1b3eb2f70d9fb Mon Sep 17 00:00:00 2001
From: Luke Shumaker <lukeshu@lukeshu.com>
Date: Tue, 14 Mar 2017 16:45:27 -0400
Subject: README

---
 README.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/README.md b/README.md
index 17db575..1114f7a 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,113 @@
+# dslog-reader
+
+`dslog-reader` is an alternative viewer for the (binary) `.dslog`,
+`.dsevents`, and `.pdplog` files produced by the official FRC Driver
+Station provided in the [FRC Update Suite][].
+
+While the [QDriverStation][] is wonderful for removing the need for
+Windows (or Wine--I have verified that the FRC Update Suite 2017.2.0
+log reader does work in wine 2.3) on anything but your competition
+driver station computer, it doesn't help you answer "what the hell
+happened during that match!?"  You could look at the log files on the
+driver station computer itself, but the drive team will be taking it
+in a few minutes for the next match.
+
+# Supported formats
+
+|           | 0   | 1   | 2   | 3   |
+|-----------+-----+-----+-----+-----|
+| .dslog    | yes | yes | no  | yes |
+| .dsevents | no  | yes | yes | yes |
+| .pdplog   | no  | no  | N/A | N/A |
+
+Regarding when each version was in use:
+
+|      | dslog | dsevents | pdplog |
+|------+-------+----------+--------|
+| 2009 |       |          |        |
+| 2010 |       |          |        |
+| 2011 |       |          |        |
+| 2012 |     0 |        0 |        |
+| 2013 |       |          |        |
+| 2014 |     1 |        1 |        |
+| 2015 |     2 |        2 | 1      |
+| 2016 |     3 |        3 | -      |
+| 2017 |     3 |        3 | -      |
+
+I don't know that the dslog/dsevents 2->3 transition happened between
+seasons, it could have happened during the 2014 season.  Blanks are
+unknowns, "-" means not-in-use.
+
+# TODO
+
+ 1. [ ] real user interface
+ 2. [ ] figure out how to robustly handle dsevents that have been
+        munged together into one event.
+ 3. [ ] parse tagged dsevents data (blocked by #2).
+ 4. [ ] figure out how to parse `.pdplog` version 0
+    - [ ] find some `.pdplog` version 0 files to test with
+ 5. [ ] figure out how to parse `.pdplog` version 1
+ 6. [ ] figure out how to parse `.dslog` version 2
+
+# References
+
+Most of the details on file formats came from posts by National
+Instruments employee Greg McKaskle on Chief Delphi:
 https://www.chiefdelphi.com/forums/showthread.php?t=104689
+
+# Alternatives
+
+## FRC Update Suite
+
+Obviously, one could run the National Instruments' "Driver Station Log
+File Viewer" (`C:\Program Files\FRC Driver
+Station\DS_LogFileViewer.exe`) that is distributed in the
+[FRC Update Suite][].
+
+Downsides:
+ - it is not Free Softare
+ - the source is not available
+ - Windows-only, though I did get it to work in Wine.
+ - no CSV export... honestly, just limited functionality, and since no
+   source code, good luck doing what you want.
+ - Almost unusable on small screens like my x60.
+
+I got the version from FRC Update Suite 2017.2.0 working with Wine on
+Parabola GNU/Linux-libre (a derivative of Arch Linux).  The tricky
+part was the dependency on .NET 4.6.1.
+
+Packages installed:
+ - wine (2.3)
+ - winetricks (20170207, imported from Arch Linux)
+ - lib32-gnutls
+ - samba (for the ntlm_auth program)
+
+Instructions:
+
+ - Run `WINEARCH=win32 winetricks --unattended dotnet461`
+   It wouldn't work with a 64-bit Wine directory, and one of the
+   installers fails unless run --unattended.
+ - Run `wine setup.exe` on the `setup.exe` file from the
+   FRCUpdateSuite `.zip` file.
+ - Lauch the program with `wine '.wine/dosdevices/c:/Program Files/FRC Driver Station/DS_LogFileViewer.exe'`
+
+## DSLOG-Reader
+
+FRC Team 548 (the Robostangs) also wrote a Free Software alternative
+to the National Instruments log viewer, [DSLOG-Reader][].
+
+Downsides:
+ - Windows-only.  It is written in C#; and while I could get it to
+   compile with Mono, much of of the plotting functionionality that it
+   uses is implemented by Mono as
+   [`throw new NotImplementedException ();`][mono source].
+ - only parses version 3 of the log format
+ - no parsing of tagged dsevents data
+
+While I did not use any of the code, I did find referencing it to be
+very helpful when writing my implementation,
+
+[FRC Update Suite]: http://www.ni.com/download/first-robotics-software-2015/5112/en/
+[QDriverStation]: https://github.com/frc-utilities/QDriverStation
+[DSLOG-Reader]: https://github.com/orangelight/DSLOG-Reader
+[mono source]: https://github.com/mono/mono/blob/master/mcs/class/System.Windows.Forms.DataVisualization/System.Windows.Forms.DataVisualization.Charting/Chart.cs
-- 
cgit v1.2.3