From 79fc69040dca79df45237a7562403ba4cc6656c0 Mon Sep 17 00:00:00 2001 From: Collin Kidder Date: Sun, 27 Sep 2015 23:22:33 -0400 Subject: [PATCH] Wrote documentation for the custom sender window. Added a graph for this new documentation. --- docs/source/customsender.rst | 113 +++++++++++++++++++++++++++- docs/source/images/CustomSender.png | Bin 0 -> 9170 bytes 2 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 docs/source/images/CustomSender.png diff --git a/docs/source/customsender.rst b/docs/source/customsender.rst index bb18734..5962254 100644 --- a/docs/source/customsender.rst +++ b/docs/source/customsender.rst @@ -1,5 +1,116 @@ Custom Sender Window ==================== -Let's send some custom frames! +**SavvyCAN Custom Frame Sender** + +.. image:: ./images/CustomSender.png + + +General Overview +================= + +This window allows you to create custom frames that will be sent out on one of the can buses. The uses are endless. +It can be used to generate valid traffic to control connected hardware. It can be used to test out various ideas +you might have for now to interact with other devices. It can replay frames from one bus into the other bus but with +modifications. + + +Layout of the View +=================== + +This screen is laid out as a data grid. + +* The first field is "En" which stands for Enabled. If the checkbox is checked + then this line will be active. +* The second field is "Bus" and sets which bus to use for sending. +* The third field is "ID" and is the ID to use for sending. It can be specified in hex or decimal formats. +* The fourth field is "Len" and sets the number of data bytes for this frame. +* The fifth field is "Data" and specifies what values will be sent for the next frame. These values can be + automatically updated by the modifiers which will be covered later on. +* The sixth field is "Trigger" which specifies when this frame will be sent. Proper syntax for triggers is + covered later. +* The seventh field is "Modifications" which specifies how the data bytes for this frame will be changed for + the next frame sent. Full syntax for this is covered later on. +* The final field is "Count" and is automatically filled out with the number of frames that have been sent as + a result of this line. + + +Writing Trigger Rules +======================= + +It should first be noted that each line can contain multiple triggers. Each trigger is separated by a comma ','. + +Triggers are allowed to have one or more conditions. Each condition contained within a single trigger is separated +by a space ' '. + +The program implments the following conditions: + +* id - Set the trigger to activate when a frame with the given ID is received. The syntax is 'id' + followed by the numeric ID you want to match. Example: 'id0x200' +* ms - Set the number of milliseconds to wait. This condition acts differently depending on whether + you have set ID matching as well. If so then ms will cause a delay of the requested number of milliseconds + after receiving a frame with the ID. If not, the trigger will constantly fire every time the requested number + of milliseconds have elapsed. The syntax is the number of desired milliseconds followed by 'ms'. For example: + '40ms'. +* x - Only allow this trigger to fire a set number of times. The syntax is the number of times you want the trigger + to fire followed by 'x'. For example: '100x'. +* bus - Only trigger when a frame with the given ID comes in on the specified bus. Otherwise the triggering frame + could come from either bus. The syntax is 'bus' followed by either '0' or '1'. For example: 'bus0' + +Now, a full example of a trigger line: "id0x200 5ms 10x bus0,1000ms" This trigger means: Trigger when a frame with ID 0x200 comes +in on bus 0. Wait 5 milliseconds before sending and only allow this to happen at most 10 times. Also, always trigger every +1 second and never stop doing this. + + +Writing Modifications +======================= + +As with the triggers, you can have multiple modifications per line; each of which is separated by a comma ','. + +Modifications always start with a data byte to modify The syntax is 'D' or 'd' followed by a number 0 through 7. +For example: 'D4'. This is then always followed by an equal sign '='. Thereafter there is a string of operands and +operations. + +Operands have a special syntax. Each operand can have multiple sections separated by colons ':'. + +* D - A data byte. Specifies which data byte 0 - 7 from the given frame to use for this operation. If specified + on its own it will reference the data in the "Data" section of this line. The syntax is 'd' or 'D' followed + by a number 0 - 7. Example: 'D3'. +* ID - Instead of grabbing data from this line's data bytes grab it from the last frame received with the given ID. + Syntax: 'ID' followed by a colon ':' followed by the ID to match against. Example: 'ID:0x200' +* BUS - Restrict which bus the frame used for grabbing the data bytes can come in on. Syntax: 'BUS' followed by + a colon ':' followed by 0 or 1 to specify which bus to use. Example: 'BUS:0' +* - Instead of using a data byte from somewhere you can instead use a numeric literal. The syntax is + the same as any number - either a series of numbers or 0x followed by a series of numbers and A - F to specify + a hexadecimal number. Example: 0x10. + +A few full examples of operands: + +* "bus:0:id:0x120:D3" = Grab byte 3 from the last frame with ID 0x120 that came in on bus 0. +* "0x200" = Use the numeric value 0x200 directly. +* "id:0x200:D7" = Grab byte 7 from the last frame received with ID 0x200. + +Each operand is usually followed by an operation and then a second operand. If no operation or second operand is found that +is also OK. Thus a modifier can be as simple as "D0 = D1" if you choose. Operands can also be directly chained such that the +output of the last operation is used as the left hand operand for the next operation. This will be shown later on. + +Modifiers can use the following operations: + +* \+ - Add the two operands together. Example: "D1 + D2" +* \- - Subtract the second operand from the first operand. Example: "D1 - D2" +* \* - Multiply the two operands together. Example: "D1 * D2" +* \/ - Divide the first operand by the second operand. Example: "D1 / D2" +* \& - Do the bitfield operation AND on the two operands. Example: D1 & 0x20 +* \| - Do the bitfield operation OR on the two operands. Example: D1 | 0x10 +* \^ - Do the bitfield operation XOR on the two operands. Example: D1 ^ 0xD2 + +Putting all of that together yields complete modifiers. For simplicity all operations +are done left to right. There is no special order of operations like in normal mathematics. + +Here are a few examples: + +* "D0=D0+1" = Take the value in D0 within this line's data bytes, add 1, and store it back in D0. +* "D1=ID:0x200:D3+ID:0x200:D4&0xF0" = Grab byte 3 from the most recently received frame with ID 0x200 and add it + to byte 4 from the same received frame. AND this new value with 0xF0 and finally store it in D1 of the data bytes for this line. +* "D2=D4 * 10 + D3 & 0x3F" = Multiply byte 4 by 10, add the new value to byte 3, AND the resulting value by 0x3F and store it in byte 2. diff --git a/docs/source/images/CustomSender.png b/docs/source/images/CustomSender.png new file mode 100644 index 0000000000000000000000000000000000000000..eb59c30bdb3187e99357e3a83ec87ee394d57281 GIT binary patch literal 9170 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