Adding on to Frontline Decoders
In some cases, you may wish to utilize the power of Frontline`s existing decoders but with some modifications or additions of your own. In order to meet this need, you may either modify or add on to existing tables within Frontline`s decoders. Before undertaking such an endeavor, we strongly suggest that you contact Frontline technical support for feasibility and proper syntax. Decoderscript provides two separate keywords to append and/or overwrite tables that exist in the Frontline decoders: APPENDS_ONLY and APPENDS_AND_OVERWRITES. In order to work properly, these must go into a file named “Custom Attributes <affected protocol/profile>.dh,” and this file needs to go into your “My Decoders” directory.
Consider the case in which you wish to add a new PSM to the L2CAP decoder for your own proprietary protocol. In your “My Decoders” directory you would need a file named “Custom Attributes L2CAP.dh,” and within your file the syntax for adding your PSM to Frontline`s table would be as follows:
TABLE myTable APPENDS_ONLY psms
{0x0020 “My Protocol” “MP” 0 myMethod}
{0x0021 “My Protocol1” }
ENDTABLE
GROUP myMethod
{
FIELD myField (Fixed 1 byte)…
…
}
Please note that in the case of table branching above, you must have a Group or Field named myMethod defined in your .dh file as you would normally with any branching statements from a table; however, unlike a normal decoder file, your custom attributes file does not need any additional syntax such as decoder id, DECODE and END_MAIN_PATH statements, or any other control statements. All that are necessary are TABLE with APPEND or APPEND_AND_OVERWRITE statements and any necessary field or group statements.
Assuming that you have decoders, decoder ids, and personality rules for your two protocols above as described in Chapter 4: Putting It All Together, the table append shown above will now cause the protocol stack to automatically traverse to your protocols and use your custom decoders when relevant. However, this will only append unique entries to an existing table. If you attempt to append a table entry with a duplicate value to an existing table, the CPAS software will notify you that your table entry will be ignored.
In some cases, you may wish to overwrite some of Frontline`s existing table entries. Take for example the Low Energy ATT decoder -- in Frontline`s table for GATT_UUIDs (GATT_UUIDS.tbl) , there exists the following table entry:
{ 0x2A19 "Battery Level" "Battery Level" 0 BatteryCharacteristic}
This table entry then branches to the group BatteryCharacteristic which simply decodes the byte value to a decimal value between 0 and 100 per the spec. Suppose, however, that you want to throw an error when the battery level drops below 25 as well as retrieving some other stored value at this time. Your syntax would look like this:
TABLE myTable APPENDS_AND_OVERWRITES GATT_UUIDs
{ 0x2A19 "My Battery Level" "My Battery Level" 0 MyBatteryCharacteristic}
ENDTABLE
GROUP MyBatteryCharacteristic
{
FIELD myblPercent (Fixed 1) (decimal) "Battery Level" VERIFY (FieldIs GreaterThan 25) NO_MOVE
FIELD someField (Fixed 0) RETRIEVE (IntraFrameField somefield) (Decimal) “Some field” NO_MOVE
}
You may notice that the original table name is GATT_UUIDS.tbl, but the table being modified here is GATT_UUIDs and not GATT_UUIDS.tbl. Why is that? Because within the ATT decoder, there is a table named GATT_UUIDs that contains all the values in GATT_UUIDS.tbl and is what the decoder actually uses when decoding. Another reason is scope – if you modify the original GATT_UUIDS.tbl file and not the local copy, then every decoder that uses this file will be affected by your change, not just the decoder that you want affected. Because of this syntax sensitivity, it is mandatory to contact Frontline technical support in order to obtain the proper table name to overwrite or append to.
Please note in the above example that there is a new, unique group name and field name for battery characteristics. Any field or group name in your custom attributes file that is also in Frontline`s existing decoder will cause decoder loading errors, in which case you simply need to rename your group or field in question and reload the decoders.
Special caution should be taken when overwriting table entries. In the above example, if there are any groups or fields in the Frontline decoder that rely upon the BatteryCharacteristics group, they will decode improperly because that group will no longer contain the correct value since it was overrwitten and your new field holds the actual battery level value. For this reason, you should only use APPENDS _AND_OVERWRITES when you are sure it does not affect further decoding. One good way to ensure that it does not affect further decoding is by adding the original branching group or field into your new branching group. Following the above example, our original table entry branched to a group or field named ‘BatteryCharacteristic’ You will need to find out from Frontline if the original branch was to a group or field (let`s say it was a group), and then you just add it to your new branch like such:
GROUP MyBatteryCharacteristic
{
GROUP BatteryCharacteristic; //this was the original branch
FIELD myblPercent (Fixed 1) (decimal) "Battery Level" VERIFY (FieldIs GreaterThan 25) NO_MOVE
FIELD someOtherField START_BIT (Move 8 bits) (Fixed 1) (decimal) “Some other field” NO_MOVE
FIELD someField (Fixed 0) RETRIEVE (IntraFrameField somefield) (Decimal) “Some field” NO_MOVE
}
You will notice that all your fields in your new branching group have the NO_MOVE keyword at the end. It is a very good idea to include that keyword to the end of every field when appending and overwriting so that you do not change the bit pointer for future fields that Frontline`s decoder looks at.
The following is a list of protocols which you can add custom attributes to, and the name which you must have for your custom attributes file (in your My Decoders directory):
| Protocol | Required Custom Attributes File name 1 |
|---|---|
| 802.11 MAC | Custom Attributes 802.11 MAC.dh |
| 802.11 Radio | Custom Attributes 802.11 Radio.dh |
| PPP | Custom Attributes PPP.dh |
| Async PPP | Custom Attributes ASYNCPPP.dh |
| Bluetooth® L2CAP | Custom Attributes L2CAP.dh |
| Bluetooth LMP | Custom Attributes LMP.dh |
| Bluetooth RFCOMM | Custom Attributes RFCOMM.dh |
| Bluetooth SDP | Custom Attributes SDP.dh |
| Ethernet | Custom Attributes ethernet.dh |
| IP | Custom Attributes IP.dh |
| IPv6 | Custom Attributes IPv6.dh |
| LE ATT | Custom Attributes ATT.dh |
| LE SMP | Custom Attributes SMP.dh |
| IEEE_P11073 MDP | Custom Attributes MDP.dh |
| USB Setup | Custom Attributes USB setup.dh |
| USB | Custom Attributes USB.dh |
| Bluetooth SSP | Start_Main_Path_BT_SSP.dh 2 |
| 802.11 Radio | End Main Path 802.11 Radio.dh 3 |
|
1. Decoders are always being added so it is recommended that you contact Frontline Technical Support for information on the latest decoders: Phone: (434) 984-4500 or Email: tech_support@fte.com 2. Will be included before any decoding begins. By setting a variable you can cause SSP.dec not to decode anything but instead traverse to another decoder. 3. Will be included as the very last thing the decoder does before End_Main_Path which means that the included code will be the last thing that is run by the the decoder. |
|