Custom decoders#

Network Analyzer provides functionality to create custom decoders. This section provides a quick guide for using this feature.

Custom decoders can be created in Lua language, which is embedded inside Network Analyzer.

Step 1: Create a Lua File#

Create a '*.lua' file that contains the logic of your decoder. Example:

local decoder = {}
 
decoder.name = "Lua Test Decoder 1"
decoder.filterName = "luadecoder1"
decoder.description = "An example of a Lua decoder"
 
-- Init function is called whenever the decoder is created the first time.
-- It is NOT called for every packet. So only do global initialization here.
function decoder.init()
end
 
-- Accept is called for EVERY packet. if Accept returns true, then decode is called.
function decoder.accept()
  log("Accept.")
  if payloadByte(0) == 0x13 then
    return false
  else
    return true
  end
end
 
-- Decode function is called for EVERY packet that is accepted.
function decoder.decode()
  log("Decode.")
  append("firstByte", 1)
  local byte2 = decode("secondByte", 1)
  appendBits("bit0", 1)
  appendBits("bit1", 1)
  appendBits("bit23", 2)
   
  if byte2 == 0x02 then
    append("theWord", 2)
  else
    appendBytes("array0", 2)
  end
   
  setSummary("Lua decoded packet")
end
 
return decoder

Step 2: Register the Lua Decoder#

The workflow inside Network Analyzer to create a Lua custom decoder is as follows:

Go to Window > Preferences > Network Analyzer > Decoding.
Click Add...
Navigate to the *.lua file location, and select it.
Make sure the left-most checkbox that enables the custom decoder is enabled.

At this point, the custom decoder is registered to the decoding system and will be used when appropriate.

Internals#

The custom decoder is Lua code, containing a decoder object, that will be read by the decoding system.

Lua Decoder Object#

The Lua object is essentially a table of key/value pairs. This table lists the keys and the types of the values expected for the given keys, in order for the decoder to be recognized as such.


Name of element	Type of element	Purpose
name	String	Human readable name of the decoder mostly to show in the Preference table.
filterName	String	Decoding key used in filtering and similar.
description	String	Description that provides more in-depth description of this object.
init	void function	Initialization function, called only once when the Lua file is loaded. Intended for global initializations.
accept	boolean function	Function that returns true/false, depending on whether the passed event is something this decoder is interested in.
decode	void function	Decoding function that performs decoding. This function will only be called if accept() function returns true.

Lua API#

Inside the functions that are part of the Lua decoder, you can use some APIs that reach into the Network Analyzer java space. Following is the list of decoding functions.


Function	Return value	Arguments	Purpose
append	void	String fieldName, int length	Appends an integer field with a given fieldName and length to the list of decoded fields.
appendBits	void	String fieldName, int length	Appends length bits as bitmask inside the last decoded integer.
appendBytes	void	String fieldName, int length	Appends length bytes as a binary blob to the list of decoded fields.
decode	int	String fieldName, int length	Decodes an integer field with a given fieldName and length, and returns the value for further use.
log	void	String	Logs the message for debugging purpose.
payloadByte	int	int index	Returns a value of the byte at the specified index.
setSummary	void	String	Sets the summary of the packet for display in Network Analyzer UI.