Writing the Protocol

Intro

The ip.buffer has a very complex and full mechanism to allow for new protocols to be added to the device – without requiring Scannex to update the firmware!

This section of the manual outlines how you extend the protocol list.

In the web-page for the source the user can select the required protocol from a drop down list.
This list of protocols is built from the Scannex-defined protocols (which are hard-coded in firmware), and user-installed protocols.

Where to put the protocol code

It depends on your business model as to where you place the code.
The easiest place is in the normal script area.

However, any code written to this area is visible to anyone with the admin password – including your customers and your competitors.

In order to hide any protocols you write, you will need to assign an OEM Private Key to each ip.buffer you ship, and encrypt the OEM script.

Beginning the definition

Begin your protocol definition with the following Lua lines:

protocols.myprotocol = {}
protocols.myprotocol.desc = 'My protocol description'

The “myprotocol” should be something reasonably descriptive.

For example, you may choose to use .necneax for the NEC NEAX2400 protocol.

So the above lines would become:

protocols.necneax={}
protocols.necneax.desc= 'NEC NEAX2400 Serial'

The following sections deal with each parameter that should be defined for the protocol.

Binary style protocol

If the protocol is binary in nature (such as the Realitis/iSDX binary, or the “Binary” protocol) then define the following entry:

protocols.myprotocol.binary = 1

This entry will disable the “Time Stamp” field in the web page.

Bidirectional protocol

If the protocol requires full bidirectional access to the source to work, then define the following entry:

protocols.myprotocol.bidi = 1

This is only required for protocols that need to have a full “conversation” with the connected device. For example, the Avaya RSP protocol is currently the only Scannex-supplied protocol that has this entry.

Protocols marked as bidirectional will prevent the pass-through from connecting in anything except “Monitor” and “Debug” mode.
In addition, the protocol will not interface with source types that are unidirectional (ie. UDP and FTP).

Parameters for the web page

If the protocol has additional parameters that require user input, then define the following entry:

protocols.myprotocols.params = 'string'

The actual value of 'string' is complex. You can define drop-down combo box entries and edit-box entries for the web.
Each parameter is separated by the bar character |.

To define a drop down combo-box, use the following method:
S;var;label;hint;default;choice1=text1;choice2=text2...

  • “var” is the variable name. The user's choice will be loaded into the protocol table as p.var and can be referenced within all of the protocol events (setup, connect, data, second).
  • “label” is the text that appears on the web-page for that parameter.
  • “hint” is the text that appears on the far right side of the web-page.
  • “default” is the default value for the variable.
  • The list of “choice1=text1” define the variable definition and the text that is displayed in the combo box.

As an example, the “ASCII lines” built-in protocol defines whether to send XON characters to the source. The string for that option would be:
S;xon;XON;Software flow controlled?;0;0=None;1=Send

The variable will be defined as xon=0 for “None”, and xon=1 for “Send”.

Edit box

A normal edit box is defined with the following method:
T;var;label;hint;default;size

  • “var” as above
  • “label” as above
  • “hint” as above
  • “default” as above.
  • “size” defines how many characters wide the edit box is.

For example, the “ASCII lines” protocol requires a timeout value to be set:

T;timeout;Timeout;Data timeout (ms);1000;5

The variable will be “timeout” and is a maximum of 5 characters wide.

Complete example

The list of parameters can be combined to produce a full set of options.
For example, the “ASCII lines” protocol would be:

protocols.ascii.params="S;xon;XON;Is the device software flow
controlled?;0;0=None;1=Send|S;codes;Allow;What to
save;0;0=ASCII only;1=ASCII + codes|T;timeout;Timeout;Data
timeout (ms);1000;5;”

This defines three parameters:

  • A combo-box for xon
  • A combo-box for codes
  • An edit box for timeout
Caution

Do not define a var that clashes with any of the “source” methods (e.g. “write”), or a var called “n”!
Doing this will prevent the protocol from working completely!