TSN.1 Editor Tutorial

A practical guide for programmers and testers


In this tutorial, we walk through an example editing session to illustrate the features of the TSN.1 Editor. You will learn

  1. How to create and encode messages
  2. How to decode messages
  3. How to diagnose message encoding errors
  4. How to incorporate the TSN.1 Editor into a Java application

1. Launch the TSN.1 Editor

This tutorial assumes that you have installed the TSN.1 Editor on your computer. For Windows users, you can launch the Editor application by double clicking the TSN.1 Editor icon. For UNIX/Linux users, type the "tsne" command at the prompt and hit enter. The Editor GUI appears shortly. The GUI consists of two panels separated by an adjustable divider. The panel on the left displays a list of TSN.1 messages in a tree. The panel to the right is used to edit a message instance. We'll show you how to use these two panels next.

2. Add a TSN.1 File and Create a Message Instance

Before creating a message, we need to load a TSN.1 file into the Editor. Go to the "File" menu and select "Add TSN.1 File". For this tutorial, we will use the file examples/wimax_mac.tsn, which is under the Editor's standard installation directory. After the file is successfully added, a new node "wimax_mac.tsn" appears in the tree under the root node "TSN.1 Files". Double click "wimax_mac.tsn" and the node expands itself showing a list of messages defined in the file. You can load multiple TSN.1 files into the editor. If your TSN.1 file imports other files, you can set the import paths as well as other additional compile flags in the "Add TSN.1 File" Dialog.

The example "wimax_mac.tsn" defines only two messages, wimax_mac_DLMAP_IE and wimax_mac_DLMAP. We want to create a wimax_mac_DLMAP message. First select the message by clicking on the wimax_mac_DLMAP node. Make sure the node is highlighted. Right click anywhere in the tree. A floating menu pops up. Select "New Instance" and enter a name for the instance in the dialog box. If a message takes arguments, you will also be asked to provide their values in this dialog box. After you press the "OK" button, a new node with the instance name is added under the message node. You can create multiple instances of a message by repeating this process. As you may have noticed, you can rename and remove an instance using the floating menu as well.

After you are done, the Editor should look like this:

Create a Message

3. Edit and Encode a Message

Now an instance is created, you can start editing the message using the right-hand side panel. The panel is divided into three areas. The top area displays a read-only version of the TSN.1 file, which defines the message encodings: field name, number of bits, etc. The middle area is the context-sensitive editor for inputting message values. The bottom area enables you to encode, decode, and diagnose the message.

To input message values, position the cursor in the editor to the right of the open curly brace. As soon as you hit enter, you will notice that the MessageType field is inserted automatically. The value "2" is also inserted in this case because it is the default value for the field. You will also notice that in the TSN.1 file area above, the ">" symbol to the left has moved to the line where the MessageType field is defined. As you enter values for the subsequent fields of the message, the ">" symbol automatically scrolls to the corresponding line in the TSN.1 file. This gives you context information to help you input appropriate values for the fields. Together with auto-completion, this makes message editing almost effortless. The auto-completion feature can be toggled on and off by right clicking anywhere in the editor and selecting the "Auto Complete" item in the popup menu. If you've made a mistake in your input, an error message is displayed right below the editor and an "X" mark will appear in front of the line where the error is detected.

Enter some values for the rest of the fields in the message. Once you are done, press the "Encode" button to encode the message. Fix errors if there are any. Upon success, the encoded data is displayed in the "Bit Stream" text field at the bottom as a hex string.

Edit a Message

4. Decode and Diagnose a Message

To decode a message, input a hex string into the "Bit Stream" text field, for example, copy and paste from another application. For this tutorial, we will just use the bit stream created in the step above, but first let's clear the editor. Right click anywhere in the editor to bring up the floating menu and select "Reset". This resets the editor content back to an empty message. Next, press the "Decode" button. The decode output is displayed back in the editor.

If there is a decoding error or if you want to see a detailed field-by-field decode output, press the "Diagnose" button and the following window appears:

Diagnose a Message

At the top, the bit stream is displayed in hex, one byte at a time. Right below it is the binary representation of the stream. The line segments below the binary stream illustrate detailed decode output with one field per line segment. To find out which field the line segment represents, move the cursor close to the segment, a tool tip pops up automatically showing the field name, number of bits, and the field value. Moving the cursor close to the hex or binary stream will show you the byte or bit position of the data at the cursor.

5. Manage Sessions

Editor sessions can be saved and loaded back. The session management functions can be accessed from the "File" menu. The information saved includes: the TSN.1 file paths, the compile flags, and the message instances. The session file is stored in XML format. This makes integration with other tools such as the TSN.1 Compiler and the TSN.1 Server possible.

6. Other Tips and Hints

You can switch the editor between different message instances simply by selecting the instance from the message tree. You can filter out the message nodes that do not have any instance underneath them. Right click anywhere in the tree panel and toggle the "View Instance Only" box in the popup menu. The message tree also provides a number of useful tool tips. If the cursor is over a TSN.1 file node, the full path of that file is shown. If it is over a message instance node and the message takes arguments, the value of those arguments are displayed.

You can copy from and paste into the editor using your platform native copy and paste mechanism, for example, Ctrl-C and Ctrl-V for Windows. By default, the data is encoded starting from the most significant bit of the first byte. You can override this by giving a different bit offset in the "Offset" input field near the "Encode" button. This also applies to decoding. When input a bit stream for decoding, you can use any of the following formats:

7. Incorporate the Editor into Your Java Application

The TSN.1 Editor provides an API that allows you to embed the right-hand side panel of the Editor inside a Java application. This API is provided through the com.protomatics.tsn.tsne.EditorPanel class, which inherits from the javax.swing.JPanel. You can add instances of the EditorPanel into your Java Swing based application just like any other JPanel. To create the TSN.1 messages for editing, you will also need a license for the TSN.1 Server. The EditorPanel class provides the following public interface:

Method Summary
 void clear()
          Clear the editor panel. Remove the current message if there is any.
 void edit(Message msg, String editorText)
          Load a message into the editor. If msg is a new message, pass null for editorText. Otherwise, pass msg.toString().
 String getEditorText()
          Get the string in the editor text area
 String getOffsetText()
          Get the string in the offset text area
 String getStreamText()
          Get the string in the stream text area
 void setEditorText(String editorText)
          Set the string in the editor text area
 void setOffsetText(String offsetText)
          Set the string in the offset text area
 void setStreamText(String streamText)
          Set the string in the stream text area

The following demo application illustrates the usage of this API. When you compile and run the application, make sure "tsne.jar" is in your classpath.

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
import javax.swing.border.*;
import javax.swing.event.*;
import javax.swing.tree.*;

import com.protomatics.tsn.tsns.*; // TSN.1 Server classes
import com.protomatics.tsn.tsne.EditorPanel;

public class EditorAPIDemo extends JFrame
{
   public EditorAPIDemo(Message msg)
   {
      setTitle("EditorAPIDemo");

      // Create the Editor Panel
      EditorPanel panel = new EditorPanel();
      panel.setPreferredSize(new Dimension(500, 700));

      // Call the edit method to load the message into the editor
      panel.edit(msg, null);

      // Add the editor into the demo app frame
      Container contentPan = getContentPane();
      contentPan.add(panel);

      addWindowListener
      (
         new WindowAdapter()
         {
            public void windowClosing(WindowEvent e)
            {
               System.exit(0);
            }
         }
      );
   }

   public static void main(String args[])
   {
      if(args.length != 2)
      {
          System.err.println("Invalid number of arguments");
          System.exit(1);
      }

      String tsnFile = args[0]; // Example: "wimax_mac.tsn"
      String msgName = args[1]; // Example: "wimax_mac_DLMAP"

      if(!TSNS.getLicense("Your license"))
      {
         System.err.println("getLicense failed.");
         System.exit(1);
      }

      TSNS tsns = new TSNS();

      tsns.load("", tsnFile);

      Message msg = tsns.createMessage(msgName);

      EditorAPIDemo frame = new EditorAPIDemo(msg);

      frame.pack();
      frame.setVisible(true);
   }
}