More documentation has been filled out.

docs/source/isotp_decoder.rst

@@ -1,5 +1,19 @@
 ISO-TP Decoder
 ===============
 
+.
+
 .. image:: ./images/ISOTPDecoder.png
 
+Using the ISO-TP Decoder
+==========================
+
+This window scans the existing captured frames and newly captured frames to see if it can find CAN traffic that seems to conform to the ISO-TP standard. ISO-TP is used to send multi-frame messages and as an encoding standard that forms the base for other protocols such as UDS and ODBII (which is essentially itself a subset of UDS). 
+
+The main list at the top shows any messages that seem to conform to ISO-TP. There will very likely be messages here which aren't really ISO-TP. You can deselect IDs that seem to generate false positives so that they quit showing up in this list. As you can see in the picture only the ids 0x7E0 through 0x7EA were selected. These IDs are standard for UDS communication. If you want to immediately recalculate the results to exclude the deselected IDs then push "Interpret Previously Captured Frames" to regenerate the whole list. Otherwise the effect of changing the ID selections will only happen for newly captured frames. 
+
+The "Show incomplete and/or corrupted messages" checkbox will cause a lot of false positives and should only be used as a last resort if you suspect that you might have some dropped traffic. 
+
+"Use extended addressing" will cause the decoder to assume that extended addressing is being used on this CAN bus. Extended addressing adds an additional byte of addressing that is found in the data bytes of the frame. This isn't that commonly used but is used on some vehicles and ISO-TP decoding won't work properly unless this setting is correct. If you find that decoding seems to have failed you might try toggling this setting to see if it helps. Remember to click "Interpret Previously Captured Frames" to recalculate things for previously captured traffic.
+
+Once you have messages in the table at the top of the window you can click on a message to get more details about it in the text box in the lower left. In the picture you can see that 0x7F 0x10 0x12 was interpreted as a UDS error response saying that the ECU does not support the requested sub-function passed to the diagnostic session control service. This is much easier than trying to remember what all those bytes mean off the top of your head!

docs/source/playbackwindow.rst

@@ -1,6 +1,37 @@
 Playback Window
 ===============
 
+.
+
 .. image:: ./images/Playback.png
 
 
+Preparing Frames for Playback
+=============================
+
+The first order of business is to load some CAN frames that you'd like to play back onto a CAN bus. In the lower left is a section titled "Playback Sequence". It is so named because this playback interface can play a chain of different CAN captures very configurably. It consists of a list of captures to playback along with how many times to play each sequence item. For instance, you could play a file twice then go to the next, then play a third one four times. A playback item can either come from a file (Load File) or from the current list of captured frames on the main window (Load Captured Data). If you load the currently captured frames it truly means "currently". That is, if more traffic comes in it will not play that new traffic back. A snapshot is taken at the time you push the button. Each sequence item has its own list of ID filters. In this way you can send only some of the frame IDs from the capture and this list can be different for each file or capture you load. The list of ID filters can be saved and loaded to make the process faster in the future.
+
+Once you've set up a sequence of frames to playback you can also decide whether you'd like to loop that sequence forever or not. Up above the Playback Sequence and ID Filtering sections is the "Loop Sequence" checkbox.
+
+Playing Back Frames
+====================
+
+The playback window can send frames on a specific bus, all buses (be careful with that!) or "From File." Some file formats store which bus each frame came in on. Also, the main window stores that info. So, captures that stored the bus properly could be used to send frames out multiple buses always to the proper bus for the frame in question. But, if you load a capture without this info it will default to bus 0 so bear that in mind. 
+
+The next order of business is frame timing. There are two approaches possible here. If you click "Use original frame timing from captured frames" then frames will be sent out in approximately the same timing as they came in with. The word approximately is used because it is difficult to get 1ms timing precision on a desktop OS. Frames that come in rapidly might have a 2-3ms jitter. In practice this is almost always irrelevant. This setting is suitable for nearly all uses.
+
+Alternatively, it is also possible to send on a set schedule. With the "Use original" checkbox not checked you can set a playback speed in milliseconds and a burst rate. Burst means that it'll send that many frames every tick. So, if you have a burst of 5 and a timing of 10ms then every 10ms 5 frames will be sent. This mode can provide for a predictable number of frames per second and could be useful to test how quickly a device really requires traffic without faulting. But, it will potentially drastically alter the timing of frames compared to their timing when they were captured.
+
+The top of the window has a series of 6 icons all in a row:
+
+1. White Left Arrow - Play the last frame (just one frame)
+2. Pause sign - Pause playback
+3. Green Left Arrow - Play frames backward
+4. Blue Stop Button - Stop playback and return to the first frame in the first capture in the sequence
+5. Green Right Arrow - Play frames forward
+6. White Right Arrow - Play the next frame (just one frame)
+
+Playback Status
+================
+
+Below the number spinners for Playback Speed and Burst Rate is text that displays the currently playing sequence item along with the current frame within that capture.

docs/source/preferences.rst

@@ -1,6 +1,39 @@
 Preference Window
 =================
 
+.
+
 .. image:: ./images/Preferences.png
 
+Setting Preferences
+====================
 
+There are a variety of preferences that can be set in the program and persisted for future sessions.
+
+"Save/Restore window positions and sizes": If this is set then the size and placement of the various windows in this application will be saved when the program is closed and loaded when each window is brought back up in the future. This can be used to create your own preferred layout. If you'd rather things come up in their default state every time then you can uncheck this box.
+
+"Display values as hexadecimal": A lot of the time people who are doing CAN reverse engineering like to see values in hexadecimal (base 16) instead of the more familar decimal (base 10) system. Checking this box will cause most of the values in the application to show up in hex. This applies to CAN ids and data bytes. Unchecking this causes values to default to decimal instead. The reason for using hex is that each hex digit is 4 bits. Integers on a computer tend to be in multiples of 8 - 8, 16, 32, 64. So, hex digits have a direct mapping to the underlying binary. Decimal does not have this correspondance AT ALL. But, the choice is yours.
+
+"Require validation of GVRET connection": GVRET style devices run over a serial connection. Serial connections can be finicky sometimes and so the connection can be validated to prove that everything is really still operating and talking. There probably isn't any reason to turn this off except while debugging to see if it changes anything. Mostly just don't touch this.
+
+"Time Keeping": There are a variety of ways one could timestamp CAN frames as they come into the program. Selecting "Seconds" will cause the timestamp to be expressed as seconds since the frame list was last cleared. This tends to be an easy choice to work with. "Microseconds" will express the timestamp as millionths of a second since the last time the frame list was cleared. This is exactly like "Seconds" mode but without any decimal point. You might find this to be a bit hard to conceptualize. The last option is "System Clock" this will timestamp frames with the current system time when the frame came in. This is still very precise but now you'll get an absolute time stamp with the full date and time. The display of this mode can be changed by editing the "Time Format String" value. It defaults to an output that looks like "JAN-10 12:34:53.234" But you can set it to other values. Look here to find a reference for how you can create new format strings: http://doc.qt.io/qt-4.8/qdatetime.html#toString
+
+"Use filtered frames in sub-windows": The main window has a filtering interface where you can uncheck IDs to hide them. Ordinarily when you bring up one of the other windows it will still use the main unfiltered list. Sometimes you really do want to deal with the filtered list of frames even in the other windows. If this is checked then the other windows will see the filtered list and not the unfiltered actual list of frames that have been captured.
+
+"OpenGL Accelerated AntiAliased Graphing": A personal favorite of mine. Checking this will cause all of the graphs to use OpenGL 3D acceleration. Most modern machines have some form of 3D acceleration so this option should be OK to use. If you check this your graphs will look a lot better and on good hardware should also be faster. In the future other options are likely to be added to the graphing screen that will likely only be enabled if OpenGL mode is also enabled. Try enabling this and see if performance is still good. It's safe to leave it off if in doubt.
+
+"Autoscroll main frame window by default": If checked it will automatically check the relevant checkbox on the main screen when the program starts. This will cause the view to automatically scroll to the bottom by default. This is merely a convenience option if you'd prefer it to be the default.
+
+"Use timestamp mode by default": This is another convenience option. With this checked the Flow view will default to using time stamps on the graphing area instead of frame numbers.
+
+"Set Auto Reference by default": The Flow view can either use static referencing or dynamic referencing (see the Flow view documentation for more info). If you'd like to use dynamic referencing and automatically set the reference by default then check this option.
+
+"Loop by default": Set the playback window to default to looping infinitely by default.
+
+"Default playback speed (ms)": Set the default timing for playback
+
+"Default Sending Bus": Set a default for which bus to send frames on.
+
+"Auto expand all nodes": Both of the referenced windows have tree views that potentially have a large number of nodes. It's more neat not to expand them all by default but it also then requires more clicks if you have to expand them to view the information. So, you can set whether you'd like to expand them all by default or not.
+
+After changing preferences it is the best practice to close and reopen the application to ensure that all settings have taken effect.

docs/source/rangestate.rst

@@ -1,6 +1,23 @@
 Range State Window
 ===================
 
+.
+
 .. image:: ./images/RangeState.png
 
+Using the Range State Window
+============================
 
+The purpose of this window is to search for signals that look like they might be important. That's a rather nebulous description. But, the idea is to find signals that seem to vary somewhat coherently. As you can see in the picture in this help, the displayed signal has some jumps but they look like they might "be something." That's the idea. It *will* generate a lot of false positives but it will still provide some decent ideas for where to look for signals. It is up to you to figure out if the signal is anything important or anything you can use.
+
+To use it first set up the follow things:
+
+1. The ID Filter list - Deselect any IDs you don't want to search.
+2. Sensitivity - This is a subjective measurement. It doesn't affect the results a lot but changing this value back and forth can alter what the program thinks is a relevant signal.
+3. Min Signal Size - The smallest signal you want to search for. You can search for signals all of the way down to 1 bit if you're feeling adventurous.
+4. Max Signal Size - The largest signal you want to search for. The range between Min and Max changes how long the process will take. If you set Min to 8 and Max to 16 then it will search for signals with 8, 9, 10, 11, 12, 13, 14, 15, 16 bits. You will get duplicates as the same basic set of bits will be used for all of the sizes.
+5. Granularity - Sets the bit jump width. What is bit jump width? The number of bits that we move over each time we search for a new signal. If you have a granularity of 1 and a minimum signal width of 8 then it will search starting at bit 0 for an 8 bit message then starting at bit 1 then bit 2, etc. If you set a granularity of 8 then it will search for an 8 bit signal at bit 0 then search at bit 8, then 16, etc. So this sets how finely we will search for signals. A lot of times signals will be found on byte edges so a granularity of 8 will cause all signal searches to start on byte boundaries and this will be OK for many things. But, some designers are more devious and place signals at uneven boundaries. You might need finer granularity to find such signals.
+6. Signal Mode - For signals over 8 bits there is a choice to make. Signals over 8 bits can be either in big or little endian mode. This relates to whether bit 0 of a signal is the highest or lowest value. You can search for only big endian signals, only little endian, or try it both ways. *Usually* the developer of a CAN device will stick to one or the other but not always.
+7. Signed Mode - Likewise, any signal over 1 bit could be either unsigned or signed. Signed signals have their highest bit as 1 for negative numbers and 0 for positive numbers. You can search for only unsigned signals, only signed, or try it both ways. There really isn't any rhyme or reason for when a signal would be signed or unsigned. It could easily be both ways so unless you're sure it's probably safest to allow the program to try it both ways and you can pick which looks best.
+
+Once you've got it all set up click "Recalculate Candidate Signals." Be prepared to wait depending on what options you selected. Once it is done processing you'll get a list of candidates in the upper list labeled "Candidate Signals." Here you can see all of the signals it found. You get the ID, the starting bit (remember, bits start at 0 and go through 63), the length, and whether it was signed/unsigned and big/little endian. If you click on or otherwise select a signal in this list then a graphical view of it will appear in the graphing area beneath. You might try the arrow keys Up and Down to move through the list. You can even hold down the arrow key and let it rapidly scroll. As it scrolls through the signals you can look at the graph and stop when you see a signal that catches your eye. This is useful as you can have hundreds of candidates and it is tedious to view them explicitly one at a time.

docs/source/scriptingwindow.rst

@@ -1,6 +1,8 @@
 Scripting Interface
 ====================
 
+.
+
 .. image:: ./images/ScriptingWindow.png
 
-
+Woah boy, this one needs some explaining! This will be a very long help file indeed! Leaving this for last!

docs/source/signaleditor.rst

@@ -1,6 +1,44 @@
 DBC Signal Editor
 =================
 
+.
+
 .. image:: ./images/SignalEditor.png
 
+Defining and Editing Signals
+============================
 
+If you're starting from scratch or otherwise adding a signal then you will need to right click in the list box in the upper left of the window. From there select "Add a New Signal." This will create a randomly named signal that you can then edit.
+
+Otherwise, select a signal to edit. The details of it will fill out the rest of the window.
+
+On the right side you can rename the signal and you'll see that it is renamed in the list as well. 
+
+"Bit Length" - This sets how many bits the signal uses. Once you do this you'll see that that many bits are now highlighted in the 8x8 data grid above. The black bit is the "start" bit, green bits are the other bits in the signal. Gray bits are already used by another signal. You can still use them for the current signal too but doing so would be quite unusual. 
+
+"Byte Order" - The way that the green bits are filled out is changed by this checkbox. Checking it selects little endian mode whereas deselecting chooses big endian mode. This will have an effect on any signal that crosses byte boundaries. 
+
+"Type" can be:
+1. UNSIGNED INTEGER - No sign bit, only positive numbers
+2. SIGNED INTEGER - The top bit is used as a sign bit
+3. SINGLE PRECISION - Floating point number (should be a 16 bit signal)
+4. DOUBLE PRECISION - Floating point number (should be a 32 bit signal)
+5. STRING - Directly turn the CAN bytes into a string
+
+"Scale" is used to multiply the signal by the value to scale it appropriately
+
+"Bias" is added to each value generated by the signal to set it at a different bias point
+
+"Min Value" is purely informational. It is just a reference to anyone else viewing the DBC information as to what you expect the lowest value to be.
+
+"Max Value" is likely informational.
+
+"Units Name" is displayed after the value when you interpret a signal on the main frames list. For instance, you could set the units name to V so that a voltage value reads something like "12.34V" when it is displayed.
+
+"Receiving Node" This is informational at the moment. You can set which node (out of all your defined nodes) is the one that receives this signal. 
+
+"Multiplexing" This is a somewhat involved topic. DBC signals can be multiplexed which means that a given frame might have a range of data that is not always found in every frame. There is a key of sorts that specifies which piece of data this particular frame is sending. This leads to the concept of multiplexed signals and multiplexors. Multiplexors are the key. They provide a value that specifies which multiplexed data item is being sent. A multiplexed signal is then connected to a specific value of the multiplexor. Thus, a multiplexed signal requires that a multiplexor also exists. You would normally set all of this to "Not multiplexed" and skip all this complication. But, multiplexed signals do exist. In that case the message would have one multiplexor and one or more multiplexed signals. So, you'd set up a multiplexor for the message and then create additional multiplexed signals that are marked as "Multiplexed" and have filled out the "Multiplex Value" with something unique.
+
+"Comment" is purely informational.
+
+Signals that use either "UNSIGNED INTEGER" or "SIGNED INTEGER" as their type can define a Value Table. This table allows text strings to be substituted in place of integer values. For instance, if you know that a value of 0x10 means PARK then you can go to the next empty entry in the list, type 0x10 for the value and PARK for the Text. This will make the interpreted value read PARK any time the signal has a value of 0x10. This is used to make a more human friendly presentation. It should be noted that if the signal has a value not in the list then it will still be shown as it's integer value. But, known good values can be entered in the Value Table to make them easier to work with. 

docs/source/sniffer.rst

@@ -1,6 +1,18 @@
 Sniffer Window
 =================
 
+.
+
 .. image:: ./images/Sniffer.png
 
+Using the Sniffer Window
+=========================
+
+This window is essentially a graphical version of the linux can_utils. The general idea here is to display a list of frames such that you only see frames that are actively updating. If a given ID has not been seen in 4 seconds the ID portion will turn RED and then disappear from the list. In this way only frames that are updating are in the list. They are ordered by last update time. Bytes that have deincremented will be red and bytes that have incremented will be green. You can use the "Filters" area to mask away some IDs so that they never show up. This can help to declutter the list. 
+
+Notching and Unnotching
+========================
+
+Honestly, I don't know. It seems that notching means to store the current value of the data bytes for each frame and then use that notch data for the comparison for increment / deincrement to color the bytes. Unnotching would then be clearing that out so that it uses the previous value from the last time the frame ID was seen. But, don't quote me on that. This should be figured out definitively and corrected.
+
 

docs/source/uds_scanner.rst

@@ -1,6 +1,21 @@
 UDS Scan Window
 =================
 
+.
+
 .. image:: ./images/UDS_Scanner.png
 
+Purpose of the UDS Scan Window
+===============================
 
+This is essentially another CAN fuzzing window but a very special one. This window is meant to search for UDS compliant (or nearly compliant) nodes on the CAN bus. It can also be used to do a blanket search for services, sub functions, and data items on a known UDS node.
+
+
+Using the UDS Scan Window
+==========================
+
+UDS queries are sent out on the bus from "Starting ID" to "Ending ID". Usually UDS compliant ECUs will respond to 0x7E0 through 0x7E7 which is why those are the defaults. Some vehicles use UDS "like" protocols on other IDs. Usually UDS nodes reply with an ID 8 higher than the request ID. This is thus the default in the program. However, some nodes cheat and do not do this. It is quite common for responses to come from an address 16 higher instead. To deal with this situation there is a checkbox "Allow adaptive reply offset." If this is checked then replies will be accepted no matter what address they come from. Deselecting this will cause only replies of the proper offset to be accepted. The offset defaults to 8 but can be changed with the "Reply Offset" selector. Additionally, you can select which bus to scan and set how long you want to wait for replies. 
+
+You need to also set a type of scan to do. You can select more than one type.
+
+"Read By ID" - UDS allows one to read data from the ECU by an ID number. These are not defined anywhere and are custom to each ECU. But, you can use this to scan a range of IDs to see if you get a response to any of them.