Documentation

Guides and reference materials for all Protomatics products.

Support

For technical support, bug reports, or general questions about any Protomatics product, please email support@protomatics.com. Our team typically responds within one business day.

TSN.1 Documents

TSN.1 Compiler

TSN.1 Server

TSN.1 Editor

Installation Guide for Windows

This guide covers installing the TSN.1 Compiler and running the example program on Windows. For full details, refer to the User's Manual.

  1. Install the Compiler — Run the self-extracting Windows installer and follow the on-screen instructions. The installation creates directories for bin, doc, examples, lib, and src.
  2. Activate the Compiler — Open a command prompt in the bin directory and run tsnc. Follow the instructions to obtain a license file, then activate with: 
    tsnc -license path/to/license.txt
    Add the bin directory to your PATH environment variable for convenience.

Installation Guide for UNIX

This guide covers installing the TSN.1 Compiler on UNIX systems (Linux, macOS, Solaris, HP-UX, etc.). For full details, refer to the User's Manual.

  1. Install the Compiler — Extract the gzip'ed tar package to your preferred location: 
    cd /usr/local
gzip -cd tsnc-v*.tar.gz | tar xvf -
    The installation creates directories for bin, doc, examples, lib, and src.
  2. Prerequisites — Java Runtime Environment (JRE) 8 or later is required. Verify with java -version. On Linux, OpenJDK is recommended over gcj.
  3. Activate the Compiler — Navigate to the bin directory and run tsnc. Follow the instructions to obtain a license file, then activate with: 
    tsnc -license path/to/license.txt
    Add the bin directory to your PATH environment variable for convenience.

Wireshark Dissector Guide

The TSN.1 Compiler can auto-generate Wireshark dissector plugins from TSN.1 specifications. This eliminates the tedious and error-prone process of writing dissectors by hand. The generated dissector code handles field registration, packet dissection, and display formatting automatically.

How It Works

  1. Describe your protocol in TSN.1 — Define message formats, field types, enumerations, and conditional fields using TSN.1 notation.
  2. Generate the dissector — Run the compiler with the -wireshark flag: 
    tsnc -wireshark your_protocol.tsn
    This generates .h and .c files containing the dissector registration and dissection functions.
  3. Write a thin wrapper — Create a packet-*.c file that registers your protocol with Wireshark (protocol name, port, transport) and calls the generated dissect function.
  4. Build and install — Place the dissector under the Wireshark plugins directory, rebuild, and your protocol appears in Wireshark's dissector list.

The generated dissector supports enumerations, nested messages, conditional fields (case of), arrays, and custom display formats (hex, IPv4, IPv6, ASCII). For a complete step-by-step example using the Echo protocol, download the Echo Dissector example.

Frequently Asked Questions

Performance and Code Size

Q: My application runs on an ARM-based embedded target. What compile flags should I use?

On an embedded target with limited resources, you want to maximize performance while minimizing code size. If you only need the pack function for some messages and unpack for others, group your messages into separate TSN.1 files accordingly. Compile pack-only files with the -pack flag and unpack-only files with the -unpack flag. If your messages always start at a fixed byte boundary, enable the -byte-aligned flag for highly efficient pack/unpack code using bit shifts and bit masks.

If pack, unpack, and sizeof are all you need, you only require two Runtime Library source files: tsnc_msg.c and tsnc_buf.c, which total about 6K in object code size.

Q: I don't care about code size. I want maximum performance and all the functions. What compile flags should I use?

Use the -all flag. If your messages are byte aligned, use the -byte-aligned flag as well for additional performance.

Q: I want to avoid dynamic memory allocation. What compile flags should I use?

Use the -static flag. If all of your messages are byte aligned, use the -byte-aligned flag as well. For C targets, you can also use the -static-union flag to generate message types that use no dynamic memory. When using the -static flag, ensure you don't have arrays that are too large — see the question about restricting array sizes below.

Customization

Q: How do I customize the generated code?

You can customize output using compile flags (applied globally) or by annotating your TSN.1 file with XML tags for finer control. For example, use the -static flag for automatic storage globally, or annotate a specific field with <storage>static</storage>. Refer to the User's Manual for all customization options.

Q: How do I display a field in a format other than decimal?

Annotate the field with the <display> tag. For example, to display a field as an IPv4 address: 

SourceAddress  32; <display>ipv4</display>

Supported display formats include: oct (octal), hex (hexadecimal), ipv4, ipv6, and ascii.

Q: I have a message with a very special encoding scheme that can't be described in TSN.1. What do I do?

You can use the <pack> and <unpack> tags to replace the generated pack and unpack functions with your own custom functions. This keeps the standard Runtime Library API transparent to your application. Refer to the "Pack" and "Unpack" sections in the "Extensions" chapter of the User's Manual for details.

Q: Can I add my own code into the generated code?

Yes. Use the <code> tag to insert arbitrary code into the generated files. The tag has attributes that let you specify the target language, the file, and the message for which the code is intended. For example, you can add additional fields into a generated message type. See the "Code" section in the "Extensions" chapter of the User's Manual.

Q: How do I restrict the size of an array?

When an array's size depends on another field, the generated type reserves the maximum possible size. For example, an 8-bit size field produces an array of 255 elements. To restrict this, specify a range constraint on the size field: 

Size  8  (0..100);
Elements[Size]  : SomeMessageType;

The generated code will return an error if the array size exceeds 100.

Q: Can I use my own data structures for arrays?

Yes. Override the default array type by annotating the array with <type>MyContainer</type>, where MyContainer is your custom data structure (linked list, hash table, etc.). Your container must implement the container API as specified in the "Type" section of the "Extensions" chapter in the User's Manual.

Miscellaneous

Q: Can I document my TSN.1 files?

Yes. Use Doxygen-style comments in your TSN.1 files, then compile with the -doxygen flag. The compiler preserves your Doxygen comments in the generated files so you can run Doxygen as usual to produce source code documentation. See the "Doc" section in the "Extensions" chapter of the User's Manual.

Q: Does the generated parser perform range checking on field values?

By default, the generated code does not check if field values are out of range, allowing you to create invalid messages for testing purposes. To enable range checking, use the -check-range flag.

Q: I thought the generated code is endianness independent. What does the "-little-endian" flag do then?

The generated code is independent of your target platform's endianness — you do not need to recompile for different platforms. The -little-endian flag specifies the endianness of the encoded data, not the platform. By default, multibyte fields are packed in network byte order (big endian) per the TSN.1 specification. Use -little-endian to pack multibyte fields in little-endian order regardless of the host platform.